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

30
README.md
View file

@ -28,17 +28,17 @@
完整文件請參閱 **[專案總覽](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) |
| ⚙️ **03 環境變數** | 所有可用設定與推薦值 | [查看](docs/03-環境變數與設定.md) | | ⚙️ **03 環境變數** | 所有可用設定與推薦值 | [查看](docs/03-環境變數與設定.md) |
| 🔌 **04 功能總覽** | 轉換器、OCR、PDF 翻譯 | [查看](docs/04-功能總覽.md) | | 🔌 **04 功能總覽** | 轉換器、OCR、PDF 翻譯 | [查看](docs/04-功能總覽.md) |
| 🔗 **05 API 文件** | REST & GraphQL API | [查看](docs/05-API文件.md) | | 🔗 **05 API 文件** | REST & GraphQL API | [查看](docs/05-API文件.md) |
| 🔧 **06 錯誤排查** | 常見問題與解決方案 | [查看](docs/06-錯誤排查與支援.md) | | 🔧 **06 錯誤排查** | 常見問題與解決方案 | [查看](docs/06-錯誤排查與支援.md) |
| 👩‍💻 **07 開發指南** | 專案結構、貢獻規範 | [查看](docs/07-開發與貢獻指南.md) | | 👩‍💻 **07 開發指南** | 專案結構、貢獻規範 | [查看](docs/07-開發與貢獻指南.md) |
| 📄 **08 授權說明** | AGPL-3.0 授權 | [查看](docs/08-授權說明.md) | | 📄 **08 授權說明** | AGPL-3.0 授權 | [查看](docs/08-授權說明.md) |
--- ---
@ -202,11 +202,11 @@ docker run -d \
### 授權摘要 ### 授權摘要
| 權利 | 說明 | | 權利 | 說明 |
|------|------| | ----------- | ------------------------ |
| ✅ 自由使用 | 個人、商業、教育用途均可 | | ✅ 自由使用 | 個人、商業、教育用途均可 |
| ✅ 自由修改 | 可修改原始碼 | | ✅ 自由修改 | 可修改原始碼 |
| ✅ 自由分發 | 可重新分發 | | ✅ 自由分發 | 可重新分發 |
### 義務 ### 義務

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

@ -25,29 +25,29 @@ ConvertX-CN 是一個**開箱即用的全功能檔案轉換服務**，基於 [C4
### 🌟 專案特色 ### 🌟 專案特色
| 特色 | 說明 | | 特色 | 說明 |
|------|------| | ----------------- | --------------------------------------- |
| 📁 **1000+ 格式** | 文件、圖片、影音、電子書一次搞定 | | 📁 **1000+ 格式** | 文件、圖片、影音、電子書一次搞定 |
| 🔧 **25+ 引擎** | LibreOffice、FFmpeg、Pandoc 全到位 | | 🔧 **25+ 引擎** | LibreOffice、FFmpeg、Pandoc 全到位 |
| 🈶 **中文優化** | 內建中日韓字型與 OCR，告別亂碼 | | 🈶 **中文優化** | 內建中日韓字型與 OCR，告別亂碼 |
| 🌐 **65 種語言** | 跨國團隊無障礙使用 | | 🌐 **65 種語言** | 跨國團隊無障礙使用 |
| 📊 **PDF 翻譯** | PDFMathTranslate + BabelDOC 雙引擎 | | 📊 **PDF 翻譯** | PDFMathTranslate + BabelDOC 雙引擎 |
| 📄 **PDF 轉 MD** | MinerU 智能擷取（保留表格、公式、圖片） | | 📄 **PDF 轉 MD** | MinerU 智能擷取（保留表格、公式、圖片） |
--- ---
## ConvertX-CN 與原始 ConvertX 的差異 ## ConvertX-CN 與原始 ConvertX 的差異
| 項目 | 原始 ConvertX | ConvertX-CN | | 項目 | 原始 ConvertX | ConvertX-CN |
|------|--------------|-------------| | --------------- | ------------- | ---------------------------------- |
| **語言支援** | 英文介面為主 | 65 種語言介面，中文優化 | | **語言支援** | 英文介面為主 | 65 種語言介面，中文優化 |
| **字型支援** | 基本字型 | 內建中日韓完整字型集 | | **字型支援** | 基本字型 | 內建中日韓完整字型集 |
| **OCR 語言** | 需手動安裝 | 預裝 7 種常用語言（Full 版 65 種） | | **OCR 語言** | 需手動安裝 | 預裝 7 種常用語言（Full 版 65 種） |
| **PDF 翻譯** | ❌ 不支援 | ✅ PDFMathTranslate + BabelDOC | | **PDF 翻譯** | ❌ 不支援 | ✅ PDFMathTranslate + BabelDOC |
| **PDF 轉 MD** | ❌ 不支援 | ✅ MinerU 智能擷取 | | **PDF 轉 MD** | ❌ 不支援 | ✅ MinerU 智能擷取 |
| **BabelDOC** | ❌ 不支援 | ✅ 進階 PDF 處理 | | **BabelDOC** | ❌ 不支援 | ✅ 進階 PDF 處理 |
| **Docker 大小** | 較小 | 較大（功能更完整） | | **Docker 大小** | 較小 | 較大（功能更完整） |
| **維護者** | C4illin | pi-docket | | **維護者** | C4illin | pi-docket |
### 新增功能清單 ### 新增功能清單
@ -64,46 +64,46 @@ ConvertX-CN 是一個**開箱即用的全功能檔案轉換服務**，基於 [C4
### 按類型分類 ### 按類型分類
| 類型 | 轉換器 | 支援格式數 | | 類型 | 轉換器 | 支援格式數 |
|------|--------|-----------| | --------------- | -------------------------------------------- | ---------- |
| 🎬 **影音** | FFmpeg | 400+ | | 🎬 **影音** | FFmpeg | 400+ |
| 🖼️ **圖片** | ImageMagick, GraphicsMagick, Vips | 300+ | | 🖼️ **圖片** | ImageMagick, GraphicsMagick, Vips | 300+ |
| 📄 **文件** | LibreOffice, Pandoc | 160+ | | 📄 **文件** | LibreOffice, Pandoc | 160+ |
| 📚 **電子書** | Calibre | 50+ | | 📚 **電子書** | Calibre | 50+ |
| ✏️ **向量圖** | Inkscape, Potrace, VTracer | 40+ | | ✏️ **向量圖** | Inkscape, Potrace, VTracer | 40+ |
| 📊 **PDF 處理** | PDFMathTranslate, BabelDOC, MinerU, OCRmyPDF | 30+ | | 📊 **PDF 處理** | PDFMathTranslate, BabelDOC, MinerU, OCRmyPDF | 30+ |
| 🎮 **3D 模型** | Assimp | 100+ | | 🎮 **3D 模型** | Assimp | 100+ |
| 📋 **資料檔案** | Dasel | 10+ | | 📋 **資料檔案** | Dasel | 10+ |
### 完整轉換器列表 ### 完整轉換器列表
| 轉換器 | 用途 | 輸入格式 | 輸出格式 | | 轉換器 | 用途 | 輸入格式 | 輸出格式 |
|--------|------|----------|----------| | ---------------- | ------------ | -------- | -------- |
| FFmpeg | 影音 | 472 | 199 | | FFmpeg | 影音 | 472 | 199 |
| ImageMagick | 圖片 | 253 | 183 | | ImageMagick | 圖片 | 253 | 183 |
| GraphicsMagick | 圖片 | 167 | 130 | | GraphicsMagick | 圖片 | 167 | 130 |
| Vips | 高效圖片處理 | 45 | 23 | | Vips | 高效圖片處理 | 45 | 23 |
| LibreOffice | 文件 | 41 | 22 | | LibreOffice | 文件 | 41 | 22 |
| Pandoc | 文件 | 43 | 65 | | Pandoc | 文件 | 43 | 65 |
| Calibre | 電子書 | 31 | 21 | | Calibre | 電子書 | 31 | 21 |
| Inkscape | 向量圖形 | 7 | 17 | | Inkscape | 向量圖形 | 7 | 17 |
| libjxl | JPEG XL | 11 | 11 | | libjxl | JPEG XL | 11 | 11 |
| libheif | HEIF/HEIC | 11 | 3 | | libheif | HEIF/HEIC | 11 | 3 |
| Assimp | 3D 模型 | 77 | 23 | | Assimp | 3D 模型 | 77 | 23 |
| Potrace | 點陣轉向量 | 4 | 11 | | Potrace | 點陣轉向量 | 4 | 11 |
| VTracer | 點陣轉向量 | 8 | 1 | | VTracer | 點陣轉向量 | 8 | 1 |
| resvg | SVG 渲染 | 1 | 1 | | resvg | SVG 渲染 | 1 | 1 |
| XeLaTeX | LaTeX | 2 | 1 | | XeLaTeX | LaTeX | 2 | 1 |
| dvisvgm | 向量圖形 | 4 | 2 | | dvisvgm | 向量圖形 | 4 | 2 |
| Dasel | 資料檔案 | 5 | 4 | | Dasel | 資料檔案 | 5 | 4 |
| msgconvert | Outlook | 1 | 1 | | msgconvert | Outlook | 1 | 1 |
| VCF to CSV | 聯絡人 | 1 | 1 | | VCF to CSV | 聯絡人 | 1 | 1 |
| Markitdown | 文件轉 MD | 6 | 1 | | Markitdown | 文件轉 MD | 6 | 1 |
| MinerU | PDF → MD | 7 | 2 | | MinerU | PDF → MD | 7 | 2 |
| PDFMathTranslate | PDF 翻譯 | 1 | 15 | | PDFMathTranslate | PDF 翻譯 | 1 | 15 |
| BabelDOC | PDF 翻譯 | 1 | 45 | | BabelDOC | PDF 翻譯 | 1 | 45 |
| OCRmyPDF | PDF OCR | 1 | 8 | | OCRmyPDF | PDF OCR | 1 | 8 |
| deark | 解包/解析 | 100+ | 1 | | deark | 解包/解析 | 100+ | 1 |
--- ---
@ -111,43 +111,43 @@ 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 |
| **部署速度** | 最快 | 中等 | 較慢 | | **部署速度** | 最快 | 中等 | 較慢 |
| **適用對象** | 輕量使用者 | 一般使用者 | 進階/多語言 | | **適用對象** | 輕量使用者 | 一般使用者 | 進階/多語言 |
| **基本轉檔** | ✅ | ✅ | ✅ | | **基本轉檔** | ✅ | ✅ | ✅ |
| **OCR（7語言）** | ❌ | ✅ | ✅ | | **OCR（7語言）** | ❌ | ✅ | ✅ |
| **PDF 翻譯** | ❌ | ✅ | ✅ | | **PDF 翻譯** | ❌ | ✅ | ✅ |
| **MinerU AI** | ❌ | ✅ | ✅ | | **MinerU AI** | ❌ | ✅ | ✅ |
| **OCR（65語言）** | ❌ | ❌ | ✅ | | **OCR（65語言）** | ❌ | ❌ | ✅ |
| **完整 TexLive** | ❌ | ❌ | ✅ | | **完整 TexLive** | ❌ | ❌ | ✅ |
### Docker Tag 說明 ### Docker Tag 說明
| Tag | 說明 | | Tag | 說明 |
|-----|------| | ------------- | ----------------- |
| `latest` | 一般版最新穩定版 | | `latest` | 一般版最新穩定版 |
| `latest-lite` | Lite 版最新穩定版 | | `latest-lite` | Lite 版最新穩定版 |
| `latest-full` | Full 版最新穩定版 | | `latest-full` | Full 版最新穩定版 |
| `0.1.16` | 一般版指定版本 | | `0.1.16` | 一般版指定版本 |
| `0.1.16-lite` | Lite 版指定版本 | | `0.1.16-lite` | Lite 版指定版本 |
| `0.1.16-full` | Full 版指定版本 | | `0.1.16-full` | Full 版指定版本 |
--- ---
## 相關文件 ## 相關文件
| 文件 | 說明 | | 文件 | 說明 |
|------|------| | ----------------------------------------- | ------------------ |
| [01-快速開始](01-快速開始.md) | 5 分鐘內完成部署 | | [01-快速開始](01-快速開始.md) | 5 分鐘內完成部署 |
| [02-部署指南](02-部署指南.md) | 詳細部署設定 | | [02-部署指南](02-部署指南.md) | 詳細部署設定 |
| [03-環境變數與設定](03-環境變數與設定.md) | 所有可用設定 | | [03-環境變數與設定](03-環境變數與設定.md) | 所有可用設定 |
| [04-功能總覽](04-功能總覽.md) | 轉換功能詳細說明 | | [04-功能總覽](04-功能總覽.md) | 轉換功能詳細說明 |
| [05-API文件](05-API文件.md) | REST & GraphQL API | | [05-API文件](05-API文件.md) | REST & GraphQL API |
| [06-錯誤排查與支援](06-錯誤排查與支援.md) | 常見問題解決 | | [06-錯誤排查與支援](06-錯誤排查與支援.md) | 常見問題解決 |
| [07-開發與貢獻指南](07-開發與貢獻指南.md) | 開發者指南 | | [07-開發與貢獻指南](07-開發與貢獻指南.md) | 開發者指南 |
| [08-授權說明](08-授權說明.md) | AGPL-3.0 授權 | | [08-授權說明](08-授權說明.md) | AGPL-3.0 授權 |
--- ---

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

@ -17,12 +17,12 @@
## 前置需求 ## 前置需求
| 需求 | 最低規格 | 建議規格 | | 需求 | 最低規格 | 建議規格 |
|------|---------|---------| | -------- | ----------------------- | -------- |
| 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 |
| 作業系統 | Linux / macOS / Windows | Linux | | 作業系統 | Linux / macOS / Windows | Linux |
> 💡 **提示**：Windows 使用者請確保已安裝 [Docker Desktop](https://docs.docker.com/desktop/install/windows-install/) > 💡 **提示**：Windows 使用者請確保已安裝 [Docker Desktop](https://docs.docker.com/desktop/install/windows-install/)
@ -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 (中文翻譯，公式與排版保留)
``` ```
@ -203,13 +209,13 @@ 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` |
| 中文顯示亂碼 | 使用一般版或 Full 版（含完整字型） | | 中文顯示亂碼 | 使用一般版或 Full 版（含完整字型） |
| 轉換時間過長 | 增加容器記憶體限制或升級硬體 | | 轉換時間過長 | 增加容器記憶體限制或升級硬體 |
> 📖 更多問題請參閱 [06-錯誤排查與支援](06-錯誤排查與支援.md) > 📖 更多問題請參閱 [06-錯誤排查與支援](06-錯誤排查與支援.md)
@ -217,12 +223,12 @@ paper_translated.pdf (中文翻譯，公式與排版保留)
## 下一步 ## 下一步
| 需求 | 推薦閱讀 | | 需求 | 推薦閱讀 |
|------|---------| | ------------ | ----------------------------------------- |
| 詳細部署設定 | [02-部署指南](02-部署指南.md) | | 詳細部署設定 | [02-部署指南](02-部署指南.md) |
| 環境變數設定 | [03-環境變數與設定](03-環境變數與設定.md) | | 環境變數設定 | [03-環境變數與設定](03-環境變數與設定.md) |
| 了解所有功能 | [04-功能總覽](04-功能總覽.md) | | 了解所有功能 | [04-功能總覽](04-功能總覽.md) |
| API 整合 | [05-API文件](05-API文件.md) | | API 整合 | [05-API文件](05-API文件.md) |
--- ---

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

@ -18,12 +18,12 @@
### 系統需求 ### 系統需求
| 項目 | 最低需求 | 建議配置 | | 項目 | 最低需求 | 建議配置 |
|------|---------|---------| | -------- | -------- | ---------- |
| CPU | 2 核心 | 4 核心以上 | | CPU | 2 核心 | 4 核心以上 |
| 記憶體 | 4 GB | 8 GB 以上 | | 記憶體 | 4 GB | 8 GB 以上 |
| 磁碟空間 | 10 GB | 30 GB SSD | | 磁碟空間 | 10 GB | 30 GB SSD |
| 網路 | 10 Mbps | 100 Mbps | | 網路 | 10 Mbps | 100 Mbps |
### 準備工作 ### 準備工作
@ -33,7 +33,7 @@
# Ubuntu / Debian # Ubuntu / Debian
curl -fsSL https://get.docker.com | sh curl -fsSL https://get.docker.com | sh
sudo usermod -aG docker $USER sudo usermod -aG docker $USER
# CentOS / RHEL # CentOS / RHEL
sudo yum install -y docker sudo yum install -y docker
sudo systemctl start docker sudo systemctl start docker
@ -52,7 +52,7 @@
```bash ```bash
# Linux / macOS # Linux / macOS
openssl rand -hex 32 openssl rand -hex 32
# Windows PowerShell # Windows PowerShell
-join ((1..32) | ForEach-Object { '{0:x2}' -f (Get-Random -Max 256) }) -join ((1..32) | ForEach-Object { '{0:x2}' -f (Get-Random -Max 256) })
``` ```
@ -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"]
@ -134,12 +134,12 @@ services:
### 環境變數說明 ### 環境變數說明
| 變數 | 說明 | 預設值 | | 變數 | 說明 | 預設值 |
|------|------|--------| | -------------- | ------------------------ | ------------------ |
| `JWT_SECRET` | 登入驗證金鑰（**必填**） | 隨機（每次重啟變） | | `JWT_SECRET` | 登入驗證金鑰（**必填**） | 隨機（每次重啟變） |
| `TZ` | 時區 | `UTC` | | `TZ` | 時區 | `UTC` |
| `HTTP_ALLOWED` | 允許 HTTP 連線 | `false` | | `HTTP_ALLOWED` | 允許 HTTP 連線 | `false` |
| `TRUST_PROXY` | 信任反向代理 | `false` | | `TRUST_PROXY` | 信任反向代理 | `false` |
> 📖 完整變數列表請參閱 [03-環境變數與設定](03-環境變數與設定.md) > 📖 完整變數列表請參閱 [03-環境變數與設定](03-環境變數與設定.md)
@ -240,8 +240,8 @@ convertx.example.com {
```yaml ```yaml
environment: environment:
- TRUST_PROXY=true # 信任反向代理的 headers - TRUST_PROXY=true # 信任反向代理的 headers
- HTTP_ALLOWED=false # 反向代理已處理 HTTPS - HTTP_ALLOWED=false # 反向代理已處理 HTTPS
``` ```
--- ---
@ -255,7 +255,7 @@ environment:
```bash ```bash
# Ubuntu / Debian # Ubuntu / Debian
sudo apt install certbot python3-certbot-nginx sudo apt install certbot python3-certbot-nginx
# CentOS / RHEL # CentOS / RHEL
sudo yum install certbot python3-certbot-nginx sudo yum install certbot python3-certbot-nginx
``` ```

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

@ -20,38 +20,38 @@
### 🔒 安全性設定 ### 🔒 安全性設定
| 變數 | 必要性 | 說明 | 預設值 | 範例 | | 變數 | 必要性 | 說明 | 預設值 | 範例 |
|------|--------|------|--------|------| | ----------------------- | -------- | ------------------ | ------------------ | ------------------------- |
| `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` |
| `ACCOUNT_REGISTRATION` | 否 | 是否允許註冊新帳號 | `true` | `true` / `false` | | `ACCOUNT_REGISTRATION` | 否 | 是否允許註冊新帳號 | `true` | `true` / `false` |
| `ALLOW_UNAUTHENTICATED` | 否 | 是否允許匿名使用 | `false` | `true` / `false` | | `ALLOW_UNAUTHENTICATED` | 否 | 是否允許匿名使用 | `false` | `true` / `false` |
### 🌐 一般設定 ### 🌐 一般設定
| 變數 | 必要性 | 說明 | 預設值 | 範例 | | 變數 | 必要性 | 說明 | 預設值 | 範例 |
|------|--------|------|--------|------| | -------------- | ------ | ------------ | ------- | ---------------- |
| `TZ` | 否 | 系統時區 | `UTC` | `Asia/Taipei` | | `TZ` | 否 | 系統時區 | `UTC` | `Asia/Taipei` |
| `LANGUAGE` | 否 | 介面語言 | `auto` | `zh-TW` | | `LANGUAGE` | 否 | 介面語言 | `auto` | `zh-TW` |
| `WEBROOT` | 否 | 子路徑前綴 | 空 | `/convertx` | | `WEBROOT` | 否 | 子路徑前綴 | 空 | `/convertx` |
| `HIDE_HISTORY` | 否 | 隱藏轉換歷史 | `false` | `true` / `false` | | `HIDE_HISTORY` | 否 | 隱藏轉換歷史 | `false` | `true` / `false` |
### ⚙️ 轉換設定 ### ⚙️ 轉換設定
| 變數 | 必要性 | 說明 | 預設值 | 範例 | | 變數 | 必要性 | 說明 | 預設值 | 範例 |
|------|--------|------|--------|------| | --------------------------- | ------ | -------------------- | ------------- | ----------------- |
| `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` |
| `FFMPEG_OUTPUT_ARGS` | 否 | FFmpeg 輸出參數 | 空 | `-c:v h264_nvenc` | | `FFMPEG_OUTPUT_ARGS` | 否 | FFmpeg 輸出參數 | 空 | `-c:v h264_nvenc` |
### 📄 PDF 翻譯設定 ### 📄 PDF 翻譯設定
| 變數 | 必要性 | 說明 | 預設值 | 範例 | | 變數 | 必要性 | 說明 | 預設值 | 範例 |
|------|--------|------|--------|------| | ------------------------------ | ------ | -------- | --------- | ------------- |
| `PDFMATHTRANSLATE_SERVICE` | 否 | 翻譯服務 | `google` | `deepl` | | `PDFMATHTRANSLATE_SERVICE` | 否 | 翻譯服務 | `google` | `deepl` |
| `PDFMATHTRANSLATE_MODELS_PATH` | 否 | 模型路徑 | `/models` | `/app/models` | | `PDFMATHTRANSLATE_MODELS_PATH` | 否 | 模型路徑 | `/models` | `/app/models` |
--- ---
@ -61,12 +61,12 @@
用於簽署登入驗證的密鑰，**強烈建議在正式環境中設定**。 用於簽署登入驗證的密鑰，**強烈建議在正式環境中設定**。
| 項目 | 說明 | | 項目 | 說明 |
|------|------| | ---------- | ---------------------- |
| **類型** | 字串 | | **類型** | 字串 |
| **預設值** | 每次重啟隨機產生 | | **預設值** | 每次重啟隨機產生 |
| **建議值** | 至少 32 字元的隨機字串 | | **建議值** | 至少 32 字元的隨機字串 |
| **必要性** | ⭐ 強烈建議 | | **必要性** | ⭐ 強烈建議 |
**問題**：若不設定，每次容器重啟後所有使用者都需要重新登入。 **問題**：若不設定，每次容器重啟後所有使用者都需要重新登入。
@ -98,77 +98,77 @@ environment:
控制是否允許非 HTTPS 連線。 控制是否允許非 HTTPS 連線。
| 項目 | 說明 | | 項目 | 說明 |
|------|------| | ---------- | ---------------- |
| **類型** | 布林值 | | **類型** | 布林值 |
| **預設值** | `false` | | **預設值** | `false` |
| **可選值** | `true` / `false` | | **可選值** | `true` / `false` |
**使用情境**： **使用情境**：
| 情境 | 建議設定 | | 情境 | 建議設定 |
|------|---------| | --------------------- | -------- |
| 本地測試 (localhost) | `true` | | 本地測試 (localhost) | `true` |
| 已設定 HTTPS | `false` | | 已設定 HTTPS | `false` |
| 無 HTTPS 但需遠端存取 | `true` | | 無 HTTPS 但需遠端存取 | `true` |
> ⚠️ **注意**：設為 `false` 但用 HTTP 存取會導致「登入後又被導回登入頁」 > ⚠️ **注意**：設為 `false` 但用 HTTP 存取會導致「登入後又被導回登入頁」
```yaml ```yaml
environment: environment:
- HTTP_ALLOWED=true # 本地開發時使用 - HTTP_ALLOWED=true # 本地開發時使用
``` ```
### TRUST_PROXY ### TRUST_PROXY
控制是否信任反向代理的 X-Forwarded-* headers。 控制是否信任反向代理的 X-Forwarded-\* headers。
| 項目 | 說明 | | 項目 | 說明 |
|------|------| | ---------- | ---------------- |
| **類型** | 布林值 | | **類型** | 布林值 |
| **預設值** | `false` | | **預設值** | `false` |
| **可選值** | `true` / `false` | | **可選值** | `true` / `false` |
**使用情境**： **使用情境**：
| 情境 | 建議設定 | | 情境 | 建議設定 |
|------|---------| | ---------------------------- | -------- |
| 直接存取容器 | `false` | | 直接存取容器 | `false` |
| 透過 Nginx / Traefik / Caddy | `true` | | 透過 Nginx / Traefik / Caddy | `true` |
```yaml ```yaml
environment: environment:
- TRUST_PROXY=true # 使用反向代理時 - TRUST_PROXY=true # 使用反向代理時
``` ```
### ACCOUNT_REGISTRATION ### ACCOUNT_REGISTRATION
控制是否允許新使用者註冊。 控制是否允許新使用者註冊。
| 項目 | 說明 | | 項目 | 說明 |
|------|------| | ---------- | ---------------- |
| **類型** | 布林值 | | **類型** | 布林值 |
| **預設值** | `true` | | **預設值** | `true` |
| **可選值** | `true` / `false` | | **可選值** | `true` / `false` |
```yaml ```yaml
environment: environment:
- ACCOUNT_REGISTRATION=false # 關閉公開註冊 - ACCOUNT_REGISTRATION=false # 關閉公開註冊
``` ```
### ALLOW_UNAUTHENTICATED ### ALLOW_UNAUTHENTICATED
控制是否允許未登入的匿名使用者使用轉換功能。 控制是否允許未登入的匿名使用者使用轉換功能。
| 項目 | 說明 | | 項目 | 說明 |
|------|------| | ---------- | ---------------- |
| **類型** | 布林值 | | **類型** | 布林值 |
| **預設值** | `false` | | **預設值** | `false` |
| **可選值** | `true` / `false` | | **可選值** | `true` / `false` |
```yaml ```yaml
environment: environment:
- ALLOW_UNAUTHENTICATED=true # 允許匿名使用 - ALLOW_UNAUTHENTICATED=true # 允許匿名使用
``` ```
--- ---
@ -179,20 +179,20 @@ 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) |
**常用時區**： **常用時區**：
| 地區 | 時區值 | | 地區 | 時區值 |
|------|--------| | -------- | ------------------ |
| 台灣 | `Asia/Taipei` | | 台灣 | `Asia/Taipei` |
| 香港 | `Asia/Hong_Kong` | | 香港 | `Asia/Hong_Kong` |
| 中國大陸 | `Asia/Shanghai` | | 中國大陸 | `Asia/Shanghai` |
| 日本 | `Asia/Tokyo` | | 日本 | `Asia/Tokyo` |
| 美國東部 | `America/New_York` | | 美國東部 | `America/New_York` |
```yaml ```yaml
@ -204,10 +204,10 @@ environment:
設定介面預設語言。 設定介面預設語言。
| 項目 | 說明 | | 項目 | 說明 |
|------|------| | ---------- | ------------------------------------- |
| **類型** | 語言代碼 | | **類型** | 語言代碼 |
| **預設值** | `auto`（自動偵測） | | **預設值** | `auto`（自動偵測） |
| **可選值** | `zh-TW`, `zh-CN`, `en`, `ja` 等 65 種 | | **可選值** | `zh-TW`, `zh-CN`, `en`, `ja` 等 65 種 |
```yaml ```yaml
@ -219,28 +219,28 @@ environment:
設定子路徑前綴，用於反向代理配置。 設定子路徑前綴，用於反向代理配置。
| 項目 | 說明 | | 項目 | 說明 |
|------|------| | ---------- | ------------ |
| **類型** | 路徑字串 | | **類型** | 路徑字串 |
| **預設值** | 空（根路徑） | | **預設值** | 空（根路徑） |
```yaml ```yaml
environment: environment:
- WEBROOT=/convertx # 訪問路徑變為 http://example.com/convertx - WEBROOT=/convertx # 訪問路徑變為 http://example.com/convertx
``` ```
### HIDE_HISTORY ### HIDE_HISTORY
控制是否隱藏轉換歷史紀錄。 控制是否隱藏轉換歷史紀錄。
| 項目 | 說明 | | 項目 | 說明 |
|------|------| | ---------- | ------- |
| **類型** | 布林值 | | **類型** | 布林值 |
| **預設值** | `false` | | **預設值** | `false` |
```yaml ```yaml
environment: environment:
- HIDE_HISTORY=true # 隱藏歷史紀錄 - HIDE_HISTORY=true # 隱藏歷史紀錄
``` ```
--- ---
@ -251,39 +251,39 @@ environment:
設定自動刪除轉換檔案的間隔時間（小時）。 設定自動刪除轉換檔案的間隔時間（小時）。
| 項目 | 說明 | | 項目 | 說明 |
|------|------| | ------------ | ----------- |
| **類型** | 數字 | | **類型** | 數字 |
| **預設值** | `24` | | **預設值** | `24` |
| **建議範圍** | `1` - `168` | | **建議範圍** | `1` - `168` |
```yaml ```yaml
environment: environment:
- AUTO_DELETE_EVERY_N_HOURS=12 # 每 12 小時清理一次 - AUTO_DELETE_EVERY_N_HOURS=12 # 每 12 小時清理一次
``` ```
### MAX_CONVERT_PROCESS ### MAX_CONVERT_PROCESS
設定最大同時轉換任務數量。 設定最大同時轉換任務數量。
| 項目 | 說明 | | 項目 | 說明 |
|------|------| | ---------- | ------------- |
| **類型** | 數字 | | **類型** | 數字 |
| **預設值** | `0`（無限制） | | **預設值** | `0`（無限制） |
| **建議值** | CPU 核心數 | | **建議值** | CPU 核心數 |
```yaml ```yaml
environment: environment:
- MAX_CONVERT_PROCESS=4 # 最多同時 4 個轉換任務 - MAX_CONVERT_PROCESS=4 # 最多同時 4 個轉換任務
``` ```
### FFMPEG_ARGS 與 FFMPEG_OUTPUT_ARGS ### FFMPEG_ARGS 與 FFMPEG_OUTPUT_ARGS
設定 FFmpeg 的全域參數。 設定 FFmpeg 的全域參數。
| 變數 | 說明 | | 變數 | 說明 |
|------|------| | -------------------- | -------------------------- |
| `FFMPEG_ARGS` | 輸入參數（套用於輸入檔案） | | `FFMPEG_ARGS` | 輸入參數（套用於輸入檔案） |
| `FFMPEG_OUTPUT_ARGS` | 輸出參數（套用於輸出檔案） | | `FFMPEG_OUTPUT_ARGS` | 輸出參數（套用於輸出檔案） |
**GPU 加速範例**： **GPU 加速範例**：
@ -303,10 +303,10 @@ environment:
設定 PDF 翻譯使用的服務。 設定 PDF 翻譯使用的服務。
| 項目 | 說明 | | 項目 | 說明 |
|------|------| | ---------- | ----------------------------- |
| **類型** | 字串 | | **類型** | 字串 |
| **預設值** | `google` | | **預設值** | `google` |
| **可選值** | `google`, `deepl`, `azure` 等 | | **可選值** | `google`, `deepl`, `azure` 等 |
```yaml ```yaml
@ -318,9 +318,9 @@ environment:
設定 PDF 翻譯模型的存放路徑。 設定 PDF 翻譯模型的存放路徑。
| 項目 | 說明 | | 項目 | 說明 |
|------|------| | ---------- | --------- |
| **類型** | 路徑字串 | | **類型** | 路徑字串 |
| **預設值** | `/models` | | **預設值** | `/models` |
```yaml ```yaml
@ -361,16 +361,16 @@ services:
- ./data:/app/data - ./data:/app/data
environment: environment:
- TZ=Asia/Taipei - TZ=Asia/Taipei
- JWT_SECRET=${JWT_SECRET} # 使用環境變數或 secrets - JWT_SECRET=${JWT_SECRET} # 使用環境變數或 secrets
- HTTP_ALLOWED=false - HTTP_ALLOWED=false
- TRUST_PROXY=true # 如果使用反向代理 - TRUST_PROXY=true # 如果使用反向代理
- ACCOUNT_REGISTRATION=false # 關閉公開註冊 - ACCOUNT_REGISTRATION=false # 關閉公開註冊
- AUTO_DELETE_EVERY_N_HOURS=12 - AUTO_DELETE_EVERY_N_HOURS=12
- MAX_CONVERT_PROCESS=4 - MAX_CONVERT_PROCESS=4
deploy: deploy:
resources: resources:
limits: limits:
cpus: '4' cpus: "4"
memory: 8G memory: 8G
``` ```
@ -390,8 +390,8 @@ services:
- TRUST_PROXY=true - TRUST_PROXY=true
- ALLOW_UNAUTHENTICATED=true - ALLOW_UNAUTHENTICATED=true
- ACCOUNT_REGISTRATION=false - ACCOUNT_REGISTRATION=false
- AUTO_DELETE_EVERY_N_HOURS=1 # 頻繁清理 - AUTO_DELETE_EVERY_N_HOURS=1 # 頻繁清理
- MAX_CONVERT_PROCESS=2 # 限制資源使用 - MAX_CONVERT_PROCESS=2 # 限制資源使用
``` ```
--- ---
@ -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
``` ```

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

@ -19,21 +19,21 @@ ConvertX-CN 內建 25+ 種轉換引擎，支援 1000+ 種檔案格式轉換。
## 轉換引擎總覽 ## 轉換引擎總覽
| 轉換器 | 用途 | 輸入格式數 | 輸出格式數 | | 轉換器 | 用途 | 輸入格式數 | 輸出格式數 |
|--------|------|-----------|-----------| | ---------------- | ------------- | ---------- | ---------- |
| FFmpeg | 影音 | 472 | 199 | | FFmpeg | 影音 | 472 | 199 |
| ImageMagick | 圖片 | 253 | 183 | | ImageMagick | 圖片 | 253 | 183 |
| GraphicsMagick | 圖片 | 167 | 130 | | GraphicsMagick | 圖片 | 167 | 130 |
| Vips | 高效圖片處理 | 45 | 23 | | Vips | 高效圖片處理 | 45 | 23 |
| LibreOffice | 文件 | 41 | 22 | | LibreOffice | 文件 | 41 | 22 |
| Pandoc | 文件 | 43 | 65 | | Pandoc | 文件 | 43 | 65 |
| Calibre | 電子書 | 31 | 21 | | Calibre | 電子書 | 31 | 21 |
| Inkscape | 向量圖形 | 7 | 17 | | Inkscape | 向量圖形 | 7 | 17 |
| PDFMathTranslate | PDF 翻譯 | 1 | 15 | | PDFMathTranslate | PDF 翻譯 | 1 | 15 |
| BabelDOC | PDF 翻譯/轉換 | 1 | 45 | | BabelDOC | PDF 翻譯/轉換 | 1 | 45 |
| MinerU | PDF → MD | 7 | 2 | | MinerU | PDF → MD | 7 | 2 |
| OCRmyPDF | PDF OCR | 1 | 8 | | OCRmyPDF | PDF OCR | 1 | 8 |
| Assimp | 3D 模型 | 77 | 23 | | Assimp | 3D 模型 | 77 | 23 |
--- ---
@ -45,11 +45,11 @@ 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+ |
**使用範例**： **使用範例**：
@ -81,12 +81,12 @@ 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 |
| 科學格式 | FITS, EXR, DPX | | 科學格式 | FITS, EXR, DPX |
**使用範例**： **使用範例**：
@ -105,6 +105,7 @@ environment:
高效能圖片處理工具，適合大圖處理。 高效能圖片處理工具，適合大圖處理。
**特點**： **特點**：
- 記憶體使用效率高 - 記憶體使用效率高
- 處理速度快 - 處理速度快
- 適合批次處理 - 適合批次處理
@ -119,11 +120,11 @@ 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 |
**使用範例**： **使用範例**：
@ -143,12 +144,12 @@ Office 文件轉換引擎。
**支援格式**： **支援格式**：
| 類型 | 格式 | | 類型 | 格式 |
|------|------| | -------- | ------------------------------------ |
| 標記語言 | Markdown, reStructuredText, AsciiDoc | | 標記語言 | Markdown, reStructuredText, AsciiDoc |
| 網頁 | HTML, EPUB | | 網頁 | HTML, EPUB |
| 排版 | LaTeX, PDF, DOCX | | 排版 | LaTeX, PDF, DOCX |
| 純文字 | TXT, RTF | | 純文字 | TXT, RTF |
**使用範例**： **使用範例**：
@ -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,21 +255,22 @@ $$E = mc^2$$
為 PDF 添加 OCR 文字層，讓掃描 PDF 可搜尋。 為 PDF 添加 OCR 文字層，讓掃描 PDF 可搜尋。
**特點**： **特點**：
- 保留原始 PDF 外觀 - 保留原始 PDF 外觀
- 添加隱藏文字層 - 添加隱藏文字層
- 支援多語言辨識 - 支援多語言辨識
**支援語言（一般版）**： **支援語言（一般版）**：
| 語言 | 代碼 | | 語言 | 代碼 |
|------|------| | -------- | --------- |
| 繁體中文 | `chi_tra` | | 繁體中文 | `chi_tra` |
| 簡體中文 | `chi_sim` | | 簡體中文 | `chi_sim` |
| 英文 | `eng` | | 英文 | `eng` |
| 日文 | `jpn` | | 日文 | `jpn` |
| 韓文 | `kor` | | 韓文 | `kor` |
| 法文 | `fra` | | 法文 | `fra` |
| 德文 | `deu` | | 德文 | `deu` |
**Full 版支援 65 種語言**。 **Full 版支援 65 種語言**。
@ -285,11 +291,11 @@ $$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 |
**使用範例**： **使用範例**：
@ -311,19 +317,19 @@ $$E = mc^2$$
向量圖形編輯與轉換。 向量圖形編輯與轉換。
| 輸入 | 輸出 | | 輸入 | 輸出 |
|------|------| | ------------ | ------------- |
| SVG, AI, EPS | PNG, PDF, EPS | | SVG, AI, EPS | PNG, PDF, EPS |
| PDF | SVG | | PDF | SVG |
### Assimp ### Assimp
3D 模型格式轉換。 3D 模型格式轉換。
| 輸入 | 輸出 | | 輸入 | 輸出 |
|------|------| | -------------- | -------------- |
| FBX, OBJ, GLTF | OBJ, STL, GLTF | | FBX, OBJ, GLTF | OBJ, STL, GLTF |
| 3DS, DAE | FBX, PLY | | 3DS, DAE | FBX, PLY |
### Potrace / VTracer ### Potrace / VTracer
@ -338,8 +344,8 @@ $$E = mc^2$$
資料檔案格式轉換。 資料檔案格式轉換。
| 輸入/輸出 | | 輸入/輸出 |
|-----------| | -------------------------- |
| JSON, YAML, TOML, XML, CSV | | JSON, YAML, TOML, XML, CSV |
``` ```
@ -351,19 +357,19 @@ $$E = mc^2$$
## 功能比較表 ## 功能比較表
| 功能 | Lite 版 | 一般版 | Full 版 | | 功能 | Lite 版 | 一般版 | Full 版 |
|------|---------|--------|---------| | ----------------- | ------- | ------ | ------- |
| FFmpeg 影音 | ✅ | ✅ | ✅ | | FFmpeg 影音 | ✅ | ✅ | ✅ |
| ImageMagick 圖片 | ✅ | ✅ | ✅ | | ImageMagick 圖片 | ✅ | ✅ | ✅ |
| LibreOffice 文件 | ✅ | ✅ | ✅ | | LibreOffice 文件 | ✅ | ✅ | ✅ |
| Pandoc 文件 | ✅ | ✅ | ✅ | | Pandoc 文件 | ✅ | ✅ | ✅ |
| Calibre 電子書 | ✅ | ✅ | ✅ | | Calibre 電子書 | ✅ | ✅ | ✅ |
| OCRmyPDF (7語言) | ❌ | ✅ | ✅ | | OCRmyPDF (7語言) | ❌ | ✅ | ✅ |
| OCRmyPDF (65語言) | ❌ | ❌ | ✅ | | OCRmyPDF (65語言) | ❌ | ❌ | ✅ |
| PDFMathTranslate | ❌ | ✅ | ✅ | | PDFMathTranslate | ❌ | ✅ | ✅ |
| BabelDOC | ❌ | ✅ | ✅ | | BabelDOC | ❌ | ✅ | ✅ |
| MinerU | ❌ | ✅ | ✅ | | MinerU | ❌ | ✅ | ✅ |
| 完整 TexLive | ❌ | ❌ | ✅ | | 完整 TexLive | ❌ | ❌ | ✅ |
--- ---

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

@ -27,21 +27,21 @@ 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 驗證密鑰 | （需自行設定） |
| `UPLOAD_DIR` | 上傳目錄 | `./data/uploads` | | `UPLOAD_DIR` | 上傳目錄 | `./data/uploads` |
| `OUTPUT_DIR` | 輸出目錄 | `./data/output` | | `OUTPUT_DIR` | 輸出目錄 | `./data/output` |
| `MAX_FILE_SIZE` | 最大檔案大小（bytes） | `104857600` | | `MAX_FILE_SIZE` | 最大檔案大小（bytes） | `104857600` |
--- ---
@ -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
} }
@ -375,17 +371,17 @@ mutation {
### HTTP 狀態碼 ### HTTP 狀態碼
| 狀態碼 | 說明 | 常見原因 | | 狀態碼 | 說明 | 常見原因 |
|--------|------|---------| | ------ | ---------- | -------------------- |
| 200 | 成功 | 請求正常處理 | | 200 | 成功 | 請求正常處理 |
| 400 | 錯誤請求 | 參數錯誤、格式不支援 | | 400 | 錯誤請求 | 參數錯誤、格式不支援 |
| 401 | 未授權 | Token 無效或過期 | | 401 | 未授權 | Token 無效或過期 |
| 403 | 禁止存取 | 權限不足 | | 403 | 禁止存取 | 權限不足 |
| 404 | 找不到 | 檔案或任務不存在 | | 404 | 找不到 | 檔案或任務不存在 |
| 413 | 檔案太大 | 超過上傳限制 | | 413 | 檔案太大 | 超過上傳限制 |
| 415 | 格式不支援 | 不支援的檔案類型 | | 415 | 格式不支援 | 不支援的檔案類型 |
| 500 | 伺服器錯誤 | 內部錯誤 | | 500 | 伺服器錯誤 | 內部錯誤 |
| 503 | 服務不可用 | 伺服器過載 | | 503 | 服務不可用 | 伺服器過載 |
### 錯誤回應格式 ### 錯誤回應格式
@ -405,15 +401,15 @@ 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 正確 |
| `UNSUPPORTED_FORMAT` | 格式不支援 | 查看支援格式列表 | | `UNSUPPORTED_FORMAT` | 格式不支援 | 查看支援格式列表 |
| `FILE_TOO_LARGE` | 檔案過大 | 壓縮或分割檔案 | | `FILE_TOO_LARGE` | 檔案過大 | 壓縮或分割檔案 |
| `CONVERSION_FAILED` | 轉換失敗 | 檢查檔案是否損壞 | | `CONVERSION_FAILED` | 轉換失敗 | 檢查檔案是否損壞 |
| `RATE_LIMITED` | 請求過頻繁 | 降低請求頻率 | | `RATE_LIMITED` | 請求過頻繁 | 降低請求頻率 |
--- ---
@ -494,49 +490,49 @@ 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();
// 輪詢狀態 // 輪詢狀態
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();
} }

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

@ -18,14 +18,14 @@
## 常見問題速查 ## 常見問題速查
| 問題 | 可能原因 | 快速解決 | | 問題 | 可能原因 | 快速解決 |
|------|---------|---------| | ------------------ | ---------------------- | ---------------------------------------------- |
| 登入後被踢回登入頁 | 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` |
| 中文顯示亂碼 | 使用 Lite 版（無字型） | 改用一般版或 Full 版 | | 中文顯示亂碼 | 使用 Lite 版（無字型） | 改用一般版或 Full 版 |
| 轉換失敗 | 格式不支援或檔案損壞 | 檢查支援格式列表，確認檔案完整 | | 轉換失敗 | 格式不支援或檔案損壞 | 檢查支援格式列表，確認檔案完整 |
| 容器啟動失敗 | 端口衝突或記憶體不足 | 檢查端口使用，增加記憶體 | | 容器啟動失敗 | 端口衝突或記憶體不足 | 檢查端口使用，增加記憶體 |
--- ---
@ -34,6 +34,7 @@
### 問題：登入後又被導回登入頁 ### 問題：登入後又被導回登入頁
**症狀**： **症狀**：
- 輸入帳密後頁面閃一下又回到登入頁 - 輸入帳密後頁面閃一下又回到登入頁
- Cookie 無法正確設定 - Cookie 無法正確設定
@ -43,19 +44,20 @@
```yaml ```yaml
environment: environment:
- HTTP_ALLOWED=true # 允許 HTTP 連線 - HTTP_ALLOWED=true # 允許 HTTP 連線
``` ```
2. **使用反向代理但未設定信任** 2. **使用反向代理但未設定信任**
```yaml ```yaml
environment: environment:
- TRUST_PROXY=true # 信任反向代理 - TRUST_PROXY=true # 信任反向代理
``` ```
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,20 +192,23 @@ 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
# Windows # Windows
netstat -ano | findstr :3000 netstat -ano | findstr :3000
``` ```
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
``` ```
@ -262,7 +273,7 @@ rm -rf ./data/uploads/*
```yaml ```yaml
environment: environment:
- AUTO_DELETE_EVERY_N_HOURS=6 # 頻繁清理 - AUTO_DELETE_EVERY_N_HOURS=6 # 頻繁清理
``` ```
--- ---
@ -272,6 +283,7 @@ environment:
### 診斷效能問題 ### 診斷效能問題
1. **查看系統資源使用**： 1. **查看系統資源使用**：
```bash ```bash
docker stats convertx-cn docker stats convertx-cn
``` ```
@ -283,20 +295,20 @@ environment:
### 效能優化建議 ### 效能優化建議
| 問題 | 解決方案 | | 問題 | 解決方案 |
|------|---------| | ------------ | -------------------------- |
| CPU 使用率高 | 限制 `MAX_CONVERT_PROCESS` | | CPU 使用率高 | 限制 `MAX_CONVERT_PROCESS` |
| 記憶體不足 | 增加容器記憶體限制 | | 記憶體不足 | 增加容器記憶體限制 |
| 磁碟 I/O 慢 | 使用 SSD，增加 Volume 效能 | | 磁碟 I/O 慢 | 使用 SSD，增加 Volume 效能 |
| 網路延遲 | 使用本地部署 | | 網路延遲 | 使用本地部署 |
### 推薦硬體配置 ### 推薦硬體配置
| 用途 | 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 |
--- ---
@ -317,22 +329,22 @@ docker logs --since "2026-01-25T00:00:00" convertx-cn
### 日誌等級 ### 日誌等級
| 等級 | 說明 | | 等級 | 說明 |
|------|------| | ------- | ---------------- |
| `ERROR` | 錯誤，需要處理 | | `ERROR` | 錯誤，需要處理 |
| `WARN` | 警告，可能有問題 | | `WARN` | 警告，可能有問題 |
| `INFO` | 一般資訊 | | `INFO` | 一般資訊 |
| `DEBUG` | 除錯資訊 | | `DEBUG` | 除錯資訊 |
### 常見日誌訊息 ### 常見日誌訊息
| 訊息 | 說明 | | 訊息 | 說明 |
|------|------| | ---------------------------- | ------------ |
| `🦊 Elysia is running at...` | 服務正常啟動 | | `🦊 Elysia is running at...` | 服務正常啟動 |
| `Conversion started...` | 開始轉換 | | `Conversion started...` | 開始轉換 |
| `Conversion completed...` | 轉換完成 | | `Conversion completed...` | 轉換完成 |
| `Error: ENOSPC...` | 磁碟空間不足 | | `Error: ENOSPC...` | 磁碟空間不足 |
| `Error: ENOMEM...` | 記憶體不足 | | `Error: ENOMEM...` | 記憶體不足 |
### 匯出日誌 ### 匯出日誌
@ -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)
```

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

@ -74,23 +74,23 @@ ConvertX-CN/
### 前端 / Web Server ### 前端 / Web Server
| 技術 | 用途 | | 技術 | 用途 |
|------|------| | ----------- | ------------------ |
| Bun | JavaScript Runtime | | Bun | JavaScript Runtime |
| Elysia | Web 框架 | | Elysia | Web 框架 |
| React | UI 元件 | | React | UI 元件 |
| TailwindCSS | 樣式框架 | | TailwindCSS | 樣式框架 |
| TypeScript | 類型安全 | | TypeScript | 類型安全 |
| SQLite | 資料庫 | | SQLite | 資料庫 |
### API Server（選用） ### API Server（選用）
| 技術 | 用途 | | 技術 | 用途 |
|------|------| | ------------- | ------------ |
| Rust | 語言 | | Rust | 語言 |
| Axum | Web 框架 | | Axum | Web 框架 |
| async-graphql | GraphQL | | async-graphql | GraphQL |
| tokio | 非同步運行時 | | tokio | 非同步運行時 |
--- ---
@ -116,7 +116,7 @@ ConvertX-CN/
```bash ```bash
# 使用 Bun # 使用 Bun
bun install bun install
# 或使用 npm # 或使用 npm
npm install npm install
``` ```
@ -133,13 +133,13 @@ ConvertX-CN/
### 開發指令 ### 開發指令
| 指令 | 說明 | | 指令 | 說明 |
|------|------| | ------------ | ------------------------ |
| `bun dev` | 啟動開發伺服器（熱重載） | | `bun dev` | 啟動開發伺服器（熱重載） |
| `bun build` | 建構生產版本 | | `bun build` | 建構生產版本 |
| `bun test` | 執行測試 | | `bun test` | 執行測試 |
| `bun lint` | 執行 Linter | | `bun lint` | 執行 Linter |
| `bun format` | 格式化程式碼 | | `bun format` | 格式化程式碼 |
### API Server 開發 ### API Server 開發
@ -154,10 +154,10 @@ cargo run
### 主要分支 ### 主要分支
| 分支 | 用途 | | 分支 | 用途 |
|------|------| | --------- | ------------------ |
| `main` | 穩定版本，用於發布 | | `main` | 穩定版本，用於發布 |
| `develop` | 開發分支，接受 PR | | `develop` | 開發分支，接受 PR |
### 功能分支 ### 功能分支
@ -171,11 +171,11 @@ 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` |
| 重構 | `refactor/描述` | `refactor/improve-converter-perf` | | 重構 | `refactor/描述` | `refactor/improve-converter-perf` |
--- ---
@ -184,11 +184,11 @@ 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);
}); });
}); });
@ -242,16 +242,16 @@ describe('FFmpeg Converter', () => {
### Type 類型 ### Type 類型
| Type | 說明 | | Type | 說明 |
|------|------| | ---------- | ------------------------ |
| `feat` | 新功能 | | `feat` | 新功能 |
| `fix` | 修復 Bug | | `fix` | 修復 Bug |
| `docs` | 文件更新 | | `docs` | 文件更新 |
| `style` | 程式碼風格（不影響功能） | | `style` | 程式碼風格（不影響功能） |
| `refactor` | 重構（不新增功能或修復） | | `refactor` | 重構（不新增功能或修復） |
| `perf` | 效能優化 | | `perf` | 效能優化 |
| `test` | 新增或修改測試 | | `test` | 新增或修改測試 |
| `chore` | 建構或輔助工具變動 | | `chore` | 建構或輔助工具變動 |
### 範例 ### 範例
@ -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,12 +362,12 @@ 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) {
return name.toLowerCase(); return name.toLowerCase();
} }
``` ```
@ -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` 註冊

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

@ -16,11 +16,11 @@ 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 授權
@ -114,29 +120,29 @@ 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 |
| Pandoc | GPL 2.0 | | Pandoc | GPL 2.0 |
| Calibre | GPL 3.0 | | Calibre | GPL 3.0 |
| Tesseract OCR | Apache 2.0 | | Tesseract OCR | Apache 2.0 |
### 框架與函式庫 ### 框架與函式庫
| 元件 | 授權 | | 元件 | 授權 |
|------|------| | ----------- | ---- |
| Bun | MIT | | Bun | MIT |
| Elysia | MIT | | Elysia | MIT |
| React | MIT | | React | MIT |
| TailwindCSS | MIT | | TailwindCSS | 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)

48
docs/說明文件.md
View file

@ -6,17 +6,17 @@
## 📚 文件目錄 ## 📚 文件目錄
| 章節 | 說明 | | 章節 | 說明 |
|------|------| | ----------------------------------------- | ---------------------------- |
| [00-專案總覽](00-專案總覽.md) | 專案定位、功能特色、版本比較 | | [00-專案總覽](00-專案總覽.md) | 專案定位、功能特色、版本比較 |
| [01-快速開始](01-快速開始.md) | 5 分鐘部署完成 | | [01-快速開始](01-快速開始.md) | 5 分鐘部署完成 |
| [02-部署指南](02-部署指南.md) | Docker 設定、反向代理、HTTPS | | [02-部署指南](02-部署指南.md) | Docker 設定、反向代理、HTTPS |
| [03-環境變數與設定](03-環境變數與設定.md) | 所有可用設定與推薦值 | | [03-環境變數與設定](03-環境變數與設定.md) | 所有可用設定與推薦值 |
| [04-功能總覽](04-功能總覽.md) | 轉換器、OCR、PDF 翻譯 | | [04-功能總覽](04-功能總覽.md) | 轉換器、OCR、PDF 翻譯 |
| [05-API文件](05-API文件.md) | REST & GraphQL API | | [05-API文件](05-API文件.md) | REST & GraphQL API |
| [06-錯誤排查與支援](06-錯誤排查與支援.md) | 常見問題與解決方案 | | [06-錯誤排查與支援](06-錯誤排查與支援.md) | 常見問題與解決方案 |
| [07-開發與貢獻指南](07-開發與貢獻指南.md) | 專案結構、貢獻規範 | | [07-開發與貢獻指南](07-開發與貢獻指南.md) | 專案結構、貢獻規範 |
| [08-授權說明](08-授權說明.md) | AGPL-3.0 授權 | | [08-授權說明](08-授權說明.md) | AGPL-3.0 授權 |
--- ---
@ -36,27 +36,27 @@
### 部署相關 ### 部署相關
| 文件 | 說明 | | 文件 | 說明 |
|------|------| | -------------------------------------------- | ----------------------- |
| [部署指南/Docker.md](部署指南/Docker.md) | Docker 部署詳細說明 | | [部署指南/Docker.md](部署指南/Docker.md) | Docker 部署詳細說明 |
| [部署指南/反向代理.md](部署指南/反向代理.md) | Nginx / Traefik / Caddy | | [部署指南/反向代理.md](部署指南/反向代理.md) | Nginx / Traefik / Caddy |
| [範例配置/說明文件.md](範例配置/說明文件.md) | 可直接使用的配置檔 | | [範例配置/說明文件.md](範例配置/說明文件.md) | 可直接使用的配置檔 |
### 功能說明 ### 功能說明
| 文件 | 說明 | | 文件 | 說明 |
|------|------| | -------------------------------------------- | ------------------ |
| [功能說明/轉換器.md](功能說明/轉換器.md) | 所有轉換器詳細資訊 | | [功能說明/轉換器.md](功能說明/轉換器.md) | 所有轉換器詳細資訊 |
| [功能說明/OCR.md](功能說明/OCR.md) | OCR 功能說明 | | [功能說明/OCR.md](功能說明/OCR.md) | OCR 功能說明 |
| [功能說明/翻譯功能.md](功能說明/翻譯功能.md) | PDF 翻譯功能 | | [功能說明/翻譯功能.md](功能說明/翻譯功能.md) | PDF 翻譯功能 |
### 開發相關 ### 開發相關
| 文件 | 說明 | | 文件 | 說明 |
|------|------| | -------------------------------------------- | -------------- |
| [開發指南/專案結構.md](開發指南/專案結構.md) | 程式碼結構說明 | | [開發指南/專案結構.md](開發指南/專案結構.md) | 程式碼結構說明 |
| [開發指南/貢獻指南.md](開發指南/貢獻指南.md) | 如何參與專案 | | [開發指南/貢獻指南.md](開發指南/貢獻指南.md) | 如何參與專案 |
| [API/總覽.md](API/總覽.md) | API 詳細說明 | | [API/總覽.md](API/總覽.md) | API 詳細說明 |
--- ---