From caecb2e001014466f6120aab83adba4e5dc053df Mon Sep 17 00:00:00 2001 From: Your Name Date: Sun, 25 Jan 2026 16:09:58 +0800 Subject: [PATCH] =?UTF-8?q?=E6=96=B0=E5=A2=9E=E9=8C=AF=E8=AA=A4=E6=8E=92?= =?UTF-8?q?=E6=9F=A5=E8=88=87=E6=94=AF=E6=8F=B4=E6=96=87=E4=BB=B6=EF=BC=8C?= =?UTF-8?q?=E6=8F=90=E4=BE=9B=E5=B8=B8=E8=A6=8B=E5=95=8F=E9=A1=8C=E8=A7=A3?= =?UTF-8?q?=E6=B1=BA=E6=96=B9=E6=A1=88=EF=BC=9B=E6=96=B0=E5=A2=9E=E9=96=8B?= =?UTF-8?q?=E7=99=BC=E8=88=87=E8=B2=A2=E7=8D=BB=E6=8C=87=E5=8D=97=EF=BC=8C?= =?UTF-8?q?=E8=AA=AA=E6=98=8E=E5=B0=88=E6=A1=88=E7=B5=90=E6=A7=8B=E8=88=87?= =?UTF-8?q?=E9=96=8B=E7=99=BC=E6=B5=81=E7=A8=8B=EF=BC=9B=E6=96=B0=E5=A2=9E?= =?UTF-8?q?=E6=8E=88=E6=AC=8A=E8=AA=AA=E6=98=8E=E6=96=87=E4=BB=B6=EF=BC=8C?= =?UTF-8?q?=E8=A9=B3=E8=BF=B0AGPL-3.0=E6=8E=88=E6=AC=8A=E6=A2=9D=E6=AC=BE?= =?UTF-8?q?=E5=8F=8A=E7=AC=AC=E4=B8=89=E6=96=B9=E5=85=83=E4=BB=B6=E4=BD=BF?= =?UTF-8?q?=E7=94=A8=E6=83=85=E6=B3=81=E3=80=82?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- LICENSE-AUTHOR | 65 ----- LICENSE-OVERVIEW.md | 125 --------- README.md | 72 ++--- docs/00-專案總覽.md | 154 +++++++++++ docs/01-快速開始.md | 229 ++++++++++++++++ docs/02-部署指南.md | 380 ++++++++++++++++++++++++++ docs/03-環境變數與設定.md | 444 +++++++++++++++++++++++++++++++ docs/04-功能總覽.md | 370 ++++++++++++++++++++++++++ docs/05-API文件.md | 547 ++++++++++++++++++++++++++++++++++++++ docs/06-錯誤排查與支援.md | 415 +++++++++++++++++++++++++++++ docs/07-開發與貢獻指南.md | 455 +++++++++++++++++++++++++++++++ docs/08-授權說明.md | 190 +++++++++++++ docs/說明文件.md | 192 ++++--------- 13 files changed, 3269 insertions(+), 369 deletions(-) delete mode 100644 LICENSE-AUTHOR delete mode 100644 LICENSE-OVERVIEW.md create mode 100644 docs/00-專案總覽.md create mode 100644 docs/01-快速開始.md create mode 100644 docs/02-部署指南.md create mode 100644 docs/03-環境變數與設定.md create mode 100644 docs/04-功能總覽.md create mode 100644 docs/05-API文件.md create mode 100644 docs/06-錯誤排查與支援.md create mode 100644 docs/07-開發與貢獻指南.md create mode 100644 docs/08-授權說明.md diff --git a/LICENSE-AUTHOR b/LICENSE-AUTHOR deleted file mode 100644 index 277b114..0000000 --- a/LICENSE-AUTHOR +++ /dev/null @@ -1,65 +0,0 @@ -# ConvertX-CN Author License - -# Custom Non-Commercial License for Original Components - -Copyright (c) 2024-2026 ConvertX-CN Author (pi-docket) - -## Definitions - -- "Original Components" refers to all code, UI designs, i18n translations, - documentation, and features created specifically for ConvertX-CN that are - NOT derived from the upstream ConvertX project. -- "Commercial Use" includes but is not limited to: - - Selling or licensing the software - - Using the software as part of a paid SaaS offering - - Using the software in a revenue-generating business context - - Incorporating the software into a commercial product - -## Grant of Rights - -Permission is hereby granted, free of charge, to any person obtaining a copy -of the Original Components, to use, copy, modify, and distribute for: - -1. **Personal Use** ✅ - Using for personal, non-commercial purposes -2. **Educational Use** ✅ - Using for learning, teaching, or academic research -3. **Non-Commercial Research** ✅ - Using for scientific or technical research - without commercial intent - -## Restrictions - -The following uses are **PROHIBITED** without explicit written permission: - -1. ❌ Commercial use of any kind -2. ❌ SaaS deployment for paying customers -3. ❌ Integration into commercial products or services -4. ❌ Reselling or sublicensing - -## Commercial Licensing - -If you wish to use the Original Components for commercial purposes, you must -obtain a commercial license from the author. - -### Contact for Commercial Licensing - -- **GitHub**: https://github.com/pi-docket -- **Issues**: https://github.com/pi-docket/ConvertX-CN/issues -- **Discussions**: https://github.com/pi-docket/ConvertX-CN/discussions - -Please open an issue or discussion with the title "[Commercial License Request]" -to initiate the licensing process. - -## Disclaimer - -THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR -IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, -FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE -AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER -LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, -OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE -SOFTWARE. - -## Relationship with AGPL-3.0 - -This license applies ONLY to the Original Components created by the -ConvertX-CN author. All upstream components derived from C4illin/ConvertX -remain licensed under GNU AGPL v3.0, and those obligations still apply. diff --git a/LICENSE-OVERVIEW.md b/LICENSE-OVERVIEW.md deleted file mode 100644 index 8ee32d0..0000000 --- a/LICENSE-OVERVIEW.md +++ /dev/null @@ -1,125 +0,0 @@ -# License Overview - -This project uses a **Mixed License / Source-Available** model. - ---- - -## 📋 Quick Summary - -| Component Type | License | Commercial Use | -| ------------------------ | --------------------- | -------------------------------- | -| Upstream (from ConvertX) | AGPL-3.0 | ✅ Allowed (with source sharing) | -| Author Original | Custom Non-Commercial | ❌ Requires Permission | - ---- - -## 1. Upstream Components (AGPL-3.0) - -### What's Covered - -Core functionality derived from [C4illin/ConvertX](https://github.com/C4illin/ConvertX): - -- Base application architecture -- Original converter integrations -- Core API structure - -### Your Obligations - -Under AGPL-3.0, if you modify and deploy this software as a network service: - -1. ✅ You must make your modified source code available -2. ✅ You must include the AGPL-3.0 license -3. ✅ You must state your changes - -### Full License - -See [LICENSE](LICENSE) for the complete AGPL-3.0 text. - ---- - -## 2. Author Original Components (Custom Non-Commercial) - -### What's Covered - -All original work created by the ConvertX-CN author: - -- 🌐 **i18n / Localization** - 65+ language translations -- 🎨 **UI Enhancements** - Custom interface improvements -- 📊 **PDF Translation** - PDFMathTranslate, BabelDOC integrations -- 📄 **MinerU Integration** - PDF to Markdown conversion -- 🔧 **New Converters** - Additional format support -- 📚 **Documentation** - Chinese documentation -- 🐳 **Docker Optimizations** - Multi-arch builds, CJK fonts - -### Permissions - -| Use Case | Allowed? | -| ----------------------- | ------------------------ | -| Personal use | ✅ Yes | -| Educational use | ✅ Yes | -| Non-commercial research | ✅ Yes | -| Commercial / SaaS | ❌ No (requires license) | - -### Full License - -See [LICENSE-AUTHOR](LICENSE-AUTHOR) for the complete terms. - ---- - -## 🤝 Commercial Licensing - -If you want to use ConvertX-CN in a commercial context: - -### Contact Methods - -1. **GitHub Issues**: https://github.com/pi-docket/ConvertX-CN/issues - - Create an issue with title: `[Commercial License Request]` - -2. **GitHub Discussions**: https://github.com/pi-docket/ConvertX-CN/discussions - - Start a discussion in the appropriate category - -3. **GitHub Profile**: https://github.com/pi-docket - - Check profile for additional contact information - -### What to Include - -When requesting a commercial license, please provide: - -- Company/Organization name -- Intended use case -- Expected scale of deployment -- Contact information - ---- - -## ❓ FAQ - -### Q: Can I self-host for my company's internal use? - -**A:** Internal use without external revenue generation is generally permitted. -If unsure, please contact us. - -### Q: Can I offer this as a paid service? - -**A:** No. You need a commercial license for SaaS or paid services. - -### Q: Do I need to share my modifications? - -**A:** For AGPL-3.0 components: Yes, if you deploy as a network service. -For author components: Depends on your license agreement. - -### Q: Can I fork and create my own version? - -**A:** Yes, but: - -- AGPL-3.0 components must remain AGPL-3.0 -- Author components cannot be used commercially without permission - ---- - -## 📞 Contact - -- **GitHub**: [@pi-docket](https://github.com/pi-docket) -- **Repository**: [ConvertX-CN](https://github.com/pi-docket/ConvertX-CN) -- **Issues**: [Report Issues](https://github.com/pi-docket/ConvertX-CN/issues) -- **Discussions**: [Community](https://github.com/pi-docket/ConvertX-CN/discussions) diff --git a/README.md b/README.md index bf69d50..5979426 100644 --- a/README.md +++ b/README.md @@ -6,8 +6,7 @@ [![Docker Pulls](https://img.shields.io/docker/pulls/convertx/convertx-cn?style=flat&logo=docker)](https://hub.docker.com/r/convertx/convertx-cn) [![GitHub Release](https://img.shields.io/github/v/release/pi-docket/ConvertX-CN)](https://github.com/pi-docket/ConvertX-CN/releases) -![License AGPL-3.0](https://img.shields.io/badge/license-AGPL--3.0-blue) -![Source Available](https://img.shields.io/badge/source-available-green) +[![License AGPL-3.0](https://img.shields.io/badge/license-AGPL--3.0-blue)](LICENSE) ![Docker Image Size (Latest Lite)]() --- @@ -17,7 +16,7 @@ | 特色 | 說明 | | ----------------- | --------------------------------------- | | 📁 **1000+ 格式** | 文件、圖片、影音、電子書一次搞定 | -| 🔧 **20+ 引擎** | LibreOffice、FFmpeg、Pandoc 全到位 | +| 🔧 **25+ 引擎** | LibreOffice、FFmpeg、Pandoc 全到位 | | 🈶 **中文優化** | 內建中日韓字型與 OCR，告別亂碼 | | 🌐 **65 種語言** | 跨國團隊無障礙使用 | | 📊 **PDF 翻譯** | PDFMathTranslate + BabelDOC 雙引擎 | @@ -25,18 +24,21 @@ --- -## 📚 文件 +## 📚 文件目錄 -完整文件請參閱 **[文件中心](docs/README.md)** +完整文件請參閱 **[專案總覽](docs/00-專案總覽.md)** -| 分類 | 連結 | -| ----------- | -------------------------------------------------------------------------------------------------------- | -| 🚀 快速入門 | [概覽](docs/快速入門/概覽.md) · [快速開始](docs/快速入門/快速開始.md) · [FAQ](docs/快速入門/常見問題.md) | -| 🐳 部署指南 | [Docker](docs/部署指南/Docker.md) · [反向代理](docs/部署指南/反向代理.md) | -| ⚙️ 配置設定 | [環境變數](docs/配置設定/環境變數.md) · [安全性](docs/配置設定/安全性.md) | -| 🔌 功能說明 | [轉換器](docs/功能說明/轉換器.md) · [OCR](docs/功能說明/OCR.md) · [翻譯](docs/功能說明/翻譯.md) | -| 🔗 API | [API 總覽](docs/API/總覽.md) · [端點說明](docs/API/端點.md) | -| 👩‍💻 開發 | [專案結構](docs/開發指南/專案結構.md) · [貢獻指南](docs/開發指南/貢獻指南.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) | --- @@ -190,38 +192,40 @@ docker run -d \ convertx/convertx-cn:latest-lite ``` -> 📖 詳細說明請參閱 [Lite 版部署指南](docs/部署指南/Docker-Lite.md) +> 📖 詳細說明請參閱 [部署指南](docs/02-部署指南.md) --- -## 📄 License Overview +## 📄 授權 -**This is a Mixed License / Source-Available Project.** +本專案採用 **[GNU Affero General Public License v3.0 (AGPL-3.0)](LICENSE)** 授權。 -### 1. Upstream Components +### 授權摘要 -Core components derived from [C4illin/ConvertX](https://github.com/C4illin/ConvertX) are licensed under **[GNU AGPL v3.0](LICENSE)**. +| 權利 | 說明 | +|------|------| +| ✅ 自由使用 | 個人、商業、教育用途均可 | +| ✅ 自由修改 | 可修改原始碼 | +| ✅ 自由分發 | 可重新分發 | -- Any modifications to these files are open source under AGPL-3.0. +### 義務 -### 2. Author Original Components +- 分發時需保留授權聲明 +- 修改後需公開原始碼 +- 網路服務需提供原始碼取得方式 +- 衍生作品需使用相同授權 -Original modules, UI, i18n, and new features created by the ConvertX-CN author are licensed under **[Custom Non-Commercial License](LICENSE-AUTHOR)**. +> 📖 詳細說明請參閱 [授權說明](docs/08-授權說明.md) -| 使用情境 | 是否允許 | -| --------------- | --------- | -| 個人使用 | ✅ 允許 | -| 教育/研究 | ✅ 允許 | -| 商業使用 / SaaS | ❌ 需授權 | +--- -### 📞 商業授權聯繫 +## 🙏 致謝 -如需商業授權，請透過以下方式聯繫： +本專案基於 [C4illin/ConvertX](https://github.com/C4illin/ConvertX) 開發，感謝原作者的貢獻。 -- **GitHub Issues**: [建立 Issue](https://github.com/pi-docket/ConvertX-CN/issues) (標題請加上 `[Commercial License Request]`) +--- + +## 📞 聯繫方式 + +- **GitHub Issues**: [建立 Issue](https://github.com/pi-docket/ConvertX-CN/issues) - **GitHub Discussions**: [社群討論](https://github.com/pi-docket/ConvertX-CN/discussions) -- **GitHub Profile**: [@pi-docket](https://github.com/pi-docket) - -> ⚠️ **Commercial Usage**: If you plan to use this project in a commercial product, SaaS, or revenue-generating service, you **must contact the author** for a license exception regarding the custom components. The AGPL obligations (sharing source code) still apply to the upstream portions. - -📄 完整授權說明 → [LICENSE-OVERVIEW.md](LICENSE-OVERVIEW.md) diff --git a/docs/00-專案總覽.md b/docs/00-專案總覽.md new file mode 100644 index 0000000..3b3d2c1 --- /dev/null +++ b/docs/00-專案總覽.md @@ -0,0 +1,154 @@ +# 專案總覽 + +ConvertX-CN 是一個**開箱即用的全功能檔案轉換服務**，基於 [C4illin/ConvertX](https://github.com/C4illin/ConvertX) 衍生開發，專注於**中文使用者體驗優化**與**進階 PDF 處理能力**。 + +--- + +## 目錄 + +- [專案定位與目標](#專案定位與目標) +- [ConvertX-CN 與原始 ConvertX 的差異](#convertx-cn-與原始-convertx-的差異) +- [支援格式總覽](#支援格式總覽) +- [版本選擇](#版本選擇) +- [相關文件](#相關文件) + +--- + +## 專案定位與目標 + +### 🎯 核心目標 + +1. **開箱即用**：一個 Docker 命令，5 分鐘內完成部署 +2. **中文優化**：內建中日韓字型與 OCR，告別亂碼問題 +3. **全格式支援**：文件、圖片、影音、電子書，一站式轉換 +4. **PDF 進階處理**：翻譯（保留公式）、智能擷取（保留表格、圖片） + +### 🌟 專案特色 + +| 特色 | 說明 | +|------|------| +| 📁 **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 | + +### 新增功能清單 + +- ✅ **PDFMathTranslate**：翻譯 PDF 並保留數學公式與排版 +- ✅ **BabelDOC**：進階 PDF 翻譯與轉換 +- ✅ **MinerU**：PDF 轉 Markdown（智能擷取表格、公式、圖片） +- ✅ **OCRmyPDF**：PDF OCR 文字辨識 +- ✅ **完整 CJK 字型**：思源黑體、思源宋體 +- ✅ **65 種介面語言**：自動偵測或手動切換 + +--- + +## 支援格式總覽 + +### 按類型分類 + +| 類型 | 轉換器 | 支援格式數 | +|------|--------|-----------| +| 🎬 **影音** | 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 | + +--- + +## 版本選擇 + +ConvertX-CN 提供三個版本，滿足不同需求： + +| 特性 | Lite 版 | 一般版（推薦） | Full 版 | +|------|---------|---------------|---------| +| **Image 大小** | ~3 GB | ~7 GB | ~15 GB | +| **部署速度** | 最快 | 中等 | 較慢 | +| **適用對象** | 輕量使用者 | 一般使用者 | 進階/多語言 | +| **基本轉檔** | ✅ | ✅ | ✅ | +| **OCR（7語言）** | ❌ | ✅ | ✅ | +| **PDF 翻譯** | ❌ | ✅ | ✅ | +| **MinerU AI** | ❌ | ✅ | ✅ | +| **OCR（65語言）** | ❌ | ❌ | ✅ | +| **完整 TexLive** | ❌ | ❌ | ✅ | + +### Docker Tag 說明 + +| Tag | 說明 | +|-----|------| +| `latest` | 一般版最新穩定版 | +| `latest-lite` | Lite 版最新穩定版 | +| `latest-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 授權 | + +--- + +[⬆️ 回到頂部](#專案總覽) diff --git a/docs/01-快速開始.md b/docs/01-快速開始.md new file mode 100644 index 0000000..8e4f2b8 --- /dev/null +++ b/docs/01-快速開始.md @@ -0,0 +1,229 @@ +# 快速開始 + +5 分鐘內完成 ConvertX-CN 部署，開始轉換檔案。 + +--- + +## 目錄 + +- [前置需求](#前置需求) +- [Docker Run（最快）](#docker-run最快) +- [Docker Compose（推薦）](#docker-compose推薦) +- [首次登入](#首次登入) +- [範例：轉換檔案](#範例轉換檔案) +- [下一步](#下一步) + +--- + +## 前置需求 + +| 需求 | 最低規格 | 建議規格 | +|------|---------|---------| +| 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/) + +--- + +## Docker Run（最快） + +### 步驟 1：建立資料夾 + +```bash +# Linux / macOS +mkdir -p ~/convertx-cn/data && cd ~/convertx-cn + +# Windows PowerShell +mkdir C:\convertx-cn\data -Force; cd C:\convertx-cn + +# Windows CMD +mkdir C:\convertx-cn\data +cd C:\convertx-cn +``` + +### 步驟 2：啟動容器 + +```bash +docker run -d \ + --name convertx-cn \ + --restart unless-stopped \ + -p 3000:3000 \ + -v ./data:/app/data \ + -e TZ=Asia/Taipei \ + -e JWT_SECRET=Xk9mPqL2vN7wR4tY6uI8oA3sD5fG1hJ0 \ + convertx/convertx-cn:latest +``` + +> ⚠️ **安全提醒**：正式環境請更換 `JWT_SECRET` 為自己的隨機字串（至少 32 字元） + +### 步驟 3：開始使用 + +開啟瀏覽器：**http://localhost:3000** + +--- + +## Docker Compose（推薦） + +### 步驟 1：建立專案資料夾 + +```bash +mkdir -p ~/convertx-cn && cd ~/convertx-cn +``` + +### 步驟 2：建立配置檔 + +建立 `docker-compose.yml` 檔案： + +```yaml +services: + convertx: + image: convertx/convertx-cn:latest + container_name: convertx-cn + restart: unless-stopped + ports: + - "3000:3000" + volumes: + - ./data:/app/data + environment: + - TZ=Asia/Taipei + - JWT_SECRET=請更換為一個長且隨機的字串至少32字元 +``` + +### 步驟 3：啟動服務 + +```bash +docker compose up -d +``` + +### 步驟 4：驗證安裝 + +```bash +# 檢查容器狀態 +docker ps + +# 查看日誌 +docker logs convertx-cn +``` + +應該看到類似輸出： + +``` +🦊 Elysia is running at http://localhost:3000 +``` + +--- + +## 首次登入 + +1. 開啟瀏覽器，訪問 **http://localhost:3000** + +2. 點擊右上角 **Register**（註冊） + +3. 輸入您的 Email 和密碼 + +4. 完成註冊後自動登入 + +### 登入流程圖示 + +``` +┌─────────────────────────────────────────────────────────────┐ +│ ConvertX-CN │ +│ │ +│ ┌──────────────────────────────────────────────────────┐ │ +│ │ │ │ +│ │ 📧 Email: user@example.com │ │ +│ │ │ │ +│ │ 🔒 Password: •••••••••• │ │ +│ │ │ │ +│ │ [ Register ] [ Login ] │ │ +│ │ │ │ +│ └──────────────────────────────────────────────────────┘ │ +│ │ +└─────────────────────────────────────────────────────────────┘ +``` + +--- + +## 範例：轉換檔案 + +### 範例 1：Word 轉 PDF + +1. 點擊「選擇檔案」或拖放 `.docx` 檔案 +2. 選擇輸出格式：`PDF` +3. 點擊「轉換」 +4. 下載轉換後的 PDF 檔案 + +**輸入：** +``` +report.docx (Microsoft Word 文件) +``` + +**輸出：** +``` +report.pdf (PDF 文件) +``` + +### 範例 2：影片轉換 + +1. 上傳 `.mov` 影片檔案 +2. 選擇輸出格式：`MP4` +3. 點擊「轉換」 + +**輸入：** +``` +video.mov (QuickTime 影片, 500 MB) +``` + +**輸出：** +``` +video.mp4 (MP4 影片, 壓縮後約 200 MB) +``` + +### 範例 3：PDF 翻譯（保留公式） + +1. 上傳學術論文 PDF +2. 選擇「PDF 翻譯」功能 +3. 選擇目標語言：繁體中文 +4. 點擊「翻譯」 + +**輸入：** +``` +paper.pdf (英文學術論文，含數學公式) +``` + +**輸出：** +``` +paper_translated.pdf (中文翻譯，公式與排版保留) +``` + +--- + +## 常見問題快查 + +| 問題 | 解決方法 | +|------|---------| +| 登入後被踢回登入頁 | 加上 `HTTP_ALLOWED=true` 或 `TRUST_PROXY=true` | +| 重啟後資料消失 | 確認 `./data:/app/data` 且資料夾存在 | +| 重啟後被登出 | 設定固定的 `JWT_SECRET` | +| 中文顯示亂碼 | 使用一般版或 Full 版（含完整字型） | +| 轉換時間過長 | 增加容器記憶體限制或升級硬體 | + +> 📖 更多問題請參閱 [06-錯誤排查與支援](06-錯誤排查與支援.md) + +--- + +## 下一步 + +| 需求 | 推薦閱讀 | +|------|---------| +| 詳細部署設定 | [02-部署指南](02-部署指南.md) | +| 環境變數設定 | [03-環境變數與設定](03-環境變數與設定.md) | +| 了解所有功能 | [04-功能總覽](04-功能總覽.md) | +| API 整合 | [05-API文件](05-API文件.md) | + +--- + +[⬆️ 回到頂部](#快速開始) | [📚 回到目錄](00-專案總覽.md) diff --git a/docs/02-部署指南.md b/docs/02-部署指南.md new file mode 100644 index 0000000..219b6c6 --- /dev/null +++ b/docs/02-部署指南.md @@ -0,0 +1,380 @@ +# 部署指南 + +詳細說明 ConvertX-CN 的各種部署方式與進階配置。 + +--- + +## 目錄 + +- [本地部署步驟](#本地部署步驟) +- [Docker 設定](#docker-設定) +- [反向代理設定](#反向代理設定) +- [HTTPS 設定](#https-設定) +- [更新與維護](#更新與維護) + +--- + +## 本地部署步驟 + +### 系統需求 + +| 項目 | 最低需求 | 建議配置 | +|------|---------|---------| +| CPU | 2 核心 | 4 核心以上 | +| 記憶體 | 4 GB | 8 GB 以上 | +| 磁碟空間 | 10 GB | 30 GB SSD | +| 網路 | 10 Mbps | 100 Mbps | + +### 準備工作 + +1. **安裝 Docker** + + ```bash + # 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 + sudo systemctl enable docker + ``` + +2. **建立專案目錄** + + ```bash + mkdir -p ~/convertx-cn/data + cd ~/convertx-cn + ``` + +3. **產生 JWT 密鑰** + + ```bash + # Linux / macOS + openssl rand -hex 32 + + # Windows PowerShell + -join ((1..32) | ForEach-Object { '{0:x2}' -f (Get-Random -Max 256) }) + ``` + +--- + +## Docker 設定 + +### 基本部署 + +```yaml +# docker-compose.yml +services: + convertx: + image: convertx/convertx-cn:latest + container_name: convertx-cn + restart: unless-stopped + ports: + - "3000:3000" + volumes: + - ./data:/app/data + environment: + - TZ=Asia/Taipei + - JWT_SECRET=您的隨機密鑰至少32字元 +``` + +### 進階部署（含資源限制） + +```yaml +# docker-compose.yml +services: + convertx: + image: convertx/convertx-cn:latest + container_name: convertx-cn + restart: unless-stopped + ports: + - "3000:3000" + volumes: + - ./data:/app/data + environment: + - TZ=Asia/Taipei + - JWT_SECRET=您的隨機密鑰至少32字元 + - MAX_CONVERT_PROCESS=4 + - AUTO_DELETE_EVERY_N_HOURS=12 + deploy: + resources: + limits: + cpus: '4' + memory: 8G + reservations: + cpus: '2' + memory: 4G + healthcheck: + test: ["CMD", "curl", "-f", "http://localhost:3000/health"] + interval: 30s + timeout: 10s + retries: 3 +``` + +### Lite 版部署 + +適用於資源有限或只需要基本轉換功能的環境： + +```yaml +# docker-compose.yml +services: + convertx: + image: convertx/convertx-cn:latest-lite + container_name: convertx-cn-lite + restart: unless-stopped + ports: + - "3000:3000" + volumes: + - ./data:/app/data + environment: + - TZ=Asia/Taipei + - JWT_SECRET=您的隨機密鑰至少32字元 +``` + +### 環境變數說明 + +| 變數 | 說明 | 預設值 | +|------|------|--------| +| `JWT_SECRET` | 登入驗證金鑰（**必填**） | 隨機（每次重啟變） | +| `TZ` | 時區 | `UTC` | +| `HTTP_ALLOWED` | 允許 HTTP 連線 | `false` | +| `TRUST_PROXY` | 信任反向代理 | `false` | + +> 📖 完整變數列表請參閱 [03-環境變數與設定](03-環境變數與設定.md) + +--- + +## 反向代理設定 + +### Nginx 設定 + +```nginx +# /etc/nginx/sites-available/convertx +server { + listen 80; + server_name convertx.example.com; + return 301 https://$server_name$request_uri; +} + +server { + listen 443 ssl http2; + server_name convertx.example.com; + + # SSL 憑證（Let's Encrypt） + ssl_certificate /etc/letsencrypt/live/convertx.example.com/fullchain.pem; + ssl_certificate_key /etc/letsencrypt/live/convertx.example.com/privkey.pem; + + # SSL 安全設定 + ssl_protocols TLSv1.2 TLSv1.3; + ssl_prefer_server_ciphers on; + ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256; + + # 檔案上傳大小限制 + client_max_body_size 500M; + + # 超時設定（大檔案轉換需要） + proxy_read_timeout 3600s; + proxy_send_timeout 3600s; + + location / { + proxy_pass http://127.0.0.1:3000; + proxy_http_version 1.1; + + # 必要的 headers + proxy_set_header Host $host; + proxy_set_header X-Real-IP $remote_addr; + proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; + proxy_set_header X-Forwarded-Proto $scheme; + + # WebSocket 支援 + proxy_set_header Upgrade $http_upgrade; + proxy_set_header Connection "upgrade"; + } +} +``` + +**啟用設定：** + +```bash +sudo ln -s /etc/nginx/sites-available/convertx /etc/nginx/sites-enabled/ +sudo nginx -t +sudo systemctl reload nginx +``` + +### Traefik 設定 + +```yaml +# docker-compose.yml +services: + convertx: + image: convertx/convertx-cn:latest + container_name: convertx-cn + restart: unless-stopped + volumes: + - ./data:/app/data + environment: + - JWT_SECRET=${JWT_SECRET} + - TRUST_PROXY=true + - HTTP_ALLOWED=false + labels: + - "traefik.enable=true" + - "traefik.http.routers.convertx.rule=Host(`convertx.example.com`)" + - "traefik.http.routers.convertx.entrypoints=websecure" + - "traefik.http.routers.convertx.tls.certresolver=letsencrypt" + - "traefik.http.services.convertx.loadbalancer.server.port=3000" +``` + +### Caddy 設定 + +``` +# Caddyfile +convertx.example.com { + reverse_proxy localhost:3000 +} +``` + +### 反向代理必要設定 + +使用反向代理時，請確保設定以下環境變數： + +```yaml +environment: + - TRUST_PROXY=true # 信任反向代理的 headers + - HTTP_ALLOWED=false # 反向代理已處理 HTTPS +``` + +--- + +## HTTPS 設定 + +### 使用 Let's Encrypt + +1. **安裝 Certbot** + + ```bash + # Ubuntu / Debian + sudo apt install certbot python3-certbot-nginx + + # CentOS / RHEL + sudo yum install certbot python3-certbot-nginx + ``` + +2. **取得憑證** + + ```bash + sudo certbot --nginx -d convertx.example.com + ``` + +3. **自動續約** + + ```bash + sudo certbot renew --dry-run + ``` + +### 使用自簽憑證（測試用） + +```bash +# 產生自簽憑證 +openssl req -x509 -nodes -days 365 -newkey rsa:2048 \ + -keyout /etc/ssl/private/convertx.key \ + -out /etc/ssl/certs/convertx.crt \ + -subj "/CN=convertx.local" +``` + +--- + +## 更新與維護 + +### 更新至最新版本 + +```bash +# 進入專案目錄 +cd ~/convertx-cn + +# 停止並更新 +docker compose down +docker compose pull +docker compose up -d + +# 清理舊映像檔 +docker image prune -f +``` + +### 備份資料 + +```bash +# 備份資料目錄 +tar -czvf convertx-backup-$(date +%Y%m%d).tar.gz ./data + +# 還原資料 +tar -xzvf convertx-backup-20260125.tar.gz +``` + +### 查看日誌 + +```bash +# 即時日誌 +docker logs -f convertx-cn + +# 最近 100 行 +docker logs --tail 100 convertx-cn + +# 指定時間範圍 +docker logs --since "2026-01-25T00:00:00" convertx-cn +``` + +### 重新啟動 + +```bash +# 重新啟動容器 +docker restart convertx-cn + +# 完全重建 +docker compose down +docker compose up -d --force-recreate +``` + +--- + +## 進階配置 + +### 使用外部資料庫 + +```yaml +services: + convertx: + image: convertx/convertx-cn:latest + environment: + - DATABASE_URL=sqlite:///app/data/mydb.sqlite + volumes: + - ./data:/app/data +``` + +### 設定 API Server + +```yaml +services: + convertx: + image: convertx/convertx-cn:latest + ports: + - "3000:3000" + volumes: + - ./data:/app/data + environment: + - JWT_SECRET=${JWT_SECRET} + + api-server: + image: convertx/convertx-cn-api:latest + ports: + - "3001:3001" + environment: + - JWT_SECRET=${JWT_SECRET} + - API_PORT=3001 + depends_on: + - convertx +``` + +--- + +[⬆️ 回到頂部](#部署指南) | [📚 回到目錄](00-專案總覽.md) diff --git a/docs/03-環境變數與設定.md b/docs/03-環境變數與設定.md new file mode 100644 index 0000000..f078301 --- /dev/null +++ b/docs/03-環境變數與設定.md @@ -0,0 +1,444 @@ +# 環境變數與設定 + +本文件詳細說明 ConvertX-CN 所有可用的環境變數與配置選項。 + +--- + +## 目錄 + +- [必填設定](#必填設定) +- [網路與安全](#網路與安全) +- [一般設定](#一般設定) +- [轉換設定](#轉換設定) +- [PDF 翻譯設定](#pdf-翻譯設定) +- [推薦配置範例](#推薦配置範例) +- [安全性建議](#安全性建議) + +--- + +## 快速參考表 + +### 🔒 安全性設定 + +| 變數 | 必要性 | 說明 | 預設值 | 範例 | +|------|--------|------|--------|------| +| `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` | + +### ⚙️ 轉換設定 + +| 變數 | 必要性 | 說明 | 預設值 | 範例 | +|------|--------|------|--------|------| +| `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` | + +--- + +## 必填設定 + +### JWT_SECRET + +用於簽署登入驗證的密鑰，**強烈建議在正式環境中設定**。 + +| 項目 | 說明 | +|------|------| +| **類型** | 字串 | +| **預設值** | 每次重啟隨機產生 | +| **建議值** | 至少 32 字元的隨機字串 | +| **必要性** | ⭐ 強烈建議 | + +**問題**：若不設定，每次容器重啟後所有使用者都需要重新登入。 + +**產生方式**： + +```bash +# Linux / macOS +openssl rand -hex 32 + +# Windows PowerShell +-join ((1..32) | ForEach-Object { '{0:x2}' -f (Get-Random -Max 256) }) + +# 線上工具 +# 使用任何密碼產生器產生 32 字元以上的隨機字串 +``` + +**使用範例**： + +```yaml +environment: + - JWT_SECRET=a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6 +``` + +--- + +## 網路與安全 + +### HTTP_ALLOWED + +控制是否允許非 HTTPS 連線。 + +| 項目 | 說明 | +|------|------| +| **類型** | 布林值 | +| **預設值** | `false` | +| **可選值** | `true` / `false` | + +**使用情境**： + +| 情境 | 建議設定 | +|------|---------| +| 本地測試 (localhost) | `true` | +| 已設定 HTTPS | `false` | +| 無 HTTPS 但需遠端存取 | `true` | + +> ⚠️ **注意**：設為 `false` 但用 HTTP 存取會導致「登入後又被導回登入頁」 + +```yaml +environment: + - HTTP_ALLOWED=true # 本地開發時使用 +``` + +### TRUST_PROXY + +控制是否信任反向代理的 X-Forwarded-* headers。 + +| 項目 | 說明 | +|------|------| +| **類型** | 布林值 | +| **預設值** | `false` | +| **可選值** | `true` / `false` | + +**使用情境**： + +| 情境 | 建議設定 | +|------|---------| +| 直接存取容器 | `false` | +| 透過 Nginx / Traefik / Caddy | `true` | + +```yaml +environment: + - TRUST_PROXY=true # 使用反向代理時 +``` + +### ACCOUNT_REGISTRATION + +控制是否允許新使用者註冊。 + +| 項目 | 說明 | +|------|------| +| **類型** | 布林值 | +| **預設值** | `true` | +| **可選值** | `true` / `false` | + +```yaml +environment: + - ACCOUNT_REGISTRATION=false # 關閉公開註冊 +``` + +### ALLOW_UNAUTHENTICATED + +控制是否允許未登入的匿名使用者使用轉換功能。 + +| 項目 | 說明 | +|------|------| +| **類型** | 布林值 | +| **預設值** | `false` | +| **可選值** | `true` / `false` | + +```yaml +environment: + - ALLOW_UNAUTHENTICATED=true # 允許匿名使用 +``` + +--- + +## 一般設定 + +### TZ + +設定系統時區，影響日誌時間顯示與自動清理排程。 + +| 項目 | 說明 | +|------|------| +| **類型** | 時區字串 | +| **預設值** | `UTC` | +| **可選值** | [時區列表](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) | + +**常用時區**： + +| 地區 | 時區值 | +|------|--------| +| 台灣 | `Asia/Taipei` | +| 香港 | `Asia/Hong_Kong` | +| 中國大陸 | `Asia/Shanghai` | +| 日本 | `Asia/Tokyo` | +| 美國東部 | `America/New_York` | + +```yaml +environment: + - TZ=Asia/Taipei +``` + +### LANGUAGE + +設定介面預設語言。 + +| 項目 | 說明 | +|------|------| +| **類型** | 語言代碼 | +| **預設值** | `auto`（自動偵測） | +| **可選值** | `zh-TW`, `zh-CN`, `en`, `ja` 等 65 種 | + +```yaml +environment: + - LANGUAGE=zh-TW +``` + +### WEBROOT + +設定子路徑前綴，用於反向代理配置。 + +| 項目 | 說明 | +|------|------| +| **類型** | 路徑字串 | +| **預設值** | 空（根路徑） | + +```yaml +environment: + - WEBROOT=/convertx # 訪問路徑變為 http://example.com/convertx +``` + +### HIDE_HISTORY + +控制是否隱藏轉換歷史紀錄。 + +| 項目 | 說明 | +|------|------| +| **類型** | 布林值 | +| **預設值** | `false` | + +```yaml +environment: + - HIDE_HISTORY=true # 隱藏歷史紀錄 +``` + +--- + +## 轉換設定 + +### AUTO_DELETE_EVERY_N_HOURS + +設定自動刪除轉換檔案的間隔時間（小時）。 + +| 項目 | 說明 | +|------|------| +| **類型** | 數字 | +| **預設值** | `24` | +| **建議範圍** | `1` - `168` | + +```yaml +environment: + - AUTO_DELETE_EVERY_N_HOURS=12 # 每 12 小時清理一次 +``` + +### MAX_CONVERT_PROCESS + +設定最大同時轉換任務數量。 + +| 項目 | 說明 | +|------|------| +| **類型** | 數字 | +| **預設值** | `0`（無限制） | +| **建議值** | CPU 核心數 | + +```yaml +environment: + - MAX_CONVERT_PROCESS=4 # 最多同時 4 個轉換任務 +``` + +### FFMPEG_ARGS 與 FFMPEG_OUTPUT_ARGS + +設定 FFmpeg 的全域參數。 + +| 變數 | 說明 | +|------|------| +| `FFMPEG_ARGS` | 輸入參數（套用於輸入檔案） | +| `FFMPEG_OUTPUT_ARGS` | 輸出參數（套用於輸出檔案） | + +**GPU 加速範例**： + +```yaml +environment: + # NVIDIA GPU 加速 + - FFMPEG_ARGS=-hwaccel cuda + - FFMPEG_OUTPUT_ARGS=-c:v h264_nvenc +``` + +--- + +## PDF 翻譯設定 + +### PDFMATHTRANSLATE_SERVICE + +設定 PDF 翻譯使用的服務。 + +| 項目 | 說明 | +|------|------| +| **類型** | 字串 | +| **預設值** | `google` | +| **可選值** | `google`, `deepl`, `azure` 等 | + +```yaml +environment: + - PDFMATHTRANSLATE_SERVICE=google +``` + +### PDFMATHTRANSLATE_MODELS_PATH + +設定 PDF 翻譯模型的存放路徑。 + +| 項目 | 說明 | +|------|------| +| **類型** | 路徑字串 | +| **預設值** | `/models` | + +```yaml +environment: + - PDFMATHTRANSLATE_MODELS_PATH=/app/models +``` + +--- + +## 推薦配置範例 + +### 本地開發環境 + +```yaml +services: + convertx: + image: convertx/convertx-cn:latest + ports: + - "3000:3000" + volumes: + - ./data:/app/data + environment: + - TZ=Asia/Taipei + - JWT_SECRET=dev-secret-key-for-local-testing + - HTTP_ALLOWED=true + - ACCOUNT_REGISTRATION=true +``` + +### 正式生產環境 + +```yaml +services: + convertx: + image: convertx/convertx-cn:latest + ports: + - "3000:3000" + volumes: + - ./data:/app/data + environment: + - TZ=Asia/Taipei + - JWT_SECRET=${JWT_SECRET} # 使用環境變數或 secrets + - HTTP_ALLOWED=false + - TRUST_PROXY=true # 如果使用反向代理 + - ACCOUNT_REGISTRATION=false # 關閉公開註冊 + - AUTO_DELETE_EVERY_N_HOURS=12 + - MAX_CONVERT_PROCESS=4 + deploy: + resources: + limits: + cpus: '4' + memory: 8G +``` + +### 公開服務（允許匿名） + +```yaml +services: + convertx: + image: convertx/convertx-cn:latest + ports: + - "3000:3000" + volumes: + - ./data:/app/data + environment: + - TZ=Asia/Taipei + - JWT_SECRET=${JWT_SECRET} + - TRUST_PROXY=true + - ALLOW_UNAUTHENTICATED=true + - ACCOUNT_REGISTRATION=false + - AUTO_DELETE_EVERY_N_HOURS=1 # 頻繁清理 + - MAX_CONVERT_PROCESS=2 # 限制資源使用 +``` + +--- + +## 安全性建議 + +### ✅ 必做事項 + +1. **設定固定的 JWT_SECRET** + - 至少 32 字元 + - 使用隨機產生的字串 + - 不要使用範例中的值 + +2. **正式環境關閉 HTTP** + ```yaml + - HTTP_ALLOWED=false + ``` + +3. **使用反向代理處理 HTTPS** + ```yaml + - TRUST_PROXY=true + ``` + +4. **限制註冊功能** + ```yaml + - ACCOUNT_REGISTRATION=false + ``` + +### ⚠️ 注意事項 + +1. **不要在公開網路暴露管理介面** +2. **定期更新 Docker 映像檔** +3. **定期備份 data 目錄** +4. **監控磁碟空間使用** + +### 🔐 進階安全設定 + +```yaml +environment: + - JWT_SECRET=${JWT_SECRET} + - HTTP_ALLOWED=false + - TRUST_PROXY=true + - ACCOUNT_REGISTRATION=false + - ALLOW_UNAUTHENTICATED=false + - AUTO_DELETE_EVERY_N_HOURS=6 +``` + +--- + +[⬆️ 回到頂部](#環境變數與設定) | [📚 回到目錄](00-專案總覽.md) diff --git a/docs/04-功能總覽.md b/docs/04-功能總覽.md new file mode 100644 index 0000000..bfdfe18 --- /dev/null +++ b/docs/04-功能總覽.md @@ -0,0 +1,370 @@ +# 功能總覽 + +ConvertX-CN 內建 25+ 種轉換引擎，支援 1000+ 種檔案格式轉換。 + +--- + +## 目錄 + +- [轉換引擎總覽](#轉換引擎總覽) +- [影音轉換](#影音轉換) +- [圖片處理](#圖片處理) +- [文件轉換](#文件轉換) +- [PDF 進階處理](#pdf-進階處理) +- [OCR 文字辨識](#ocr-文字辨識) +- [電子書轉換](#電子書轉換) +- [其他轉換器](#其他轉換器) + +--- + +## 轉換引擎總覽 + +| 轉換器 | 用途 | 輸入格式數 | 輸出格式數 | +|--------|------|-----------|-----------| +| 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 + +最強大的影音轉換工具，支援幾乎所有影音格式。 + +**支援格式**： + +| 類型 | 輸入 | 輸出 | +|------|------|------| +| 影片 | 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+ | + +**使用範例**： + +``` +輸入：video.mov (500 MB) +輸出：video.mp4 (200 MB, H.264 編碼) +``` + +``` +輸入：audio.flac (50 MB) +輸出：audio.mp3 (8 MB, 320kbps) +``` + +**GPU 加速設定**： + +```yaml +environment: + - FFMPEG_ARGS=-hwaccel cuda + - FFMPEG_OUTPUT_ARGS=-c:v h264_nvenc +``` + +--- + +## 圖片處理 + +### ImageMagick + +通用圖片處理工具，支援 250+ 種格式。 + +**支援格式**： + +| 類型 | 格式範例 | +|------|---------| +| 常見格式 | PNG, JPEG, GIF, WebP, AVIF, HEIC | +| RAW 相機 | CR2, CR3, NEF, ARW, DNG | +| 向量/文件 | PDF, PSD, AI, EPS, SVG | +| 科學格式 | FITS, EXR, DPX | + +**使用範例**： + +``` +輸入：photo.heic (iPhone 照片) +輸出：photo.jpg (JPEG 格式，相容性更好) +``` + +``` +輸入：screenshot.png (4 MB) +輸出：screenshot.webp (800 KB, 壓縮率更高) +``` + +### Vips + +高效能圖片處理工具，適合大圖處理。 + +**特點**： +- 記憶體使用效率高 +- 處理速度快 +- 適合批次處理 + +--- + +## 文件轉換 + +### LibreOffice + +Office 文件轉換引擎。 + +**支援格式**： + +| 輸入 | 輸出 | +|------|------| +| DOC, DOCX, ODT | PDF, HTML, TXT | +| XLS, XLSX, ODS | PDF, CSV, HTML | +| PPT, PPTX, ODP | PDF, PNG, SVG | + +**使用範例**： + +``` +輸入：report.docx (Word 文件) +輸出：report.pdf (PDF 文件，保留排版) +``` + +``` +輸入：data.xlsx (Excel 試算表) +輸出：data.csv (CSV 純文字) +``` + +### Pandoc + +萬用文件轉換器，支援 Markdown、LaTeX、HTML 等。 + +**支援格式**： + +| 類型 | 格式 | +|------|------| +| 標記語言 | Markdown, reStructuredText, AsciiDoc | +| 網頁 | HTML, EPUB | +| 排版 | LaTeX, PDF, DOCX | +| 純文字 | TXT, RTF | + +**使用範例**： + +``` +輸入：README.md (Markdown) +輸出：README.pdf (排版精美的 PDF) +``` + +``` +輸入：thesis.tex (LaTeX) +輸出：thesis.docx (Word 文件) +``` + +--- + +## PDF 進階處理 + +### PDFMathTranslate + +翻譯 PDF 並**保留數學公式與排版**。 + +**特點**： +- 保留原始排版 +- 保留數學公式 +- 保留圖表位置 +- 支援多種翻譯引擎 + +**支援語言**： +- 英文 ↔ 中文 +- 英文 ↔ 日文 +- 其他語言組合 + +**使用範例**： + +``` +輸入：paper.pdf (英文學術論文，含數學公式) +輸出：paper_zh.pdf (中文翻譯，公式保留) +``` + +### BabelDOC + +進階 PDF 翻譯與轉換引擎。 + +**特點**： +- 高品質翻譯 +- 支援複雜排版 +- 多格式輸出 + +**使用範例**： + +``` +輸入：manual.pdf (英文使用手冊) +輸出：manual_translated.pdf (繁體中文版) +``` + +### MinerU + +**PDF 轉 Markdown**，智能擷取內容。 + +**特點**： +- 智能識別表格 +- 保留公式（轉為 LaTeX） +- 擷取圖片 +- 保持結構層次 + +**使用範例**： + +``` +輸入：textbook.pdf (教科書 PDF) +輸出：textbook.md (Markdown 格式) + └── images/ (擷取的圖片) +``` + +輸出內容範例： + +```markdown +# 第一章 緒論 + +## 1.1 背景 + +根據研究顯示... + +| 項目 | 數值 | 說明 | +|------|------|------| +| A | 100 | 描述 | +| B | 200 | 描述 | + +公式如下： + +$$E = mc^2$$ +``` + +--- + +## OCR 文字辨識 + +### OCRmyPDF + +為 PDF 添加 OCR 文字層，讓掃描 PDF 可搜尋。 + +**特點**： +- 保留原始 PDF 外觀 +- 添加隱藏文字層 +- 支援多語言辨識 + +**支援語言（一般版）**： + +| 語言 | 代碼 | +|------|------| +| 繁體中文 | `chi_tra` | +| 簡體中文 | `chi_sim` | +| 英文 | `eng` | +| 日文 | `jpn` | +| 韓文 | `kor` | +| 法文 | `fra` | +| 德文 | `deu` | + +**Full 版支援 65 種語言**。 + +**使用範例**： + +``` +輸入：scan.pdf (掃描版 PDF，無法選取文字) +輸出：scan_ocr.pdf (可搜尋、可複製的 PDF) +``` + +--- + +## 電子書轉換 + +### Calibre + +電子書格式轉換器。 + +**支援格式**： + +| 輸入 | 輸出 | +|------|------| +| EPUB, MOBI, AZW3 | EPUB, MOBI, PDF | +| PDF, TXT, HTML | AZW3, DOCX, TXT | +| CBZ, CBR (漫畫) | PDF, EPUB | + +**使用範例**： + +``` +輸入：book.epub (EPUB 電子書) +輸出：book.mobi (Kindle 格式) +``` + +``` +輸入：comic.cbz (漫畫壓縮檔) +輸出：comic.pdf (PDF 格式) +``` + +--- + +## 其他轉換器 + +### Inkscape + +向量圖形編輯與轉換。 + +| 輸入 | 輸出 | +|------|------| +| SVG, AI, EPS | PNG, PDF, EPS | +| PDF | SVG | + +### Assimp + +3D 模型格式轉換。 + +| 輸入 | 輸出 | +|------|------| +| FBX, OBJ, GLTF | OBJ, STL, GLTF | +| 3DS, DAE | FBX, PLY | + +### Potrace / VTracer + +點陣圖轉向量圖。 + +``` +輸入：logo.png (點陣圖) +輸出：logo.svg (向量圖，可無限放大) +``` + +### Dasel + +資料檔案格式轉換。 + +| 輸入/輸出 | +|-----------| +| JSON, YAML, TOML, XML, CSV | + +``` +輸入：config.yaml +輸出：config.json +``` + +--- + +## 功能比較表 + +| 功能 | Lite 版 | 一般版 | Full 版 | +|------|---------|--------|---------| +| FFmpeg 影音 | ✅ | ✅ | ✅ | +| ImageMagick 圖片 | ✅ | ✅ | ✅ | +| LibreOffice 文件 | ✅ | ✅ | ✅ | +| Pandoc 文件 | ✅ | ✅ | ✅ | +| Calibre 電子書 | ✅ | ✅ | ✅ | +| OCRmyPDF (7語言) | ❌ | ✅ | ✅ | +| OCRmyPDF (65語言) | ❌ | ❌ | ✅ | +| PDFMathTranslate | ❌ | ✅ | ✅ | +| BabelDOC | ❌ | ✅ | ✅ | +| MinerU | ❌ | ✅ | ✅ | +| 完整 TexLive | ❌ | ❌ | ✅ | + +--- + +[⬆️ 回到頂部](#功能總覽) | [📚 回到目錄](00-專案總覽.md) diff --git a/docs/05-API文件.md b/docs/05-API文件.md new file mode 100644 index 0000000..8031fdb --- /dev/null +++ b/docs/05-API文件.md @@ -0,0 +1,547 @@ +# API 文件 + +ConvertX-CN 提供選用的 API Server，支援 REST 和 GraphQL 兩種 API 介面。 + +--- + +## 目錄 + +- [快速啟用](#快速啟用) +- [認證機制](#認證機制) +- [REST API 端點](#rest-api-端點) +- [GraphQL API](#graphql-api) +- [錯誤碼說明](#錯誤碼說明) +- [使用範例](#使用範例) + +--- + +## 快速啟用 + +API Server 是**選用功能**，不影響 Web UI 使用。 + +### 啟用方式 + +```bash +docker compose --profile api up -d +``` + +### 服務端口 + +| 服務 | 端口 | 說明 | +|------|------|------| +| 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 請求（除健康檢查外）都需要 JWT Bearer Token： + +```http +Authorization: Bearer +``` + +### Token 結構 + +```json +{ + "sub": "user-id", + "exp": 1234567890, + "iat": 1234567890, + "email": "user@example.com", + "roles": ["user"] +} +``` + +> ⚠️ **注意**：API Server 只負責驗證 JWT，不負責產生 JWT。Token 應由獨立的認證服務產生。 + +--- + +## REST API 端點 + +**Base URL**: `http://localhost:3001/api/v1` + +### 健康檢查 + +檢查 API Server 運行狀態。 + +**請求**： + +```http +GET /health +``` + +**回應**： + +```json +{ + "status": "healthy", + "version": "0.1.0", + "timestamp": "2026-01-25T10:30:00Z" +} +``` + +--- + +### 取得支援格式 + +取得所有支援的輸入/輸出格式。 + +**請求**： + +```http +GET /api/v1/formats +Authorization: Bearer +``` + +**回應**： + +```json +{ + "converters": [ + { + "name": "ffmpeg", + "inputFormats": ["mp4", "mkv", "avi", "..."], + "outputFormats": ["mp4", "webm", "mp3", "..."] + }, + { + "name": "imagemagick", + "inputFormats": ["png", "jpg", "heic", "..."], + "outputFormats": ["png", "jpg", "webp", "..."] + } + ] +} +``` + +--- + +### 上傳檔案 + +上傳待轉換的檔案。 + +**請求**： + +```http +POST /api/v1/upload +Authorization: Bearer +Content-Type: multipart/form-data + +file: +``` + +**回應**： + +```json +{ + "success": true, + "fileId": "abc123", + "filename": "document.docx", + "size": 1048576, + "mimeType": "application/vnd.openxmlformats-officedocument.wordprocessingml.document" +} +``` + +--- + +### 開始轉換 + +對已上傳的檔案進行轉換。 + +**請求**： + +```http +POST /api/v1/convert +Authorization: Bearer +Content-Type: application/json + +{ + "fileId": "abc123", + "outputFormat": "pdf", + "options": { + "quality": "high" + } +} +``` + +**回應**： + +```json +{ + "success": true, + "jobId": "job456", + "status": "processing", + "estimatedTime": 30 +} +``` + +--- + +### 查詢轉換狀態 + +取得轉換任務的當前狀態。 + +**請求**： + +```http +GET /api/v1/jobs/{jobId} +Authorization: Bearer +``` + +**回應（處理中）**： + +```json +{ + "jobId": "job456", + "status": "processing", + "progress": 45, + "message": "Converting page 3 of 10..." +} +``` + +**回應（完成）**： + +```json +{ + "jobId": "job456", + "status": "completed", + "progress": 100, + "result": { + "fileId": "result789", + "filename": "document.pdf", + "size": 524288, + "downloadUrl": "/api/v1/download/result789" + } +} +``` + +--- + +### 下載結果 + +下載轉換完成的檔案。 + +**請求**： + +```http +GET /api/v1/download/{fileId} +Authorization: Bearer +``` + +**回應**： + +``` +HTTP/1.1 200 OK +Content-Type: application/pdf +Content-Disposition: attachment; filename="document.pdf" + + +``` + +--- + +### 刪除檔案 + +刪除已上傳或轉換完成的檔案。 + +**請求**： + +```http +DELETE /api/v1/files/{fileId} +Authorization: Bearer +``` + +**回應**： + +```json +{ + "success": true, + "message": "File deleted successfully" +} +``` + +--- + +## GraphQL API + +**Endpoint**: `http://localhost:3001/graphql` + +### Schema 概覽 + +```graphql +type Query { + health: Health! + formats: [Converter!]! + job(id: ID!): Job + jobs: [Job!]! +} + +type Mutation { + upload(file: Upload!): UploadResult! + convert(input: ConvertInput!): ConvertResult! + deleteFile(fileId: ID!): DeleteResult! +} + +type Health { + status: String! + version: String! + timestamp: String! +} + +type Converter { + name: String! + inputFormats: [String!]! + outputFormats: [String!]! +} + +type Job { + id: ID! + status: JobStatus! + progress: Int! + message: String + result: ConvertedFile +} + +enum JobStatus { + PENDING + PROCESSING + COMPLETED + FAILED +} +``` + +### 查詢範例 + +**取得所有格式**： + +```graphql +query { + formats { + name + inputFormats + outputFormats + } +} +``` + +**查詢任務狀態**： + +```graphql +query { + job(id: "job456") { + status + progress + message + result { + filename + size + downloadUrl + } + } +} +``` + +### 變更範例 + +**開始轉換**： + +```graphql +mutation { + convert(input: { + fileId: "abc123" + outputFormat: "pdf" + options: { quality: "high" } + }) { + jobId + status + } +} +``` + +--- + +## 錯誤碼說明 + +### HTTP 狀態碼 + +| 狀態碼 | 說明 | 常見原因 | +|--------|------|---------| +| 200 | 成功 | 請求正常處理 | +| 400 | 錯誤請求 | 參數錯誤、格式不支援 | +| 401 | 未授權 | Token 無效或過期 | +| 403 | 禁止存取 | 權限不足 | +| 404 | 找不到 | 檔案或任務不存在 | +| 413 | 檔案太大 | 超過上傳限制 | +| 415 | 格式不支援 | 不支援的檔案類型 | +| 500 | 伺服器錯誤 | 內部錯誤 | +| 503 | 服務不可用 | 伺服器過載 | + +### 錯誤回應格式 + +```json +{ + "success": false, + "error": { + "code": "UNSUPPORTED_FORMAT", + "message": "The format 'xyz' is not supported", + "details": { + "inputFormat": "xyz", + "supportedFormats": ["pdf", "docx", "png"] + } + } +} +``` + +### 常見錯誤碼 + +| 錯誤碼 | 說明 | 解決方法 | +|--------|------|---------| +| `INVALID_TOKEN` | Token 無效 | 重新取得有效 Token | +| `TOKEN_EXPIRED` | Token 過期 | 刷新 Token | +| `FILE_NOT_FOUND` | 檔案不存在 | 確認檔案 ID 正確 | +| `UNSUPPORTED_FORMAT` | 格式不支援 | 查看支援格式列表 | +| `FILE_TOO_LARGE` | 檔案過大 | 壓縮或分割檔案 | +| `CONVERSION_FAILED` | 轉換失敗 | 檢查檔案是否損壞 | +| `RATE_LIMITED` | 請求過頻繁 | 降低請求頻率 | + +--- + +## 使用範例 + +### cURL 範例 + +**上傳並轉換檔案**： + +```bash +# 1. 上傳檔案 +FILE_RESPONSE=$(curl -X POST \ + -H "Authorization: Bearer $TOKEN" \ + -F "file=@document.docx" \ + http://localhost:3001/api/v1/upload) + +FILE_ID=$(echo $FILE_RESPONSE | jq -r '.fileId') + +# 2. 開始轉換 +JOB_RESPONSE=$(curl -X POST \ + -H "Authorization: Bearer $TOKEN" \ + -H "Content-Type: application/json" \ + -d "{\"fileId\": \"$FILE_ID\", \"outputFormat\": \"pdf\"}" \ + http://localhost:3001/api/v1/convert) + +JOB_ID=$(echo $JOB_RESPONSE | jq -r '.jobId') + +# 3. 等待完成並下載 +sleep 10 + +curl -H "Authorization: Bearer $TOKEN" \ + http://localhost:3001/api/v1/download/$FILE_ID \ + -o output.pdf +``` + +### Python 範例 + +```python +import requests + +BASE_URL = "http://localhost:3001/api/v1" +TOKEN = "your-jwt-token" +HEADERS = {"Authorization": f"Bearer {TOKEN}"} + +# 上傳檔案 +with open("document.docx", "rb") as f: + response = requests.post( + f"{BASE_URL}/upload", + headers=HEADERS, + files={"file": f} + ) + file_id = response.json()["fileId"] + +# 開始轉換 +response = requests.post( + f"{BASE_URL}/convert", + headers=HEADERS, + json={"fileId": file_id, "outputFormat": "pdf"} +) +job_id = response.json()["jobId"] + +# 輪詢狀態 +import time +while True: + response = requests.get(f"{BASE_URL}/jobs/{job_id}", headers=HEADERS) + status = response.json()["status"] + if status == "completed": + break + time.sleep(2) + +# 下載結果 +result_id = response.json()["result"]["fileId"] +response = requests.get(f"{BASE_URL}/download/{result_id}", headers=HEADERS) +with open("output.pdf", "wb") as f: + f.write(response.content) +``` + +### JavaScript 範例 + +```javascript +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); + + const uploadResponse = await fetch(`${BASE_URL}/upload`, { + method: 'POST', + headers: { 'Authorization': `Bearer ${TOKEN}` }, + body: formData + }); + const { fileId } = await uploadResponse.json(); + + // 開始轉換 + const convertResponse = await fetch(`${BASE_URL}/convert`, { + method: 'POST', + headers: { + 'Authorization': `Bearer ${TOKEN}`, + 'Content-Type': 'application/json' + }, + 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}` } + }); + const job = await statusResponse.json(); + if (job.status === 'completed') { + result = job.result; + break; + } + await new Promise(resolve => setTimeout(resolve, 2000)); + } + + // 下載結果 + const downloadResponse = await fetch(`${BASE_URL}/download/${result.fileId}`, { + headers: { 'Authorization': `Bearer ${TOKEN}` } + }); + return await downloadResponse.blob(); +} +``` + +--- + +[⬆️ 回到頂部](#api-文件) | [📚 回到目錄](00-專案總覽.md) diff --git a/docs/06-錯誤排查與支援.md b/docs/06-錯誤排查與支援.md new file mode 100644 index 0000000..dc83e7d --- /dev/null +++ b/docs/06-錯誤排查與支援.md @@ -0,0 +1,415 @@ +# 錯誤排查與支援 + +本文件提供常見問題的排查步驟與解決方案。 + +--- + +## 目錄 + +- [常見問題速查](#常見問題速查) +- [登入與認證問題](#登入與認證問題) +- [轉換相關問題](#轉換相關問題) +- [Docker 相關問題](#docker-相關問題) +- [效能問題](#效能問題) +- [日誌收集與分析](#日誌收集與分析) +- [取得支援](#取得支援) + +--- + +## 常見問題速查 + +| 問題 | 可能原因 | 快速解決 | +|------|---------|---------| +| 登入後被踢回登入頁 | HTTP/HTTPS 設定不正確 | 加上 `HTTP_ALLOWED=true` 或 `TRUST_PROXY=true` | +| 重啟後資料消失 | Volume 未正確掛載 | 確認 `./data:/app/data` 且資料夾存在 | +| 重啟後被登出 | JWT_SECRET 未固定 | 設定固定的 `JWT_SECRET` | +| 中文顯示亂碼 | 使用 Lite 版（無字型） | 改用一般版或 Full 版 | +| 轉換失敗 | 格式不支援或檔案損壞 | 檢查支援格式列表，確認檔案完整 | +| 容器啟動失敗 | 端口衝突或記憶體不足 | 檢查端口使用，增加記憶體 | + +--- + +## 登入與認證問題 + +### 問題：登入後又被導回登入頁 + +**症狀**： +- 輸入帳密後頁面閃一下又回到登入頁 +- Cookie 無法正確設定 + +**原因與解決**： + +1. **使用 HTTP 但未允許** + + ```yaml + environment: + - HTTP_ALLOWED=true # 允許 HTTP 連線 + ``` + +2. **使用反向代理但未設定信任** + + ```yaml + environment: + - TRUST_PROXY=true # 信任反向代理 + ``` + +3. **反向代理未正確傳遞 headers** + + Nginx 設定需包含： + ```nginx + proxy_set_header X-Forwarded-Proto $scheme; + proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; + ``` + +### 問題：重啟容器後需要重新登入 + +**症狀**： +- 每次重啟容器後所有使用者都需要重新登入 + +**原因**：JWT_SECRET 未固定，每次啟動會產生新的隨機密鑰。 + +**解決**： + +```yaml +environment: + - JWT_SECRET=您的固定隨機密鑰至少32字元 +``` + +產生密鑰： + +```bash +openssl rand -hex 32 +``` + +### 問題：無法註冊新帳號 + +**症狀**： +- 找不到註冊按鈕 +- 註冊時顯示錯誤 + +**原因**：註冊功能被關閉 + +**解決**： + +```yaml +environment: + - ACCOUNT_REGISTRATION=true +``` + +--- + +## 轉換相關問題 + +### 問題：轉換失敗，顯示「格式不支援」 + +**排查步驟**： + +1. **確認格式支援** + - 查看 [04-功能總覽](04-功能總覽.md) 的格式列表 + - 確認輸入和輸出格式都有支援 + +2. **確認版本** + - Lite 版功能較少，某些格式可能不支援 + - 改用一般版或 Full 版 + +3. **檢查檔案** + - 確認檔案未損壞 + - 嘗試用其他軟體開啟確認 + +### 問題：中文文件轉換後出現亂碼 + +**原因**：缺少中文字型 + +**解決**： + +1. **使用一般版或 Full 版**（已內建 CJK 字型） + +2. **Lite 版手動掛載字型**： + ```yaml + volumes: + - ./fonts:/usr/share/fonts/custom + ``` + +### 問題：PDF 翻譯功能無法使用 + +**排查步驟**： + +1. **確認版本**：Lite 版不支援 PDF 翻譯 + +2. **確認設定**： + ```yaml + environment: + - PDFMATHTRANSLATE_SERVICE=google + ``` + +3. **檢查網路**：翻譯功能需要網路連線 + +### 問題：轉換時間過長 + +**可能原因**： + +1. 檔案太大 +2. 系統資源不足 +3. 同時轉換任務過多 + +**解決方案**： + +1. **限制同時轉換數**： + ```yaml + environment: + - MAX_CONVERT_PROCESS=4 + ``` + +2. **增加資源限制**： + ```yaml + deploy: + resources: + limits: + cpus: '4' + memory: 8G + ``` + +3. **啟用 GPU 加速**（FFmpeg）： + ```yaml + environment: + - FFMPEG_ARGS=-hwaccel cuda + - FFMPEG_OUTPUT_ARGS=-c:v h264_nvenc + ``` + +--- + +## Docker 相關問題 + +### 問題：容器無法啟動 + +**排查步驟**： + +1. **檢查日誌**： + ```bash + docker logs convertx-cn + ``` + +2. **檢查端口佔用**： + ```bash + # Linux / macOS + lsof -i :3000 + + # Windows + netstat -ano | findstr :3000 + ``` + +3. **檢查磁碟空間**： + ```bash + docker system df + ``` + +4. **檢查記憶體**： + ```bash + docker stats + ``` + +### 問題：資料在重啟後消失 + +**原因**：Volume 未正確掛載 + +**確認方式**： + +```bash +docker inspect convertx-cn | grep -A 10 Mounts +``` + +**正確設定**： + +```yaml +volumes: + - ./data:/app/data +``` + +確保本機的 `./data` 資料夾存在： + +```bash +mkdir -p ./data +``` + +### 問題：拉取 Image 失敗 + +**解決方案**： + +1. **檢查網路連線** + +2. **使用鏡像站**（中國大陸）： + ```bash + docker pull registry.cn-hangzhou.aliyuncs.com/convertx/convertx-cn:latest + ``` + +3. **手動下載**： + 從 GitHub Releases 下載 Image tarball + +### 問題：磁碟空間不足 + +**清理方式**： + +```bash +# 清理未使用的資源 +docker system prune -a + +# 清理舊的轉換檔案 +rm -rf ./data/output/* +rm -rf ./data/uploads/* +``` + +**預防措施**： + +```yaml +environment: + - AUTO_DELETE_EVERY_N_HOURS=6 # 頻繁清理 +``` + +--- + +## 效能問題 + +### 診斷效能問題 + +1. **查看系統資源使用**： + ```bash + docker stats convertx-cn + ``` + +2. **查看容器內部狀態**： + ```bash + docker exec -it convertx-cn top + ``` + +### 效能優化建議 + +| 問題 | 解決方案 | +|------|---------| +| CPU 使用率高 | 限制 `MAX_CONVERT_PROCESS` | +| 記憶體不足 | 增加容器記憶體限制 | +| 磁碟 I/O 慢 | 使用 SSD，增加 Volume 效能 | +| 網路延遲 | 使用本地部署 | + +### 推薦硬體配置 + +| 用途 | CPU | 記憶體 | 磁碟 | +|------|-----|--------|------| +| 個人使用 | 2 核 | 4 GB | 20 GB | +| 小團隊 | 4 核 | 8 GB | 50 GB | +| 生產環境 | 8 核 | 16 GB | 100 GB SSD | + +--- + +## 日誌收集與分析 + +### 查看日誌 + +```bash +# 即時日誌 +docker logs -f convertx-cn + +# 最近 100 行 +docker logs --tail 100 convertx-cn + +# 指定時間範圍 +docker logs --since "2026-01-25T00:00:00" convertx-cn +``` + +### 日誌等級 + +| 等級 | 說明 | +|------|------| +| `ERROR` | 錯誤，需要處理 | +| `WARN` | 警告，可能有問題 | +| `INFO` | 一般資訊 | +| `DEBUG` | 除錯資訊 | + +### 常見日誌訊息 + +| 訊息 | 說明 | +|------|------| +| `🦊 Elysia is running at...` | 服務正常啟動 | +| `Conversion started...` | 開始轉換 | +| `Conversion completed...` | 轉換完成 | +| `Error: ENOSPC...` | 磁碟空間不足 | +| `Error: ENOMEM...` | 記憶體不足 | + +### 匯出日誌 + +```bash +# 匯出到檔案 +docker logs convertx-cn > convertx-logs.txt 2>&1 + +# 壓縮匯出 +docker logs convertx-cn 2>&1 | gzip > convertx-logs.gz +``` + +--- + +## 取得支援 + +### 自助資源 + +1. **查閱文件**：先查看本專案文件 +2. **搜尋 Issues**：[GitHub Issues](https://github.com/pi-docket/ConvertX-CN/issues) +3. **社群討論**：[GitHub Discussions](https://github.com/pi-docket/ConvertX-CN/discussions) + +### 提交問題 + +提交 Issue 時請包含： + +1. **環境資訊**： + - Docker 版本 + - ConvertX-CN 版本（Image Tag） + - 作業系統 + +2. **問題描述**： + - 預期行為 + - 實際行為 + - 重現步驟 + +3. **相關資訊**： + - 環境變數設定（隱藏敏感資訊） + - 相關日誌 + - 螢幕截圖（如適用） + +### Issue 範本 + +```markdown +## 環境 +- ConvertX-CN 版本：`latest` +- Docker 版本：`24.0.5` +- 作業系統：Ubuntu 22.04 + +## 問題描述 +登入後被踢回登入頁。 + +## 重現步驟 +1. 訪問 http://localhost:3000 +2. 輸入帳號密碼 +3. 點擊登入 +4. 頁面閃一下後回到登入頁 + +## 環境變數 +```yaml +environment: + - TZ=Asia/Taipei + - JWT_SECRET=**** +``` + +## 日誌 +``` +[相關日誌內容] +``` +``` + +### 聯繫方式 + +| 管道 | 連結 | +|------|------| +| GitHub Issues | [建立 Issue](https://github.com/pi-docket/ConvertX-CN/issues) | +| GitHub Discussions | [社群討論](https://github.com/pi-docket/ConvertX-CN/discussions) | + +--- + +[⬆️ 回到頂部](#錯誤排查與支援) | [📚 回到目錄](00-專案總覽.md) diff --git a/docs/07-開發與貢獻指南.md b/docs/07-開發與貢獻指南.md new file mode 100644 index 0000000..1836d92 --- /dev/null +++ b/docs/07-開發與貢獻指南.md @@ -0,0 +1,455 @@ +# 開發與貢獻指南 + +歡迎參與 ConvertX-CN 的開發！本文件說明專案結構、開發流程與貢獻規範。 + +--- + +## 目錄 + +- [專案結構](#專案結構) +- [本地開發環境](#本地開發環境) +- [分支策略](#分支策略) +- [測試流程](#測試流程) +- [提交規範](#提交規範) +- [Pull Request 流程](#pull-request-流程) +- [程式碼風格](#程式碼風格) + +--- + +## 專案結構 + +``` +ConvertX-CN/ +├── src/ # 前端原始碼 +│ ├── index.tsx # 主入口 +│ ├── main.css # 主樣式 +│ ├── components/ # React 元件 +│ ├── converters/ # 轉換器定義 +│ ├── db/ # 資料庫相關 +│ ├── helpers/ # 工具函數 +│ ├── i18n/ # 國際化 +│ ├── icons/ # 圖示元件 +│ ├── locales/ # 翻譯檔案 +│ ├── pages/ # 頁面元件 +│ ├── theme/ # 主題相關 +│ └── transfer/ # 檔案傳輸 +│ +├── api-server/ # Rust API Server（選用） +│ ├── src/ # Rust 原始碼 +│ │ ├── main.rs # 入口點 +│ │ ├── auth.rs # 認證模組 +│ │ ├── config.rs # 設定模組 +│ │ ├── conversion.rs # 轉換邏輯 +│ │ ├── graphql.rs # GraphQL 端點 +│ │ └── rest.rs # REST 端點 +│ ├── docs/ # API 文件 +│ └── tests/ # 測試 +│ +├── docs/ # 專案文件 +├── tests/ # 測試 +│ ├── converters/ # 轉換器測試 +│ ├── e2e/ # 端對端測試 +│ └── transfer/ # 傳輸測試 +│ +├── scripts/ # 腳本 +│ ├── download-models.sh # 下載模型 +│ ├── install-fonts.sh # 安裝字型 +│ └── verify-*.sh # 驗證腳本 +│ +├── public/ # 靜態資源 +├── data/ # 資料目錄（runtime） +│ +├── Dockerfile # 一般版建構檔 +├── Dockerfile.lite # Lite 版建構檔 +├── Dockerfile.full # Full 版建構檔 +├── compose.yaml # Docker Compose +├── package.json # Node.js 依賴 +├── tsconfig.json # TypeScript 設定 +└── biome.json # Linter 設定 +``` + +--- + +## 技術棧 + +### 前端 / Web Server + +| 技術 | 用途 | +|------|------| +| Bun | JavaScript Runtime | +| Elysia | Web 框架 | +| React | UI 元件 | +| TailwindCSS | 樣式框架 | +| TypeScript | 類型安全 | +| SQLite | 資料庫 | + +### API Server（選用） + +| 技術 | 用途 | +|------|------| +| Rust | 語言 | +| Axum | Web 框架 | +| async-graphql | GraphQL | +| tokio | 非同步運行時 | + +--- + +## 本地開發環境 + +### 前置需求 + +- Node.js 20+ 或 Bun 1.0+ +- Docker（用於測試） +- Git + +### 設定步驟 + +1. **Clone 專案** + + ```bash + git clone https://github.com/pi-docket/ConvertX-CN.git + cd ConvertX-CN + ``` + +2. **安裝依賴** + + ```bash + # 使用 Bun + bun install + + # 或使用 npm + npm install + ``` + +3. **啟動開發伺服器** + + ```bash + bun dev + ``` + +4. **開啟瀏覽器** + + 訪問 `http://localhost:3000` + +### 開發指令 + +| 指令 | 說明 | +|------|------| +| `bun dev` | 啟動開發伺服器（熱重載） | +| `bun build` | 建構生產版本 | +| `bun test` | 執行測試 | +| `bun lint` | 執行 Linter | +| `bun format` | 格式化程式碼 | + +### API Server 開發 + +```bash +cd api-server +cargo run +``` + +--- + +## 分支策略 + +### 主要分支 + +| 分支 | 用途 | +|------|------| +| `main` | 穩定版本，用於發布 | +| `develop` | 開發分支，接受 PR | + +### 功能分支 + +建立新功能時，從 `develop` 分支建立： + +```bash +git checkout develop +git pull origin develop +git checkout -b feature/your-feature-name +``` + +### 分支命名規範 + +| 類型 | 格式 | 範例 | +|------|------|------| +| 功能 | `feature/描述` | `feature/add-pdf-watermark` | +| 修復 | `fix/描述` | `fix/login-redirect-issue` | +| 文件 | `docs/描述` | `docs/update-api-docs` | +| 重構 | `refactor/描述` | `refactor/improve-converter-perf` | + +--- + +## 測試流程 + +### 測試類型 + +| 類型 | 位置 | 說明 | +|------|------|------| +| 單元測試 | `tests/` | 測試個別函數 | +| 整合測試 | `tests/converters/` | 測試轉換器 | +| E2E 測試 | `tests/e2e/` | 端對端測試 | + +### 執行測試 + +```bash +# 執行所有測試 +bun test + +# 執行特定測試 +bun test tests/converters/ + +# 執行 E2E 測試 +bun run test:e2e +``` + +### 測試覆蓋率 + +```bash +bun test --coverage +``` + +### 新增測試 + +為新功能撰寫測試： + +```typescript +// tests/converters/ffmpeg.test.ts +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'); + expect(result.success).toBe(true); + }); +}); +``` + +--- + +## 提交規範 + +### Commit Message 格式 + +``` +(): + + + +