7.8 KiB
7.8 KiB
錯誤排查與支援
本文件提供常見問題的排查步驟與解決方案。
目錄
常見問題速查
| 問題 | 可能原因 | 快速解決 |
|---|---|---|
| 登入後被踢回登入頁 | HTTP/HTTPS 設定不正確 | 加上 HTTP_ALLOWED=true 或 TRUST_PROXY=true |
| 重啟後資料消失 | Volume 未正確掛載 | 確認 ./data:/app/data 且資料夾存在 |
| 重啟後被登出 | JWT_SECRET 未固定 | 設定固定的 JWT_SECRET |
| 中文顯示亂碼 | 使用 Lite 版（無字型） | 改用一般版或 Full 版 |
| 轉換失敗 | 格式不支援或檔案損壞 | 檢查支援格式列表，確認檔案完整 |
| 容器啟動失敗 | 端口衝突或記憶體不足 | 檢查端口使用，增加記憶體 |
登入與認證問題
問題：登入後又被導回登入頁
症狀：
- 輸入帳密後頁面閃一下又回到登入頁
- Cookie 無法正確設定
原因與解決：
-
使用 HTTP 但未允許
environment: - HTTP_ALLOWED=true # 允許 HTTP 連線 -
使用反向代理但未設定信任
environment: - TRUST_PROXY=true # 信任反向代理 -
反向代理未正確傳遞 headers
Nginx 設定需包含：
proxy_set_header X-Forwarded-Proto $scheme; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
問題：重啟容器後需要重新登入
症狀：
- 每次重啟容器後所有使用者都需要重新登入
原因：JWT_SECRET 未固定，每次啟動會產生新的隨機密鑰。
解決：
environment:
- JWT_SECRET=您的固定隨機密鑰至少32字元
產生密鑰：
openssl rand -hex 32
問題：無法註冊新帳號
症狀：
- 找不到註冊按鈕
- 註冊時顯示錯誤
原因：註冊功能被關閉
解決：
environment:
- ACCOUNT_REGISTRATION=true
轉換相關問題
問題：轉換失敗，顯示「格式不支援」
排查步驟：
-
確認格式支援
- 查看 04-功能總覽 的格式列表
- 確認輸入和輸出格式都有支援
-
確認版本
- Lite 版功能較少，某些格式可能不支援
- 改用一般版或 Full 版
-
檢查檔案
- 確認檔案未損壞
- 嘗試用其他軟體開啟確認
問題：中文文件轉換後出現亂碼
原因：缺少中文字型
解決：
-
使用一般版或 Full 版（已內建 CJK 字型）
-
Lite 版手動掛載字型：
volumes: - ./fonts:/usr/share/fonts/custom
問題：PDF 翻譯功能無法使用
排查步驟：
-
確認版本：Lite 版不支援 PDF 翻譯
-
確認設定：
environment: - PDFMATHTRANSLATE_SERVICE=google -
檢查網路：翻譯功能需要網路連線
問題：轉換時間過長
可能原因：
- 檔案太大
- 系統資源不足
- 同時轉換任務過多
解決方案：
-
限制同時轉換數：
environment: - MAX_CONVERT_PROCESS=4 -
增加資源限制：
deploy: resources: limits: cpus: '4' memory: 8G -
啟用 GPU 加速（FFmpeg）：
environment: - FFMPEG_ARGS=-hwaccel cuda - FFMPEG_OUTPUT_ARGS=-c:v h264_nvenc
Docker 相關問題
問題：容器無法啟動
排查步驟：
-
檢查日誌：
docker logs convertx-cn -
檢查端口佔用：
# Linux / macOS lsof -i :3000 # Windows netstat -ano | findstr :3000 -
檢查磁碟空間：
docker system df -
檢查記憶體：
docker stats
問題：資料在重啟後消失
原因：Volume 未正確掛載
確認方式：
docker inspect convertx-cn | grep -A 10 Mounts
正確設定：
volumes:
- ./data:/app/data
確保本機的 ./data 資料夾存在：
mkdir -p ./data
問題：拉取 Image 失敗
解決方案：
-
檢查網路連線
-
使用鏡像站（中國大陸）：
docker pull registry.cn-hangzhou.aliyuncs.com/convertx/convertx-cn:latest -
手動下載： 從 GitHub Releases 下載 Image tarball
問題：磁碟空間不足
清理方式：
# 清理未使用的資源
docker system prune -a
# 清理舊的轉換檔案
rm -rf ./data/output/*
rm -rf ./data/uploads/*
預防措施：
environment:
- AUTO_DELETE_EVERY_N_HOURS=6 # 頻繁清理
效能問題
診斷效能問題
-
查看系統資源使用：
docker stats convertx-cn -
查看容器內部狀態：
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 |
日誌收集與分析
查看日誌
# 即時日誌
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... |
記憶體不足 |
匯出日誌
# 匯出到檔案
docker logs convertx-cn > convertx-logs.txt 2>&1
# 壓縮匯出
docker logs convertx-cn 2>&1 | gzip > convertx-logs.gz
取得支援
自助資源
- 查閱文件：先查看本專案文件
- 搜尋 Issues：GitHub Issues
- 社群討論：GitHub Discussions
提交問題
提交 Issue 時請包含：
-
環境資訊：
- Docker 版本
- ConvertX-CN 版本（Image Tag）
- 作業系統
-
問題描述：
- 預期行為
- 實際行為
- 重現步驟
-
相關資訊：
- 環境變數設定（隱藏敏感資訊）
- 相關日誌
- 螢幕截圖（如適用）
Issue 範本
## 環境
- 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)