新增錯誤排查與支援文件，提供常見問題解決方案；新增開發與貢獻指南，說明專案結構與開發流程；新增授權說明文件，詳述AGPL-3.0授權條款及第三方元件使用情況。
This commit is contained in:
Your Name
parent
11d751250b
commit
caecb2e001
13 changed files with 3269 additions and 369 deletions
154
docs/00-專案總覽.md
Normal file
154
docs/00-專案總覽.md
Normal 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
229
docs/01-快速開始.md
Normal 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
380
docs/02-部署指南.md
Normal 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
444
docs/03-環境變數與設定.md
Normal 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
370
docs/04-功能總覽.md
Normal 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
547
docs/05-API文件.md
Normal 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
415
docs/06-錯誤排查與支援.md
Normal 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
455
docs/07-開發與貢獻指南.md
Normal 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
190
docs/08-授權說明.md
Normal 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)
|
||||
192
docs/說明文件.md
192
docs/說明文件.md
|
|
@ -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) 發問！
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue