From 394dcbec1a7649b7cff1c1729a2e965cf1a5361f Mon Sep 17 00:00:00 2001 From: Your Name Date: Sun, 25 Jan 2026 16:10:07 +0800 Subject: [PATCH] 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. --- README.md | 30 +++--- docs/00-專案總覽.md | 164 ++++++++++++++--------------- docs/01-快速開始.md | 40 ++++--- docs/02-部署指南.md | 38 +++---- docs/03-環境變數與設定.md | 214 +++++++++++++++++++------------------- docs/04-功能總覽.md | 138 ++++++++++++------------ docs/05-API文件.md | 104 +++++++++--------- docs/06-錯誤排查與支援.md | 92 +++++++++------- docs/07-開發與貢獻指南.md | 122 +++++++++++----------- docs/08-授權說明.md | 45 ++++---- docs/說明文件.md | 48 ++++----- 11 files changed, 538 insertions(+), 497 deletions(-) diff --git a/README.md b/README.md index 5979426..ac1de06 100644 --- a/README.md +++ b/README.md @@ -28,17 +28,17 @@ 完整文件請參閱 **[專案總覽](docs/00-專案總覽.md)** -| 章節 | 說明 | 連結 | -| ---- | ---- | ---- | -| 📖 **00 專案總覽** | 專案定位、功能特色、版本比較 | [查看](docs/00-專案總覽.md) | -| 🚀 **01 快速開始** | 5 分鐘部署完成 | [查看](docs/01-快速開始.md) | -| 🐳 **02 部署指南** | Docker 設定、反向代理、HTTPS | [查看](docs/02-部署指南.md) | -| ⚙️ **03 環境變數** | 所有可用設定與推薦值 | [查看](docs/03-環境變數與設定.md) | -| 🔌 **04 功能總覽** | 轉換器、OCR、PDF 翻譯 | [查看](docs/04-功能總覽.md) | -| 🔗 **05 API 文件** | REST & GraphQL API | [查看](docs/05-API文件.md) | -| 🔧 **06 錯誤排查** | 常見問題與解決方案 | [查看](docs/06-錯誤排查與支援.md) | -| 👩‍💻 **07 開發指南** | 專案結構、貢獻規範 | [查看](docs/07-開發與貢獻指南.md) | -| 📄 **08 授權說明** | AGPL-3.0 授權 | [查看](docs/08-授權說明.md) | +| 章節 | 說明 | 連結 | +| ------------------ | ---------------------------- | --------------------------------- | +| 📖 **00 專案總覽** | 專案定位、功能特色、版本比較 | [查看](docs/00-專案總覽.md) | +| 🚀 **01 快速開始** | 5 分鐘部署完成 | [查看](docs/01-快速開始.md) | +| 🐳 **02 部署指南** | Docker 設定、反向代理、HTTPS | [查看](docs/02-部署指南.md) | +| ⚙️ **03 環境變數** | 所有可用設定與推薦值 | [查看](docs/03-環境變數與設定.md) | +| 🔌 **04 功能總覽** | 轉換器、OCR、PDF 翻譯 | [查看](docs/04-功能總覽.md) | +| 🔗 **05 API 文件** | REST & GraphQL API | [查看](docs/05-API文件.md) | +| 🔧 **06 錯誤排查** | 常見問題與解決方案 | [查看](docs/06-錯誤排查與支援.md) | +| 👩‍💻 **07 開發指南** | 專案結構、貢獻規範 | [查看](docs/07-開發與貢獻指南.md) | +| 📄 **08 授權說明** | AGPL-3.0 授權 | [查看](docs/08-授權說明.md) | --- @@ -202,11 +202,11 @@ docker run -d \ ### 授權摘要 -| 權利 | 說明 | -|------|------| +| 權利 | 說明 | +| ----------- | ------------------------ | | ✅ 自由使用 | 個人、商業、教育用途均可 | -| ✅ 自由修改 | 可修改原始碼 | -| ✅ 自由分發 | 可重新分發 | +| ✅ 自由修改 | 可修改原始碼 | +| ✅ 自由分發 | 可重新分發 | ### 義務 diff --git a/docs/00-專案總覽.md b/docs/00-專案總覽.md index 3b3d2c1..70ffa43 100644 --- a/docs/00-專案總覽.md +++ b/docs/00-專案總覽.md @@ -25,29 +25,29 @@ ConvertX-CN 是一個**開箱即用的全功能檔案轉換服務**，基於 [C4 ### 🌟 專案特色 -| 特色 | 說明 | -|------|------| -| 📁 **1000+ 格式** | 文件、圖片、影音、電子書一次搞定 | -| 🔧 **25+ 引擎** | LibreOffice、FFmpeg、Pandoc 全到位 | -| 🈶 **中文優化** | 內建中日韓字型與 OCR，告別亂碼 | -| 🌐 **65 種語言** | 跨國團隊無障礙使用 | -| 📊 **PDF 翻譯** | PDFMathTranslate + BabelDOC 雙引擎 | -| 📄 **PDF 轉 MD** | MinerU 智能擷取（保留表格、公式、圖片） | +| 特色 | 說明 | +| ----------------- | --------------------------------------- | +| 📁 **1000+ 格式** | 文件、圖片、影音、電子書一次搞定 | +| 🔧 **25+ 引擎** | LibreOffice、FFmpeg、Pandoc 全到位 | +| 🈶 **中文優化** | 內建中日韓字型與 OCR，告別亂碼 | +| 🌐 **65 種語言** | 跨國團隊無障礙使用 | +| 📊 **PDF 翻譯** | PDFMathTranslate + BabelDOC 雙引擎 | +| 📄 **PDF 轉 MD** | MinerU 智能擷取（保留表格、公式、圖片） | --- ## ConvertX-CN 與原始 ConvertX 的差異 -| 項目 | 原始 ConvertX | ConvertX-CN | -|------|--------------|-------------| -| **語言支援** | 英文介面為主 | 65 種語言介面，中文優化 | -| **字型支援** | 基本字型 | 內建中日韓完整字型集 | -| **OCR 語言** | 需手動安裝 | 預裝 7 種常用語言（Full 版 65 種） | -| **PDF 翻譯** | ❌ 不支援 | ✅ PDFMathTranslate + BabelDOC | -| **PDF 轉 MD** | ❌ 不支援 | ✅ MinerU 智能擷取 | -| **BabelDOC** | ❌ 不支援 | ✅ 進階 PDF 處理 | -| **Docker 大小** | 較小 | 較大（功能更完整） | -| **維護者** | C4illin | pi-docket | +| 項目 | 原始 ConvertX | ConvertX-CN | +| --------------- | ------------- | ---------------------------------- | +| **語言支援** | 英文介面為主 | 65 種語言介面，中文優化 | +| **字型支援** | 基本字型 | 內建中日韓完整字型集 | +| **OCR 語言** | 需手動安裝 | 預裝 7 種常用語言（Full 版 65 種） | +| **PDF 翻譯** | ❌ 不支援 | ✅ PDFMathTranslate + BabelDOC | +| **PDF 轉 MD** | ❌ 不支援 | ✅ MinerU 智能擷取 | +| **BabelDOC** | ❌ 不支援 | ✅ 進階 PDF 處理 | +| **Docker 大小** | 較小 | 較大（功能更完整） | +| **維護者** | C4illin | pi-docket | ### 新增功能清單 @@ -64,46 +64,46 @@ ConvertX-CN 是一個**開箱即用的全功能檔案轉換服務**，基於 [C4 ### 按類型分類 -| 類型 | 轉換器 | 支援格式數 | -|------|--------|-----------| -| 🎬 **影音** | FFmpeg | 400+ | -| 🖼️ **圖片** | ImageMagick, GraphicsMagick, Vips | 300+ | -| 📄 **文件** | LibreOffice, Pandoc | 160+ | -| 📚 **電子書** | Calibre | 50+ | -| ✏️ **向量圖** | Inkscape, Potrace, VTracer | 40+ | -| 📊 **PDF 處理** | PDFMathTranslate, BabelDOC, MinerU, OCRmyPDF | 30+ | -| 🎮 **3D 模型** | Assimp | 100+ | -| 📋 **資料檔案** | Dasel | 10+ | +| 類型 | 轉換器 | 支援格式數 | +| --------------- | -------------------------------------------- | ---------- | +| 🎬 **影音** | FFmpeg | 400+ | +| 🖼️ **圖片** | ImageMagick, GraphicsMagick, Vips | 300+ | +| 📄 **文件** | LibreOffice, Pandoc | 160+ | +| 📚 **電子書** | Calibre | 50+ | +| ✏️ **向量圖** | Inkscape, Potrace, VTracer | 40+ | +| 📊 **PDF 處理** | PDFMathTranslate, BabelDOC, MinerU, OCRmyPDF | 30+ | +| 🎮 **3D 模型** | Assimp | 100+ | +| 📋 **資料檔案** | Dasel | 10+ | ### 完整轉換器列表 -| 轉換器 | 用途 | 輸入格式 | 輸出格式 | -|--------|------|----------|----------| -| FFmpeg | 影音 | 472 | 199 | -| ImageMagick | 圖片 | 253 | 183 | -| GraphicsMagick | 圖片 | 167 | 130 | -| Vips | 高效圖片處理 | 45 | 23 | -| LibreOffice | 文件 | 41 | 22 | -| Pandoc | 文件 | 43 | 65 | -| Calibre | 電子書 | 31 | 21 | -| Inkscape | 向量圖形 | 7 | 17 | -| libjxl | JPEG XL | 11 | 11 | -| libheif | HEIF/HEIC | 11 | 3 | -| Assimp | 3D 模型 | 77 | 23 | -| Potrace | 點陣轉向量 | 4 | 11 | -| VTracer | 點陣轉向量 | 8 | 1 | -| resvg | SVG 渲染 | 1 | 1 | -| XeLaTeX | LaTeX | 2 | 1 | -| dvisvgm | 向量圖形 | 4 | 2 | -| Dasel | 資料檔案 | 5 | 4 | -| msgconvert | Outlook | 1 | 1 | -| VCF to CSV | 聯絡人 | 1 | 1 | -| Markitdown | 文件轉 MD | 6 | 1 | -| MinerU | PDF → MD | 7 | 2 | -| PDFMathTranslate | PDF 翻譯 | 1 | 15 | -| BabelDOC | PDF 翻譯 | 1 | 45 | -| OCRmyPDF | PDF OCR | 1 | 8 | -| deark | 解包/解析 | 100+ | 1 | +| 轉換器 | 用途 | 輸入格式 | 輸出格式 | +| ---------------- | ------------ | -------- | -------- | +| FFmpeg | 影音 | 472 | 199 | +| ImageMagick | 圖片 | 253 | 183 | +| GraphicsMagick | 圖片 | 167 | 130 | +| Vips | 高效圖片處理 | 45 | 23 | +| LibreOffice | 文件 | 41 | 22 | +| Pandoc | 文件 | 43 | 65 | +| Calibre | 電子書 | 31 | 21 | +| Inkscape | 向量圖形 | 7 | 17 | +| libjxl | JPEG XL | 11 | 11 | +| libheif | HEIF/HEIC | 11 | 3 | +| Assimp | 3D 模型 | 77 | 23 | +| Potrace | 點陣轉向量 | 4 | 11 | +| VTracer | 點陣轉向量 | 8 | 1 | +| resvg | SVG 渲染 | 1 | 1 | +| XeLaTeX | LaTeX | 2 | 1 | +| dvisvgm | 向量圖形 | 4 | 2 | +| Dasel | 資料檔案 | 5 | 4 | +| msgconvert | Outlook | 1 | 1 | +| VCF to CSV | 聯絡人 | 1 | 1 | +| Markitdown | 文件轉 MD | 6 | 1 | +| MinerU | PDF → MD | 7 | 2 | +| PDFMathTranslate | PDF 翻譯 | 1 | 15 | +| BabelDOC | PDF 翻譯 | 1 | 45 | +| OCRmyPDF | PDF OCR | 1 | 8 | +| deark | 解包/解析 | 100+ | 1 | --- @@ -111,43 +111,43 @@ ConvertX-CN 是一個**開箱即用的全功能檔案轉換服務**，基於 [C4 ConvertX-CN 提供三個版本，滿足不同需求： -| 特性 | Lite 版 | 一般版（推薦） | Full 版 | -|------|---------|---------------|---------| -| **Image 大小** | ~3 GB | ~7 GB | ~15 GB | -| **部署速度** | 最快 | 中等 | 較慢 | -| **適用對象** | 輕量使用者 | 一般使用者 | 進階/多語言 | -| **基本轉檔** | ✅ | ✅ | ✅ | -| **OCR（7語言）** | ❌ | ✅ | ✅ | -| **PDF 翻譯** | ❌ | ✅ | ✅ | -| **MinerU AI** | ❌ | ✅ | ✅ | -| **OCR（65語言）** | ❌ | ❌ | ✅ | -| **完整 TexLive** | ❌ | ❌ | ✅ | +| 特性 | Lite 版 | 一般版（推薦） | Full 版 | +| ----------------- | ---------- | -------------- | ----------- | +| **Image 大小** | ~3 GB | ~7 GB | ~15 GB | +| **部署速度** | 最快 | 中等 | 較慢 | +| **適用對象** | 輕量使用者 | 一般使用者 | 進階/多語言 | +| **基本轉檔** | ✅ | ✅ | ✅ | +| **OCR（7語言）** | ❌ | ✅ | ✅ | +| **PDF 翻譯** | ❌ | ✅ | ✅ | +| **MinerU AI** | ❌ | ✅ | ✅ | +| **OCR（65語言）** | ❌ | ❌ | ✅ | +| **完整 TexLive** | ❌ | ❌ | ✅ | ### Docker Tag 說明 -| Tag | 說明 | -|-----|------| -| `latest` | 一般版最新穩定版 | +| Tag | 說明 | +| ------------- | ----------------- | +| `latest` | 一般版最新穩定版 | | `latest-lite` | Lite 版最新穩定版 | | `latest-full` | Full 版最新穩定版 | -| `0.1.16` | 一般版指定版本 | -| `0.1.16-lite` | Lite 版指定版本 | -| `0.1.16-full` | Full 版指定版本 | +| `0.1.16` | 一般版指定版本 | +| `0.1.16-lite` | Lite 版指定版本 | +| `0.1.16-full` | Full 版指定版本 | --- ## 相關文件 -| 文件 | 說明 | -|------|------| -| [01-快速開始](01-快速開始.md) | 5 分鐘內完成部署 | -| [02-部署指南](02-部署指南.md) | 詳細部署設定 | -| [03-環境變數與設定](03-環境變數與設定.md) | 所有可用設定 | -| [04-功能總覽](04-功能總覽.md) | 轉換功能詳細說明 | -| [05-API文件](05-API文件.md) | REST & GraphQL API | -| [06-錯誤排查與支援](06-錯誤排查與支援.md) | 常見問題解決 | -| [07-開發與貢獻指南](07-開發與貢獻指南.md) | 開發者指南 | -| [08-授權說明](08-授權說明.md) | AGPL-3.0 授權 | +| 文件 | 說明 | +| ----------------------------------------- | ------------------ | +| [01-快速開始](01-快速開始.md) | 5 分鐘內完成部署 | +| [02-部署指南](02-部署指南.md) | 詳細部署設定 | +| [03-環境變數與設定](03-環境變數與設定.md) | 所有可用設定 | +| [04-功能總覽](04-功能總覽.md) | 轉換功能詳細說明 | +| [05-API文件](05-API文件.md) | REST & GraphQL API | +| [06-錯誤排查與支援](06-錯誤排查與支援.md) | 常見問題解決 | +| [07-開發與貢獻指南](07-開發與貢獻指南.md) | 開發者指南 | +| [08-授權說明](08-授權說明.md) | AGPL-3.0 授權 | --- diff --git a/docs/01-快速開始.md b/docs/01-快速開始.md index 8e4f2b8..291541b 100644 --- a/docs/01-快速開始.md +++ b/docs/01-快速開始.md @@ -17,12 +17,12 @@ ## 前置需求 -| 需求 | 最低規格 | 建議規格 | -|------|---------|---------| -| Docker | 20.10+ | 24.0+ | -| 記憶體 | 4 GB | 8 GB | -| 磁碟空間 | 10 GB | 30 GB | -| 作業系統 | Linux / macOS / Windows | Linux | +| 需求 | 最低規格 | 建議規格 | +| -------- | ----------------------- | -------- | +| Docker | 20.10+ | 24.0+ | +| 記憶體 | 4 GB | 8 GB | +| 磁碟空間 | 10 GB | 30 GB | +| 作業系統 | Linux / macOS / Windows | Linux | > 💡 **提示**：Windows 使用者請確保已安裝 [Docker Desktop](https://docs.docker.com/desktop/install/windows-install/) @@ -157,11 +157,13 @@ docker logs convertx-cn 4. 下載轉換後的 PDF 檔案 **輸入：** + ``` report.docx (Microsoft Word 文件) ``` **輸出：** + ``` report.pdf (PDF 文件) ``` @@ -173,11 +175,13 @@ report.pdf (PDF 文件) 3. 點擊「轉換」 **輸入：** + ``` video.mov (QuickTime 影片, 500 MB) ``` **輸出：** + ``` video.mp4 (MP4 影片, 壓縮後約 200 MB) ``` @@ -190,11 +194,13 @@ video.mp4 (MP4 影片, 壓縮後約 200 MB) 4. 點擊「翻譯」 **輸入：** + ``` paper.pdf (英文學術論文，含數學公式) ``` **輸出：** + ``` paper_translated.pdf (中文翻譯，公式與排版保留) ``` @@ -203,13 +209,13 @@ paper_translated.pdf (中文翻譯，公式與排版保留) ## 常見問題快查 -| 問題 | 解決方法 | -|------|---------| +| 問題 | 解決方法 | +| ------------------ | ---------------------------------------------- | | 登入後被踢回登入頁 | 加上 `HTTP_ALLOWED=true` 或 `TRUST_PROXY=true` | -| 重啟後資料消失 | 確認 `./data:/app/data` 且資料夾存在 | -| 重啟後被登出 | 設定固定的 `JWT_SECRET` | -| 中文顯示亂碼 | 使用一般版或 Full 版（含完整字型） | -| 轉換時間過長 | 增加容器記憶體限制或升級硬體 | +| 重啟後資料消失 | 確認 `./data:/app/data` 且資料夾存在 | +| 重啟後被登出 | 設定固定的 `JWT_SECRET` | +| 中文顯示亂碼 | 使用一般版或 Full 版（含完整字型） | +| 轉換時間過長 | 增加容器記憶體限制或升級硬體 | > 📖 更多問題請參閱 [06-錯誤排查與支援](06-錯誤排查與支援.md) @@ -217,12 +223,12 @@ paper_translated.pdf (中文翻譯，公式與排版保留) ## 下一步 -| 需求 | 推薦閱讀 | -|------|---------| -| 詳細部署設定 | [02-部署指南](02-部署指南.md) | +| 需求 | 推薦閱讀 | +| ------------ | ----------------------------------------- | +| 詳細部署設定 | [02-部署指南](02-部署指南.md) | | 環境變數設定 | [03-環境變數與設定](03-環境變數與設定.md) | -| 了解所有功能 | [04-功能總覽](04-功能總覽.md) | -| API 整合 | [05-API文件](05-API文件.md) | +| 了解所有功能 | [04-功能總覽](04-功能總覽.md) | +| API 整合 | [05-API文件](05-API文件.md) | --- diff --git a/docs/02-部署指南.md b/docs/02-部署指南.md index 219b6c6..f2a95b0 100644 --- a/docs/02-部署指南.md +++ b/docs/02-部署指南.md @@ -18,12 +18,12 @@ ### 系統需求 -| 項目 | 最低需求 | 建議配置 | -|------|---------|---------| -| CPU | 2 核心 | 4 核心以上 | -| 記憶體 | 4 GB | 8 GB 以上 | -| 磁碟空間 | 10 GB | 30 GB SSD | -| 網路 | 10 Mbps | 100 Mbps | +| 項目 | 最低需求 | 建議配置 | +| -------- | -------- | ---------- | +| CPU | 2 核心 | 4 核心以上 | +| 記憶體 | 4 GB | 8 GB 以上 | +| 磁碟空間 | 10 GB | 30 GB SSD | +| 網路 | 10 Mbps | 100 Mbps | ### 準備工作 @@ -33,7 +33,7 @@ # Ubuntu / Debian curl -fsSL https://get.docker.com | sh sudo usermod -aG docker $USER - + # CentOS / RHEL sudo yum install -y docker sudo systemctl start docker @@ -52,7 +52,7 @@ ```bash # Linux / macOS openssl rand -hex 32 - + # Windows PowerShell -join ((1..32) | ForEach-Object { '{0:x2}' -f (Get-Random -Max 256) }) ``` @@ -100,10 +100,10 @@ services: deploy: resources: limits: - cpus: '4' + cpus: "4" memory: 8G reservations: - cpus: '2' + cpus: "2" memory: 4G healthcheck: test: ["CMD", "curl", "-f", "http://localhost:3000/health"] @@ -134,12 +134,12 @@ services: ### 環境變數說明 -| 變數 | 說明 | 預設值 | -|------|------|--------| -| `JWT_SECRET` | 登入驗證金鑰（**必填**） | 隨機（每次重啟變） | -| `TZ` | 時區 | `UTC` | -| `HTTP_ALLOWED` | 允許 HTTP 連線 | `false` | -| `TRUST_PROXY` | 信任反向代理 | `false` | +| 變數 | 說明 | 預設值 | +| -------------- | ------------------------ | ------------------ | +| `JWT_SECRET` | 登入驗證金鑰（**必填**） | 隨機（每次重啟變） | +| `TZ` | 時區 | `UTC` | +| `HTTP_ALLOWED` | 允許 HTTP 連線 | `false` | +| `TRUST_PROXY` | 信任反向代理 | `false` | > 📖 完整變數列表請參閱 [03-環境變數與設定](03-環境變數與設定.md) @@ -240,8 +240,8 @@ convertx.example.com { ```yaml environment: - - TRUST_PROXY=true # 信任反向代理的 headers - - HTTP_ALLOWED=false # 反向代理已處理 HTTPS + - TRUST_PROXY=true # 信任反向代理的 headers + - HTTP_ALLOWED=false # 反向代理已處理 HTTPS ``` --- @@ -255,7 +255,7 @@ environment: ```bash # Ubuntu / Debian sudo apt install certbot python3-certbot-nginx - + # CentOS / RHEL sudo yum install certbot python3-certbot-nginx ``` diff --git a/docs/03-環境變數與設定.md b/docs/03-環境變數與設定.md index f078301..6d85fbd 100644 --- a/docs/03-環境變數與設定.md +++ b/docs/03-環境變數與設定.md @@ -20,38 +20,38 @@ ### 🔒 安全性設定 -| 變數 | 必要性 | 說明 | 預設值 | 範例 | -|------|--------|------|--------|------| -| `JWT_SECRET` | **必須** | Token 驗證密鑰 | 隨機（每次重啟變） | `Xk9mPqL2vN7wR4tY6uI8...` | -| `HTTP_ALLOWED` | 否 | 是否允許 HTTP 連線 | `false` | `true` / `false` | -| `TRUST_PROXY` | 否 | 是否信任反向代理 | `false` | `true` / `false` | -| `ACCOUNT_REGISTRATION` | 否 | 是否允許註冊新帳號 | `true` | `true` / `false` | -| `ALLOW_UNAUTHENTICATED` | 否 | 是否允許匿名使用 | `false` | `true` / `false` | +| 變數 | 必要性 | 說明 | 預設值 | 範例 | +| ----------------------- | -------- | ------------------ | ------------------ | ------------------------- | +| `JWT_SECRET` | **必須** | Token 驗證密鑰 | 隨機（每次重啟變） | `Xk9mPqL2vN7wR4tY6uI8...` | +| `HTTP_ALLOWED` | 否 | 是否允許 HTTP 連線 | `false` | `true` / `false` | +| `TRUST_PROXY` | 否 | 是否信任反向代理 | `false` | `true` / `false` | +| `ACCOUNT_REGISTRATION` | 否 | 是否允許註冊新帳號 | `true` | `true` / `false` | +| `ALLOW_UNAUTHENTICATED` | 否 | 是否允許匿名使用 | `false` | `true` / `false` | ### 🌐 一般設定 -| 變數 | 必要性 | 說明 | 預設值 | 範例 | -|------|--------|------|--------|------| -| `TZ` | 否 | 系統時區 | `UTC` | `Asia/Taipei` | -| `LANGUAGE` | 否 | 介面語言 | `auto` | `zh-TW` | -| `WEBROOT` | 否 | 子路徑前綴 | 空 | `/convertx` | -| `HIDE_HISTORY` | 否 | 隱藏轉換歷史 | `false` | `true` / `false` | +| 變數 | 必要性 | 說明 | 預設值 | 範例 | +| -------------- | ------ | ------------ | ------- | ---------------- | +| `TZ` | 否 | 系統時區 | `UTC` | `Asia/Taipei` | +| `LANGUAGE` | 否 | 介面語言 | `auto` | `zh-TW` | +| `WEBROOT` | 否 | 子路徑前綴 | 空 | `/convertx` | +| `HIDE_HISTORY` | 否 | 隱藏轉換歷史 | `false` | `true` / `false` | ### ⚙️ 轉換設定 -| 變數 | 必要性 | 說明 | 預設值 | 範例 | -|------|--------|------|--------|------| -| `AUTO_DELETE_EVERY_N_HOURS` | 否 | 自動刪除間隔（小時） | `24` | `12` | -| `MAX_CONVERT_PROCESS` | 否 | 最大同時轉換數 | `0`（無限制） | `4` | -| `FFMPEG_ARGS` | 否 | FFmpeg 輸入參數 | 空 | `-hwaccel cuda` | -| `FFMPEG_OUTPUT_ARGS` | 否 | FFmpeg 輸出參數 | 空 | `-c:v h264_nvenc` | +| 變數 | 必要性 | 說明 | 預設值 | 範例 | +| --------------------------- | ------ | -------------------- | ------------- | ----------------- | +| `AUTO_DELETE_EVERY_N_HOURS` | 否 | 自動刪除間隔（小時） | `24` | `12` | +| `MAX_CONVERT_PROCESS` | 否 | 最大同時轉換數 | `0`（無限制） | `4` | +| `FFMPEG_ARGS` | 否 | FFmpeg 輸入參數 | 空 | `-hwaccel cuda` | +| `FFMPEG_OUTPUT_ARGS` | 否 | FFmpeg 輸出參數 | 空 | `-c:v h264_nvenc` | ### 📄 PDF 翻譯設定 -| 變數 | 必要性 | 說明 | 預設值 | 範例 | -|------|--------|------|--------|------| -| `PDFMATHTRANSLATE_SERVICE` | 否 | 翻譯服務 | `google` | `deepl` | -| `PDFMATHTRANSLATE_MODELS_PATH` | 否 | 模型路徑 | `/models` | `/app/models` | +| 變數 | 必要性 | 說明 | 預設值 | 範例 | +| ------------------------------ | ------ | -------- | --------- | ------------- | +| `PDFMATHTRANSLATE_SERVICE` | 否 | 翻譯服務 | `google` | `deepl` | +| `PDFMATHTRANSLATE_MODELS_PATH` | 否 | 模型路徑 | `/models` | `/app/models` | --- @@ -61,12 +61,12 @@ 用於簽署登入驗證的密鑰，**強烈建議在正式環境中設定**。 -| 項目 | 說明 | -|------|------| -| **類型** | 字串 | -| **預設值** | 每次重啟隨機產生 | +| 項目 | 說明 | +| ---------- | ---------------------- | +| **類型** | 字串 | +| **預設值** | 每次重啟隨機產生 | | **建議值** | 至少 32 字元的隨機字串 | -| **必要性** | ⭐ 強烈建議 | +| **必要性** | ⭐ 強烈建議 | **問題**：若不設定，每次容器重啟後所有使用者都需要重新登入。 @@ -98,77 +98,77 @@ environment: 控制是否允許非 HTTPS 連線。 -| 項目 | 說明 | -|------|------| -| **類型** | 布林值 | -| **預設值** | `false` | +| 項目 | 說明 | +| ---------- | ---------------- | +| **類型** | 布林值 | +| **預設值** | `false` | | **可選值** | `true` / `false` | **使用情境**： -| 情境 | 建議設定 | -|------|---------| -| 本地測試 (localhost) | `true` | -| 已設定 HTTPS | `false` | -| 無 HTTPS 但需遠端存取 | `true` | +| 情境 | 建議設定 | +| --------------------- | -------- | +| 本地測試 (localhost) | `true` | +| 已設定 HTTPS | `false` | +| 無 HTTPS 但需遠端存取 | `true` | > ⚠️ **注意**：設為 `false` 但用 HTTP 存取會導致「登入後又被導回登入頁」 ```yaml environment: - - HTTP_ALLOWED=true # 本地開發時使用 + - HTTP_ALLOWED=true # 本地開發時使用 ``` ### TRUST_PROXY -控制是否信任反向代理的 X-Forwarded-* headers。 +控制是否信任反向代理的 X-Forwarded-\* headers。 -| 項目 | 說明 | -|------|------| -| **類型** | 布林值 | -| **預設值** | `false` | +| 項目 | 說明 | +| ---------- | ---------------- | +| **類型** | 布林值 | +| **預設值** | `false` | | **可選值** | `true` / `false` | **使用情境**： -| 情境 | 建議設定 | -|------|---------| -| 直接存取容器 | `false` | -| 透過 Nginx / Traefik / Caddy | `true` | +| 情境 | 建議設定 | +| ---------------------------- | -------- | +| 直接存取容器 | `false` | +| 透過 Nginx / Traefik / Caddy | `true` | ```yaml environment: - - TRUST_PROXY=true # 使用反向代理時 + - TRUST_PROXY=true # 使用反向代理時 ``` ### ACCOUNT_REGISTRATION 控制是否允許新使用者註冊。 -| 項目 | 說明 | -|------|------| -| **類型** | 布林值 | -| **預設值** | `true` | +| 項目 | 說明 | +| ---------- | ---------------- | +| **類型** | 布林值 | +| **預設值** | `true` | | **可選值** | `true` / `false` | ```yaml environment: - - ACCOUNT_REGISTRATION=false # 關閉公開註冊 + - ACCOUNT_REGISTRATION=false # 關閉公開註冊 ``` ### ALLOW_UNAUTHENTICATED 控制是否允許未登入的匿名使用者使用轉換功能。 -| 項目 | 說明 | -|------|------| -| **類型** | 布林值 | -| **預設值** | `false` | +| 項目 | 說明 | +| ---------- | ---------------- | +| **類型** | 布林值 | +| **預設值** | `false` | | **可選值** | `true` / `false` | ```yaml 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) | **常用時區**： -| 地區 | 時區值 | -|------|--------| -| 台灣 | `Asia/Taipei` | -| 香港 | `Asia/Hong_Kong` | -| 中國大陸 | `Asia/Shanghai` | -| 日本 | `Asia/Tokyo` | +| 地區 | 時區值 | +| -------- | ------------------ | +| 台灣 | `Asia/Taipei` | +| 香港 | `Asia/Hong_Kong` | +| 中國大陸 | `Asia/Shanghai` | +| 日本 | `Asia/Tokyo` | | 美國東部 | `America/New_York` | ```yaml @@ -204,10 +204,10 @@ environment: 設定介面預設語言。 -| 項目 | 說明 | -|------|------| -| **類型** | 語言代碼 | -| **預設值** | `auto`（自動偵測） | +| 項目 | 說明 | +| ---------- | ------------------------------------- | +| **類型** | 語言代碼 | +| **預設值** | `auto`（自動偵測） | | **可選值** | `zh-TW`, `zh-CN`, `en`, `ja` 等 65 種 | ```yaml @@ -219,28 +219,28 @@ environment: 設定子路徑前綴，用於反向代理配置。 -| 項目 | 說明 | -|------|------| -| **類型** | 路徑字串 | +| 項目 | 說明 | +| ---------- | ------------ | +| **類型** | 路徑字串 | | **預設值** | 空（根路徑） | ```yaml environment: - - WEBROOT=/convertx # 訪問路徑變為 http://example.com/convertx + - WEBROOT=/convertx # 訪問路徑變為 http://example.com/convertx ``` ### HIDE_HISTORY 控制是否隱藏轉換歷史紀錄。 -| 項目 | 說明 | -|------|------| -| **類型** | 布林值 | +| 項目 | 說明 | +| ---------- | ------- | +| **類型** | 布林值 | | **預設值** | `false` | ```yaml environment: - - HIDE_HISTORY=true # 隱藏歷史紀錄 + - HIDE_HISTORY=true # 隱藏歷史紀錄 ``` --- @@ -251,39 +251,39 @@ environment: 設定自動刪除轉換檔案的間隔時間（小時）。 -| 項目 | 說明 | -|------|------| -| **類型** | 數字 | -| **預設值** | `24` | +| 項目 | 說明 | +| ------------ | ----------- | +| **類型** | 數字 | +| **預設值** | `24` | | **建議範圍** | `1` - `168` | ```yaml environment: - - AUTO_DELETE_EVERY_N_HOURS=12 # 每 12 小時清理一次 + - AUTO_DELETE_EVERY_N_HOURS=12 # 每 12 小時清理一次 ``` ### MAX_CONVERT_PROCESS 設定最大同時轉換任務數量。 -| 項目 | 說明 | -|------|------| -| **類型** | 數字 | +| 項目 | 說明 | +| ---------- | ------------- | +| **類型** | 數字 | | **預設值** | `0`（無限制） | -| **建議值** | CPU 核心數 | +| **建議值** | CPU 核心數 | ```yaml environment: - - MAX_CONVERT_PROCESS=4 # 最多同時 4 個轉換任務 + - MAX_CONVERT_PROCESS=4 # 最多同時 4 個轉換任務 ``` ### FFMPEG_ARGS 與 FFMPEG_OUTPUT_ARGS 設定 FFmpeg 的全域參數。 -| 變數 | 說明 | -|------|------| -| `FFMPEG_ARGS` | 輸入參數（套用於輸入檔案） | +| 變數 | 說明 | +| -------------------- | -------------------------- | +| `FFMPEG_ARGS` | 輸入參數（套用於輸入檔案） | | `FFMPEG_OUTPUT_ARGS` | 輸出參數（套用於輸出檔案） | **GPU 加速範例**： @@ -303,10 +303,10 @@ environment: 設定 PDF 翻譯使用的服務。 -| 項目 | 說明 | -|------|------| -| **類型** | 字串 | -| **預設值** | `google` | +| 項目 | 說明 | +| ---------- | ----------------------------- | +| **類型** | 字串 | +| **預設值** | `google` | | **可選值** | `google`, `deepl`, `azure` 等 | ```yaml @@ -318,9 +318,9 @@ environment: 設定 PDF 翻譯模型的存放路徑。 -| 項目 | 說明 | -|------|------| -| **類型** | 路徑字串 | +| 項目 | 說明 | +| ---------- | --------- | +| **類型** | 路徑字串 | | **預設值** | `/models` | ```yaml @@ -361,16 +361,16 @@ services: - ./data:/app/data environment: - TZ=Asia/Taipei - - JWT_SECRET=${JWT_SECRET} # 使用環境變數或 secrets + - JWT_SECRET=${JWT_SECRET} # 使用環境變數或 secrets - HTTP_ALLOWED=false - - TRUST_PROXY=true # 如果使用反向代理 - - ACCOUNT_REGISTRATION=false # 關閉公開註冊 + - TRUST_PROXY=true # 如果使用反向代理 + - ACCOUNT_REGISTRATION=false # 關閉公開註冊 - AUTO_DELETE_EVERY_N_HOURS=12 - MAX_CONVERT_PROCESS=4 deploy: resources: limits: - cpus: '4' + cpus: "4" memory: 8G ``` @@ -390,8 +390,8 @@ services: - TRUST_PROXY=true - ALLOW_UNAUTHENTICATED=true - ACCOUNT_REGISTRATION=false - - AUTO_DELETE_EVERY_N_HOURS=1 # 頻繁清理 - - MAX_CONVERT_PROCESS=2 # 限制資源使用 + - AUTO_DELETE_EVERY_N_HOURS=1 # 頻繁清理 + - MAX_CONVERT_PROCESS=2 # 限制資源使用 ``` --- @@ -406,11 +406,13 @@ services: - 不要使用範例中的值 2. **正式環境關閉 HTTP** + ```yaml - HTTP_ALLOWED=false ``` 3. **使用反向代理處理 HTTPS** + ```yaml - TRUST_PROXY=true ``` diff --git a/docs/04-功能總覽.md b/docs/04-功能總覽.md index bfdfe18..4511095 100644 --- a/docs/04-功能總覽.md +++ b/docs/04-功能總覽.md @@ -19,21 +19,21 @@ ConvertX-CN 內建 25+ 種轉換引擎，支援 1000+ 種檔案格式轉換。 ## 轉換引擎總覽 -| 轉換器 | 用途 | 輸入格式數 | 輸出格式數 | -|--------|------|-----------|-----------| -| FFmpeg | 影音 | 472 | 199 | -| ImageMagick | 圖片 | 253 | 183 | -| GraphicsMagick | 圖片 | 167 | 130 | -| Vips | 高效圖片處理 | 45 | 23 | -| LibreOffice | 文件 | 41 | 22 | -| Pandoc | 文件 | 43 | 65 | -| Calibre | 電子書 | 31 | 21 | -| Inkscape | 向量圖形 | 7 | 17 | -| PDFMathTranslate | PDF 翻譯 | 1 | 15 | -| BabelDOC | PDF 翻譯/轉換 | 1 | 45 | -| MinerU | PDF → MD | 7 | 2 | -| OCRmyPDF | PDF OCR | 1 | 8 | -| Assimp | 3D 模型 | 77 | 23 | +| 轉換器 | 用途 | 輸入格式數 | 輸出格式數 | +| ---------------- | ------------- | ---------- | ---------- | +| FFmpeg | 影音 | 472 | 199 | +| ImageMagick | 圖片 | 253 | 183 | +| GraphicsMagick | 圖片 | 167 | 130 | +| Vips | 高效圖片處理 | 45 | 23 | +| LibreOffice | 文件 | 41 | 22 | +| Pandoc | 文件 | 43 | 65 | +| Calibre | 電子書 | 31 | 21 | +| Inkscape | 向量圖形 | 7 | 17 | +| PDFMathTranslate | PDF 翻譯 | 1 | 15 | +| BabelDOC | PDF 翻譯/轉換 | 1 | 45 | +| MinerU | PDF → MD | 7 | 2 | +| OCRmyPDF | PDF OCR | 1 | 8 | +| Assimp | 3D 模型 | 77 | 23 | --- @@ -45,11 +45,11 @@ ConvertX-CN 內建 25+ 種轉換引擎，支援 1000+ 種檔案格式轉換。 **支援格式**： -| 類型 | 輸入 | 輸出 | -|------|------|------| +| 類型 | 輸入 | 輸出 | +| ---- | ------------------------------------ | -------------------------- | | 影片 | MP4, MKV, AVI, MOV, WebM, FLV 等 65+ | MP4, MKV, WebM, AVI 等 50+ | -| 音訊 | MP3, FLAC, WAV, AAC, OGG 等 120+ | MP3, FLAC, WAV, AAC 等 85+ | -| 字幕 | SRT, ASS, VTT 等 25+ | SRT, ASS, VTT 等 12+ | +| 音訊 | MP3, FLAC, WAV, AAC, OGG 等 120+ | MP3, FLAC, WAV, AAC 等 85+ | +| 字幕 | SRT, ASS, VTT 等 25+ | SRT, ASS, VTT 等 12+ | **使用範例**： @@ -81,12 +81,12 @@ environment: **支援格式**： -| 類型 | 格式範例 | -|------|---------| -| 常見格式 | PNG, JPEG, GIF, WebP, AVIF, HEIC | -| RAW 相機 | CR2, CR3, NEF, ARW, DNG | -| 向量/文件 | PDF, PSD, AI, EPS, SVG | -| 科學格式 | FITS, EXR, DPX | +| 類型 | 格式範例 | +| --------- | -------------------------------- | +| 常見格式 | PNG, JPEG, GIF, WebP, AVIF, HEIC | +| RAW 相機 | CR2, CR3, NEF, ARW, DNG | +| 向量/文件 | PDF, PSD, AI, EPS, SVG | +| 科學格式 | FITS, EXR, DPX | **使用範例**： @@ -105,6 +105,7 @@ environment: 高效能圖片處理工具，適合大圖處理。 **特點**： + - 記憶體使用效率高 - 處理速度快 - 適合批次處理 @@ -119,11 +120,11 @@ Office 文件轉換引擎。 **支援格式**： -| 輸入 | 輸出 | -|------|------| +| 輸入 | 輸出 | +| -------------- | -------------- | | DOC, DOCX, ODT | PDF, HTML, TXT | | 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 | -| 網頁 | HTML, EPUB | -| 排版 | LaTeX, PDF, DOCX | -| 純文字 | TXT, RTF | +| 網頁 | HTML, EPUB | +| 排版 | LaTeX, PDF, DOCX | +| 純文字 | TXT, RTF | **使用範例**： @@ -171,12 +172,14 @@ Office 文件轉換引擎。 翻譯 PDF 並**保留數學公式與排版**。 **特點**： + - 保留原始排版 - 保留數學公式 - 保留圖表位置 - 支援多種翻譯引擎 **支援語言**： + - 英文 ↔ 中文 - 英文 ↔ 日文 - 其他語言組合 @@ -193,6 +196,7 @@ Office 文件轉換引擎。 進階 PDF 翻譯與轉換引擎。 **特點**： + - 高品質翻譯 - 支援複雜排版 - 多格式輸出 @@ -209,6 +213,7 @@ Office 文件轉換引擎。 **PDF 轉 Markdown**，智能擷取內容。 **特點**： + - 智能識別表格 - 保留公式（轉為 LaTeX） - 擷取圖片 @@ -232,7 +237,7 @@ Office 文件轉換引擎。 根據研究顯示... | 項目 | 數值 | 說明 | -|------|------|------| +| ---- | ---- | ---- | | A | 100 | 描述 | | B | 200 | 描述 | @@ -250,21 +255,22 @@ $$E = mc^2$$ 為 PDF 添加 OCR 文字層，讓掃描 PDF 可搜尋。 **特點**： + - 保留原始 PDF 外觀 - 添加隱藏文字層 - 支援多語言辨識 **支援語言（一般版）**： -| 語言 | 代碼 | -|------|------| +| 語言 | 代碼 | +| -------- | --------- | | 繁體中文 | `chi_tra` | | 簡體中文 | `chi_sim` | -| 英文 | `eng` | -| 日文 | `jpn` | -| 韓文 | `kor` | -| 法文 | `fra` | -| 德文 | `deu` | +| 英文 | `eng` | +| 日文 | `jpn` | +| 韓文 | `kor` | +| 法文 | `fra` | +| 德文 | `deu` | **Full 版支援 65 種語言**。 @@ -285,11 +291,11 @@ $$E = mc^2$$ **支援格式**： -| 輸入 | 輸出 | -|------|------| +| 輸入 | 輸出 | +| ---------------- | --------------- | | EPUB, MOBI, AZW3 | EPUB, MOBI, PDF | -| PDF, TXT, HTML | AZW3, DOCX, TXT | -| CBZ, CBR (漫畫) | PDF, EPUB | +| PDF, TXT, HTML | AZW3, DOCX, TXT | +| CBZ, CBR (漫畫) | PDF, EPUB | **使用範例**： @@ -311,19 +317,19 @@ $$E = mc^2$$ 向量圖形編輯與轉換。 -| 輸入 | 輸出 | -|------|------| +| 輸入 | 輸出 | +| ------------ | ------------- | | SVG, AI, EPS | PNG, PDF, EPS | -| PDF | SVG | +| PDF | SVG | ### Assimp 3D 模型格式轉換。 -| 輸入 | 輸出 | -|------|------| +| 輸入 | 輸出 | +| -------------- | -------------- | | FBX, OBJ, GLTF | OBJ, STL, GLTF | -| 3DS, DAE | FBX, PLY | +| 3DS, DAE | FBX, PLY | ### Potrace / VTracer @@ -338,8 +344,8 @@ $$E = mc^2$$ 資料檔案格式轉換。 -| 輸入/輸出 | -|-----------| +| 輸入/輸出 | +| -------------------------- | | JSON, YAML, TOML, XML, CSV | ``` @@ -351,19 +357,19 @@ $$E = mc^2$$ ## 功能比較表 -| 功能 | Lite 版 | 一般版 | Full 版 | -|------|---------|--------|---------| -| FFmpeg 影音 | ✅ | ✅ | ✅ | -| ImageMagick 圖片 | ✅ | ✅ | ✅ | -| LibreOffice 文件 | ✅ | ✅ | ✅ | -| Pandoc 文件 | ✅ | ✅ | ✅ | -| Calibre 電子書 | ✅ | ✅ | ✅ | -| OCRmyPDF (7語言) | ❌ | ✅ | ✅ | -| OCRmyPDF (65語言) | ❌ | ❌ | ✅ | -| PDFMathTranslate | ❌ | ✅ | ✅ | -| BabelDOC | ❌ | ✅ | ✅ | -| MinerU | ❌ | ✅ | ✅ | -| 完整 TexLive | ❌ | ❌ | ✅ | +| 功能 | Lite 版 | 一般版 | Full 版 | +| ----------------- | ------- | ------ | ------- | +| FFmpeg 影音 | ✅ | ✅ | ✅ | +| ImageMagick 圖片 | ✅ | ✅ | ✅ | +| LibreOffice 文件 | ✅ | ✅ | ✅ | +| Pandoc 文件 | ✅ | ✅ | ✅ | +| Calibre 電子書 | ✅ | ✅ | ✅ | +| OCRmyPDF (7語言) | ❌ | ✅ | ✅ | +| OCRmyPDF (65語言) | ❌ | ❌ | ✅ | +| PDFMathTranslate | ❌ | ✅ | ✅ | +| BabelDOC | ❌ | ✅ | ✅ | +| MinerU | ❌ | ✅ | ✅ | +| 完整 TexLive | ❌ | ❌ | ✅ | --- diff --git a/docs/05-API文件.md b/docs/05-API文件.md index 8031fdb..f44d99d 100644 --- a/docs/05-API文件.md +++ b/docs/05-API文件.md @@ -27,21 +27,21 @@ docker compose --profile api up -d ### 服務端口 -| 服務 | 端口 | 說明 | -|------|------|------| -| Web UI | 3000 | 網頁介面 | +| 服務 | 端口 | 說明 | +| ---------- | ---- | -------------- | +| Web UI | 3000 | 網頁介面 | | API Server | 3001 | REST & GraphQL | ### 環境變數 -| 變數 | 說明 | 預設值 | -|------|------|--------| -| `API_HOST` | 監聽地址 | `0.0.0.0` | -| `API_PORT` | 監聽埠 | `3001` | -| `JWT_SECRET` | JWT 驗證密鑰 | （需自行設定） | -| `UPLOAD_DIR` | 上傳目錄 | `./data/uploads` | -| `OUTPUT_DIR` | 輸出目錄 | `./data/output` | -| `MAX_FILE_SIZE` | 最大檔案大小（bytes） | `104857600` | +| 變數 | 說明 | 預設值 | +| --------------- | --------------------- | ---------------- | +| `API_HOST` | 監聽地址 | `0.0.0.0` | +| `API_PORT` | 監聽埠 | `3001` | +| `JWT_SECRET` | JWT 驗證密鑰 | （需自行設定） | +| `UPLOAD_DIR` | 上傳目錄 | `./data/uploads` | +| `OUTPUT_DIR` | 輸出目錄 | `./data/output` | +| `MAX_FILE_SIZE` | 最大檔案大小（bytes） | `104857600` | --- @@ -358,11 +358,7 @@ query { ```graphql mutation { - convert(input: { - fileId: "abc123" - outputFormat: "pdf" - options: { quality: "high" } - }) { + convert(input: { fileId: "abc123", outputFormat: "pdf", options: { quality: "high" } }) { jobId status } @@ -375,17 +371,17 @@ mutation { ### HTTP 狀態碼 -| 狀態碼 | 說明 | 常見原因 | -|--------|------|---------| -| 200 | 成功 | 請求正常處理 | -| 400 | 錯誤請求 | 參數錯誤、格式不支援 | -| 401 | 未授權 | Token 無效或過期 | -| 403 | 禁止存取 | 權限不足 | -| 404 | 找不到 | 檔案或任務不存在 | -| 413 | 檔案太大 | 超過上傳限制 | -| 415 | 格式不支援 | 不支援的檔案類型 | -| 500 | 伺服器錯誤 | 內部錯誤 | -| 503 | 服務不可用 | 伺服器過載 | +| 狀態碼 | 說明 | 常見原因 | +| ------ | ---------- | -------------------- | +| 200 | 成功 | 請求正常處理 | +| 400 | 錯誤請求 | 參數錯誤、格式不支援 | +| 401 | 未授權 | Token 無效或過期 | +| 403 | 禁止存取 | 權限不足 | +| 404 | 找不到 | 檔案或任務不存在 | +| 413 | 檔案太大 | 超過上傳限制 | +| 415 | 格式不支援 | 不支援的檔案類型 | +| 500 | 伺服器錯誤 | 內部錯誤 | +| 503 | 服務不可用 | 伺服器過載 | ### 錯誤回應格式 @@ -405,15 +401,15 @@ mutation { ### 常見錯誤碼 -| 錯誤碼 | 說明 | 解決方法 | -|--------|------|---------| -| `INVALID_TOKEN` | Token 無效 | 重新取得有效 Token | -| `TOKEN_EXPIRED` | Token 過期 | 刷新 Token | -| `FILE_NOT_FOUND` | 檔案不存在 | 確認檔案 ID 正確 | -| `UNSUPPORTED_FORMAT` | 格式不支援 | 查看支援格式列表 | -| `FILE_TOO_LARGE` | 檔案過大 | 壓縮或分割檔案 | -| `CONVERSION_FAILED` | 轉換失敗 | 檢查檔案是否損壞 | -| `RATE_LIMITED` | 請求過頻繁 | 降低請求頻率 | +| 錯誤碼 | 說明 | 解決方法 | +| -------------------- | ---------- | ------------------ | +| `INVALID_TOKEN` | Token 無效 | 重新取得有效 Token | +| `TOKEN_EXPIRED` | Token 過期 | 刷新 Token | +| `FILE_NOT_FOUND` | 檔案不存在 | 確認檔案 ID 正確 | +| `UNSUPPORTED_FORMAT` | 格式不支援 | 查看支援格式列表 | +| `FILE_TOO_LARGE` | 檔案過大 | 壓縮或分割檔案 | +| `CONVERSION_FAILED` | 轉換失敗 | 檢查檔案是否損壞 | +| `RATE_LIMITED` | 請求過頻繁 | 降低請求頻率 | --- @@ -494,49 +490,49 @@ with open("output.pdf", "wb") as f: ### JavaScript 範例 ```javascript -const BASE_URL = 'http://localhost:3001/api/v1'; -const TOKEN = 'your-jwt-token'; +const BASE_URL = "http://localhost:3001/api/v1"; +const TOKEN = "your-jwt-token"; async function convertFile(file, outputFormat) { // 上傳檔案 const formData = new FormData(); - formData.append('file', file); - + formData.append("file", file); + const uploadResponse = await fetch(`${BASE_URL}/upload`, { - method: 'POST', - headers: { 'Authorization': `Bearer ${TOKEN}` }, - body: formData + method: "POST", + headers: { Authorization: `Bearer ${TOKEN}` }, + body: formData, }); const { fileId } = await uploadResponse.json(); - + // 開始轉換 const convertResponse = await fetch(`${BASE_URL}/convert`, { - method: 'POST', + method: "POST", headers: { - 'Authorization': `Bearer ${TOKEN}`, - 'Content-Type': 'application/json' + Authorization: `Bearer ${TOKEN}`, + "Content-Type": "application/json", }, - body: JSON.stringify({ fileId, outputFormat }) + body: JSON.stringify({ fileId, outputFormat }), }); const { jobId } = await convertResponse.json(); - + // 輪詢狀態 let result; while (true) { const statusResponse = await fetch(`${BASE_URL}/jobs/${jobId}`, { - headers: { 'Authorization': `Bearer ${TOKEN}` } + headers: { Authorization: `Bearer ${TOKEN}` }, }); const job = await statusResponse.json(); - if (job.status === 'completed') { + if (job.status === "completed") { result = job.result; break; } - await new Promise(resolve => setTimeout(resolve, 2000)); + await new Promise((resolve) => setTimeout(resolve, 2000)); } - + // 下載結果 const downloadResponse = await fetch(`${BASE_URL}/download/${result.fileId}`, { - headers: { 'Authorization': `Bearer ${TOKEN}` } + headers: { Authorization: `Bearer ${TOKEN}` }, }); return await downloadResponse.blob(); } diff --git a/docs/06-錯誤排查與支援.md b/docs/06-錯誤排查與支援.md index dc83e7d..cf1e798 100644 --- a/docs/06-錯誤排查與支援.md +++ b/docs/06-錯誤排查與支援.md @@ -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) +``` diff --git a/docs/07-開發與貢獻指南.md b/docs/07-開發與貢獻指南.md index 1836d92..75d6388 100644 --- a/docs/07-開發與貢獻指南.md +++ b/docs/07-開發與貢獻指南.md @@ -74,23 +74,23 @@ ConvertX-CN/ ### 前端 / Web Server -| 技術 | 用途 | -|------|------| -| Bun | JavaScript Runtime | -| Elysia | Web 框架 | -| React | UI 元件 | -| TailwindCSS | 樣式框架 | -| TypeScript | 類型安全 | -| SQLite | 資料庫 | +| 技術 | 用途 | +| ----------- | ------------------ | +| Bun | JavaScript Runtime | +| Elysia | Web 框架 | +| React | UI 元件 | +| TailwindCSS | 樣式框架 | +| TypeScript | 類型安全 | +| SQLite | 資料庫 | ### API Server（選用） -| 技術 | 用途 | -|------|------| -| Rust | 語言 | -| Axum | Web 框架 | -| async-graphql | GraphQL | -| tokio | 非同步運行時 | +| 技術 | 用途 | +| ------------- | ------------ | +| Rust | 語言 | +| Axum | Web 框架 | +| async-graphql | GraphQL | +| tokio | 非同步運行時 | --- @@ -116,7 +116,7 @@ ConvertX-CN/ ```bash # 使用 Bun bun install - + # 或使用 npm npm install ``` @@ -133,13 +133,13 @@ ConvertX-CN/ ### 開發指令 -| 指令 | 說明 | -|------|------| -| `bun dev` | 啟動開發伺服器（熱重載） | -| `bun build` | 建構生產版本 | -| `bun test` | 執行測試 | -| `bun lint` | 執行 Linter | -| `bun format` | 格式化程式碼 | +| 指令 | 說明 | +| ------------ | ------------------------ | +| `bun dev` | 啟動開發伺服器（熱重載） | +| `bun build` | 建構生產版本 | +| `bun test` | 執行測試 | +| `bun lint` | 執行 Linter | +| `bun format` | 格式化程式碼 | ### API Server 開發 @@ -154,10 +154,10 @@ cargo run ### 主要分支 -| 分支 | 用途 | -|------|------| -| `main` | 穩定版本，用於發布 | -| `develop` | 開發分支，接受 PR | +| 分支 | 用途 | +| --------- | ------------------ | +| `main` | 穩定版本，用於發布 | +| `develop` | 開發分支，接受 PR | ### 功能分支 @@ -171,11 +171,11 @@ git checkout -b feature/your-feature-name ### 分支命名規範 -| 類型 | 格式 | 範例 | -|------|------|------| -| 功能 | `feature/描述` | `feature/add-pdf-watermark` | -| 修復 | `fix/描述` | `fix/login-redirect-issue` | -| 文件 | `docs/描述` | `docs/update-api-docs` | +| 類型 | 格式 | 範例 | +| ---- | --------------- | --------------------------------- | +| 功能 | `feature/描述` | `feature/add-pdf-watermark` | +| 修復 | `fix/描述` | `fix/login-redirect-issue` | +| 文件 | `docs/描述` | `docs/update-api-docs` | | 重構 | `refactor/描述` | `refactor/improve-converter-perf` | --- @@ -184,11 +184,11 @@ git checkout -b feature/your-feature-name ### 測試類型 -| 類型 | 位置 | 說明 | -|------|------|------| -| 單元測試 | `tests/` | 測試個別函數 | -| 整合測試 | `tests/converters/` | 測試轉換器 | -| E2E 測試 | `tests/e2e/` | 端對端測試 | +| 類型 | 位置 | 說明 | +| -------- | ------------------- | ------------ | +| 單元測試 | `tests/` | 測試個別函數 | +| 整合測試 | `tests/converters/` | 測試轉換器 | +| E2E 測試 | `tests/e2e/` | 端對端測試 | ### 執行測試 @@ -215,12 +215,12 @@ bun test --coverage ```typescript // tests/converters/ffmpeg.test.ts -import { describe, it, expect } from 'bun:test'; -import { convertVideo } from '@/converters/ffmpeg'; +import { describe, it, expect } from "bun:test"; +import { convertVideo } from "@/converters/ffmpeg"; -describe('FFmpeg Converter', () => { - it('should convert MP4 to WebM', async () => { - const result = await convertVideo('input.mp4', 'webm'); +describe("FFmpeg Converter", () => { + it("should convert MP4 to WebM", async () => { + const result = await convertVideo("input.mp4", "webm"); expect(result.success).toBe(true); }); }); @@ -242,16 +242,16 @@ describe('FFmpeg Converter', () => { ### Type 類型 -| Type | 說明 | -|------|------| -| `feat` | 新功能 | -| `fix` | 修復 Bug | -| `docs` | 文件更新 | -| `style` | 程式碼風格（不影響功能） | +| Type | 說明 | +| ---------- | ------------------------ | +| `feat` | 新功能 | +| `fix` | 修復 Bug | +| `docs` | 文件更新 | +| `style` | 程式碼風格（不影響功能） | | `refactor` | 重構（不新增功能或修復） | -| `perf` | 效能優化 | -| `test` | 新增或修改測試 | -| `chore` | 建構或輔助工具變動 | +| `perf` | 效能優化 | +| `test` | 新增或修改測試 | +| `chore` | 建構或輔助工具變動 | ### 範例 @@ -303,9 +303,11 @@ bun format ```markdown ## 變更描述 + 簡述這個 PR 做了什麼。 ## 變更類型 + - [ ] 新功能 - [ ] Bug 修復 - [ ] 文件更新 @@ -313,9 +315,11 @@ bun format - [ ] 其他 ## 測試 + 描述如何測試這些變更。 ## 相關 Issue + Closes #123 ## 截圖（如適用） @@ -358,12 +362,12 @@ bun format ```typescript // ✅ 正確 const formatConverter = (name: string): string => { - return name.toLowerCase() -} + return name.toLowerCase(); +}; // ❌ 錯誤 function formatConverter(name) { - return name.toLowerCase(); + return name.toLowerCase(); } ``` @@ -388,16 +392,16 @@ cargo clippy ```typescript // src/converters/myconverter.ts - import { Converter } from './types' + import { Converter } from "./types"; export const myConverter: Converter = { - name: 'myconverter', - inputFormats: ['xyz', 'abc'], - outputFormats: ['pdf', 'png'], + name: "myconverter", + inputFormats: ["xyz", "abc"], + outputFormats: ["pdf", "png"], convert: async (input, output, options) => { // 轉換邏輯 - } - } + }, + }; ``` 3. 在 `src/converters/main.ts` 註冊 diff --git a/docs/08-授權說明.md b/docs/08-授權說明.md index 012f1b5..9caf07a 100644 --- a/docs/08-授權說明.md +++ b/docs/08-授權說明.md @@ -16,11 +16,11 @@ ConvertX-CN 專案採用 **GNU Affero General Public License v3.0 (AGPL-3.0)** ## 授權摘要 -| 項目 | 說明 | -|------|------| -| **授權類型** | AGPL-3.0 | +| 項目 | 說明 | +| ------------ | --------------------- | +| **授權類型** | AGPL-3.0 | | **授權檔案** | [LICENSE](../LICENSE) | -| **適用範圍** | 整個專案所有程式碼 | +| **適用範圍** | 整個專案所有程式碼 | --- @@ -53,6 +53,7 @@ ConvertX-CN 專案採用 **GNU Affero General Public License v3.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 授權 @@ -68,12 +70,14 @@ ConvertX-CN 專案採用 **GNU Affero General Public License v3.0 (AGPL-3.0)** **這是 AGPL 與 GPL 的主要差異：** 如果您將修改後的版本部署為網路服務（如 SaaS），您必須： + - 向服務使用者提供取得原始碼的方式 - 原始碼必須包含您的所有修改 ### 📋 標明變更 如果您修改了程式碼： + - 必須標明您做了哪些修改 - 必須標明修改日期 @@ -88,6 +92,7 @@ ConvertX-CN 專案採用 **GNU Affero General Public License v3.0 (AGPL-3.0)** ### Q: 我修改了程式碼後部署在公司內部，需要公開嗎？ **A: 視情況而定** + - 如果只有公司內部員工使用 → 不需要公開 - 如果對外提供服務（客戶可存取）→ 需要公開 @@ -102,6 +107,7 @@ ConvertX-CN 專案採用 **GNU Affero General Public License v3.0 (AGPL-3.0)** ### Q: 如果我將 ConvertX-CN 作為 SaaS 服務提供，需要做什麼？ **A: 您需要**： + 1. 在服務中提供原始碼下載連結 2. 包含您對程式碼的所有修改 3. 使用 AGPL-3.0 授權 @@ -114,29 +120,29 @@ ConvertX-CN 使用了多個第三方開源元件，各元件的授權如下： ### 上游專案 -| 專案 | 授權 | -|------|------| +| 專案 | 授權 | +| ----------------------------------------------- | -------- | | [ConvertX](https://github.com/C4illin/ConvertX) | AGPL-3.0 | ### 轉換引擎 -| 元件 | 授權 | -|------|------| -| FFmpeg | LGPL / GPL | -| ImageMagick | Apache 2.0 | -| LibreOffice | MPL 2.0 | -| Pandoc | GPL 2.0 | -| Calibre | GPL 3.0 | +| 元件 | 授權 | +| ------------- | ---------- | +| FFmpeg | LGPL / GPL | +| ImageMagick | Apache 2.0 | +| LibreOffice | MPL 2.0 | +| Pandoc | GPL 2.0 | +| Calibre | GPL 3.0 | | Tesseract OCR | Apache 2.0 | ### 框架與函式庫 -| 元件 | 授權 | -|------|------| -| Bun | MIT | -| Elysia | MIT | -| React | MIT | -| TailwindCSS | MIT | +| 元件 | 授權 | +| ----------- | ---- | +| Bun | MIT | +| Elysia | MIT | +| React | MIT | +| TailwindCSS | MIT | --- @@ -145,6 +151,7 @@ ConvertX-CN 使用了多個第三方開源元件，各元件的授權如下： 完整的 AGPL-3.0 授權文字請參閱專案根目錄的 [LICENSE](../LICENSE) 檔案。 您也可以在以下網址查看： + - [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) diff --git a/docs/說明文件.md b/docs/說明文件.md index 681b568..e3a77f4 100644 --- a/docs/說明文件.md +++ b/docs/說明文件.md @@ -6,17 +6,17 @@ ## 📚 文件目錄 -| 章節 | 說明 | -|------|------| -| [00-專案總覽](00-專案總覽.md) | 專案定位、功能特色、版本比較 | -| [01-快速開始](01-快速開始.md) | 5 分鐘部署完成 | -| [02-部署指南](02-部署指南.md) | Docker 設定、反向代理、HTTPS | -| [03-環境變數與設定](03-環境變數與設定.md) | 所有可用設定與推薦值 | -| [04-功能總覽](04-功能總覽.md) | 轉換器、OCR、PDF 翻譯 | -| [05-API文件](05-API文件.md) | REST & GraphQL API | -| [06-錯誤排查與支援](06-錯誤排查與支援.md) | 常見問題與解決方案 | -| [07-開發與貢獻指南](07-開發與貢獻指南.md) | 專案結構、貢獻規範 | -| [08-授權說明](08-授權說明.md) | AGPL-3.0 授權 | +| 章節 | 說明 | +| ----------------------------------------- | ---------------------------- | +| [00-專案總覽](00-專案總覽.md) | 專案定位、功能特色、版本比較 | +| [01-快速開始](01-快速開始.md) | 5 分鐘部署完成 | +| [02-部署指南](02-部署指南.md) | Docker 設定、反向代理、HTTPS | +| [03-環境變數與設定](03-環境變數與設定.md) | 所有可用設定與推薦值 | +| [04-功能總覽](04-功能總覽.md) | 轉換器、OCR、PDF 翻譯 | +| [05-API文件](05-API文件.md) | REST & GraphQL API | +| [06-錯誤排查與支援](06-錯誤排查與支援.md) | 常見問題與解決方案 | +| [07-開發與貢獻指南](07-開發與貢獻指南.md) | 專案結構、貢獻規範 | +| [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) | 可直接使用的配置檔 | +| [範例配置/說明文件.md](範例配置/說明文件.md) | 可直接使用的配置檔 | ### 功能說明 -| 文件 | 說明 | -|------|------| -| [功能說明/轉換器.md](功能說明/轉換器.md) | 所有轉換器詳細資訊 | -| [功能說明/OCR.md](功能說明/OCR.md) | OCR 功能說明 | -| [功能說明/翻譯功能.md](功能說明/翻譯功能.md) | PDF 翻譯功能 | +| 文件 | 說明 | +| -------------------------------------------- | ------------------ | +| [功能說明/轉換器.md](功能說明/轉換器.md) | 所有轉換器詳細資訊 | +| [功能說明/OCR.md](功能說明/OCR.md) | OCR 功能說明 | +| [功能說明/翻譯功能.md](功能說明/翻譯功能.md) | PDF 翻譯功能 | ### 開發相關 -| 文件 | 說明 | -|------|------| +| 文件 | 說明 | +| -------------------------------------------- | -------------- | | [開發指南/專案結構.md](開發指南/專案結構.md) | 程式碼結構說明 | -| [開發指南/貢獻指南.md](開發指南/貢獻指南.md) | 如何參與專案 | -| [API/總覽.md](API/總覽.md) | API 詳細說明 | +| [開發指南/貢獻指南.md](開發指南/貢獻指南.md) | 如何參與專案 | +| [API/總覽.md](API/總覽.md) | API 詳細說明 | ---