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

Refactor documentation for improved clarity and consistency

Browse source 
- 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 2026-01-25 16:10:07 +08:00
parent caecb2e001
commit 394dcbec1a
11 changed files with 538 additions and 497 deletions
Download patch file Download diff file Expand all files Collapse all files

4
README.md
View file

@ -29,7 +29,7 @@
完整文件請參閱 **[專案總覽](docs/00-專案總覽.md)** 完整文件請參閱 **[專案總覽](docs/00-專案總覽.md)**
| 章節 | 說明 | 連結 | | 章節 | 說明 | 連結 |
| ---- | ---- | ---- | | ------------------ | ---------------------------- | --------------------------------- |
| 📖 **00 專案總覽** | 專案定位、功能特色、版本比較 | [查看](docs/00-專案總覽.md) | | 📖 **00 專案總覽** | 專案定位、功能特色、版本比較 | [查看](docs/00-專案總覽.md) |
| 🚀 **01 快速開始** | 5 分鐘部署完成 | [查看](docs/01-快速開始.md) | | 🚀 **01 快速開始** | 5 分鐘部署完成 | [查看](docs/01-快速開始.md) |
| 🐳 **02 部署指南** | Docker 設定、反向代理、HTTPS | [查看](docs/02-部署指南.md) | | 🐳 **02 部署指南** | Docker 設定、反向代理、HTTPS | [查看](docs/02-部署指南.md) |
@ -203,7 +203,7 @@ docker run -d \
### 授權摘要 ### 授權摘要
| 權利 | 說明 | | 權利 | 說明 |
|------|------| | ----------- | ------------------------ |
| ✅ 自由使用 | 個人、商業、教育用途均可 | | ✅ 自由使用 | 個人、商業、教育用途均可 |
| ✅ 自由修改 | 可修改原始碼 | | ✅ 自由修改 | 可修改原始碼 |
| ✅ 自由分發 | 可重新分發 | | ✅ 自由分發 | 可重新分發 |

14
docs/00-專案總覽.md
View file

@ -26,7 +26,7 @@ ConvertX-CN 是一個**開箱即用的全功能檔案轉換服務**，基於 [C4
### 🌟 專案特色 ### 🌟 專案特色
| 特色 | 說明 | | 特色 | 說明 |
|------|------| | ----------------- | --------------------------------------- |
| 📁 **1000+ 格式** | 文件、圖片、影音、電子書一次搞定 | | 📁 **1000+ 格式** | 文件、圖片、影音、電子書一次搞定 |
| 🔧 **25+ 引擎** | LibreOffice、FFmpeg、Pandoc 全到位 | | 🔧 **25+ 引擎** | LibreOffice、FFmpeg、Pandoc 全到位 |
| 🈶 **中文優化** | 內建中日韓字型與 OCR，告別亂碼 | | 🈶 **中文優化** | 內建中日韓字型與 OCR，告別亂碼 |
@ -39,7 +39,7 @@ ConvertX-CN 是一個**開箱即用的全功能檔案轉換服務**，基於 [C4
## ConvertX-CN 與原始 ConvertX 的差異 ## ConvertX-CN 與原始 ConvertX 的差異
| 項目 | 原始 ConvertX | ConvertX-CN | | 項目 | 原始 ConvertX | ConvertX-CN |
|------|--------------|-------------| | --------------- | ------------- | ---------------------------------- |
| **語言支援** | 英文介面為主 | 65 種語言介面，中文優化 | | **語言支援** | 英文介面為主 | 65 種語言介面，中文優化 |
| **字型支援** | 基本字型 | 內建中日韓完整字型集 | | **字型支援** | 基本字型 | 內建中日韓完整字型集 |
| **OCR 語言** | 需手動安裝 | 預裝 7 種常用語言（Full 版 65 種） | | **OCR 語言** | 需手動安裝 | 預裝 7 種常用語言（Full 版 65 種） |
@ -65,7 +65,7 @@ ConvertX-CN 是一個**開箱即用的全功能檔案轉換服務**，基於 [C4
### 按類型分類 ### 按類型分類
| 類型 | 轉換器 | 支援格式數 | | 類型 | 轉換器 | 支援格式數 |
|------|--------|-----------| | --------------- | -------------------------------------------- | ---------- |
| 🎬 **影音** | FFmpeg | 400+ | | 🎬 **影音** | FFmpeg | 400+ |
| 🖼️ **圖片** | ImageMagick, GraphicsMagick, Vips | 300+ | | 🖼️ **圖片** | ImageMagick, GraphicsMagick, Vips | 300+ |
| 📄 **文件** | LibreOffice, Pandoc | 160+ | | 📄 **文件** | LibreOffice, Pandoc | 160+ |
@ -78,7 +78,7 @@ ConvertX-CN 是一個**開箱即用的全功能檔案轉換服務**，基於 [C4
### 完整轉換器列表 ### 完整轉換器列表
| 轉換器 | 用途 | 輸入格式 | 輸出格式 | | 轉換器 | 用途 | 輸入格式 | 輸出格式 |
|--------|------|----------|----------| | ---------------- | ------------ | -------- | -------- |
| FFmpeg | 影音 | 472 | 199 | | FFmpeg | 影音 | 472 | 199 |
| ImageMagick | 圖片 | 253 | 183 | | ImageMagick | 圖片 | 253 | 183 |
| GraphicsMagick | 圖片 | 167 | 130 | | GraphicsMagick | 圖片 | 167 | 130 |
@ -112,7 +112,7 @@ ConvertX-CN 是一個**開箱即用的全功能檔案轉換服務**，基於 [C4
ConvertX-CN 提供三個版本，滿足不同需求： ConvertX-CN 提供三個版本，滿足不同需求：
| 特性 | Lite 版 | 一般版（推薦） | Full 版 | | 特性 | Lite 版 | 一般版（推薦） | Full 版 |
|------|---------|---------------|---------| | ----------------- | ---------- | -------------- | ----------- |
| **Image 大小** | ~3 GB | ~7 GB | ~15 GB | | **Image 大小** | ~3 GB | ~7 GB | ~15 GB |
| **部署速度** | 最快 | 中等 | 較慢 | | **部署速度** | 最快 | 中等 | 較慢 |
| **適用對象** | 輕量使用者 | 一般使用者 | 進階/多語言 | | **適用對象** | 輕量使用者 | 一般使用者 | 進階/多語言 |
@ -126,7 +126,7 @@ ConvertX-CN 提供三個版本，滿足不同需求：
### Docker Tag 說明 ### Docker Tag 說明
| Tag | 說明 | | Tag | 說明 |
|-----|------| | ------------- | ----------------- |
| `latest` | 一般版最新穩定版 | | `latest` | 一般版最新穩定版 |
| `latest-lite` | Lite 版最新穩定版 | | `latest-lite` | Lite 版最新穩定版 |
| `latest-full` | Full 版最新穩定版 | | `latest-full` | Full 版最新穩定版 |
@ -139,7 +139,7 @@ ConvertX-CN 提供三個版本，滿足不同需求：
## 相關文件 ## 相關文件
| 文件 | 說明 | | 文件 | 說明 |
|------|------| | ----------------------------------------- | ------------------ |
| [01-快速開始](01-快速開始.md) | 5 分鐘內完成部署 | | [01-快速開始](01-快速開始.md) | 5 分鐘內完成部署 |
| [02-部署指南](02-部署指南.md) | 詳細部署設定 | | [02-部署指南](02-部署指南.md) | 詳細部署設定 |
| [03-環境變數與設定](03-環境變數與設定.md) | 所有可用設定 | | [03-環境變數與設定](03-環境變數與設定.md) | 所有可用設定 |

12
docs/01-快速開始.md
View file

@ -18,7 +18,7 @@
## 前置需求 ## 前置需求
| 需求 | 最低規格 | 建議規格 | | 需求 | 最低規格 | 建議規格 |
|------|---------|---------| | -------- | ----------------------- | -------- |
| Docker | 20.10+ | 24.0+ | | Docker | 20.10+ | 24.0+ |
| 記憶體 | 4 GB | 8 GB | | 記憶體 | 4 GB | 8 GB |
| 磁碟空間 | 10 GB | 30 GB | | 磁碟空間 | 10 GB | 30 GB |
@ -157,11 +157,13 @@ docker logs convertx-cn
4. 下載轉換後的 PDF 檔案 4. 下載轉換後的 PDF 檔案
**輸入：** **輸入：**
``` ```
report.docx (Microsoft Word 文件) report.docx (Microsoft Word 文件)
``` ```
**輸出：** **輸出：**
``` ```
report.pdf (PDF 文件) report.pdf (PDF 文件)
``` ```
@ -173,11 +175,13 @@ report.pdf (PDF 文件)
3. 點擊「轉換」 3. 點擊「轉換」
**輸入：** **輸入：**
``` ```
video.mov (QuickTime 影片, 500 MB) video.mov (QuickTime 影片, 500 MB)
``` ```
**輸出：** **輸出：**
``` ```
video.mp4 (MP4 影片, 壓縮後約 200 MB) video.mp4 (MP4 影片, 壓縮後約 200 MB)
``` ```
@ -190,11 +194,13 @@ video.mp4 (MP4 影片, 壓縮後約 200 MB)
4. 點擊「翻譯」 4. 點擊「翻譯」
**輸入：** **輸入：**
``` ```
paper.pdf (英文學術論文，含數學公式) paper.pdf (英文學術論文，含數學公式)
``` ```
**輸出：** **輸出：**
``` ```
paper_translated.pdf (中文翻譯，公式與排版保留) paper_translated.pdf (中文翻譯，公式與排版保留)
``` ```
@ -204,7 +210,7 @@ paper_translated.pdf (中文翻譯，公式與排版保留)
## 常見問題快查 ## 常見問題快查
| 問題 | 解決方法 | | 問題 | 解決方法 |
|------|---------| | ------------------ | ---------------------------------------------- |
| 登入後被踢回登入頁 | 加上 `HTTP_ALLOWED=true` 或 `TRUST_PROXY=true` | | 登入後被踢回登入頁 | 加上 `HTTP_ALLOWED=true` 或 `TRUST_PROXY=true` |
| 重啟後資料消失 | 確認 `./data:/app/data` 且資料夾存在 | | 重啟後資料消失 | 確認 `./data:/app/data` 且資料夾存在 |
| 重啟後被登出 | 設定固定的 `JWT_SECRET` | | 重啟後被登出 | 設定固定的 `JWT_SECRET` |
@ -218,7 +224,7 @@ paper_translated.pdf (中文翻譯，公式與排版保留)
## 下一步 ## 下一步
| 需求 | 推薦閱讀 | | 需求 | 推薦閱讀 |
|------|---------| | ------------ | ----------------------------------------- |
| 詳細部署設定 | [02-部署指南](02-部署指南.md) | | 詳細部署設定 | [02-部署指南](02-部署指南.md) |
| 環境變數設定 | [03-環境變數與設定](03-環境變數與設定.md) | | 環境變數設定 | [03-環境變數與設定](03-環境變數與設定.md) |
| 了解所有功能 | [04-功能總覽](04-功能總覽.md) | | 了解所有功能 | [04-功能總覽](04-功能總覽.md) |

8
docs/02-部署指南.md
View file

@ -19,7 +19,7 @@
### 系統需求 ### 系統需求
| 項目 | 最低需求 | 建議配置 | | 項目 | 最低需求 | 建議配置 |
|------|---------|---------| | -------- | -------- | ---------- |
| CPU | 2 核心 | 4 核心以上 | | CPU | 2 核心 | 4 核心以上 |
| 記憶體 | 4 GB | 8 GB 以上 | | 記憶體 | 4 GB | 8 GB 以上 |
| 磁碟空間 | 10 GB | 30 GB SSD | | 磁碟空間 | 10 GB | 30 GB SSD |
@ -100,10 +100,10 @@ services:
deploy: deploy:
resources: resources:
limits: limits:
cpus: '4' cpus: "4"
memory: 8G memory: 8G
reservations: reservations:
cpus: '2' cpus: "2"
memory: 4G memory: 4G
healthcheck: healthcheck:
test: ["CMD", "curl", "-f", "http://localhost:3000/health"] test: ["CMD", "curl", "-f", "http://localhost:3000/health"]
@ -135,7 +135,7 @@ services:
### 環境變數說明 ### 環境變數說明
| 變數 | 說明 | 預設值 | | 變數 | 說明 | 預設值 |
|------|------|--------| | -------------- | ------------------------ | ------------------ |
| `JWT_SECRET` | 登入驗證金鑰（**必填**） | 隨機（每次重啟變） | | `JWT_SECRET` | 登入驗證金鑰（**必填**） | 隨機（每次重啟變） |
| `TZ` | 時區 | `UTC` | | `TZ` | 時區 | `UTC` |
| `HTTP_ALLOWED` | 允許 HTTP 連線 | `false` | | `HTTP_ALLOWED` | 允許 HTTP 連線 | `false` |

48
docs/03-環境變數與設定.md
View file

@ -21,7 +21,7 @@
### 🔒 安全性設定 ### 🔒 安全性設定
| 變數 | 必要性 | 說明 | 預設值 | 範例 | | 變數 | 必要性 | 說明 | 預設值 | 範例 |
|------|--------|------|--------|------| | ----------------------- | -------- | ------------------ | ------------------ | ------------------------- |
| `JWT_SECRET` | **必須** | Token 驗證密鑰 | 隨機（每次重啟變） | `Xk9mPqL2vN7wR4tY6uI8...` | | `JWT_SECRET` | **必須** | Token 驗證密鑰 | 隨機（每次重啟變） | `Xk9mPqL2vN7wR4tY6uI8...` |
| `HTTP_ALLOWED` | 否 | 是否允許 HTTP 連線 | `false` | `true` / `false` | | `HTTP_ALLOWED` | 否 | 是否允許 HTTP 連線 | `false` | `true` / `false` |
| `TRUST_PROXY` | 否 | 是否信任反向代理 | `false` | `true` / `false` | | `TRUST_PROXY` | 否 | 是否信任反向代理 | `false` | `true` / `false` |
@ -31,7 +31,7 @@
### 🌐 一般設定 ### 🌐 一般設定
| 變數 | 必要性 | 說明 | 預設值 | 範例 | | 變數 | 必要性 | 說明 | 預設值 | 範例 |
|------|--------|------|--------|------| | -------------- | ------ | ------------ | ------- | ---------------- |
| `TZ` | 否 | 系統時區 | `UTC` | `Asia/Taipei` | | `TZ` | 否 | 系統時區 | `UTC` | `Asia/Taipei` |
| `LANGUAGE` | 否 | 介面語言 | `auto` | `zh-TW` | | `LANGUAGE` | 否 | 介面語言 | `auto` | `zh-TW` |
| `WEBROOT` | 否 | 子路徑前綴 | 空 | `/convertx` | | `WEBROOT` | 否 | 子路徑前綴 | 空 | `/convertx` |
@ -40,7 +40,7 @@
### ⚙️ 轉換設定 ### ⚙️ 轉換設定
| 變數 | 必要性 | 說明 | 預設值 | 範例 | | 變數 | 必要性 | 說明 | 預設值 | 範例 |
|------|--------|------|--------|------| | --------------------------- | ------ | -------------------- | ------------- | ----------------- |
| `AUTO_DELETE_EVERY_N_HOURS` | 否 | 自動刪除間隔（小時） | `24` | `12` | | `AUTO_DELETE_EVERY_N_HOURS` | 否 | 自動刪除間隔（小時） | `24` | `12` |
| `MAX_CONVERT_PROCESS` | 否 | 最大同時轉換數 | `0`（無限制） | `4` | | `MAX_CONVERT_PROCESS` | 否 | 最大同時轉換數 | `0`（無限制） | `4` |
| `FFMPEG_ARGS` | 否 | FFmpeg 輸入參數 | 空 | `-hwaccel cuda` | | `FFMPEG_ARGS` | 否 | FFmpeg 輸入參數 | 空 | `-hwaccel cuda` |
@ -49,7 +49,7 @@
### 📄 PDF 翻譯設定 ### 📄 PDF 翻譯設定
| 變數 | 必要性 | 說明 | 預設值 | 範例 | | 變數 | 必要性 | 說明 | 預設值 | 範例 |
|------|--------|------|--------|------| | ------------------------------ | ------ | -------- | --------- | ------------- |
| `PDFMATHTRANSLATE_SERVICE` | 否 | 翻譯服務 | `google` | `deepl` | | `PDFMATHTRANSLATE_SERVICE` | 否 | 翻譯服務 | `google` | `deepl` |
| `PDFMATHTRANSLATE_MODELS_PATH` | 否 | 模型路徑 | `/models` | `/app/models` | | `PDFMATHTRANSLATE_MODELS_PATH` | 否 | 模型路徑 | `/models` | `/app/models` |
@ -62,7 +62,7 @@
用於簽署登入驗證的密鑰，**強烈建議在正式環境中設定**。 用於簽署登入驗證的密鑰，**強烈建議在正式環境中設定**。
| 項目 | 說明 | | 項目 | 說明 |
|------|------| | ---------- | ---------------------- |
| **類型** | 字串 | | **類型** | 字串 |
| **預設值** | 每次重啟隨機產生 | | **預設值** | 每次重啟隨機產生 |
| **建議值** | 至少 32 字元的隨機字串 | | **建議值** | 至少 32 字元的隨機字串 |
@ -99,7 +99,7 @@ environment:
控制是否允許非 HTTPS 連線。 控制是否允許非 HTTPS 連線。
| 項目 | 說明 | | 項目 | 說明 |
|------|------| | ---------- | ---------------- |
| **類型** | 布林值 | | **類型** | 布林值 |
| **預設值** | `false` | | **預設值** | `false` |
| **可選值** | `true` / `false` | | **可選值** | `true` / `false` |
@ -107,7 +107,7 @@ environment:
**使用情境**： **使用情境**：
| 情境 | 建議設定 | | 情境 | 建議設定 |
|------|---------| | --------------------- | -------- |
| 本地測試 (localhost) | `true` | | 本地測試 (localhost) | `true` |
| 已設定 HTTPS | `false` | | 已設定 HTTPS | `false` |
| 無 HTTPS 但需遠端存取 | `true` | | 無 HTTPS 但需遠端存取 | `true` |
@ -121,10 +121,10 @@ environment:
### TRUST_PROXY ### TRUST_PROXY
控制是否信任反向代理的 X-Forwarded-* headers。 控制是否信任反向代理的 X-Forwarded-\* headers。
| 項目 | 說明 | | 項目 | 說明 |
|------|------| | ---------- | ---------------- |
| **類型** | 布林值 | | **類型** | 布林值 |
| **預設值** | `false` | | **預設值** | `false` |
| **可選值** | `true` / `false` | | **可選值** | `true` / `false` |
@ -132,7 +132,7 @@ environment:
**使用情境**： **使用情境**：
| 情境 | 建議設定 | | 情境 | 建議設定 |
|------|---------| | ---------------------------- | -------- |
| 直接存取容器 | `false` | | 直接存取容器 | `false` |
| 透過 Nginx / Traefik / Caddy | `true` | | 透過 Nginx / Traefik / Caddy | `true` |
@ -146,7 +146,7 @@ environment:
控制是否允許新使用者註冊。 控制是否允許新使用者註冊。
| 項目 | 說明 | | 項目 | 說明 |
|------|------| | ---------- | ---------------- |
| **類型** | 布林值 | | **類型** | 布林值 |
| **預設值** | `true` | | **預設值** | `true` |
| **可選值** | `true` / `false` | | **可選值** | `true` / `false` |
@ -161,7 +161,7 @@ environment:
控制是否允許未登入的匿名使用者使用轉換功能。 控制是否允許未登入的匿名使用者使用轉換功能。
| 項目 | 說明 | | 項目 | 說明 |
|------|------| | ---------- | ---------------- |
| **類型** | 布林值 | | **類型** | 布林值 |
| **預設值** | `false` | | **預設值** | `false` |
| **可選值** | `true` / `false` | | **可選值** | `true` / `false` |
@ -180,7 +180,7 @@ environment:
設定系統時區，影響日誌時間顯示與自動清理排程。 設定系統時區，影響日誌時間顯示與自動清理排程。
| 項目 | 說明 | | 項目 | 說明 |
|------|------| | ---------- | ------------------------------------------------------------------------ |
| **類型** | 時區字串 | | **類型** | 時區字串 |
| **預設值** | `UTC` | | **預設值** | `UTC` |
| **可選值** | [時區列表](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) | | **可選值** | [時區列表](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) |
@ -188,7 +188,7 @@ environment:
**常用時區**： **常用時區**：
| 地區 | 時區值 | | 地區 | 時區值 |
|------|--------| | -------- | ------------------ |
| 台灣 | `Asia/Taipei` | | 台灣 | `Asia/Taipei` |
| 香港 | `Asia/Hong_Kong` | | 香港 | `Asia/Hong_Kong` |
| 中國大陸 | `Asia/Shanghai` | | 中國大陸 | `Asia/Shanghai` |
@ -205,7 +205,7 @@ environment:
設定介面預設語言。 設定介面預設語言。
| 項目 | 說明 | | 項目 | 說明 |
|------|------| | ---------- | ------------------------------------- |
| **類型** | 語言代碼 | | **類型** | 語言代碼 |
| **預設值** | `auto`（自動偵測） | | **預設值** | `auto`（自動偵測） |
| **可選值** | `zh-TW`, `zh-CN`, `en`, `ja` 等 65 種 | | **可選值** | `zh-TW`, `zh-CN`, `en`, `ja` 等 65 種 |
@ -220,7 +220,7 @@ environment:
設定子路徑前綴，用於反向代理配置。 設定子路徑前綴，用於反向代理配置。
| 項目 | 說明 | | 項目 | 說明 |
|------|------| | ---------- | ------------ |
| **類型** | 路徑字串 | | **類型** | 路徑字串 |
| **預設值** | 空（根路徑） | | **預設值** | 空（根路徑） |
@ -234,7 +234,7 @@ environment:
控制是否隱藏轉換歷史紀錄。 控制是否隱藏轉換歷史紀錄。
| 項目 | 說明 | | 項目 | 說明 |
|------|------| | ---------- | ------- |
| **類型** | 布林值 | | **類型** | 布林值 |
| **預設值** | `false` | | **預設值** | `false` |
@ -252,7 +252,7 @@ environment:
設定自動刪除轉換檔案的間隔時間（小時）。 設定自動刪除轉換檔案的間隔時間（小時）。
| 項目 | 說明 | | 項目 | 說明 |
|------|------| | ------------ | ----------- |
| **類型** | 數字 | | **類型** | 數字 |
| **預設值** | `24` | | **預設值** | `24` |
| **建議範圍** | `1` - `168` | | **建議範圍** | `1` - `168` |
@ -267,7 +267,7 @@ environment:
設定最大同時轉換任務數量。 設定最大同時轉換任務數量。
| 項目 | 說明 | | 項目 | 說明 |
|------|------| | ---------- | ------------- |
| **類型** | 數字 | | **類型** | 數字 |
| **預設值** | `0`（無限制） | | **預設值** | `0`（無限制） |
| **建議值** | CPU 核心數 | | **建議值** | CPU 核心數 |
@ -282,7 +282,7 @@ environment:
設定 FFmpeg 的全域參數。 設定 FFmpeg 的全域參數。
| 變數 | 說明 | | 變數 | 說明 |
|------|------| | -------------------- | -------------------------- |
| `FFMPEG_ARGS` | 輸入參數（套用於輸入檔案） | | `FFMPEG_ARGS` | 輸入參數（套用於輸入檔案） |
| `FFMPEG_OUTPUT_ARGS` | 輸出參數（套用於輸出檔案） | | `FFMPEG_OUTPUT_ARGS` | 輸出參數（套用於輸出檔案） |
@ -304,7 +304,7 @@ environment:
設定 PDF 翻譯使用的服務。 設定 PDF 翻譯使用的服務。
| 項目 | 說明 | | 項目 | 說明 |
|------|------| | ---------- | ----------------------------- |
| **類型** | 字串 | | **類型** | 字串 |
| **預設值** | `google` | | **預設值** | `google` |
| **可選值** | `google`, `deepl`, `azure` 等 | | **可選值** | `google`, `deepl`, `azure` 等 |
@ -319,7 +319,7 @@ environment:
設定 PDF 翻譯模型的存放路徑。 設定 PDF 翻譯模型的存放路徑。
| 項目 | 說明 | | 項目 | 說明 |
|------|------| | ---------- | --------- |
| **類型** | 路徑字串 | | **類型** | 路徑字串 |
| **預設值** | `/models` | | **預設值** | `/models` |
@ -370,7 +370,7 @@ services:
deploy: deploy:
resources: resources:
limits: limits:
cpus: '4' cpus: "4"
memory: 8G memory: 8G
``` ```
@ -406,11 +406,13 @@ services:
- 不要使用範例中的值 - 不要使用範例中的值
2. **正式環境關閉 HTTP** 2. **正式環境關閉 HTTP**
```yaml ```yaml
- HTTP_ALLOWED=false - HTTP_ALLOWED=false
``` ```
3. **使用反向代理處理 HTTPS** 3. **使用反向代理處理 HTTPS**
```yaml ```yaml
- TRUST_PROXY=true - TRUST_PROXY=true
``` ```

30
docs/04-功能總覽.md
View file

@ -20,7 +20,7 @@ ConvertX-CN 內建 25+ 種轉換引擎，支援 1000+ 種檔案格式轉換。
## 轉換引擎總覽 ## 轉換引擎總覽
| 轉換器 | 用途 | 輸入格式數 | 輸出格式數 | | 轉換器 | 用途 | 輸入格式數 | 輸出格式數 |
|--------|------|-----------|-----------| | ---------------- | ------------- | ---------- | ---------- |
| FFmpeg | 影音 | 472 | 199 | | FFmpeg | 影音 | 472 | 199 |
| ImageMagick | 圖片 | 253 | 183 | | ImageMagick | 圖片 | 253 | 183 |
| GraphicsMagick | 圖片 | 167 | 130 | | GraphicsMagick | 圖片 | 167 | 130 |
@ -46,7 +46,7 @@ ConvertX-CN 內建 25+ 種轉換引擎，支援 1000+ 種檔案格式轉換。
**支援格式**： **支援格式**：
| 類型 | 輸入 | 輸出 | | 類型 | 輸入 | 輸出 |
|------|------|------| | ---- | ------------------------------------ | -------------------------- |
| 影片 | MP4, MKV, AVI, MOV, WebM, FLV 等 65+ | MP4, MKV, WebM, AVI 等 50+ | | 影片 | MP4, MKV, AVI, MOV, WebM, FLV 等 65+ | MP4, MKV, WebM, AVI 等 50+ |
| 音訊 | MP3, FLAC, WAV, AAC, OGG 等 120+ | MP3, FLAC, WAV, AAC 等 85+ | | 音訊 | MP3, FLAC, WAV, AAC, OGG 等 120+ | MP3, FLAC, WAV, AAC 等 85+ |
| 字幕 | SRT, ASS, VTT 等 25+ | SRT, ASS, VTT 等 12+ | | 字幕 | SRT, ASS, VTT 等 25+ | SRT, ASS, VTT 等 12+ |
@ -82,7 +82,7 @@ environment:
**支援格式**： **支援格式**：
| 類型 | 格式範例 | | 類型 | 格式範例 |
|------|---------| | --------- | -------------------------------- |
| 常見格式 | PNG, JPEG, GIF, WebP, AVIF, HEIC | | 常見格式 | PNG, JPEG, GIF, WebP, AVIF, HEIC |
| RAW 相機 | CR2, CR3, NEF, ARW, DNG | | RAW 相機 | CR2, CR3, NEF, ARW, DNG |
| 向量/文件 | PDF, PSD, AI, EPS, SVG | | 向量/文件 | PDF, PSD, AI, EPS, SVG |
@ -105,6 +105,7 @@ environment:
高效能圖片處理工具，適合大圖處理。 高效能圖片處理工具，適合大圖處理。
**特點**： **特點**：
- 記憶體使用效率高 - 記憶體使用效率高
- 處理速度快 - 處理速度快
- 適合批次處理 - 適合批次處理
@ -120,7 +121,7 @@ Office 文件轉換引擎。
**支援格式**： **支援格式**：
| 輸入 | 輸出 | | 輸入 | 輸出 |
|------|------| | -------------- | -------------- |
| DOC, DOCX, ODT | PDF, HTML, TXT | | DOC, DOCX, ODT | PDF, HTML, TXT |
| XLS, XLSX, ODS | PDF, CSV, HTML | | XLS, XLSX, ODS | PDF, CSV, HTML |
| PPT, PPTX, ODP | PDF, PNG, SVG | | PPT, PPTX, ODP | PDF, PNG, SVG |
@ -144,7 +145,7 @@ Office 文件轉換引擎。
**支援格式**： **支援格式**：
| 類型 | 格式 | | 類型 | 格式 |
|------|------| | -------- | ------------------------------------ |
| 標記語言 | Markdown, reStructuredText, AsciiDoc | | 標記語言 | Markdown, reStructuredText, AsciiDoc |
| 網頁 | HTML, EPUB | | 網頁 | HTML, EPUB |
| 排版 | LaTeX, PDF, DOCX | | 排版 | LaTeX, PDF, DOCX |
@ -171,12 +172,14 @@ Office 文件轉換引擎。
翻譯 PDF 並**保留數學公式與排版**。 翻譯 PDF 並**保留數學公式與排版**。
**特點**： **特點**：
- 保留原始排版 - 保留原始排版
- 保留數學公式 - 保留數學公式
- 保留圖表位置 - 保留圖表位置
- 支援多種翻譯引擎 - 支援多種翻譯引擎
**支援語言**： **支援語言**：
- 英文 ↔ 中文 - 英文 ↔ 中文
- 英文 ↔ 日文 - 英文 ↔ 日文
- 其他語言組合 - 其他語言組合
@ -193,6 +196,7 @@ Office 文件轉換引擎。
進階 PDF 翻譯與轉換引擎。 進階 PDF 翻譯與轉換引擎。
**特點**： **特點**：
- 高品質翻譯 - 高品質翻譯
- 支援複雜排版 - 支援複雜排版
- 多格式輸出 - 多格式輸出
@ -209,6 +213,7 @@ Office 文件轉換引擎。
**PDF 轉 Markdown**，智能擷取內容。 **PDF 轉 Markdown**，智能擷取內容。
**特點**： **特點**：
- 智能識別表格 - 智能識別表格
- 保留公式（轉為 LaTeX） - 保留公式（轉為 LaTeX）
- 擷取圖片 - 擷取圖片
@ -232,7 +237,7 @@ Office 文件轉換引擎。
根據研究顯示... 根據研究顯示...
| 項目 | 數值 | 說明 | | 項目 | 數值 | 說明 |
|------|------|------| | ---- | ---- | ---- |
| A | 100 | 描述 | | A | 100 | 描述 |
| B | 200 | 描述 | | B | 200 | 描述 |
@ -250,6 +255,7 @@ $$E = mc^2$$
為 PDF 添加 OCR 文字層，讓掃描 PDF 可搜尋。 為 PDF 添加 OCR 文字層，讓掃描 PDF 可搜尋。
**特點**： **特點**：
- 保留原始 PDF 外觀 - 保留原始 PDF 外觀
- 添加隱藏文字層 - 添加隱藏文字層
- 支援多語言辨識 - 支援多語言辨識
@ -257,7 +263,7 @@ $$E = mc^2$$
**支援語言（一般版）**： **支援語言（一般版）**：
| 語言 | 代碼 | | 語言 | 代碼 |
|------|------| | -------- | --------- |
| 繁體中文 | `chi_tra` | | 繁體中文 | `chi_tra` |
| 簡體中文 | `chi_sim` | | 簡體中文 | `chi_sim` |
| 英文 | `eng` | | 英文 | `eng` |
@ -286,7 +292,7 @@ $$E = mc^2$$
**支援格式**： **支援格式**：
| 輸入 | 輸出 | | 輸入 | 輸出 |
|------|------| | ---------------- | --------------- |
| EPUB, MOBI, AZW3 | EPUB, MOBI, PDF | | EPUB, MOBI, AZW3 | EPUB, MOBI, PDF |
| PDF, TXT, HTML | AZW3, DOCX, TXT | | PDF, TXT, HTML | AZW3, DOCX, TXT |
| CBZ, CBR (漫畫) | PDF, EPUB | | CBZ, CBR (漫畫) | PDF, EPUB |
@ -312,7 +318,7 @@ $$E = mc^2$$
向量圖形編輯與轉換。 向量圖形編輯與轉換。
| 輸入 | 輸出 | | 輸入 | 輸出 |
|------|------| | ------------ | ------------- |
| SVG, AI, EPS | PNG, PDF, EPS | | SVG, AI, EPS | PNG, PDF, EPS |
| PDF | SVG | | PDF | SVG |
@ -321,7 +327,7 @@ $$E = mc^2$$
3D 模型格式轉換。 3D 模型格式轉換。
| 輸入 | 輸出 | | 輸入 | 輸出 |
|------|------| | -------------- | -------------- |
| FBX, OBJ, GLTF | OBJ, STL, GLTF | | FBX, OBJ, GLTF | OBJ, STL, GLTF |
| 3DS, DAE | FBX, PLY | | 3DS, DAE | FBX, PLY |
@ -339,7 +345,7 @@ $$E = mc^2$$
資料檔案格式轉換。 資料檔案格式轉換。
| 輸入/輸出 | | 輸入/輸出 |
|-----------| | -------------------------- |
| JSON, YAML, TOML, XML, CSV | | JSON, YAML, TOML, XML, CSV |
``` ```
@ -352,7 +358,7 @@ $$E = mc^2$$
## 功能比較表 ## 功能比較表
| 功能 | Lite 版 | 一般版 | Full 版 | | 功能 | Lite 版 | 一般版 | Full 版 |
|------|---------|--------|---------| | ----------------- | ------- | ------ | ------- |
| FFmpeg 影音 | ✅ | ✅ | ✅ | | FFmpeg 影音 | ✅ | ✅ | ✅ |
| ImageMagick 圖片 | ✅ | ✅ | ✅ | | ImageMagick 圖片 | ✅ | ✅ | ✅ |
| LibreOffice 文件 | ✅ | ✅ | ✅ | | LibreOffice 文件 | ✅ | ✅ | ✅ |

42
docs/05-API文件.md
View file

@ -28,14 +28,14 @@ docker compose --profile api up -d
### 服務端口 ### 服務端口
| 服務 | 端口 | 說明 | | 服務 | 端口 | 說明 |
|------|------|------| | ---------- | ---- | -------------- |
| Web UI | 3000 | 網頁介面 | | Web UI | 3000 | 網頁介面 |
| API Server | 3001 | REST & GraphQL | | API Server | 3001 | REST & GraphQL |
### 環境變數 ### 環境變數
| 變數 | 說明 | 預設值 | | 變數 | 說明 | 預設值 |
|------|------|--------| | --------------- | --------------------- | ---------------- |
| `API_HOST` | 監聽地址 | `0.0.0.0` | | `API_HOST` | 監聽地址 | `0.0.0.0` |
| `API_PORT` | 監聽埠 | `3001` | | `API_PORT` | 監聽埠 | `3001` |
| `JWT_SECRET` | JWT 驗證密鑰 | （需自行設定） | | `JWT_SECRET` | JWT 驗證密鑰 | （需自行設定） |
@ -358,11 +358,7 @@ query {
```graphql ```graphql
mutation { mutation {
convert(input: { convert(input: { fileId: "abc123", outputFormat: "pdf", options: { quality: "high" } }) {
fileId: "abc123"
outputFormat: "pdf"
options: { quality: "high" }
}) {
jobId jobId
status status
} }
@ -376,7 +372,7 @@ mutation {
### HTTP 狀態碼 ### HTTP 狀態碼
| 狀態碼 | 說明 | 常見原因 | | 狀態碼 | 說明 | 常見原因 |
|--------|------|---------| | ------ | ---------- | -------------------- |
| 200 | 成功 | 請求正常處理 | | 200 | 成功 | 請求正常處理 |
| 400 | 錯誤請求 | 參數錯誤、格式不支援 | | 400 | 錯誤請求 | 參數錯誤、格式不支援 |
| 401 | 未授權 | Token 無效或過期 | | 401 | 未授權 | Token 無效或過期 |
@ -406,7 +402,7 @@ mutation {
### 常見錯誤碼 ### 常見錯誤碼
| 錯誤碼 | 說明 | 解決方法 | | 錯誤碼 | 說明 | 解決方法 |
|--------|------|---------| | -------------------- | ---------- | ------------------ |
| `INVALID_TOKEN` | Token 無效 | 重新取得有效 Token | | `INVALID_TOKEN` | Token 無效 | 重新取得有效 Token |
| `TOKEN_EXPIRED` | Token 過期 | 刷新 Token | | `TOKEN_EXPIRED` | Token 過期 | 刷新 Token |
| `FILE_NOT_FOUND` | 檔案不存在 | 確認檔案 ID 正確 | | `FILE_NOT_FOUND` | 檔案不存在 | 確認檔案 ID 正確 |
@ -494,29 +490,29 @@ with open("output.pdf", "wb") as f:
### JavaScript 範例 ### JavaScript 範例
```javascript ```javascript
const BASE_URL = 'http://localhost:3001/api/v1'; const BASE_URL = "http://localhost:3001/api/v1";
const TOKEN = 'your-jwt-token'; const TOKEN = "your-jwt-token";
async function convertFile(file, outputFormat) { async function convertFile(file, outputFormat) {
// 上傳檔案 // 上傳檔案
const formData = new FormData(); const formData = new FormData();
formData.append('file', file); formData.append("file", file);
const uploadResponse = await fetch(`${BASE_URL}/upload`, { const uploadResponse = await fetch(`${BASE_URL}/upload`, {
method: 'POST', method: "POST",
headers: { 'Authorization': `Bearer ${TOKEN}` }, headers: { Authorization: `Bearer ${TOKEN}` },
body: formData body: formData,
}); });
const { fileId } = await uploadResponse.json(); const { fileId } = await uploadResponse.json();
// 開始轉換 // 開始轉換
const convertResponse = await fetch(`${BASE_URL}/convert`, { const convertResponse = await fetch(`${BASE_URL}/convert`, {
method: 'POST', method: "POST",
headers: { headers: {
'Authorization': `Bearer ${TOKEN}`, Authorization: `Bearer ${TOKEN}`,
'Content-Type': 'application/json' "Content-Type": "application/json",
}, },
body: JSON.stringify({ fileId, outputFormat }) body: JSON.stringify({ fileId, outputFormat }),
}); });
const { jobId } = await convertResponse.json(); const { jobId } = await convertResponse.json();
@ -524,19 +520,19 @@ async function convertFile(file, outputFormat) {
let result; let result;
while (true) { while (true) {
const statusResponse = await fetch(`${BASE_URL}/jobs/${jobId}`, { const statusResponse = await fetch(`${BASE_URL}/jobs/${jobId}`, {
headers: { 'Authorization': `Bearer ${TOKEN}` } headers: { Authorization: `Bearer ${TOKEN}` },
}); });
const job = await statusResponse.json(); const job = await statusResponse.json();
if (job.status === 'completed') { if (job.status === "completed") {
result = job.result; result = job.result;
break; break;
} }
await new Promise(resolve => setTimeout(resolve, 2000)); await new Promise((resolve) => setTimeout(resolve, 2000));
} }
// 下載結果 // 下載結果
const downloadResponse = await fetch(`${BASE_URL}/download/${result.fileId}`, { const downloadResponse = await fetch(`${BASE_URL}/download/${result.fileId}`, {
headers: { 'Authorization': `Bearer ${TOKEN}` } headers: { Authorization: `Bearer ${TOKEN}` },
}); });
return await downloadResponse.blob(); return await downloadResponse.blob();
} }

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

@ -19,7 +19,7 @@
## 常見問題速查 ## 常見問題速查
| 問題 | 可能原因 | 快速解決 | | 問題 | 可能原因 | 快速解決 |
|------|---------|---------| | ------------------ | ---------------------- | ---------------------------------------------- |
| 登入後被踢回登入頁 | HTTP/HTTPS 設定不正確 | 加上 `HTTP_ALLOWED=true` 或 `TRUST_PROXY=true` | | 登入後被踢回登入頁 | HTTP/HTTPS 設定不正確 | 加上 `HTTP_ALLOWED=true` 或 `TRUST_PROXY=true` |
| 重啟後資料消失 | Volume 未正確掛載 | 確認 `./data:/app/data` 且資料夾存在 | | 重啟後資料消失 | Volume 未正確掛載 | 確認 `./data:/app/data` 且資料夾存在 |
| 重啟後被登出 | JWT_SECRET 未固定 | 設定固定的 `JWT_SECRET` | | 重啟後被登出 | JWT_SECRET 未固定 | 設定固定的 `JWT_SECRET` |
@ -34,6 +34,7 @@
### 問題：登入後又被導回登入頁 ### 問題：登入後又被導回登入頁
**症狀**： **症狀**：
- 輸入帳密後頁面閃一下又回到登入頁 - 輸入帳密後頁面閃一下又回到登入頁
- Cookie 無法正確設定 - Cookie 無法正確設定
@ -56,6 +57,7 @@
3. **反向代理未正確傳遞 headers** 3. **反向代理未正確傳遞 headers**
Nginx 設定需包含： Nginx 設定需包含：
```nginx ```nginx
proxy_set_header X-Forwarded-Proto $scheme; proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
@ -64,6 +66,7 @@
### 問題：重啟容器後需要重新登入 ### 問題：重啟容器後需要重新登入
**症狀**： **症狀**：
- 每次重啟容器後所有使用者都需要重新登入 - 每次重啟容器後所有使用者都需要重新登入
**原因**：JWT_SECRET 未固定，每次啟動會產生新的隨機密鑰。 **原因**：JWT_SECRET 未固定，每次啟動會產生新的隨機密鑰。
@ -84,6 +87,7 @@ openssl rand -hex 32
### 問題：無法註冊新帳號 ### 問題：無法註冊新帳號
**症狀**： **症狀**：
- 找不到註冊按鈕 - 找不到註冊按鈕
- 註冊時顯示錯誤 - 註冊時顯示錯誤
@ -137,6 +141,7 @@ environment:
1. **確認版本**：Lite 版不支援 PDF 翻譯 1. **確認版本**：Lite 版不支援 PDF 翻譯
2. **確認設定**： 2. **確認設定**：
```yaml ```yaml
environment: environment:
- PDFMATHTRANSLATE_SERVICE=google - PDFMATHTRANSLATE_SERVICE=google
@ -155,17 +160,19 @@ environment:
**解決方案**： **解決方案**：
1. **限制同時轉換數**： 1. **限制同時轉換數**：
```yaml ```yaml
environment: environment:
- MAX_CONVERT_PROCESS=4 - MAX_CONVERT_PROCESS=4
``` ```
2. **增加資源限制**： 2. **增加資源限制**：
```yaml ```yaml
deploy: deploy:
resources: resources:
limits: limits:
cpus: '4' cpus: "4"
memory: 8G memory: 8G
``` ```
@ -185,11 +192,13 @@ environment:
**排查步驟**： **排查步驟**：
1. **檢查日誌**： 1. **檢查日誌**：
```bash ```bash
docker logs convertx-cn docker logs convertx-cn
``` ```
2. **檢查端口佔用**： 2. **檢查端口佔用**：
```bash ```bash
# Linux / macOS # Linux / macOS
lsof -i :3000 lsof -i :3000
@ -199,6 +208,7 @@ environment:
``` ```
3. **檢查磁碟空間**： 3. **檢查磁碟空間**：
```bash ```bash
docker system df docker system df
``` ```
@ -238,6 +248,7 @@ mkdir -p ./data
1. **檢查網路連線** 1. **檢查網路連線**
2. **使用鏡像站**（中國大陸）： 2. **使用鏡像站**（中國大陸）：
```bash ```bash
docker pull registry.cn-hangzhou.aliyuncs.com/convertx/convertx-cn:latest docker pull registry.cn-hangzhou.aliyuncs.com/convertx/convertx-cn:latest
``` ```
@ -272,6 +283,7 @@ environment:
### 診斷效能問題 ### 診斷效能問題
1. **查看系統資源使用**： 1. **查看系統資源使用**：
```bash ```bash
docker stats convertx-cn docker stats convertx-cn
``` ```
@ -284,7 +296,7 @@ environment:
### 效能優化建議 ### 效能優化建議
| 問題 | 解決方案 | | 問題 | 解決方案 |
|------|---------| | ------------ | -------------------------- |
| CPU 使用率高 | 限制 `MAX_CONVERT_PROCESS` | | CPU 使用率高 | 限制 `MAX_CONVERT_PROCESS` |
| 記憶體不足 | 增加容器記憶體限制 | | 記憶體不足 | 增加容器記憶體限制 |
| 磁碟 I/O 慢 | 使用 SSD，增加 Volume 效能 | | 磁碟 I/O 慢 | 使用 SSD，增加 Volume 效能 |
@ -293,7 +305,7 @@ environment:
### 推薦硬體配置 ### 推薦硬體配置
| 用途 | CPU | 記憶體 | 磁碟 | | 用途 | CPU | 記憶體 | 磁碟 |
|------|-----|--------|------| | -------- | ---- | ------ | ---------- |
| 個人使用 | 2 核 | 4 GB | 20 GB | | 個人使用 | 2 核 | 4 GB | 20 GB |
| 小團隊 | 4 核 | 8 GB | 50 GB | | 小團隊 | 4 核 | 8 GB | 50 GB |
| 生產環境 | 8 核 | 16 GB | 100 GB SSD | | 生產環境 | 8 核 | 16 GB | 100 GB SSD |
@ -318,7 +330,7 @@ docker logs --since "2026-01-25T00:00:00" convertx-cn
### 日誌等級 ### 日誌等級
| 等級 | 說明 | | 等級 | 說明 |
|------|------| | ------- | ---------------- |
| `ERROR` | 錯誤，需要處理 | | `ERROR` | 錯誤，需要處理 |
| `WARN` | 警告，可能有問題 | | `WARN` | 警告，可能有問題 |
| `INFO` | 一般資訊 | | `INFO` | 一般資訊 |
@ -327,7 +339,7 @@ docker logs --since "2026-01-25T00:00:00" convertx-cn
### 常見日誌訊息 ### 常見日誌訊息
| 訊息 | 說明 | | 訊息 | 說明 |
|------|------| | ---------------------------- | ------------ |
| `🦊 Elysia is running at...` | 服務正常啟動 | | `🦊 Elysia is running at...` | 服務正常啟動 |
| `Conversion started...` | 開始轉換 | | `Conversion started...` | 開始轉換 |
| `Conversion completed...` | 轉換完成 | | `Conversion completed...` | 轉換完成 |
@ -375,32 +387,39 @@ docker logs convertx-cn 2>&1 | gzip > convertx-logs.gz
### Issue 範本 ### Issue 範本
```markdown ````markdown
## 環境 ## 環境
- ConvertX-CN 版本：`latest` - ConvertX-CN 版本：`latest`
- Docker 版本：`24.0.5` - Docker 版本：`24.0.5`
- 作業系統：Ubuntu 22.04 - 作業系統：Ubuntu 22.04
## 問題描述 ## 問題描述
登入後被踢回登入頁。 登入後被踢回登入頁。
## 重現步驟 ## 重現步驟
1. 訪問 http://localhost:3000 1. 訪問 http://localhost:3000
2. 輸入帳號密碼 2. 輸入帳號密碼
3. 點擊登入 3. 點擊登入
4. 頁面閃一下後回到登入頁 4. 頁面閃一下後回到登入頁
## 環境變數 ## 環境變數
```yaml ```yaml
environment: environment:
- TZ=Asia/Taipei - TZ=Asia/Taipei
- JWT_SECRET=**** - JWT_SECRET=****
``` ```
````
## 日誌 ## 日誌
``` ```
[相關日誌內容] [相關日誌內容]
``` ```
``` ```
### 聯繫方式 ### 聯繫方式
@ -413,3 +432,4 @@ environment:
--- ---
[⬆️ 回到頂部](#錯誤排查與支援) | [📚 回到目錄](00-專案總覽.md) [⬆️ 回到頂部](#錯誤排查與支援) | [📚 回到目錄](00-專案總覽.md)
```

44
docs/07-開發與貢獻指南.md
View file

@ -75,7 +75,7 @@ ConvertX-CN/
### 前端 / Web Server ### 前端 / Web Server
| 技術 | 用途 | | 技術 | 用途 |
|------|------| | ----------- | ------------------ |
| Bun | JavaScript Runtime | | Bun | JavaScript Runtime |
| Elysia | Web 框架 | | Elysia | Web 框架 |
| React | UI 元件 | | React | UI 元件 |
@ -86,7 +86,7 @@ ConvertX-CN/
### API Server（選用） ### API Server（選用）
| 技術 | 用途 | | 技術 | 用途 |
|------|------| | ------------- | ------------ |
| Rust | 語言 | | Rust | 語言 |
| Axum | Web 框架 | | Axum | Web 框架 |
| async-graphql | GraphQL | | async-graphql | GraphQL |
@ -134,7 +134,7 @@ ConvertX-CN/
### 開發指令 ### 開發指令
| 指令 | 說明 | | 指令 | 說明 |
|------|------| | ------------ | ------------------------ |
| `bun dev` | 啟動開發伺服器（熱重載） | | `bun dev` | 啟動開發伺服器（熱重載） |
| `bun build` | 建構生產版本 | | `bun build` | 建構生產版本 |
| `bun test` | 執行測試 | | `bun test` | 執行測試 |
@ -155,7 +155,7 @@ cargo run
### 主要分支 ### 主要分支
| 分支 | 用途 | | 分支 | 用途 |
|------|------| | --------- | ------------------ |
| `main` | 穩定版本，用於發布 | | `main` | 穩定版本，用於發布 |
| `develop` | 開發分支，接受 PR | | `develop` | 開發分支，接受 PR |
@ -172,7 +172,7 @@ git checkout -b feature/your-feature-name
### 分支命名規範 ### 分支命名規範
| 類型 | 格式 | 範例 | | 類型 | 格式 | 範例 |
|------|------|------| | ---- | --------------- | --------------------------------- |
| 功能 | `feature/描述` | `feature/add-pdf-watermark` | | 功能 | `feature/描述` | `feature/add-pdf-watermark` |
| 修復 | `fix/描述` | `fix/login-redirect-issue` | | 修復 | `fix/描述` | `fix/login-redirect-issue` |
| 文件 | `docs/描述` | `docs/update-api-docs` | | 文件 | `docs/描述` | `docs/update-api-docs` |
@ -185,7 +185,7 @@ git checkout -b feature/your-feature-name
### 測試類型 ### 測試類型
| 類型 | 位置 | 說明 | | 類型 | 位置 | 說明 |
|------|------|------| | -------- | ------------------- | ------------ |
| 單元測試 | `tests/` | 測試個別函數 | | 單元測試 | `tests/` | 測試個別函數 |
| 整合測試 | `tests/converters/` | 測試轉換器 | | 整合測試 | `tests/converters/` | 測試轉換器 |
| E2E 測試 | `tests/e2e/` | 端對端測試 | | E2E 測試 | `tests/e2e/` | 端對端測試 |
@ -215,12 +215,12 @@ bun test --coverage
```typescript ```typescript
// tests/converters/ffmpeg.test.ts // tests/converters/ffmpeg.test.ts
import { describe, it, expect } from 'bun:test'; import { describe, it, expect } from "bun:test";
import { convertVideo } from '@/converters/ffmpeg'; import { convertVideo } from "@/converters/ffmpeg";
describe('FFmpeg Converter', () => { describe("FFmpeg Converter", () => {
it('should convert MP4 to WebM', async () => { it("should convert MP4 to WebM", async () => {
const result = await convertVideo('input.mp4', 'webm'); const result = await convertVideo("input.mp4", "webm");
expect(result.success).toBe(true); expect(result.success).toBe(true);
}); });
}); });
@ -243,7 +243,7 @@ describe('FFmpeg Converter', () => {
### Type 類型 ### Type 類型
| Type | 說明 | | Type | 說明 |
|------|------| | ---------- | ------------------------ |
| `feat` | 新功能 | | `feat` | 新功能 |
| `fix` | 修復 Bug | | `fix` | 修復 Bug |
| `docs` | 文件更新 | | `docs` | 文件更新 |
@ -303,9 +303,11 @@ bun format
```markdown ```markdown
## 變更描述 ## 變更描述
簡述這個 PR 做了什麼。 簡述這個 PR 做了什麼。
## 變更類型 ## 變更類型
- [ ] 新功能 - [ ] 新功能
- [ ] Bug 修復 - [ ] Bug 修復
- [ ] 文件更新 - [ ] 文件更新
@ -313,9 +315,11 @@ bun format
- [ ] 其他 - [ ] 其他
## 測試 ## 測試
描述如何測試這些變更。 描述如何測試這些變更。
## 相關 Issue ## 相關 Issue
Closes #123 Closes #123
## 截圖（如適用） ## 截圖（如適用）
@ -358,8 +362,8 @@ bun format
```typescript ```typescript
// ✅ 正確 // ✅ 正確
const formatConverter = (name: string): string => { const formatConverter = (name: string): string => {
return name.toLowerCase() return name.toLowerCase();
} };
// ❌ 錯誤 // ❌ 錯誤
function formatConverter(name) { function formatConverter(name) {
@ -388,16 +392,16 @@ cargo clippy
```typescript ```typescript
// src/converters/myconverter.ts // src/converters/myconverter.ts
import { Converter } from './types' import { Converter } from "./types";
export const myConverter: Converter = { export const myConverter: Converter = {
name: 'myconverter', name: "myconverter",
inputFormats: ['xyz', 'abc'], inputFormats: ["xyz", "abc"],
outputFormats: ['pdf', 'png'], outputFormats: ["pdf", "png"],
convert: async (input, output, options) => { convert: async (input, output, options) => {
// 轉換邏輯 // 轉換邏輯
} },
} };
``` ```
3. 在 `src/converters/main.ts` 註冊 3. 在 `src/converters/main.ts` 註冊

15
docs/08-授權說明.md
View file

@ -17,7 +17,7 @@ ConvertX-CN 專案採用 **GNU Affero General Public License v3.0 (AGPL-3.0)**
## 授權摘要 ## 授權摘要
| 項目 | 說明 | | 項目 | 說明 |
|------|------| | ------------ | --------------------- |
| **授權類型** | AGPL-3.0 | | **授權類型** | AGPL-3.0 |
| **授權檔案** | [LICENSE](../LICENSE) | | **授權檔案** | [LICENSE](../LICENSE) |
| **適用範圍** | 整個專案所有程式碼 | | **適用範圍** | 整個專案所有程式碼 |
@ -53,6 +53,7 @@ ConvertX-CN 專案採用 **GNU Affero General Public License v3.0 (AGPL-3.0)**
### 📋 保留授權聲明 ### 📋 保留授權聲明
分發時必須包含： 分發時必須包含：
- 原始授權聲明 - 原始授權聲明
- 著作權聲明 - 著作權聲明
- 完整的 AGPL-3.0 授權文字 - 完整的 AGPL-3.0 授權文字
@ -60,6 +61,7 @@ ConvertX-CN 專案採用 **GNU Affero General Public License v3.0 (AGPL-3.0)**
### 📋 公開原始碼 ### 📋 公開原始碼
如果您修改了程式碼： 如果您修改了程式碼：
- 必須公開修改後的原始碼 - 必須公開修改後的原始碼
- 必須使用相同的 AGPL-3.0 授權 - 必須使用相同的 AGPL-3.0 授權
@ -68,12 +70,14 @@ ConvertX-CN 專案採用 **GNU Affero General Public License v3.0 (AGPL-3.0)**
**這是 AGPL 與 GPL 的主要差異：** **這是 AGPL 與 GPL 的主要差異：**
如果您將修改後的版本部署為網路服務（如 SaaS），您必須： 如果您將修改後的版本部署為網路服務（如 SaaS），您必須：
- 向服務使用者提供取得原始碼的方式 - 向服務使用者提供取得原始碼的方式
- 原始碼必須包含您的所有修改 - 原始碼必須包含您的所有修改
### 📋 標明變更 ### 📋 標明變更
如果您修改了程式碼： 如果您修改了程式碼：
- 必須標明您做了哪些修改 - 必須標明您做了哪些修改
- 必須標明修改日期 - 必須標明修改日期
@ -88,6 +92,7 @@ ConvertX-CN 專案採用 **GNU Affero General Public License v3.0 (AGPL-3.0)**
### Q: 我修改了程式碼後部署在公司內部，需要公開嗎？ ### Q: 我修改了程式碼後部署在公司內部，需要公開嗎？
**A: 視情況而定** **A: 視情況而定**
- 如果只有公司內部員工使用 → 不需要公開 - 如果只有公司內部員工使用 → 不需要公開
- 如果對外提供服務（客戶可存取）→ 需要公開 - 如果對外提供服務（客戶可存取）→ 需要公開
@ -102,6 +107,7 @@ ConvertX-CN 專案採用 **GNU Affero General Public License v3.0 (AGPL-3.0)**
### Q: 如果我將 ConvertX-CN 作為 SaaS 服務提供，需要做什麼？ ### Q: 如果我將 ConvertX-CN 作為 SaaS 服務提供，需要做什麼？
**A: 您需要**： **A: 您需要**：
1. 在服務中提供原始碼下載連結 1. 在服務中提供原始碼下載連結
2. 包含您對程式碼的所有修改 2. 包含您對程式碼的所有修改
3. 使用 AGPL-3.0 授權 3. 使用 AGPL-3.0 授權
@ -115,13 +121,13 @@ ConvertX-CN 使用了多個第三方開源元件，各元件的授權如下：
### 上游專案 ### 上游專案
| 專案 | 授權 | | 專案 | 授權 |
|------|------| | ----------------------------------------------- | -------- |
| [ConvertX](https://github.com/C4illin/ConvertX) | AGPL-3.0 | | [ConvertX](https://github.com/C4illin/ConvertX) | AGPL-3.0 |
### 轉換引擎 ### 轉換引擎
| 元件 | 授權 | | 元件 | 授權 |
|------|------| | ------------- | ---------- |
| FFmpeg | LGPL / GPL | | FFmpeg | LGPL / GPL |
| ImageMagick | Apache 2.0 | | ImageMagick | Apache 2.0 |
| LibreOffice | MPL 2.0 | | LibreOffice | MPL 2.0 |
@ -132,7 +138,7 @@ ConvertX-CN 使用了多個第三方開源元件，各元件的授權如下：
### 框架與函式庫 ### 框架與函式庫
| 元件 | 授權 | | 元件 | 授權 |
|------|------| | ----------- | ---- |
| Bun | MIT | | Bun | MIT |
| Elysia | MIT | | Elysia | MIT |
| React | MIT | | React | MIT |
@ -145,6 +151,7 @@ ConvertX-CN 使用了多個第三方開源元件，各元件的授權如下：
完整的 AGPL-3.0 授權文字請參閱專案根目錄的 [LICENSE](../LICENSE) 檔案。 完整的 AGPL-3.0 授權文字請參閱專案根目錄的 [LICENSE](../LICENSE) 檔案。
您也可以在以下網址查看： 您也可以在以下網址查看：
- [GNU AGPL-3.0 官方網站](https://www.gnu.org/licenses/agpl-3.0.html) - [GNU AGPL-3.0 官方網站](https://www.gnu.org/licenses/agpl-3.0.html)
- [AGPL-3.0 中文翻譯](https://www.gnu.org/licenses/agpl-3.0.zh-cn.html) - [AGPL-3.0 中文翻譯](https://www.gnu.org/licenses/agpl-3.0.zh-cn.html)

8
docs/說明文件.md
View file

@ -7,7 +7,7 @@
## 📚 文件目錄 ## 📚 文件目錄
| 章節 | 說明 | | 章節 | 說明 |
|------|------| | ----------------------------------------- | ---------------------------- |
| [00-專案總覽](00-專案總覽.md) | 專案定位、功能特色、版本比較 | | [00-專案總覽](00-專案總覽.md) | 專案定位、功能特色、版本比較 |
| [01-快速開始](01-快速開始.md) | 5 分鐘部署完成 | | [01-快速開始](01-快速開始.md) | 5 分鐘部署完成 |
| [02-部署指南](02-部署指南.md) | Docker 設定、反向代理、HTTPS | | [02-部署指南](02-部署指南.md) | Docker 設定、反向代理、HTTPS |
@ -37,7 +37,7 @@
### 部署相關 ### 部署相關
| 文件 | 說明 | | 文件 | 說明 |
|------|------| | -------------------------------------------- | ----------------------- |
| [部署指南/Docker.md](部署指南/Docker.md) | Docker 部署詳細說明 | | [部署指南/Docker.md](部署指南/Docker.md) | Docker 部署詳細說明 |
| [部署指南/反向代理.md](部署指南/反向代理.md) | Nginx / Traefik / Caddy | | [部署指南/反向代理.md](部署指南/反向代理.md) | Nginx / Traefik / Caddy |
| [範例配置/說明文件.md](範例配置/說明文件.md) | 可直接使用的配置檔 | | [範例配置/說明文件.md](範例配置/說明文件.md) | 可直接使用的配置檔 |
@ -45,7 +45,7 @@
### 功能說明 ### 功能說明
| 文件 | 說明 | | 文件 | 說明 |
|------|------| | -------------------------------------------- | ------------------ |
| [功能說明/轉換器.md](功能說明/轉換器.md) | 所有轉換器詳細資訊 | | [功能說明/轉換器.md](功能說明/轉換器.md) | 所有轉換器詳細資訊 |
| [功能說明/OCR.md](功能說明/OCR.md) | OCR 功能說明 | | [功能說明/OCR.md](功能說明/OCR.md) | OCR 功能說明 |
| [功能說明/翻譯功能.md](功能說明/翻譯功能.md) | PDF 翻譯功能 | | [功能說明/翻譯功能.md](功能說明/翻譯功能.md) | PDF 翻譯功能 |
@ -53,7 +53,7 @@
### 開發相關 ### 開發相關
| 文件 | 說明 | | 文件 | 說明 |
|------|------| | -------------------------------------------- | -------------- |
| [開發指南/專案結構.md](開發指南/專案結構.md) | 程式碼結構說明 | | [開發指南/專案結構.md](開發指南/專案結構.md) | 程式碼結構說明 |
| [開發指南/貢獻指南.md](開發指南/貢獻指南.md) | 如何參與專案 | | [開發指南/貢獻指南.md](開發指南/貢獻指南.md) | 如何參與專案 |
| [API/總覽.md](API/總覽.md) | API 詳細說明 | | [API/總覽.md](API/總覽.md) | API 詳細說明 |