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