convertor/docs/06-錯誤排查與支援.md

錯誤排查與支援

本文件提供常見問題的排查步驟與解決方案。

---

目錄

• 常見問題速查
• 登入與認證問題
• 轉換相關問題
• Docker 相關問題
• 效能問題
• 日誌收集與分析
• 取得支援

---

常見問題速查

問題	可能原因	快速解決
登入後被踢回登入頁	HTTP/HTTPS 設定不正確	加上 HTTP_ALLOWED=true 或 TRUST_PROXY=true
重啟後資料消失	Volume 未正確掛載	確認 ./data:/app/data 且資料夾存在
重啟後被登出	JWT_SECRET 未固定	設定固定的 JWT_SECRET
中文顯示亂碼	使用 Lite 版（無字型）	改用一般版或 Full 版
轉換失敗	格式不支援或檔案損壞	檢查支援格式列表，確認檔案完整
容器啟動失敗	端口衝突或記憶體不足	檢查端口使用，增加記憶體

---

登入與認證問題

問題：登入後又被導回登入頁

症狀：

• 輸入帳密後頁面閃一下又回到登入頁
• Cookie 無法正確設定

原因與解決：

1. 使用 HTTP 但未允許

   environment:
     - HTTP_ALLOWED=true # 允許 HTTP 連線
   

2. 使用反向代理但未設定信任

   environment:
     - TRUST_PROXY=true # 信任反向代理
   

3. 反向代理未正確傳遞 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

---

轉換相關問題

問題：轉換失敗，顯示「格式不支援」

排查步驟：

1. 確認格式支援

   • 查看 04-功能總覽 的格式列表
   • 確認輸入和輸出格式都有支援

2. 確認版本

   • Lite 版功能較少，某些格式可能不支援
   • 改用一般版或 Full 版

3. 檢查檔案

   • 確認檔案未損壞
   • 嘗試用其他軟體開啟確認

問題：中文文件轉換後出現亂碼

原因：缺少中文字型

解決：

1. 使用一般版或 Full 版（已內建 CJK 字型）

2. Lite 版手動掛載字型：

   volumes:
     - ./fonts:/usr/share/fonts/custom
   

問題：PDF 翻譯功能無法使用

排查步驟：

1. 確認版本：Lite 版不支援 PDF 翻譯

2. 確認設定：

   environment:
     - PDFMATHTRANSLATE_SERVICE=google
   

3. 檢查網路：翻譯功能需要網路連線

問題：轉換時間過長

可能原因：

1. 檔案太大
2. 系統資源不足
3. 同時轉換任務過多

解決方案：

1. 限制同時轉換數：

   environment:
     - MAX_CONVERT_PROCESS=4
   

2. 增加資源限制：

   deploy:
     resources:
       limits:
         cpus: "4"
         memory: 8G
   

3. 啟用 GPU 加速（FFmpeg）：

   environment:
     - FFMPEG_ARGS=-hwaccel cuda
     - FFMPEG_OUTPUT_ARGS=-c:v h264_nvenc
   

---

Docker 相關問題

問題：容器無法啟動

排查步驟：

1. 檢查日誌：

   docker logs convertx-cn
   

2. 檢查端口佔用：

   # Linux / macOS
   lsof -i :3000
   
   # Windows
   netstat -ano | findstr :3000
   

3. 檢查磁碟空間：

   docker system df
   

4. 檢查記憶體：

   docker stats
   

問題：資料在重啟後消失

原因：Volume 未正確掛載

確認方式：

docker inspect convertx-cn | grep -A 10 Mounts

正確設定：

volumes:
  - ./data:/app/data

確保本機的 ./data 資料夾存在：

mkdir -p ./data

問題：拉取 Image 失敗

解決方案：

1. 檢查網路連線

2. 使用鏡像站（中國大陸）：

   docker pull registry.cn-hangzhou.aliyuncs.com/convertx/convertx-cn:latest
   

3. 手動下載： 從 GitHub Releases 下載 Image tarball

問題：磁碟空間不足

清理方式：

# 清理未使用的資源
docker system prune -a

# 清理舊的轉換檔案
rm -rf ./data/output/*
rm -rf ./data/uploads/*

預防措施：

environment:
  - AUTO_DELETE_EVERY_N_HOURS=6 # 頻繁清理

---

效能問題

診斷效能問題

1. 查看系統資源使用：

   docker stats convertx-cn
   

2. 查看容器內部狀態：

   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

---

取得支援

自助資源

1. 查閱文件：先查看本專案文件
2. 搜尋 Issues：GitHub Issues
3. 社群討論：GitHub Discussions

提交問題

提交 Issue 時請包含：

1. 環境資訊：

   • Docker 版本
   • ConvertX-CN 版本（Image Tag）
   • 作業系統

2. 問題描述：

   • 預期行為
   • 實際行為
   • 重現步驟

3. 相關資訊：

   • 環境變數設定（隱藏敏感資訊）
   • 相關日誌
   • 螢幕截圖（如適用）

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)