Elijah/convertor
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

新增錯誤排查與支援文件，提供常見問題解決方案；新增開發與貢獻指南，說明專案結構與開發流程；新增授權說明文件，詳述AGPL-3.0授權條款及第三方元件使用情況。

Browse source
This commit is contained in:
Your Name 2026-01-25 16:09:58 +08:00
parent 11d751250b
commit caecb2e001
13 changed files with 3269 additions and 369 deletions
Download patch file Download diff file Expand all files Collapse all files

415
docs/06-錯誤排查與支援.md Normal file
View file

@ -0,0 +1,415 @@
# 錯誤排查與支援
本文件提供常見問題的排查步驟與解決方案。
---
## 目錄
- [常見問題速查](#常見問題速查)
- [登入與認證問題](#登入與認證問題)
- [轉換相關問題](#轉換相關問題)
- [Docker 相關問題](#docker-相關問題)
- [效能問題](#效能問題)
- [日誌收集與分析](#日誌收集與分析)
- [取得支援](#取得支援)
---
## 常見問題速查
| 問題 | 可能原因 | 快速解決 |
|------|---------|---------|
| 登入後被踢回登入頁 | HTTP/HTTPS 設定不正確 | 加上 `HTTP_ALLOWED=true` 或 `TRUST_PROXY=true` |
| 重啟後資料消失 | Volume 未正確掛載 | 確認 `./data:/app/data` 且資料夾存在 |
| 重啟後被登出 | JWT_SECRET 未固定 | 設定固定的 `JWT_SECRET` |
| 中文顯示亂碼 | 使用 Lite 版（無字型） | 改用一般版或 Full 版 |
| 轉換失敗 | 格式不支援或檔案損壞 | 檢查支援格式列表，確認檔案完整 |
| 容器啟動失敗 | 端口衝突或記憶體不足 | 檢查端口使用，增加記憶體 |
---
## 登入與認證問題
### 問題：登入後又被導回登入頁
**症狀**：
- 輸入帳密後頁面閃一下又回到登入頁
- Cookie 無法正確設定
**原因與解決**：
1. **使用 HTTP 但未允許**
```yaml
environment:
- HTTP_ALLOWED=true # 允許 HTTP 連線
```
2. **使用反向代理但未設定信任**
```yaml
environment:
- TRUST_PROXY=true # 信任反向代理
```
3. **反向代理未正確傳遞 headers**
Nginx 設定需包含：
```nginx
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
```
### 問題：重啟容器後需要重新登入
**症狀**：
- 每次重啟容器後所有使用者都需要重新登入
**原因**：JWT_SECRET 未固定，每次啟動會產生新的隨機密鑰。
**解決**：
```yaml
environment:
- JWT_SECRET=您的固定隨機密鑰至少32字元
```
產生密鑰：
```bash
openssl rand -hex 32
```
### 問題：無法註冊新帳號
**症狀**：
- 找不到註冊按鈕
- 註冊時顯示錯誤
**原因**：註冊功能被關閉
**解決**：
```yaml
environment:
- ACCOUNT_REGISTRATION=true
```
---
## 轉換相關問題
### 問題：轉換失敗，顯示「格式不支援」
**排查步驟**：
1. **確認格式支援**
- 查看 [04-功能總覽](04-功能總覽.md) 的格式列表
- 確認輸入和輸出格式都有支援
2. **確認版本**
- Lite 版功能較少，某些格式可能不支援
- 改用一般版或 Full 版
3. **檢查檔案**
- 確認檔案未損壞
- 嘗試用其他軟體開啟確認
### 問題：中文文件轉換後出現亂碼
**原因**：缺少中文字型
**解決**：
1. **使用一般版或 Full 版**（已內建 CJK 字型）
2. **Lite 版手動掛載字型**：
```yaml
volumes:
- ./fonts:/usr/share/fonts/custom
```
### 問題：PDF 翻譯功能無法使用
**排查步驟**：
1. **確認版本**：Lite 版不支援 PDF 翻譯
2. **確認設定**：
```yaml
environment:
- PDFMATHTRANSLATE_SERVICE=google
```
3. **檢查網路**：翻譯功能需要網路連線
### 問題：轉換時間過長
**可能原因**：
1. 檔案太大
2. 系統資源不足
3. 同時轉換任務過多
**解決方案**：
1. **限制同時轉換數**：
```yaml
environment:
- MAX_CONVERT_PROCESS=4
```
2. **增加資源限制**：
```yaml
deploy:
resources:
limits:
cpus: '4'
memory: 8G
```
3. **啟用 GPU 加速**（FFmpeg）：
```yaml
environment:
- FFMPEG_ARGS=-hwaccel cuda
- FFMPEG_OUTPUT_ARGS=-c:v h264_nvenc
```
---
## Docker 相關問題
### 問題：容器無法啟動
**排查步驟**：
1. **檢查日誌**：
```bash
docker logs convertx-cn
```
2. **檢查端口佔用**：
```bash
# Linux / macOS
lsof -i :3000
# Windows
netstat -ano | findstr :3000
```
3. **檢查磁碟空間**：
```bash
docker system df
```
4. **檢查記憶體**：
```bash
docker stats
```
### 問題：資料在重啟後消失
**原因**：Volume 未正確掛載
**確認方式**：
```bash
docker inspect convertx-cn | grep -A 10 Mounts
```
**正確設定**：
```yaml
volumes:
- ./data:/app/data
```
確保本機的 `./data` 資料夾存在：
```bash
mkdir -p ./data
```
### 問題：拉取 Image 失敗
**解決方案**：
1. **檢查網路連線**
2. **使用鏡像站**（中國大陸）：
```bash
docker pull registry.cn-hangzhou.aliyuncs.com/convertx/convertx-cn:latest
```
3. **手動下載**：
從 GitHub Releases 下載 Image tarball
### 問題：磁碟空間不足
**清理方式**：
```bash
# 清理未使用的資源
docker system prune -a
# 清理舊的轉換檔案
rm -rf ./data/output/*
rm -rf ./data/uploads/*
```
**預防措施**：
```yaml
environment:
- AUTO_DELETE_EVERY_N_HOURS=6 # 頻繁清理
```
---
## 效能問題
### 診斷效能問題
1. **查看系統資源使用**：
```bash
docker stats convertx-cn
```
2. **查看容器內部狀態**：
```bash
docker exec -it convertx-cn top
```
### 效能優化建議
| 問題 | 解決方案 |
|------|---------|
| CPU 使用率高 | 限制 `MAX_CONVERT_PROCESS` |
| 記憶體不足 | 增加容器記憶體限制 |
| 磁碟 I/O 慢 | 使用 SSD，增加 Volume 效能 |
| 網路延遲 | 使用本地部署 |
### 推薦硬體配置
| 用途 | CPU | 記憶體 | 磁碟 |
|------|-----|--------|------|
| 個人使用 | 2 核 | 4 GB | 20 GB |
| 小團隊 | 4 核 | 8 GB | 50 GB |
| 生產環境 | 8 核 | 16 GB | 100 GB SSD |
---
## 日誌收集與分析
### 查看日誌
```bash
# 即時日誌
docker logs -f convertx-cn
# 最近 100 行
docker logs --tail 100 convertx-cn
# 指定時間範圍
docker logs --since "2026-01-25T00:00:00" convertx-cn
```
### 日誌等級
| 等級 | 說明 |
|------|------|
| `ERROR` | 錯誤，需要處理 |
| `WARN` | 警告，可能有問題 |
| `INFO` | 一般資訊 |
| `DEBUG` | 除錯資訊 |
### 常見日誌訊息
| 訊息 | 說明 |
|------|------|
| `🦊 Elysia is running at...` | 服務正常啟動 |
| `Conversion started...` | 開始轉換 |
| `Conversion completed...` | 轉換完成 |
| `Error: ENOSPC...` | 磁碟空間不足 |
| `Error: ENOMEM...` | 記憶體不足 |
### 匯出日誌
```bash
# 匯出到檔案
docker logs convertx-cn > convertx-logs.txt 2>&1
# 壓縮匯出
docker logs convertx-cn 2>&1 | gzip > convertx-logs.gz
```
---
## 取得支援
### 自助資源
1. **查閱文件**：先查看本專案文件
2. **搜尋 Issues**：[GitHub Issues](https://github.com/pi-docket/ConvertX-CN/issues)
3. **社群討論**：[GitHub Discussions](https://github.com/pi-docket/ConvertX-CN/discussions)
### 提交問題
提交 Issue 時請包含：
1. **環境資訊**：
- Docker 版本
- ConvertX-CN 版本（Image Tag）
- 作業系統
2. **問題描述**：
- 預期行為
- 實際行為
- 重現步驟
3. **相關資訊**：
- 環境變數設定（隱藏敏感資訊）
- 相關日誌
- 螢幕截圖（如適用）
### Issue 範本
```markdown
## 環境
- ConvertX-CN 版本：`latest`
- Docker 版本：`24.0.5`
- 作業系統：Ubuntu 22.04
## 問題描述
登入後被踢回登入頁。
## 重現步驟
1. 訪問 http://localhost:3000
2. 輸入帳號密碼
3. 點擊登入
4. 頁面閃一下後回到登入頁
## 環境變數
```yaml
environment:
- TZ=Asia/Taipei
- JWT_SECRET=****
```
## 日誌
```
[相關日誌內容]
```
```
### 聯繫方式
| 管道 | 連結 |
|------|------|
| GitHub Issues | [建立 Issue](https://github.com/pi-docket/ConvertX-CN/issues) |
| GitHub Discussions | [社群討論](https://github.com/pi-docket/ConvertX-CN/discussions) |
---
[⬆️ 回到頂部](#錯誤排查與支援) | [📚 回到目錄](00-專案總覽.md)