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

新增錯誤排查與支援文件，提供常見問題解決方案；新增開發與貢獻指南，說明專案結構與開發流程；新增授權說明文件，詳述AGPL-3.0授權條款及第三方元件使用情況。

Browse source
This commit is contained in:
Your Name 2026-01-25 16:09:58 +08:00
parent 11d751250b
commit caecb2e001
13 changed files with 3269 additions and 369 deletions
Download patch file Download diff file Expand all files Collapse all files

65
LICENSE-AUTHOR
View file

@ -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.

125
LICENSE-OVERVIEW.md
View file

@ -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)

72
README.md
View file

@ -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)](<https://img.shields.io/docker/image-size/convertx/convertx-cn/latest-lite?label=image%20size%20(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)

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

@ -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 授權 |
---
[⬆️ 回到頂部](#專案總覽)

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

@ -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)

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

@ -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)

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

@ -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)

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

@ -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)

547
docs/05-API文件.md Normal file
View file

@ -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 <your-jwt-token>
```
### 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 <token>
```
**回應**：
```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 <token>
Content-Type: multipart/form-data
file: <binary>
```
**回應**：
```json
{
"success": true,
"fileId": "abc123",
"filename": "document.docx",
"size": 1048576,
"mimeType": "application/vnd.openxmlformats-officedocument.wordprocessingml.document"
}
```
---
### 開始轉換
對已上傳的檔案進行轉換。
**請求**：
```http
POST /api/v1/convert
Authorization: Bearer <token>
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 <token>
```
**回應（處理中）**：
```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 <token>
```
**回應**：
```
HTTP/1.1 200 OK
Content-Type: application/pdf
Content-Disposition: attachment; filename="document.pdf"
<binary content>
```
---
### 刪除檔案
刪除已上傳或轉換完成的檔案。
**請求**：
```http
DELETE /api/v1/files/{fileId}
Authorization: Bearer <token>
```
**回應**：
```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)

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

@ -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)

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

@ -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 格式
```
<type>(<scope>): <subject>
<body>
<footer>
```
### Type 類型
| Type | 說明 |
|------|------|
| `feat` | 新功能 |
| `fix` | 修復 Bug |
| `docs` | 文件更新 |
| `style` | 程式碼風格（不影響功能） |
| `refactor` | 重構（不新增功能或修復） |
| `perf` | 效能優化 |
| `test` | 新增或修改測試 |
| `chore` | 建構或輔助工具變動 |
### 範例
```
feat(converter): 新增 AVIF 格式支援
- 在 ImageMagick 轉換器新增 AVIF 輸入/輸出
- 更新格式支援列表
Closes #123
```
```
fix(auth): 修復登入後重導向問題
當 HTTP_ALLOWED=false 且使用 HTTP 存取時，
Cookie 無法正確設定導致登入失敗。
修復方式：在設定 Cookie 前檢查協議。
Fixes #456
```
### 提交前檢查
```bash
# 執行 Linter
bun lint
# 執行測試
bun test
# 格式化程式碼
bun format
```
---
## Pull Request 流程
### 提交 PR 前
1. 確保程式碼通過所有測試
2. 確保程式碼符合風格規範
3. 更新相關文件
4. 撰寫清楚的 PR 描述
### PR 範本
```markdown
## 變更描述
簡述這個 PR 做了什麼。
## 變更類型
- [ ] 新功能
- [ ] Bug 修復
- [ ] 文件更新
- [ ] 重構
- [ ] 其他
## 測試
描述如何測試這些變更。
## 相關 Issue
Closes #123
## 截圖（如適用）
```
### 審核流程
1. 提交 PR 到 `develop` 分支
2. 等待 CI 通過
3. 請求 Review
4. 根據回饋修改
5. 合併
---
## 程式碼風格
### TypeScript / JavaScript
使用 Biome 進行 Linting 和格式化：
```bash
# 檢查
bun lint
# 格式化
bun format
```
### 主要規範
- 使用 2 空格縮排
- 使用單引號
- 不使用分號（除非必要）
- 使用 `const` / `let`，避免 `var`
- 使用箭頭函數
### 範例
```typescript
// ✅ 正確
const formatConverter = (name: string): string => {
return name.toLowerCase()
}
// ❌ 錯誤
function formatConverter(name) {
return name.toLowerCase();
}
```
### Rust
遵循 Rust 官方風格指南：
```bash
cargo fmt --check
cargo clippy
```
---
## 新增轉換器
### 步驟
1. 在 `src/converters/` 建立新檔案
2. 定義轉換器：
```typescript
// src/converters/myconverter.ts
import { Converter } from './types'
export const myConverter: Converter = {
name: 'myconverter',
inputFormats: ['xyz', 'abc'],
outputFormats: ['pdf', 'png'],
convert: async (input, output, options) => {
// 轉換邏輯
}
}
```
3. 在 `src/converters/main.ts` 註冊
4. 新增測試
5. 更新文件
---
## 國際化
### 新增翻譯
1. 在 `src/locales/` 找到對應語言檔案
2. 新增翻譯字串：
```json
{
"converter.newFeature": "新功能說明"
}
```
3. 在所有語言檔案中新增相同的 Key
### 新增語言
1. 在 `src/locales/` 建立新的語言檔案
2. 在 `src/i18n/index.ts` 註冊新語言
---
## 發布流程
### 版本號規則
遵循 [Semantic Versioning](https://semver.org/)：
- `MAJOR.MINOR.PATCH`
- MAJOR：不相容的 API 變更
- MINOR：向下相容的新功能
- PATCH：向下相容的 Bug 修復
### 發布步驟
1. 更新 `CHANGELOG.md`
2. 更新版本號
3. 建立 Release Tag
4. CI 自動建構並發布 Docker Image
---
[⬆️ 回到頂部](#開發與貢獻指南) | [📚 回到目錄](00-專案總覽.md)

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

@ -0,0 +1,190 @@
# 授權說明
ConvertX-CN 專案採用 **GNU Affero General Public License v3.0 (AGPL-3.0)** 授權。
---
## 目錄
- [授權摘要](#授權摘要)
- [您的權利](#您的權利)
- [您的義務](#您的義務)
- [常見問題](#常見問題)
- [第三方元件](#第三方元件)
---
## 授權摘要
| 項目 | 說明 |
|------|------|
| **授權類型** | AGPL-3.0 |
| **授權檔案** | [LICENSE](../LICENSE) |
| **適用範圍** | 整個專案所有程式碼 |
---
## 您的權利
根據 AGPL-3.0 授權，您可以：
### ✅ 自由使用
- 個人使用
- 商業使用
- 教育/研究使用
### ✅ 自由修改
- 修改原始碼
- 客製化功能
- 整合到您的系統
### ✅ 自由分發
- 重新分發原始碼
- 分發修改後的版本
- 提供網路服務
---
## 您的義務
### 📋 保留授權聲明
分發時必須包含：
- 原始授權聲明
- 著作權聲明
- 完整的 AGPL-3.0 授權文字
### 📋 公開原始碼
如果您修改了程式碼：
- 必須公開修改後的原始碼
- 必須使用相同的 AGPL-3.0 授權
### 📋 網路使用條款
**這是 AGPL 與 GPL 的主要差異：**
如果您將修改後的版本部署為網路服務（如 SaaS），您必須：
- 向服務使用者提供取得原始碼的方式
- 原始碼必須包含您的所有修改
### 📋 標明變更
如果您修改了程式碼：
- 必須標明您做了哪些修改
- 必須標明修改日期
---
## 常見問題
### Q: 我可以將 ConvertX-CN 用於商業用途嗎？
**A: 可以**，但您需要遵守 AGPL-3.0 的條款，包括公開原始碼。
### Q: 我修改了程式碼後部署在公司內部，需要公開嗎？
**A: 視情況而定**
- 如果只有公司內部員工使用 → 不需要公開
- 如果對外提供服務（客戶可存取）→ 需要公開
### Q: 我可以在 ConvertX-CN 基礎上開發閉源軟體嗎？
**A: 不可以**，AGPL-3.0 要求衍生作品也必須使用相同授權。
### Q: 我只是使用 ConvertX-CN 轉換檔案，需要遵守什麼條款嗎？
**A: 不需要**，單純使用不需要遵守任何條款。只有當您修改或分發程式碼時，才需要遵守授權條款。
### Q: 如果我將 ConvertX-CN 作為 SaaS 服務提供，需要做什麼？
**A: 您需要**：
1. 在服務中提供原始碼下載連結
2. 包含您對程式碼的所有修改
3. 使用 AGPL-3.0 授權
---
## 第三方元件
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 |
| Tesseract OCR | Apache 2.0 |
### 框架與函式庫
| 元件 | 授權 |
|------|------|
| Bun | MIT |
| Elysia | MIT |
| React | MIT |
| TailwindCSS | MIT |
---
## 授權全文
完整的 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)
---
## 授權聲明範本
如果您基於 ConvertX-CN 開發了衍生作品，請在您的專案中包含類似以下的授權聲明：
```
本軟體基於 ConvertX-CN (https://github.com/pi-docket/ConvertX-CN) 開發，
原始專案採用 AGPL-3.0 授權。
本軟體同樣採用 AGPL-3.0 授權。
Copyright (C) 2026 [您的名稱]
This program is free software: you can redistribute it and/or modify
it under the terms of the GNU Affero General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU Affero General Public License for more details.
You should have received a copy of the GNU Affero General Public License
along with this program. If not, see <https://www.gnu.org/licenses/>.
```
---
## 聯繫方式
如果您對授權有任何疑問，歡迎透過以下方式聯繫：
- **GitHub Issues**: [建立 Issue](https://github.com/pi-docket/ConvertX-CN/issues)
- **GitHub Discussions**: [社群討論](https://github.com/pi-docket/ConvertX-CN/discussions)
---
[⬆️ 回到頂部](#授權說明) | [📚 回到目錄](00-專案總覽.md)

190
docs/說明文件.md
View file

@ -1,6 +1,22 @@
# ConvertX-CN 文件中心
歡迎來到 ConvertX-CN 文件！選擇您的角色快速找到所需資訊。
歡迎來到 ConvertX-CN 文件！選擇您需要的章節快速找到所需資訊。
---
## 📚 文件目錄
| 章節 | 說明 |
|------|------|
| [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 授權 |
---
@ -8,117 +24,45 @@
剛開始使用？從這裡開始：
1. **[概覽](快速入門/概覽.md)** — 了解 ConvertX-CN 是什麼
2. **[快速開始](快速入門/快速開始.md)** — 5 分鐘內完成部署
3. **[常見問題](快速入門/常見問題.md)** — 解決常見問題
1. **[專案總覽](00-專案總覽.md)** — 了解 ConvertX-CN 是什麼
2. **[快速開始](01-快速開始.md)** — 5 分鐘內完成部署
3. **[錯誤排查](06-錯誤排查與支援.md)** — 解決常見問題
---
## 👤 使用者指南
## 📁 補充文件
適合一般使用者：
以下為詳細的補充文件，提供更深入的資訊：
### 部署相關
| 文件 | 說明 |
| ------------------------------------ | -------------------- |
| [快速開始](快速入門/快速開始.md) | 最快部署方式 |
| [支援的轉換器](功能說明/轉換器.md) | 所有可用的轉換格式 |
| [OCR 功能](功能說明/OCR.md) | 光學字元辨識 |
| [翻譯功能](功能說明/翻譯功能.md) | PDF 翻譯（保留公式） |
| [多語言介面](功能說明/多語言介面.md) | 切換介面語言 |
| [常見問題](快速入門/常見問題.md) | FAQ |
|------|------|
| [部署指南/Docker.md](部署指南/Docker.md) | Docker 部署詳細說明 |
| [部署指南/反向代理.md](部署指南/反向代理.md) | Nginx / Traefik / Caddy |
| [範例配置/說明文件.md](範例配置/說明文件.md) | 可直接使用的配置檔 |
### 功能說明
| 文件 | 說明 |
|------|------|
| [功能說明/轉換器.md](功能說明/轉換器.md) | 所有轉換器詳細資訊 |
| [功能說明/OCR.md](功能說明/OCR.md) | OCR 功能說明 |
| [功能說明/翻譯功能.md](功能說明/翻譯功能.md) | PDF 翻譯功能 |
### 開發相關
| 文件 | 說明 |
|------|------|
| [開發指南/專案結構.md](開發指南/專案結構.md) | 程式碼結構說明 |
| [開發指南/貢獻指南.md](開發指南/貢獻指南.md) | 如何參與專案 |
| [API/總覽.md](API/總覽.md) | API 詳細說明 |
---
## 🛠️ 系統管理員指南
## 📄 授權
適合部署與維護人員：
### 部署
| 文件 | 說明 |
| -------------------------------------- | --------------------------- |
| [Docker 部署](部署指南/Docker.md) | Docker Run & Docker Compose |
| [Lite 版部署](部署指南/Docker-Lite.md) | 輕量版（較小 Image） |
| [反向代理](部署指南/反向代理.md) | Nginx / Traefik / Caddy |
| [範例配置](範例配置/說明文件.md) | 可直接使用的配置檔 |
### 配置
| 文件 | 說明 |
| ------------------------------------ | ------------------ |
| [環境變數](配置設定/環境變數.md) | 所有可用設定 |
| [安全性設定](配置設定/安全性.md) | HTTPS、認證、防護 |
| [清理與限制](配置設定/清理與限制.md) | 自動清理、資源限制 |
---
## 👩‍💻 開發者指南
適合貢獻者與擴充開發：
### 開發
| 文件 | 說明 |
| -------------------------------- | -------------- |
| [專案結構](開發指南/專案結構.md) | 程式碼結構說明 |
| [本地開發](開發指南/本地開發.md) | 開發環境設定 |
| [貢獻指南](開發指南/貢獻指南.md) | 如何參與專案 |
### API
| 文件 | 說明 |
| ----------------------- | ------------------ |
| [API 總覽](API/總覽.md) | REST & GraphQL API |
| [API 端點](API/端點.md) | 詳細端點說明 |
### 測試
| 文件 | 說明 |
| ---------------------------- | -------------- |
| [測試策略](測試/測試策略.md) | 測試類型與方法 |
| [CI/CD](測試/CI-CD.md) | 持續整合設定 |
| [E2E 測試](測試/E2E測試.md) | 端對端測試 |
---
## 📁 文件結構
```
docs/
├── 說明文件.md ← 您在這裡
├── 快速入門/
│ ├── 概覽.md
│ ├── 快速開始.md
│ └── 常見問題.md
├── 部署指南/
│ ├── Docker部署.md
│ └── 反向代理.md
├── 配置設定/
│ ├── 環境變數.md
│ ├── 安全性.md
│ └── 清理與限制.md
├── 功能說明/
│ ├── 轉換器.md
│ ├── 翻譯功能.md
│ ├── OCR.md
│ └── 多語言介面.md
├── API/
│ ├── 總覽.md
│ └── 端點.md
├── 測試/
│ ├── 測試策略.md
│ ├── CI-CD.md
│ └── E2E測試.md
├── 開發指南/
│ ├── 專案結構.md
│ ├── 本地開發.md
│ └── 貢獻指南.md
└── 範例配置/
├── compose.minimal.example.yml
├── compose.production.example.yml
├── traefik.example.yml
└── nginx.example.conf
```
本專案採用 **AGPL-3.0** 授權，詳情請參閱 [08-授權說明](08-授權說明.md)。
---
@ -129,45 +73,3 @@ docs/
- 💬 [Discussions](https://github.com/pi-docket/ConvertX-CN/discussions)
- 📝 [Changelog](../CHANGELOG.md)
- 📄 [License](../LICENSE)
---
## 📖 閱讀路徑建議
### 我是新手
1. [概覽](快速入門/概覽.md)
2. [快速開始](快速入門/快速開始.md)
3. [支援的轉換器](功能說明/轉換器.md)
### 我要部署到生產環境
1. [Docker 部署](部署指南/Docker部署.md)
2. [反向代理](部署指南/反向代理.md)
3. [安全性設定](配置設定/安全性.md)
4. [環境變數](配置設定/環境變數.md)
### 我想參與開發
1. [專案結構](開發指南/專案結構.md)
2. [本地開發](開發指南/本地開發.md)
3. [貢獻指南](開發指南/貢獻指南.md)
4. [測試策略](測試/測試策略.md)
---
## 🌐 多語言文件
此文件以繁體中文為主，我們也提供其他語言版本：
| 語言 | 說明 | 狀態 |
| -------------------------------- | --------------------- | --------- |
| [English](多語言/en/Overview.md) | English documentation | 🔄 進行中 |
| [简体中文](多語言/zh-CN/概述.md) | 简体中文文档 | 📋 規劃中 |
| [日本語](多語言/ja/概要.md) | 日本語ドキュメント | 📋 規劃中 |
> 📝 **想幫忙翻譯？** 請參閱 [翻譯指南](多語言/翻譯指南.md)
---
> 💡 **找不到您需要的資訊？** 歡迎到 [GitHub Discussions](https://github.com/pi-docket/ConvertX-CN/discussions) 發問！