Refactor documentation for improved clarity and consistency
- Updated tables for service ports, environment variables, HTTP status codes, and error codes to enhance readability. - Streamlined JavaScript examples for file conversion and added comments for better understanding. - Enhanced troubleshooting section with clearer formatting and additional explanations. - Improved licensing section with detailed requirements and third-party component licenses. - Organized the document structure for better navigation and accessibility.
This commit is contained in:
Your Name
parent
caecb2e001
commit
394dcbec1a
11 changed files with 538 additions and 497 deletions
|
|
@ -18,14 +18,14 @@
|
|||
|
||||
## 常見問題速查
|
||||
|
||||
| 問題 | 可能原因 | 快速解決 |
|
||||
|------|---------|---------|
|
||||
| 登入後被踢回登入頁 | HTTP/HTTPS 設定不正確 | 加上 `HTTP_ALLOWED=true` 或 `TRUST_PROXY=true` |
|
||||
| 重啟後資料消失 | Volume 未正確掛載 | 確認 `./data:/app/data` 且資料夾存在 |
|
||||
| 重啟後被登出 | JWT_SECRET 未固定 | 設定固定的 `JWT_SECRET` |
|
||||
| 中文顯示亂碼 | 使用 Lite 版（無字型） | 改用一般版或 Full 版 |
|
||||
| 轉換失敗 | 格式不支援或檔案損壞 | 檢查支援格式列表，確認檔案完整 |
|
||||
| 容器啟動失敗 | 端口衝突或記憶體不足 | 檢查端口使用，增加記憶體 |
|
||||
| 問題 | 可能原因 | 快速解決 |
|
||||
| ------------------ | ---------------------- | ---------------------------------------------- |
|
||||
| 登入後被踢回登入頁 | HTTP/HTTPS 設定不正確 | 加上 `HTTP_ALLOWED=true` 或 `TRUST_PROXY=true` |
|
||||
| 重啟後資料消失 | Volume 未正確掛載 | 確認 `./data:/app/data` 且資料夾存在 |
|
||||
| 重啟後被登出 | JWT_SECRET 未固定 | 設定固定的 `JWT_SECRET` |
|
||||
| 中文顯示亂碼 | 使用 Lite 版（無字型） | 改用一般版或 Full 版 |
|
||||
| 轉換失敗 | 格式不支援或檔案損壞 | 檢查支援格式列表，確認檔案完整 |
|
||||
| 容器啟動失敗 | 端口衝突或記憶體不足 | 檢查端口使用，增加記憶體 |
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -34,6 +34,7 @@
|
|||
### 問題：登入後又被導回登入頁
|
||||
|
||||
**症狀**：
|
||||
|
||||
- 輸入帳密後頁面閃一下又回到登入頁
|
||||
- Cookie 無法正確設定
|
||||
|
||||
|
|
@ -43,19 +44,20 @@
|
|||
|
||||
```yaml
|
||||
environment:
|
||||
- HTTP_ALLOWED=true # 允許 HTTP 連線
|
||||
- HTTP_ALLOWED=true # 允許 HTTP 連線
|
||||
```
|
||||
|
||||
2. **使用反向代理但未設定信任**
|
||||
|
||||
```yaml
|
||||
environment:
|
||||
- TRUST_PROXY=true # 信任反向代理
|
||||
- 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;
|
||||
|
|
@ -64,6 +66,7 @@
|
|||
### 問題：重啟容器後需要重新登入
|
||||
|
||||
**症狀**：
|
||||
|
||||
- 每次重啟容器後所有使用者都需要重新登入
|
||||
|
||||
**原因**：JWT_SECRET 未固定，每次啟動會產生新的隨機密鑰。
|
||||
|
|
@ -84,6 +87,7 @@ openssl rand -hex 32
|
|||
### 問題：無法註冊新帳號
|
||||
|
||||
**症狀**：
|
||||
|
||||
- 找不到註冊按鈕
|
||||
- 註冊時顯示錯誤
|
||||
|
||||
|
|
@ -137,6 +141,7 @@ environment:
|
|||
1. **確認版本**：Lite 版不支援 PDF 翻譯
|
||||
|
||||
2. **確認設定**：
|
||||
|
||||
```yaml
|
||||
environment:
|
||||
- PDFMATHTRANSLATE_SERVICE=google
|
||||
|
|
@ -155,17 +160,19 @@ environment:
|
|||
**解決方案**：
|
||||
|
||||
1. **限制同時轉換數**：
|
||||
|
||||
```yaml
|
||||
environment:
|
||||
- MAX_CONVERT_PROCESS=4
|
||||
```
|
||||
|
||||
2. **增加資源限制**：
|
||||
|
||||
```yaml
|
||||
deploy:
|
||||
resources:
|
||||
limits:
|
||||
cpus: '4'
|
||||
cpus: "4"
|
||||
memory: 8G
|
||||
```
|
||||
|
||||
|
|
@ -185,20 +192,23 @@ environment:
|
|||
**排查步驟**：
|
||||
|
||||
1. **檢查日誌**：
|
||||
|
||||
```bash
|
||||
docker logs convertx-cn
|
||||
```
|
||||
|
||||
2. **檢查端口佔用**：
|
||||
|
||||
```bash
|
||||
# Linux / macOS
|
||||
lsof -i :3000
|
||||
|
||||
|
||||
# Windows
|
||||
netstat -ano | findstr :3000
|
||||
```
|
||||
|
||||
3. **檢查磁碟空間**：
|
||||
|
||||
```bash
|
||||
docker system df
|
||||
```
|
||||
|
|
@ -238,6 +248,7 @@ mkdir -p ./data
|
|||
1. **檢查網路連線**
|
||||
|
||||
2. **使用鏡像站**（中國大陸）：
|
||||
|
||||
```bash
|
||||
docker pull registry.cn-hangzhou.aliyuncs.com/convertx/convertx-cn:latest
|
||||
```
|
||||
|
|
@ -262,7 +273,7 @@ rm -rf ./data/uploads/*
|
|||
|
||||
```yaml
|
||||
environment:
|
||||
- AUTO_DELETE_EVERY_N_HOURS=6 # 頻繁清理
|
||||
- AUTO_DELETE_EVERY_N_HOURS=6 # 頻繁清理
|
||||
```
|
||||
|
||||
---
|
||||
|
|
@ -272,6 +283,7 @@ environment:
|
|||
### 診斷效能問題
|
||||
|
||||
1. **查看系統資源使用**：
|
||||
|
||||
```bash
|
||||
docker stats convertx-cn
|
||||
```
|
||||
|
|
@ -283,20 +295,20 @@ environment:
|
|||
|
||||
### 效能優化建議
|
||||
|
||||
| 問題 | 解決方案 |
|
||||
|------|---------|
|
||||
| 問題 | 解決方案 |
|
||||
| ------------ | -------------------------- |
|
||||
| CPU 使用率高 | 限制 `MAX_CONVERT_PROCESS` |
|
||||
| 記憶體不足 | 增加容器記憶體限制 |
|
||||
| 磁碟 I/O 慢 | 使用 SSD，增加 Volume 效能 |
|
||||
| 網路延遲 | 使用本地部署 |
|
||||
| 記憶體不足 | 增加容器記憶體限制 |
|
||||
| 磁碟 I/O 慢 | 使用 SSD，增加 Volume 效能 |
|
||||
| 網路延遲 | 使用本地部署 |
|
||||
|
||||
### 推薦硬體配置
|
||||
|
||||
| 用途 | CPU | 記憶體 | 磁碟 |
|
||||
|------|-----|--------|------|
|
||||
| 個人使用 | 2 核 | 4 GB | 20 GB |
|
||||
| 小團隊 | 4 核 | 8 GB | 50 GB |
|
||||
| 生產環境 | 8 核 | 16 GB | 100 GB SSD |
|
||||
| 用途 | CPU | 記憶體 | 磁碟 |
|
||||
| -------- | ---- | ------ | ---------- |
|
||||
| 個人使用 | 2 核 | 4 GB | 20 GB |
|
||||
| 小團隊 | 4 核 | 8 GB | 50 GB |
|
||||
| 生產環境 | 8 核 | 16 GB | 100 GB SSD |
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -317,22 +329,22 @@ docker logs --since "2026-01-25T00:00:00" convertx-cn
|
|||
|
||||
### 日誌等級
|
||||
|
||||
| 等級 | 說明 |
|
||||
|------|------|
|
||||
| `ERROR` | 錯誤，需要處理 |
|
||||
| `WARN` | 警告，可能有問題 |
|
||||
| `INFO` | 一般資訊 |
|
||||
| `DEBUG` | 除錯資訊 |
|
||||
| 等級 | 說明 |
|
||||
| ------- | ---------------- |
|
||||
| `ERROR` | 錯誤，需要處理 |
|
||||
| `WARN` | 警告，可能有問題 |
|
||||
| `INFO` | 一般資訊 |
|
||||
| `DEBUG` | 除錯資訊 |
|
||||
|
||||
### 常見日誌訊息
|
||||
|
||||
| 訊息 | 說明 |
|
||||
|------|------|
|
||||
| 訊息 | 說明 |
|
||||
| ---------------------------- | ------------ |
|
||||
| `🦊 Elysia is running at...` | 服務正常啟動 |
|
||||
| `Conversion started...` | 開始轉換 |
|
||||
| `Conversion completed...` | 轉換完成 |
|
||||
| `Error: ENOSPC...` | 磁碟空間不足 |
|
||||
| `Error: ENOMEM...` | 記憶體不足 |
|
||||
| `Conversion started...` | 開始轉換 |
|
||||
| `Conversion completed...` | 轉換完成 |
|
||||
| `Error: ENOSPC...` | 磁碟空間不足 |
|
||||
| `Error: ENOMEM...` | 記憶體不足 |
|
||||
|
||||
### 匯出日誌
|
||||
|
||||
|
|
@ -375,32 +387,39 @@ docker logs convertx-cn 2>&1 | gzip > convertx-logs.gz
|
|||
|
||||
### Issue 範本
|
||||
|
||||
```markdown
|
||||
````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=****
|
||||
```
|
||||
````
|
||||
|
||||
## 日誌
|
||||
|
||||
```
|
||||
[相關日誌內容]
|
||||
```
|
||||
|
||||
```
|
||||
|
||||
### 聯繫方式
|
||||
|
|
@ -413,3 +432,4 @@ environment:
|
|||
---
|
||||
|
||||
[⬆️ 回到頂部](#錯誤排查與支援) | [📚 回到目錄](00-專案總覽.md)
|
||||
```
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue