feat: 新增 OCRmyPDF 轉換引擎 (v0.1.14)
## 新功能 - OCRmyPDF 轉換引擎：將掃描版 PDF 轉換為可搜尋 PDF - 支援 7 種語言：en, zh-TW, zh, ja, ko, de, fr - 與 PDFMathTranslate 風格一致的 UI 格式 (pdf-<lang>) - 自動偵測頁面方向並旋轉 - 自動校正傾斜 - 跳過已有文字層的頁面 - 詳細的 5 階段處理進度輸出 ## 建置 - Dockerfile：安裝 ocrmypdf 與 Tesseract OCR 語言包 ## 文件 - 更新 OCR 功能文件 - 文件目錄結構改為中文名稱 ## 測試 - 修復 BabelDOC 和 PDFMathTranslate 測試的 OCR mock - 所有 345 個測試通過
This commit is contained in:
Your Name
parent
f24eec070c
commit
a06df23b1d
53 changed files with 1427 additions and 675 deletions
|
|
@ -123,6 +123,6 @@ curl -X POST \
|
|||
|
||||
## 相關文件
|
||||
|
||||
- [API 端點詳細說明](endpoints.md)
|
||||
- [API 端點詳細說明](端點.md)
|
||||
- [API 規格文件](../../api-server/docs/API_SPEC.md)
|
||||
- [架構說明](../../api-server/docs/ARCHITECTURE.md)
|
||||
156
docs/README.md
156
docs/README.md
|
|
@ -8,9 +8,9 @@
|
|||
|
||||
剛開始使用？從這裡開始：
|
||||
|
||||
1. **[概覽](getting-started/overview.md)** — 了解 ConvertX-CN 是什麼
|
||||
2. **[快速開始](getting-started/quick-start.md)** — 5 分鐘內完成部署
|
||||
3. **[常見問題](getting-started/faq.md)** — 解決常見問題
|
||||
1. **[概覽](快速入門/概覽.md)** — 了解 ConvertX-CN 是什麼
|
||||
2. **[快速開始](快速入門/快速開始.md)** — 5 分鐘內完成部署
|
||||
3. **[常見問題](快速入門/常見問題.md)** — 解決常見問題
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -18,14 +18,14 @@
|
|||
|
||||
適合一般使用者：
|
||||
|
||||
| 文件 | 說明 |
|
||||
| ------------------------------------------ | -------------------- |
|
||||
| [快速開始](getting-started/quick-start.md) | 最快部署方式 |
|
||||
| [支援的轉換器](features/converters.md) | 所有可用的轉換格式 |
|
||||
| [OCR 功能](features/ocr.md) | 光學字元辨識 |
|
||||
| [翻譯功能](features/translation.md) | PDF 翻譯（保留公式） |
|
||||
| [多語言介面](features/i18n.md) | 切換介面語言 |
|
||||
| [常見問題](getting-started/faq.md) | FAQ |
|
||||
| 文件 | 說明 |
|
||||
| ---------------------------------- | -------------------- |
|
||||
| [快速開始](快速入門/快速開始.md) | 最快部署方式 |
|
||||
| [支援的轉換器](功能說明/轉換器.md) | 所有可用的轉換格式 |
|
||||
| [OCR 功能](功能說明/OCR.md) | 光學字元辨識 |
|
||||
| [翻譯功能](功能說明/翻譯.md) | PDF 翻譯（保留公式） |
|
||||
| [多語言介面](功能說明/多語言.md) | 切換介面語言 |
|
||||
| [常見問題](快速入門/常見問題.md) | FAQ |
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -35,19 +35,19 @@
|
|||
|
||||
### 部署
|
||||
|
||||
| 文件 | 說明 |
|
||||
| --------------------------------------- | --------------------------- |
|
||||
| [Docker 部署](deployment/docker.md) | Docker Run & Docker Compose |
|
||||
| [反向代理](deployment/reverse-proxy.md) | Nginx / Traefik / Caddy |
|
||||
| [範例配置](samples/README.md) | 可直接使用的配置檔 |
|
||||
| 文件 | 說明 |
|
||||
| --------------------------------- | --------------------------- |
|
||||
| [Docker 部署](部署指南/Docker.md) | Docker Run & Docker Compose |
|
||||
| [反向代理](部署指南/反向代理.md) | Nginx / Traefik / Caddy |
|
||||
| [範例配置](範例/README.md) | 可直接使用的配置檔 |
|
||||
|
||||
### 配置
|
||||
|
||||
| 文件 | 說明 |
|
||||
| -------------------------------------------------- | ------------------ |
|
||||
| [環境變數](configuration/environment-variables.md) | 所有可用設定 |
|
||||
| [安全性設定](configuration/security.md) | HTTPS、認證、防護 |
|
||||
| [清理與限制](configuration/limits-and-cleanup.md) | 自動清理、資源限制 |
|
||||
| 文件 | 說明 |
|
||||
| ------------------------------------ | ------------------ |
|
||||
| [環境變數](配置設定/環境變數.md) | 所有可用設定 |
|
||||
| [安全性設定](配置設定/安全性.md) | HTTPS、認證、防護 |
|
||||
| [清理與限制](配置設定/清理與限制.md) | 自動清理、資源限制 |
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -57,26 +57,26 @@
|
|||
|
||||
### 開發
|
||||
|
||||
| 文件 | 說明 |
|
||||
| -------------------------------------------- | -------------- |
|
||||
| [專案結構](development/project-structure.md) | 程式碼結構說明 |
|
||||
| [本地開發](development/local-development.md) | 開發環境設定 |
|
||||
| [貢獻指南](development/contribution.md) | 如何參與專案 |
|
||||
| 文件 | 說明 |
|
||||
| -------------------------------- | -------------- |
|
||||
| [專案結構](開發指南/專案結構.md) | 程式碼結構說明 |
|
||||
| [本地開發](開發指南/本地開發.md) | 開發環境設定 |
|
||||
| [貢獻指南](開發指南/貢獻指南.md) | 如何參與專案 |
|
||||
|
||||
### API
|
||||
|
||||
| 文件 | 說明 |
|
||||
| ---------------------------- | ------------------ |
|
||||
| [API 總覽](api/overview.md) | REST & GraphQL API |
|
||||
| [API 端點](api/endpoints.md) | 詳細端點說明 |
|
||||
| 文件 | 說明 |
|
||||
| ----------------------- | ------------------ |
|
||||
| [API 總覽](API/總覽.md) | REST & GraphQL API |
|
||||
| [API 端點](API/端點.md) | 詳細端點說明 |
|
||||
|
||||
### 測試
|
||||
|
||||
| 文件 | 說明 |
|
||||
| ------------------------------------ | -------------- |
|
||||
| [測試策略](testing/test-strategy.md) | 測試類型與方法 |
|
||||
| [CI/CD](testing/ci-cd.md) | 持續整合設定 |
|
||||
| [E2E 測試](testing/e2e-tests.md) | 端對端測試 |
|
||||
| 文件 | 說明 |
|
||||
| ---------------------------- | -------------- |
|
||||
| [測試策略](測試/測試策略.md) | 測試類型與方法 |
|
||||
| [CI/CD](測試/CI-CD.md) | 持續整合設定 |
|
||||
| [E2E 測試](測試/E2E測試.md) | 端對端測試 |
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -85,38 +85,38 @@
|
|||
```
|
||||
docs/
|
||||
├── README.md ← 您在這裡
|
||||
├── getting-started/ # 快速入門
|
||||
│ ├── overview.md # 概覽
|
||||
│ ├── quick-start.md # 快速開始
|
||||
│ └── faq.md # 常見問題
|
||||
├── deployment/ # 部署指南
|
||||
│ ├── docker.md # Docker 部署
|
||||
│ └── reverse-proxy.md # 反向代理
|
||||
├── configuration/ # 配置設定
|
||||
│ ├── environment-variables.md # 環境變數
|
||||
│ ├── security.md # 安全性
|
||||
│ └── limits-and-cleanup.md # 清理與限制
|
||||
├── features/ # 功能說明
|
||||
│ ├── converters.md # 轉換器
|
||||
│ ├── translation.md # 翻譯
|
||||
│ ├── ocr.md # OCR
|
||||
│ └── i18n.md # 多語言
|
||||
├── api/ # API 文件
|
||||
│ ├── overview.md # API 總覽
|
||||
│ └── endpoints.md # API 端點
|
||||
├── testing/ # 測試
|
||||
│ ├── test-strategy.md # 測試策略
|
||||
│ ├── ci-cd.md # CI/CD
|
||||
│ └── e2e-tests.md # E2E 測試
|
||||
├── development/ # 開發指南
|
||||
│ ├── project-structure.md # 專案結構
|
||||
│ ├── local-development.md # 本地開發
|
||||
│ └── contribution.md # 貢獻指南
|
||||
└── samples/ # 範例檔案
|
||||
├── compose.minimal.yml # 最小配置
|
||||
├── compose.production.yml # 生產環境
|
||||
├── compose.with-traefik.yml # Traefik 整合
|
||||
└── nginx.example.conf # Nginx 設定
|
||||
├── 快速入門/
|
||||
│ ├── 概覽.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.yml
|
||||
├── compose.production.yml
|
||||
├── compose.with-traefik.yml
|
||||
└── nginx.example.conf
|
||||
```
|
||||
|
||||
---
|
||||
|
|
@ -135,23 +135,23 @@ docs/
|
|||
|
||||
### 我是新手
|
||||
|
||||
1. [概覽](getting-started/overview.md)
|
||||
2. [快速開始](getting-started/quick-start.md)
|
||||
3. [支援的轉換器](features/converters.md)
|
||||
1. [概覽](快速入門/概覽.md)
|
||||
2. [快速開始](快速入門/快速開始.md)
|
||||
3. [支援的轉換器](功能說明/轉換器.md)
|
||||
|
||||
### 我要部署到生產環境
|
||||
|
||||
1. [Docker 部署](deployment/docker.md)
|
||||
2. [反向代理](deployment/reverse-proxy.md)
|
||||
3. [安全性設定](configuration/security.md)
|
||||
4. [環境變數](configuration/environment-variables.md)
|
||||
1. [Docker 部署](部署指南/Docker.md)
|
||||
2. [反向代理](部署指南/反向代理.md)
|
||||
3. [安全性設定](配置設定/安全性.md)
|
||||
4. [環境變數](配置設定/環境變數.md)
|
||||
|
||||
### 我想參與開發
|
||||
|
||||
1. [專案結構](development/project-structure.md)
|
||||
2. [本地開發](development/local-development.md)
|
||||
3. [貢獻指南](development/contribution.md)
|
||||
4. [測試策略](testing/test-strategy.md)
|
||||
1. [專案結構](開發指南/專案結構.md)
|
||||
2. [本地開發](開發指南/本地開發.md)
|
||||
3. [貢獻指南](開發指南/貢獻指南.md)
|
||||
4. [測試策略](測試/測試策略.md)
|
||||
|
||||
---
|
||||
|
||||
|
|
|
|||
|
|
@ -4,8 +4,8 @@
|
|||
>
|
||||
> 本文件內容已整合至新的文件結構，請參閱：
|
||||
>
|
||||
> - 🐳 [Docker 部署（含硬體加速）](deployment/docker.md)
|
||||
> - 🔧 [反向代理設定](deployment/reverse-proxy.md)
|
||||
> - 🐳 [Docker 部署（含硬體加速）](部署指南/Docker.md)
|
||||
> - 🔧 [反向代理設定](部署指南/反向代理.md)
|
||||
>
|
||||
> 此文件將在未來版本中移除。
|
||||
|
||||
|
|
|
|||
|
|
@ -4,9 +4,9 @@
|
|||
>
|
||||
> 本文件內容已整合至新的文件結構，請參閱：
|
||||
>
|
||||
> - ⚙️ [環境變數設定](../configuration/environment-variables.md)
|
||||
> - 🔒 [安全性設定](../configuration/security.md)
|
||||
> - 🧹 [清理與限制](../configuration/limits-and-cleanup.md)
|
||||
> - ⚙️ [環境變數設定](../配置設定/環境變數.md)
|
||||
> - 🔒 [安全性設定](../配置設定/安全性.md)
|
||||
> - 🧹 [清理與限制](../配置設定/清理與限制.md)
|
||||
>
|
||||
> 此文件將在未來版本中移除。
|
||||
|
||||
|
|
|
|||
|
|
@ -4,7 +4,7 @@
|
|||
>
|
||||
> 本文件內容已整合至新的文件結構，請參閱：
|
||||
>
|
||||
> - 🔒 [安全性設定](../configuration/security.md)
|
||||
> - 🔒 [安全性設定](../配置設定/安全性.md)
|
||||
>
|
||||
> 此文件將在未來版本中移除。
|
||||
|
||||
|
|
|
|||
|
|
@ -4,9 +4,9 @@
|
|||
>
|
||||
> 本文件內容已整合至新的文件結構，請參閱：
|
||||
>
|
||||
> - 🔌 [轉換器完整說明](features/converters.md)
|
||||
> - 📊 [OCR 功能](features/ocr.md)
|
||||
> - 🌐 [翻譯功能](features/translation.md)
|
||||
> - 🔌 [轉換器完整說明](功能說明/轉換器.md)
|
||||
> - 📊 [OCR 功能](功能說明/OCR.md)
|
||||
> - 🌐 [翻譯功能](功能說明/翻譯.md)
|
||||
>
|
||||
> 此文件將在未來版本中移除。
|
||||
|
||||
|
|
|
|||
|
|
@ -4,9 +4,9 @@
|
|||
>
|
||||
> 本文件內容已整合至新的文件結構，請參閱：
|
||||
>
|
||||
> - 🐳 [Docker 部署](deployment/docker.md)
|
||||
> - 🔧 [反向代理設定](deployment/reverse-proxy.md)
|
||||
> - 🔒 [安全性設定](configuration/security.md)
|
||||
> - 🐳 [Docker 部署](部署指南/Docker.md)
|
||||
> - 🔧 [反向代理設定](部署指南/反向代理.md)
|
||||
> - 🔒 [安全性設定](配置設定/安全性.md)
|
||||
>
|
||||
> 此文件將在未來版本中移除。
|
||||
|
||||
|
|
|
|||
|
|
@ -4,8 +4,8 @@
|
|||
>
|
||||
> 本文件內容已整合至新的文件結構，請參閱：
|
||||
>
|
||||
> - 📦 [Docker 部署指南](deployment/docker.md)
|
||||
> - 🔧 [反向代理設定](deployment/reverse-proxy.md)
|
||||
> - 📦 [Docker 部署指南](部署指南/Docker.md)
|
||||
> - 🔧 [反向代理設定](部署指南/反向代理.md)
|
||||
>
|
||||
> 此文件將在未來版本中移除。
|
||||
|
||||
|
|
|
|||
|
|
@ -4,7 +4,7 @@
|
|||
>
|
||||
> 本文件內容已整合至新的文件結構，請參閱：
|
||||
>
|
||||
> - ❓ [常見問題 FAQ](getting-started/faq.md)
|
||||
> - ❓ [常見問題 FAQ](快速入門/常見問題.md)
|
||||
>
|
||||
> 此文件將在未來版本中移除。
|
||||
|
||||
|
|
|
|||
|
|
@ -1,118 +0,0 @@
|
|||
# 翻譯功能
|
||||
|
||||
ConvertX-CN 內建 PDFMathTranslate 引擎，可翻譯 PDF 同時保留數學公式與排版。
|
||||
|
||||
---
|
||||
|
||||
## 功能特色
|
||||
|
||||
- 📊 **保留數學公式**：LaTeX 公式完整保留
|
||||
- 📈 **保留圖表**：圖片、表格位置不變
|
||||
- 📑 **保留目錄**：連結與結構完整
|
||||
- 🌐 **多語言支援**：15+ 種目標語言
|
||||
|
||||
---
|
||||
|
||||
## 支援的目標語言
|
||||
|
||||
| 格式代碼 | 目標語言 |
|
||||
| ----------- | -------- |
|
||||
| `pdf-en` | 英文 |
|
||||
| `pdf-zh` | 簡體中文 |
|
||||
| `pdf-zh-TW` | 繁體中文 |
|
||||
| `pdf-ja` | 日文 |
|
||||
| `pdf-ko` | 韓文 |
|
||||
| `pdf-de` | 德文 |
|
||||
| `pdf-fr` | 法文 |
|
||||
| `pdf-es` | 西班牙文 |
|
||||
| `pdf-it` | 義大利文 |
|
||||
| `pdf-pt` | 葡萄牙文 |
|
||||
| `pdf-ru` | 俄文 |
|
||||
| `pdf-ar` | 阿拉伯文 |
|
||||
| `pdf-hi` | 印地文 |
|
||||
| `pdf-vi` | 越南文 |
|
||||
| `pdf-th` | 泰文 |
|
||||
|
||||
---
|
||||
|
||||
## 使用方式
|
||||
|
||||
1. 上傳 PDF 檔案
|
||||
2. 在目標格式選擇 `pdf-zh-TW`（或其他語言）
|
||||
3. 點擊轉換
|
||||
4. 下載翻譯後的 PDF
|
||||
|
||||
---
|
||||
|
||||
## 輸出格式
|
||||
|
||||
所有輸出一律打包為 `.tar` 檔案，包含：
|
||||
|
||||
```
|
||||
output.tar
|
||||
├── original.pdf # 原始 PDF
|
||||
└── translated-*.pdf # 翻譯後的 PDF
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 環境變數設定
|
||||
|
||||
### PDFMATHTRANSLATE_SERVICE
|
||||
|
||||
選擇翻譯服務提供商。
|
||||
|
||||
| 值 | 說明 |
|
||||
| -------- | ------------------- |
|
||||
| `google` | Google 翻譯（預設） |
|
||||
| `deepl` | DeepL 翻譯 |
|
||||
| `openai` | OpenAI API |
|
||||
| `azure` | Azure Translator |
|
||||
|
||||
```yaml
|
||||
environment:
|
||||
- PDFMATHTRANSLATE_SERVICE=google
|
||||
```
|
||||
|
||||
### 使用付費服務
|
||||
|
||||
如需使用 DeepL 或 OpenAI 等付費服務，需設定 API Key：
|
||||
|
||||
```yaml
|
||||
environment:
|
||||
- PDFMATHTRANSLATE_SERVICE=openai
|
||||
- OPENAI_API_KEY=sk-xxxxx
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 適用場景
|
||||
|
||||
### ✅ 適合
|
||||
|
||||
- 學術論文翻譯
|
||||
- 數學/物理教科書
|
||||
- 技術文件翻譯
|
||||
- AI/ML 論文
|
||||
|
||||
### ⚠️ 限制
|
||||
|
||||
- 掃描版 PDF（需先 OCR）
|
||||
- 複雜排版的雜誌
|
||||
- 手寫文件
|
||||
|
||||
---
|
||||
|
||||
## 注意事項
|
||||
|
||||
1. **模型已預載**：所需模型已在 Docker build 階段下載
|
||||
2. **不會隱式下載**：Runtime 不會下載額外模型
|
||||
3. **預設免費服務**：使用 Google 翻譯（免費）
|
||||
|
||||
---
|
||||
|
||||
## 相關文件
|
||||
|
||||
- [支援的轉換器](converters.md)
|
||||
- [OCR 功能](ocr.md)
|
||||
- [環境變數設定](../configuration/environment-variables.md)
|
||||
|
|
@ -4,9 +4,9 @@
|
|||
>
|
||||
> 本文件內容已整合至新的文件結構，請參閱：
|
||||
>
|
||||
> - 📖 [概覽](getting-started/overview.md)
|
||||
> - 🚀 [快速開始](getting-started/quick-start.md)
|
||||
> - ❓ [常見問題](getting-started/faq.md)
|
||||
> - 📖 [概覽](快速入門/概覽.md)
|
||||
> - 🚀 [快速開始](快速入門/快速開始.md)
|
||||
> - ❓ [常見問題](快速入門/常見問題.md)
|
||||
>
|
||||
> 此文件將在未來版本中移除。
|
||||
|
||||
|
|
|
|||
|
|
@ -4,7 +4,7 @@
|
|||
>
|
||||
> 本文件內容已整合至新的文件結構，請參閱：
|
||||
>
|
||||
> - 🌐 [多語言介面支援](features/i18n.md)
|
||||
> - 🌐 [多語言介面支援](功能說明/多語言.md)
|
||||
>
|
||||
> 此文件將在未來版本中移除。
|
||||
|
||||
|
|
|
|||
|
|
@ -4,8 +4,8 @@
|
|||
>
|
||||
> 本文件內容已整合至新的文件結構，請參閱：
|
||||
>
|
||||
> - 🛠️ [專案結構](development/project-structure.md)
|
||||
> - 🐳 [Docker 部署](deployment/docker.md)
|
||||
> - 🛠️ [專案結構](開發指南/專案結構.md)
|
||||
> - 🐳 [Docker 部署](部署指南/Docker.md)
|
||||
>
|
||||
> 此文件將在未來版本中移除。
|
||||
|
||||
|
|
|
|||
|
|
@ -1,6 +1,10 @@
|
|||
# OCR 功能
|
||||
|
||||
ConvertX-CN 內建 Tesseract OCR，可將圖片中的文字轉換為可編輯文字。
|
||||
ConvertX-CN 內建 Tesseract OCR 與 ocrmypdf，提供完整的 OCR 功能：
|
||||
|
||||
- **圖片 OCR**：將圖片中的文字轉換為可編輯文字
|
||||
- **PDF OCR**：將掃描版 PDF 轉換為可搜尋 PDF（加入文字層）
|
||||
- **PDF 自動偵測**：翻譯引擎會自動偵測掃描版 PDF 並進行 OCR 處理
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -22,24 +26,51 @@ ConvertX-CN 完整版內建以下 OCR 語言：
|
|||
|
||||
## 使用方式
|
||||
|
||||
### PDF → 可搜尋 PDF（OCR）
|
||||
|
||||
將掃描版 PDF 轉換為可搜尋 PDF：
|
||||
|
||||
1. 上傳 PDF 檔案
|
||||
2. 選擇 Converter: `OCRmyPDF`
|
||||
3. 選擇目標語言：
|
||||
| 格式 | 說明 |
|
||||
| ---- | ---- |
|
||||
| `pdf-en` | English |
|
||||
| `pdf-zh-TW` | 繁體中文 |
|
||||
| `pdf-zh` | 簡體中文 |
|
||||
| `pdf-ja` | 日本語 |
|
||||
| `pdf-ko` | 한국어 |
|
||||
| `pdf-de` | Deutsch |
|
||||
| `pdf-fr` | Français |
|
||||
4. 進行轉換
|
||||
|
||||
> 💡 **功能特點**：
|
||||
>
|
||||
> - 自動偵測頁面方向並旋轉
|
||||
> - 自動校正傾斜
|
||||
> - 跳過已有文字層的頁面
|
||||
> - 詳細的處理進度輸出
|
||||
|
||||
### 圖片 → 文字
|
||||
|
||||
1. 上傳圖片（PNG, JPG, TIFF 等）
|
||||
2. 選擇目標格式 `txt` 或 `pdf`（可搜尋）
|
||||
3. 進行轉換
|
||||
|
||||
### PDF → 可搜尋 PDF
|
||||
### 掃描版 PDF 翻譯（自動處理）
|
||||
|
||||
1. 上傳掃描版 PDF
|
||||
2. 選擇 OCR 處理
|
||||
3. 獲得可搜尋的 PDF
|
||||
當使用 PDFMathTranslate 或 BabelDOC 翻譯 PDF 時：
|
||||
|
||||
1. 系統會**自動偵測**是否為掃描版 PDF（無文字層）
|
||||
2. 若為掃描版，系統會**自動執行 OCR** 加入文字層
|
||||
3. 翻譯引擎使用 OCR 處理後的 PDF 進行翻譯
|
||||
4. 使用者無需手動操作，全程自動完成
|
||||
|
||||
---
|
||||
|
||||
## 支援的輸入格式
|
||||
|
||||
- **點陣圖**：PNG, JPG, JPEG, TIFF, BMP, GIF
|
||||
- **文件**：PDF（掃描版）
|
||||
- **其他**：WebP, PNM, PBM
|
||||
|
||||
---
|
||||
|
|
@ -78,14 +109,18 @@ Tesseract 可同時辨識多種語言，但準確度可能下降。
|
|||
|
||||
### 方法一：自訂 Dockerfile
|
||||
|
||||
> 💡 在 `Dockerfile.full` 中取消註解以下內容
|
||||
|
||||
```dockerfile
|
||||
# 在 Dockerfile.full 中取消註解
|
||||
RUN apt-get update && apt-get install -y --no-install-recommends \
|
||||
tesseract-ocr-spa \ # 西班牙文
|
||||
tesseract-ocr-ita \ # 義大利文
|
||||
tesseract-ocr-spa \
|
||||
tesseract-ocr-ita \
|
||||
&& rm -rf /var/lib/apt/lists/*
|
||||
```
|
||||
|
||||
- `tesseract-ocr-spa` — 西班牙文
|
||||
- `tesseract-ocr-ita` — 義大利文
|
||||
|
||||
### 方法二：掛載語言包
|
||||
|
||||
```yaml
|
||||
|
|
@ -112,6 +147,6 @@ volumes:
|
|||
|
||||
## 相關文件
|
||||
|
||||
- [支援的轉換器](converters.md)
|
||||
- [翻譯功能](translation.md)
|
||||
- [Docker 部署](../deployment/docker.md)
|
||||
- [支援的轉換器](轉換器.md)
|
||||
- [翻譯功能](翻譯.md)
|
||||
- [Docker 部署](../部署指南/Docker.md)
|
||||
|
|
@ -128,5 +128,5 @@ http://localhost:3000/?lang=ja
|
|||
|
||||
## 相關文件
|
||||
|
||||
- [貢獻指南](../development/contribution.md)
|
||||
- [專案結構](../development/project-structure.md)
|
||||
- [貢獻指南](../開發指南/貢獻指南.md)
|
||||
- [專案結構](../開發指南/專案結構.md)
|
||||
187
docs/功能說明/翻譯.md
Normal file
187
docs/功能說明/翻譯.md
Normal file
|
|
@ -0,0 +1,187 @@
|
|||
# 翻譯功能
|
||||
|
||||
ConvertX-CN 內建兩個 PDF 翻譯引擎：
|
||||
|
||||
| 引擎 | 命令 | 輸出格式 | 特色 |
|
||||
| -------------------- | ---------- | --------------------- | -------------------- |
|
||||
| **PDFMathTranslate** | `pdf2zh` | PDF | 保留數學公式與排版 |
|
||||
| **BabelDOC** | `babeldoc` | PDF / Markdown / HTML | 多格式輸出、快速翻譯 |
|
||||
|
||||
---
|
||||
|
||||
## PDFMathTranslate
|
||||
|
||||
適合學術論文、數學/物理教科書等需要保留公式的文件。
|
||||
|
||||
### 功能特色
|
||||
|
||||
- 📊 **保留數學公式**：LaTeX 公式完整保留
|
||||
- 📈 **保留圖表**：圖片、表格位置不變
|
||||
- 📑 **保留目錄**：連結與結構完整
|
||||
- 🌐 **多語言支援**：15+ 種目標語言
|
||||
|
||||
### 使用方式
|
||||
|
||||
1. 上傳 PDF 檔案
|
||||
2. 在目標格式選擇 `pdf-zh-TW`（或其他語言代碼）
|
||||
3. 點擊轉換
|
||||
4. 下載翻譯後的 PDF（.tar 檔案）
|
||||
|
||||
---
|
||||
|
||||
## BabelDOC
|
||||
|
||||
適合一般文件翻譯，支援多種輸出格式。
|
||||
|
||||
### 功能特色
|
||||
|
||||
- 📄 **多格式輸出**：PDF、Markdown、HTML
|
||||
- ⚡ **快速翻譯**：針對一般文件優化
|
||||
- 🔄 **格式轉換**：可同時翻譯並轉換格式
|
||||
|
||||
### 使用方式
|
||||
|
||||
1. 上傳 PDF 檔案
|
||||
2. 在目標格式選擇：
|
||||
- `pdf-zh-TW`：翻譯後輸出 PDF
|
||||
- `md-zh-TW`：翻譯後輸出 Markdown
|
||||
- `html-zh-TW`：翻譯後輸出 HTML
|
||||
3. 點擊轉換
|
||||
4. 下載結果（.tar 檔案）
|
||||
|
||||
---
|
||||
|
||||
## 支援的目標語言
|
||||
|
||||
兩個引擎都支援以下語言：
|
||||
|
||||
| 格式代碼 | 目標語言 |
|
||||
| ----------- | -------- |
|
||||
| `pdf-en` | 英文 |
|
||||
| `pdf-zh` | 簡體中文 |
|
||||
| `pdf-zh-TW` | 繁體中文 |
|
||||
| `pdf-ja` | 日文 |
|
||||
| `pdf-ko` | 韓文 |
|
||||
| `pdf-de` | 德文 |
|
||||
| `pdf-fr` | 法文 |
|
||||
| `pdf-es` | 西班牙文 |
|
||||
| `pdf-it` | 義大利文 |
|
||||
| `pdf-pt` | 葡萄牙文 |
|
||||
| `pdf-ru` | 俄文 |
|
||||
| `pdf-ar` | 阿拉伯文 |
|
||||
| `pdf-hi` | 印地文 |
|
||||
| `pdf-vi` | 越南文 |
|
||||
| `pdf-th` | 泰文 |
|
||||
|
||||
> 💡 BabelDOC 額外支援 `md-<lang>` 和 `html-<lang>` 格式
|
||||
|
||||
---
|
||||
|
||||
## 輸出格式
|
||||
|
||||
所有輸出一律打包為 `.tar` 檔案：
|
||||
|
||||
### PDFMathTranslate 輸出
|
||||
|
||||
```
|
||||
output.tar
|
||||
├── original.pdf # 原始 PDF
|
||||
└── translated-*.pdf # 翻譯後的 PDF
|
||||
```
|
||||
|
||||
### BabelDOC 輸出
|
||||
|
||||
```
|
||||
output.tar
|
||||
├── translated-*.pdf # 翻譯後的 PDF（如果選擇 pdf-*）
|
||||
├── translated-*.md # 翻譯後的 Markdown（如果選擇 md-*）
|
||||
└── translated-*.html # 翻譯後的 HTML（如果選擇 html-*）
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 環境變數設定
|
||||
|
||||
### 翻譯服務（PDFMathTranslate）
|
||||
|
||||
> 💡 `PDFMATHTRANSLATE_SERVICE` 可選值：`google`（預設）、`bing`、`deepl`、`openai`、`azure`
|
||||
|
||||
```yaml
|
||||
environment:
|
||||
- PDFMATHTRANSLATE_SERVICE=google
|
||||
```
|
||||
|
||||
| 服務 | 說明 | 需要 API Key |
|
||||
| -------- | ---------------- | ------------ |
|
||||
| `google` | Google 翻譯 | ❌ 免費 |
|
||||
| `bing` | Bing 翻譯 | ❌ 免費 |
|
||||
| `deepl` | DeepL 翻譯 | ✅ |
|
||||
| `openai` | OpenAI API | ✅ |
|
||||
| `azure` | Azure Translator | ✅ |
|
||||
|
||||
### 使用付費服務
|
||||
|
||||
如需使用付費服務，需設定對應的 API Key：
|
||||
|
||||
```yaml
|
||||
environment:
|
||||
- PDFMATHTRANSLATE_SERVICE=openai
|
||||
- OPENAI_API_KEY=sk-xxxxx
|
||||
# 或
|
||||
- PDFMATHTRANSLATE_SERVICE=deepl
|
||||
- DEEPL_API_KEY=xxxxx
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 適用場景
|
||||
|
||||
### PDFMathTranslate 適合
|
||||
|
||||
- ✅ 學術論文翻譯
|
||||
- ✅ 數學/物理教科書
|
||||
- ✅ 包含 LaTeX 公式的文件
|
||||
- ✅ AI/ML 論文
|
||||
|
||||
### BabelDOC 適合
|
||||
|
||||
- ✅ 一般文件翻譯
|
||||
- ✅ 需要 Markdown 輸出（方便後續編輯）
|
||||
- ✅ 需要 HTML 輸出（網頁展示）
|
||||
- ✅ 快速翻譯大量文件
|
||||
|
||||
### ⚠️ 共同限制
|
||||
|
||||
- 掃描版 PDF（系統會自動偵測並使用 OCR 處理）
|
||||
- 複雜排版的雜誌
|
||||
- 手寫文件
|
||||
|
||||
---
|
||||
|
||||
## 如何選擇引擎？
|
||||
|
||||
| 需求 | 推薦引擎 |
|
||||
| ------------------ | ---------------- |
|
||||
| 有數學公式 | PDFMathTranslate |
|
||||
| 需要 Markdown 輸出 | BabelDOC |
|
||||
| 需要 HTML 輸出 | BabelDOC |
|
||||
| 一般商業文件 | 兩者皆可 |
|
||||
| 追求翻譯品質 | PDFMathTranslate |
|
||||
| 追求翻譯速度 | BabelDOC |
|
||||
|
||||
---
|
||||
|
||||
## 注意事項
|
||||
|
||||
1. **模型已預載**：所需模型已在 Docker build 階段下載
|
||||
2. **不會隱式下載**：Runtime 不會下載額外模型
|
||||
3. **預設免費服務**：使用 Google/Bing 翻譯（免費）
|
||||
4. **離線模式**：可設定 `HF_HUB_OFFLINE=1` 確保完全離線
|
||||
|
||||
---
|
||||
|
||||
## 相關文件
|
||||
|
||||
- [支援的轉換器](轉換器.md)
|
||||
- [OCR 功能](OCR.md)
|
||||
- [環境變數設定](../配置設定/環境變數.md)
|
||||
|
|
@ -130,7 +130,7 @@ docker compose up -d
|
|||
- 繁體中文、簡體中文
|
||||
- 日文、韓文
|
||||
- 英文、德文、法文
|
||||
- 更多詳見 [多語言支援](../features/i18n.md)
|
||||
- 更多詳見 [多語言支援](../功能說明/多語言.md)
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -138,7 +138,7 @@ docker compose up -d
|
|||
|
||||
### Q: 支援哪些格式？
|
||||
|
||||
1000+ 種格式，詳見 [支援的轉換器](../features/converters.md)
|
||||
1000+ 種格式，詳見 [支援的轉換器](../功能說明/轉換器.md)
|
||||
|
||||
### Q: 轉換失敗怎麼辦？
|
||||
|
||||
|
|
@ -169,11 +169,11 @@ client_max_body_size 500M;
|
|||
|
||||
### Q: 如何使用反向代理？
|
||||
|
||||
詳見 [反向代理設定](../deployment/reverse-proxy.md)
|
||||
詳見 [反向代理設定](../部署指南/反向代理.md)
|
||||
|
||||
### Q: 如何啟用硬體加速？
|
||||
|
||||
詳見 [進階配置 - 硬體加速](../deployment/docker.md#硬體加速)
|
||||
詳見 [進階配置 - 硬體加速](../部署指南/Docker.md#硬體加速)
|
||||
|
||||
### Q: 如何啟用 API Server？
|
||||
|
||||
|
|
@ -181,7 +181,7 @@ client_max_body_size 500M;
|
|||
docker compose --profile api up -d
|
||||
```
|
||||
|
||||
詳見 [API 文件](../api/overview.md)
|
||||
詳見 [API 文件](../API/總覽.md)
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -138,7 +138,7 @@ environment:
|
|||
|
||||
## 下一步
|
||||
|
||||
- 📖 [Docker 詳細配置](../deployment/docker.md)
|
||||
- ⚙️ [環境變數設定](../configuration/environment-variables.md)
|
||||
- 🔒 [安全性設定](../configuration/security.md)
|
||||
- 🔧 [反向代理設定](../deployment/reverse-proxy.md)
|
||||
- 📖 [Docker 詳細配置](../部署指南/Docker.md)
|
||||
- ⚙️ [環境變數設定](../配置設定/環境變數.md)
|
||||
- 🔒 [安全性設定](../配置設定/安全性.md)
|
||||
- 🔧 [反向代理設定](../部署指南/反向代理.md)
|
||||
|
|
@ -78,6 +78,6 @@ ConvertX-CN 是 fork 自 [C4illin/ConvertX](https://github.com/C4illin/ConvertX)
|
|||
|
||||
## 下一步
|
||||
|
||||
- 🚀 [快速開始](quick-start.md) — 5 分鐘內完成部署
|
||||
- ❓ [常見問題](faq.md) — 解決常見問題
|
||||
- 📦 [Docker 部署](../deployment/docker.md) — 詳細部署指南
|
||||
- 🚀 [快速開始](快速開始.md) — 5 分鐘內完成部署
|
||||
- ❓ [常見問題](常見問題.md) — 解決常見問題
|
||||
- 📦 [Docker 部署](../部署指南/Docker.md) — 詳細部署指南
|
||||
|
|
@ -143,6 +143,6 @@ docker build -t convertx-cn-test .
|
|||
|
||||
## 相關文件
|
||||
|
||||
- [測試策略](test-strategy.md)
|
||||
- [E2E 測試](e2e-tests.md)
|
||||
- [貢獻指南](../development/contribution.md)
|
||||
- [測試策略](測試策略.md)
|
||||
- [E2E 測試](E2E測試.md)
|
||||
- [貢獻指南](../開發指南/貢獻指南.md)
|
||||
|
|
@ -176,6 +176,6 @@ npx playwright codegen http://localhost:3000
|
|||
|
||||
## 相關文件
|
||||
|
||||
- [測試策略](test-strategy.md)
|
||||
- [CI/CD](ci-cd.md)
|
||||
- [本地開發](../development/local-development.md)
|
||||
- [測試策略](測試策略.md)
|
||||
- [CI/CD](CI-CD.md)
|
||||
- [本地開發](../開發指南/本地開發.md)
|
||||
|
|
@ -49,6 +49,6 @@ docker compose up -d
|
|||
|
||||
## 相關文件
|
||||
|
||||
- [Docker 部署](../deployment/docker.md)
|
||||
- [環境變數](../configuration/environment-variables.md)
|
||||
- [反向代理](../deployment/reverse-proxy.md)
|
||||
- [Docker 部署](../部署指南/Docker.md)
|
||||
- [環境變數](../配置設定/環境變數.md)
|
||||
- [反向代理](../部署指南/反向代理.md)
|
||||
|
|
@ -97,21 +97,29 @@ docker run -d \
|
|||
|
||||
**重要**：請務必先建立資料夾，否則 Docker 會建立匿名 volume。
|
||||
|
||||
```bash
|
||||
# Linux / macOS
|
||||
mkdir -p ~/convertx-cn/data
|
||||
**Linux / macOS：**
|
||||
|
||||
# Windows PowerShell
|
||||
```bash
|
||||
mkdir -p ~/convertx-cn/data
|
||||
```
|
||||
|
||||
**Windows PowerShell：**
|
||||
|
||||
```powershell
|
||||
mkdir C:\convertx-cn\data
|
||||
```
|
||||
|
||||
### 備份與還原
|
||||
|
||||
```bash
|
||||
# 備份
|
||||
tar -czvf convertx-backup-$(date +%Y%m%d).tar.gz ./data
|
||||
**備份：**
|
||||
|
||||
# 還原
|
||||
```bash
|
||||
tar -czvf convertx-backup-$(date +%Y%m%d).tar.gz ./data
|
||||
```
|
||||
|
||||
**還原：**
|
||||
|
||||
```bash
|
||||
tar -xzvf convertx-backup-20260120.tar.gz
|
||||
```
|
||||
|
||||
|
|
@ -199,18 +207,23 @@ services:
|
|||
|
||||
## 版本更新
|
||||
|
||||
```bash
|
||||
# 拉取最新版本
|
||||
docker pull convertx/convertx-cn:latest
|
||||
**1. 拉取最新版本：**
|
||||
|
||||
# 停止並移除舊容器
|
||||
```bash
|
||||
docker pull convertx/convertx-cn:latest
|
||||
```
|
||||
|
||||
**2. 停止並移除舊容器：**
|
||||
|
||||
```bash
|
||||
docker stop convertx-cn
|
||||
docker rm convertx-cn
|
||||
```
|
||||
|
||||
# 重新啟動（使用相同的參數）
|
||||
docker run -d \
|
||||
--name convertx-cn \
|
||||
# ... 其他參數
|
||||
**3. 重新啟動（使用相同的參數）：**
|
||||
|
||||
```bash
|
||||
docker run -d --name convertx-cn ...
|
||||
```
|
||||
|
||||
或使用 Docker Compose：
|
||||
|
|
@ -228,7 +241,12 @@ docker compose up -d
|
|||
|
||||
```bash
|
||||
docker logs convertx-cn
|
||||
docker logs -f convertx-cn # 持續追蹤
|
||||
```
|
||||
|
||||
持續追蹤日誌：
|
||||
|
||||
```bash
|
||||
docker logs -f convertx-cn
|
||||
```
|
||||
|
||||
### 進入容器
|
||||
|
|
@ -251,5 +269,5 @@ docker exec -it convertx-cn /bin/bash
|
|||
## 相關文件
|
||||
|
||||
- [Docker Compose 詳解](docker-compose.md)
|
||||
- [反向代理設定](reverse-proxy.md)
|
||||
- [環境變數設定](../configuration/environment-variables.md)
|
||||
- [反向代理設定](反向代理.md)
|
||||
- [環境變數設定](../配置設定/環境變數.md)
|
||||
|
|
@ -111,7 +111,7 @@ environment:
|
|||
- AUTO_DELETE_EVERY_N_HOURS=24
|
||||
```
|
||||
|
||||
完整環境變數說明請參考 [環境變數文件](../config/environment.md)。
|
||||
完整環境變數說明請參考 [環境變數文件](../配置設定/環境變數.md)。
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -59,6 +59,8 @@ cd C:\convertx-cn
|
|||
|
||||
在專案資料夾建立 `docker-compose.yml`：
|
||||
|
||||
> 💡 `JWT_SECRET` 請改成你自己的隨機字串（至少 32 字元）
|
||||
|
||||
```yaml
|
||||
services:
|
||||
convertx:
|
||||
|
|
@ -71,7 +73,7 @@ services:
|
|||
- ./data:/app/data
|
||||
environment:
|
||||
- TZ=Asia/Taipei
|
||||
- JWT_SECRET=請改成你自己的隨機字串至少32字元
|
||||
- JWT_SECRET=your-random-secret-at-least-32-chars
|
||||
```
|
||||
|
||||
### 必要參數說明
|
||||
|
|
@ -119,12 +121,12 @@ docker compose logs -f # Ctrl+C 退出
|
|||
| 重啟後被登出 | 設定固定的 `JWT_SECRET` |
|
||||
| 3000 埠被佔用 | 改用 `"8080:3000"` |
|
||||
|
||||
更多問題請參考 [FAQ](../faq.md)。
|
||||
更多問題請參考 [FAQ](../快速入門/常見問題.md)。
|
||||
|
||||
---
|
||||
|
||||
## 下一步
|
||||
|
||||
- [環境變數完整說明](../config/environment.md)
|
||||
- [反向代理與 HTTPS](../deployment.md)
|
||||
- [環境變數完整說明](../配置設定/環境變數.md)
|
||||
- [反向代理與 HTTPS](反向代理.md)
|
||||
- [版本更新方法](update.md)
|
||||
|
|
@ -24,12 +24,12 @@ docker compose up -d
|
|||
|
||||
### 更新到指定版本
|
||||
|
||||
修改 `docker-compose.yml`：
|
||||
修改 `docker-compose.yml`（指定要更新的版本號）：
|
||||
|
||||
```yaml
|
||||
services:
|
||||
convertx:
|
||||
image: convertx/convertx-cn:v0.1.9 # 指定版本
|
||||
image: convertx/convertx-cn:v0.1.9
|
||||
```
|
||||
|
||||
然後執行：
|
||||
|
|
@ -78,12 +78,12 @@ Copy-Item -Recurse .\data .\data.backup.$(Get-Date -Format "yyyyMMdd")
|
|||
|
||||
## 回滾版本
|
||||
|
||||
如果新版本有問題，可以回滾到舊版本：
|
||||
如果新版本有問題，可以回滾到舊版本（將版本號改為舊版本）：
|
||||
|
||||
```yaml
|
||||
services:
|
||||
convertx:
|
||||
image: convertx/convertx-cn:v0.1.8 # 舊版本
|
||||
image: convertx/convertx-cn:v0.1.8
|
||||
```
|
||||
|
||||
```bash
|
||||
|
|
@ -120,6 +120,8 @@ docker rmi convertx/convertx-cn:v0.1.7
|
|||
|
||||
可使用 [Watchtower](https://containrrr.dev/watchtower/) 自動更新容器：
|
||||
|
||||
> 💡 `--interval 86400` — 每 24 小時檢查一次更新
|
||||
|
||||
```yaml
|
||||
services:
|
||||
convertx:
|
||||
|
|
@ -130,7 +132,7 @@ services:
|
|||
image: containrrr/watchtower
|
||||
volumes:
|
||||
- /var/run/docker.sock:/var/run/docker.sock
|
||||
command: --interval 86400 # 每 24 小時檢查一次
|
||||
command: --interval 86400
|
||||
```
|
||||
|
||||
> ⚠️ 自動更新適合測試環境。生產環境建議手動更新，確認新版本穩定後再升級。
|
||||
|
|
@ -8,10 +8,13 @@
|
|||
|
||||
透過反向代理存取時，請設定：
|
||||
|
||||
- `TRUST_PROXY=true` — 信任 X-Forwarded-\* headers
|
||||
- `HTTP_ALLOWED=false` — Proxy 已處理 HTTPS
|
||||
|
||||
```yaml
|
||||
environment:
|
||||
- TRUST_PROXY=true # 信任 X-Forwarded-* headers
|
||||
- HTTP_ALLOWED=false # Proxy 已處理 HTTPS
|
||||
- TRUST_PROXY=true
|
||||
- HTTP_ALLOWED=false
|
||||
```
|
||||
|
||||
---
|
||||
|
|
@ -10,9 +10,11 @@
|
|||
|
||||
控制是否允許非 HTTPS 連線。
|
||||
|
||||
- `HTTP_ALLOWED=true` — 允許 HTTP（不安全，僅測試用）
|
||||
- `HTTP_ALLOWED=false` — 僅允許 HTTPS（預設）
|
||||
|
||||
```yaml
|
||||
- HTTP_ALLOWED=true # 允許 HTTP（不安全，僅測試用）
|
||||
- HTTP_ALLOWED=false # 僅允許 HTTPS（預設）
|
||||
- HTTP_ALLOWED=false
|
||||
```
|
||||
|
||||
#### 運作原理
|
||||
|
|
@ -40,9 +42,11 @@
|
|||
|
||||
是否信任反向代理傳來的 headers。
|
||||
|
||||
- `TRUST_PROXY=true` — 信任 X-Forwarded-\* headers
|
||||
- `TRUST_PROXY=false` — 不信任（預設）
|
||||
|
||||
```yaml
|
||||
- TRUST_PROXY=true # 信任 X-Forwarded-* headers
|
||||
- TRUST_PROXY=false # 不信任（預設）
|
||||
- TRUST_PROXY=false
|
||||
```
|
||||
|
||||
#### 運作原理
|
||||
|
|
@ -69,9 +73,11 @@
|
|||
|
||||
### ACCOUNT_REGISTRATION
|
||||
|
||||
- `ACCOUNT_REGISTRATION=true` — 開放註冊
|
||||
- `ACCOUNT_REGISTRATION=false` — 關閉註冊
|
||||
|
||||
```yaml
|
||||
- ACCOUNT_REGISTRATION=true # 開放註冊
|
||||
- ACCOUNT_REGISTRATION=false # 關閉註冊
|
||||
- ACCOUNT_REGISTRATION=false
|
||||
```
|
||||
|
||||
#### 建議流程
|
||||
|
|
@ -95,22 +101,41 @@
|
|||
|
||||
#### 產生方式
|
||||
|
||||
```bash
|
||||
# Linux / macOS
|
||||
openssl rand -hex 32
|
||||
**Linux / macOS：**
|
||||
|
||||
# 輸出範例：a1b2c3d4e5f6789...（64 字元）
|
||||
```bash
|
||||
openssl rand -hex 32
|
||||
```
|
||||
|
||||
**Windows PowerShell：**
|
||||
|
||||
```powershell
|
||||
-join ((1..32) | ForEach-Object { '{0:x2}' -f (Get-Random -Max 256) })
|
||||
```
|
||||
|
||||
**線上工具：**
|
||||
|
||||
- https://generate-secret.vercel.app/32
|
||||
|
||||
**Node.js：**
|
||||
|
||||
```bash
|
||||
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
|
||||
```
|
||||
|
||||
> 💡 產生的密鑰應為 32-64 字元的隨機字串，例如：`a1b2c3d4e5f6789...`
|
||||
|
||||
---
|
||||
|
||||
## 公開服務安全
|
||||
|
||||
### ALLOW_UNAUTHENTICATED
|
||||
|
||||
- `ALLOW_UNAUTHENTICATED=true` — 允許未登入使用
|
||||
- `ALLOW_UNAUTHENTICATED=false` — 必須登入（預設）
|
||||
|
||||
```yaml
|
||||
- ALLOW_UNAUTHENTICATED=true # 允許未登入使用
|
||||
- ALLOW_UNAUTHENTICATED=false # 必須登入（預設）
|
||||
- ALLOW_UNAUTHENTICATED=false
|
||||
```
|
||||
|
||||
#### 風險
|
||||
|
|
@ -125,12 +150,16 @@ openssl rand -hex 32
|
|||
|
||||
若需要公開服務，建議：
|
||||
|
||||
- `AUTO_DELETE_EVERY_N_HOURS=1` — 頻繁清理
|
||||
- `HIDE_HISTORY=true` — 隱藏歷史
|
||||
- `MAX_CONVERT_PROCESS=2` — 限制同時轉換數
|
||||
|
||||
```yaml
|
||||
environment:
|
||||
- ALLOW_UNAUTHENTICATED=true
|
||||
- AUTO_DELETE_EVERY_N_HOURS=1 # 頻繁清理
|
||||
- HIDE_HISTORY=true # 隱藏歷史
|
||||
- MAX_CONVERT_PROCESS=2 # 限制同時轉換數
|
||||
- AUTO_DELETE_EVERY_N_HOURS=1
|
||||
- HIDE_HISTORY=true
|
||||
- MAX_CONVERT_PROCESS=2
|
||||
```
|
||||
|
||||
---
|
||||
|
|
@ -139,31 +168,36 @@ environment:
|
|||
|
||||
### 防火牆
|
||||
|
||||
只開放必要的埠：
|
||||
只開放必要的埠。
|
||||
|
||||
**UFW (Ubuntu) 開放單一埠：**
|
||||
|
||||
```bash
|
||||
# UFW (Ubuntu)
|
||||
sudo ufw allow 3000/tcp
|
||||
```
|
||||
|
||||
# 或只允許特定 IP
|
||||
**只允許特定 IP 範圍：**
|
||||
|
||||
```bash
|
||||
sudo ufw allow from 192.168.1.0/24 to any port 3000
|
||||
```
|
||||
|
||||
### 只允許本機存取
|
||||
|
||||
> 💡 `127.0.0.1:3000:3000` 只有本機可存取
|
||||
|
||||
```yaml
|
||||
ports:
|
||||
- "127.0.0.1:3000:3000" # 只有本機可存取
|
||||
- "127.0.0.1:3000:3000"
|
||||
```
|
||||
|
||||
搭配反向代理提供對外服務。
|
||||
|
||||
### 限制上傳大小
|
||||
|
||||
在反向代理層限制：
|
||||
在反向代理層限制（Nginx 範例）：
|
||||
|
||||
```nginx
|
||||
# Nginx
|
||||
client_max_body_size 100M;
|
||||
```
|
||||
|
||||
|
|
@ -173,21 +207,25 @@ client_max_body_size 100M;
|
|||
|
||||
### 定期清理
|
||||
|
||||
> 💡 每 24 小時自動清理過期檔案
|
||||
|
||||
```yaml
|
||||
- AUTO_DELETE_EVERY_N_HOURS=24 # 每 24 小時清理
|
||||
- AUTO_DELETE_EVERY_N_HOURS=24
|
||||
```
|
||||
|
||||
### 備份
|
||||
|
||||
使用 crontab 設定定期備份（每天凌晨 2 點）：
|
||||
|
||||
```bash
|
||||
# 定期備份資料
|
||||
0 2 * * * tar -czvf /backup/convertx-$(date +\%Y\%m\%d).tar.gz /path/to/data
|
||||
```
|
||||
|
||||
### 權限設定
|
||||
|
||||
限制資料夾權限，僅允許擁有者存取：
|
||||
|
||||
```bash
|
||||
# 限制資料夾權限
|
||||
chmod 700 ./data
|
||||
```
|
||||
|
||||
|
|
@ -214,6 +252,6 @@ chmod 700 ./data
|
|||
|
||||
## 相關文件
|
||||
|
||||
- [環境變數設定](environment-variables.md)
|
||||
- [反向代理設定](../deployment/reverse-proxy.md)
|
||||
- [Docker 部署](../deployment/docker.md)
|
||||
- [環境變數設定](環境變數.md)
|
||||
- [反向代理設定](../部署指南/反向代理.md)
|
||||
- [Docker 部署](../部署指南/Docker.md)
|
||||
|
|
@ -16,16 +16,13 @@
|
|||
| 停用 | `0` |
|
||||
| 單位 | 小時 |
|
||||
|
||||
- `AUTO_DELETE_EVERY_N_HOURS=24` — 每 24 小時清理一次
|
||||
- `AUTO_DELETE_EVERY_N_HOURS=1` — 每 1 小時清理一次（公開服務建議）
|
||||
- `AUTO_DELETE_EVERY_N_HOURS=0` — 停用自動清理
|
||||
|
||||
```yaml
|
||||
environment:
|
||||
# 每 24 小時清理一次
|
||||
- AUTO_DELETE_EVERY_N_HOURS=24
|
||||
|
||||
# 每 1 小時清理一次（公開服務建議）
|
||||
- AUTO_DELETE_EVERY_N_HOURS=1
|
||||
|
||||
# 停用自動清理
|
||||
- AUTO_DELETE_EVERY_N_HOURS=0
|
||||
```
|
||||
|
||||
### 清理範圍
|
||||
|
|
@ -49,13 +46,12 @@ environment:
|
|||
| ------ | ------------- |
|
||||
| 預設值 | `0`（無限制） |
|
||||
|
||||
- `MAX_CONVERT_PROCESS=2` — 最多同時 2 個轉換任務
|
||||
- `MAX_CONVERT_PROCESS=0` — 無限制
|
||||
|
||||
```yaml
|
||||
environment:
|
||||
# 最多同時 2 個轉換任務
|
||||
- MAX_CONVERT_PROCESS=2
|
||||
|
||||
# 無限制
|
||||
- MAX_CONVERT_PROCESS=0
|
||||
```
|
||||
|
||||
#### 使用建議
|
||||
|
|
@ -152,17 +148,22 @@ find ./data/output -mtime +7 -delete
|
|||
|
||||
### 個人使用
|
||||
|
||||
- `AUTO_DELETE_EVERY_N_HOURS=168` — 一週清理一次
|
||||
- `MAX_CONVERT_PROCESS=0` — 無限制
|
||||
|
||||
```yaml
|
||||
environment:
|
||||
- AUTO_DELETE_EVERY_N_HOURS=168 # 一週
|
||||
- MAX_CONVERT_PROCESS=0 # 無限制
|
||||
- AUTO_DELETE_EVERY_N_HOURS=168
|
||||
- MAX_CONVERT_PROCESS=0
|
||||
```
|
||||
|
||||
### 小型團隊
|
||||
|
||||
> 💡 `AUTO_DELETE_EVERY_N_HOURS=24` — 每天清理一次
|
||||
|
||||
```yaml
|
||||
environment:
|
||||
- AUTO_DELETE_EVERY_N_HOURS=24 # 一天
|
||||
- AUTO_DELETE_EVERY_N_HOURS=24
|
||||
- MAX_CONVERT_PROCESS=4
|
||||
|
||||
deploy:
|
||||
|
|
@ -173,9 +174,11 @@ deploy:
|
|||
|
||||
### 公開服務
|
||||
|
||||
> 💡 `AUTO_DELETE_EVERY_N_HOURS=1` — 每小時清理一次
|
||||
|
||||
```yaml
|
||||
environment:
|
||||
- AUTO_DELETE_EVERY_N_HOURS=1 # 一小時
|
||||
- AUTO_DELETE_EVERY_N_HOURS=1
|
||||
- MAX_CONVERT_PROCESS=2
|
||||
- ALLOW_UNAUTHENTICATED=true
|
||||
- HIDE_HISTORY=true
|
||||
|
|
@ -191,6 +194,6 @@ deploy:
|
|||
|
||||
## 相關文件
|
||||
|
||||
- [環境變數設定](environment-variables.md)
|
||||
- [安全性設定](security.md)
|
||||
- [Docker 部署](../deployment/docker.md)
|
||||
- [環境變數設定](環境變數.md)
|
||||
- [安全性設定](安全性.md)
|
||||
- [Docker 部署](../部署指南/Docker.md)
|
||||
|
|
@ -174,6 +174,6 @@ api-server/
|
|||
|
||||
## 相關文件
|
||||
|
||||
- [本地開發](local-development.md)
|
||||
- [貢獻指南](contribution.md)
|
||||
- [測試策略](../testing/test-strategy.md)
|
||||
- [本地開發](本地開發.md)
|
||||
- [貢獻指南](貢獻指南.md)
|
||||
- [測試策略](../測試/測試策略.md)
|
||||
|
|
@ -187,6 +187,6 @@ docs: update deployment guide
|
|||
|
||||
## 相關文件
|
||||
|
||||
- [專案結構](project-structure.md)
|
||||
- [本地開發](local-development.md)
|
||||
- [測試策略](../testing/test-strategy.md)
|
||||
- [專案結構](專案結構.md)
|
||||
- [本地開發](本地開發.md)
|
||||
- [測試策略](../測試/測試策略.md)
|
||||
Loading…
Add table
Add a link
Reference in a new issue