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

# 錯誤排查與支援

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

---

## 目錄

- [常見問題速查](#常見問題速查)
- [登入與認證問題](#登入與認證問題)
- [轉換相關問題](#轉換相關問題)
- [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)
```