diff --git a/README.md b/README.md index 0dd199a..e83675e 100644 --- a/README.md +++ b/README.md @@ -11,93 +11,41 @@ ## 為什麼選擇 ConvertX-CN？ -ConvertX-CN 不只是轉檔工具，而是 **文件轉換與翻譯的一站式平台**： - -- **1000+ 格式全支援**：文件、圖片、影音、電子書一次搞定 -- **20+ 轉換引擎整合**：LibreOffice、FFmpeg、Pandoc 全到位 -- **中文友善設計**：內建中日韓字型與 OCR，告別亂碼 -- **65 種介面語言**：跨國團隊無障礙使用 -- **MinerU**：強化文件解析與穩定度(測試) -- **PDFMathTranslate**：數學、工程、AI 論文公式安全翻譯與完整保留(測試) +| 特色 | 說明 | +| ----------------- | ------------------------------------ | +| 📁 **1000+ 格式** | 文件、圖片、影音、電子書一次搞定 | +| 🔧 **20+ 引擎** | LibreOffice、FFmpeg、Pandoc 全到位 | +| 🈶 **中文優化** | 內建中日韓字型與 OCR，告別亂碼 | +| 🌐 **65 種語言** | 跨國團隊無障礙使用 | +| 📊 **PDF 翻譯** | 數學公式完整保留（PDFMathTranslate） | --- -## 線上示範 +## 📚 文件 -想先試用再部署？歡迎使用我們的示範站： +完整文件請參閱 **[文件中心](docs/README.md)** -🔗 **https://convertx-cn.bioailab.qzz.io** - -| 項目 | 內容 | -| -------- | ----------------- | -| 範例帳號 | admin@example.com | -| 範例密碼 | admin | - -> ⚠️ 示範站僅供測試，請勿上傳敏感檔案。資料可能定期清除。 +| 分類 | 連結 | +| ----------- | ------------------------------------------------------------------------------------------------------------------------------- | +| 🚀 快速入門 | [概覽](docs/getting-started/overview.md) · [快速開始](docs/getting-started/quick-start.md) · [FAQ](docs/getting-started/faq.md) | +| 🐳 部署指南 | [Docker](docs/deployment/docker.md) · [反向代理](docs/deployment/reverse-proxy.md) | +| ⚙️ 配置設定 | [環境變數](docs/configuration/environment-variables.md) · [安全性](docs/configuration/security.md) | +| 🔌 功能說明 | [轉換器](docs/features/converters.md) · [OCR](docs/features/ocr.md) · [翻譯](docs/features/translation.md) | +| 🔗 API | [API 總覽](docs/api/overview.md) · [端點說明](docs/api/endpoints.md) | +| 👩‍💻 開發 | [專案結構](docs/development/project-structure.md) · [貢獻指南](docs/development/contribution.md) | --- -## 快速啟動（Docker Run） +## 🚀 快速開始 -### 1. 建立資料夾 - -```bash -mkdir -p ~/convertx-cn/data && cd ~/convertx-cn -``` - -### 2. 啟動容器 - -JWT_SECRET=請改成你自己的隨機字串至少32字元 - -```bash -docker run -d \ - --name convertx-cn \ - --restart unless-stopped \ - -p 3000:3000 \ - -v ./data:/app/data \ - -e TZ=Asia/Taipei \ - -e JWT_SECRET=e78a2da4-135f-06a8-fa46-17ef7990f5d1 \ - convertx/convertx-cn:latest -``` - -### 3. 開啟瀏覽器 - -```bash - http://localhost:3000 -``` - -> 首次下載約 4-6 GB，請耐心等待。 - ---- - -## Docker Compose（推薦） - -### 1. 建立專案資料夾 - -### Linux / macOS +### Docker Compose（推薦） ```bash +# 1. 建立專案資料夾 mkdir -p ~/convertx-cn && cd ~/convertx-cn -``` -### Windows PowerShell - -```bash -mkdir C:\convertx-cn; cd C:\convertx-cn -``` - -### Windows CMD - -```bash -mkdir C:\convertx-cn -cd C:\convertx-cn -``` - -### 2. 建立 docker-compose.yml（在專案資料夾下） - -- 範例內容（請修改 JWT_SECRET=請改成你自己的隨機字串至少32字元）： - -```yaml +# 2. 建立 docker-compose.yml +cat > docker-compose.yml << 'EOF' services: convertx: image: convertx/convertx-cn:latest @@ -109,57 +57,60 @@ services: - ./data:/app/data environment: - TZ=Asia/Taipei - - JWT_SECRET=e78a2da4-135f-06a8-fa46-17ef7990f5d1 -``` + - JWT_SECRET=請更換為長且隨機的字串至少32字元 +EOF -### 3. 啟動： - -```bash +# 3. 啟動 docker compose up -d ``` -更多範例 → [docs/docker-compose/](docs/docker-compose/) +開啟瀏覽器：`http://localhost:3000` + +> 📖 詳細說明請參閱 [快速開始](docs/getting-started/quick-start.md) + +### Docker Run + +```bash +mkdir -p ~/convertx-cn/data && cd ~/convertx-cn + +docker run -d \ + --name convertx-cn \ + --restart unless-stopped \ + -p 3000:3000 \ + -v ./data:/app/data \ + -e TZ=Asia/Taipei \ + -e JWT_SECRET=請更換為長且隨機的字串 \ + convertx/convertx-cn:latest +``` --- -## 重要：資料夾說明 +## 🔗 線上示範 -`./data` 是你**主機上的實體資料夾**，用於存放上傳檔案、轉換結果與使用者資料。 +🔗 **https://convertx-cn.bioailab.qzz.io** -| 作業系統 | 建立指令 | -| ------------- | ----------------------------- | -| Linux / macOS | `mkdir -p ~/convertx-cn/data` | -| Windows (PS) | `mkdir C:\convertx-cn\data` | -| Windows (CMD) | `mkdir C:\convertx-cn\data` | +| 項目 | 內容 | +| ---- | ----------------- | +| 帳號 | admin@example.com | +| 密碼 | admin | -> 若不先建立，Docker 會建立匿名 volume，導致資料難以存取或備份。 +> ⚠️ 示範站僅供測試，請勿上傳敏感檔案 --- -## 必要參數 +## ⚡ 常見問題速查 -| 參數 | 說明 | -| ------------ | ---------------------------------- | -| `./data` | 主機資料夾，必須先建立 | -| `JWT_SECRET` | 登入驗證金鑰，不設會每次重啟被登出 | +| 問題 | 解決方法 | +| ------------------ | ---------------------------------------------- | +| 登入後被踢回登入頁 | 加上 `HTTP_ALLOWED=true` 或 `TRUST_PROXY=true` | +| 重啟後資料消失 | 確認 `./data:/app/data` 且資料夾存在 | +| 重啟後被登出 | 設定固定的 `JWT_SECRET` | -其他環境變數 → [docs/config/environment.md](docs/config/environment.md) +更多問題 → [FAQ](docs/getting-started/faq.md) --- -## 常見問題 - -| 問題 | 解法 | -| -------------------- | ---------------------------------------------- | -| 登入後又被踢回登入頁 | 加上 `HTTP_ALLOWED=true` 或 `TRUST_PROXY=true` | -| 重啟後資料消失 | 確認 `./data:/app/data` 且資料夾存在 | -| 重啟後被登出 | 設定固定的 `JWT_SECRET` | - -更多問題 → [docs/faq.md](docs/faq.md) - ---- - -## 支援格式 +## 📦 支援格式 | 轉換器 | 用途 | 格式數 | | ---------------- | -------- | ------ | @@ -169,113 +120,19 @@ docker compose up -d | Pandoc | 文件 | 100+ | | Calibre | 電子書 | 40+ | | Inkscape | 向量圖 | 20+ | -| MinerU | 文件→MD | 2 | | PDFMathTranslate | PDF 翻譯 | 15+ | -完整列表 → [docs/converters.md](docs/converters.md) +完整列表 → [轉換器文件](docs/features/converters.md) --- -## Dark Mode +## 🖼️ 預覽 -ConvertX-CN 支援亮色與暗色主題。 - -- 可手動切換主題（點擊導覽列的太陽/月亮圖示） -- 偏好設定自動儲存於瀏覽器 -- 預設跟隨系統色彩偏好 +![ConvertX-CN Preview](images/preview.png) --- -## MinerU - -ConvertX 內建文件轉換引擎。 - -- md-t（表格以 Markdown 呈現） -- md-i（表格以圖片呈現） - -輸出格式：.tar（不壓縮封裝） - ---- - -## PDFMathTranslate 引擎 - -PDFMathTranslate 是一個內容轉換引擎，用於翻譯 PDF 文件同時保留數學公式與排版。 - -### 功能特點 - -- 📊 保留數學公式、圖表、目錄與註解 -- 🌐 支援多種目標語言（中文、英文、日文、韓文等） -- 🤖 支援多種翻譯服務（Google、DeepL、OpenAI 等） - -### 輸出格式 - -所有輸出一律打包為 `.tar` 檔案，包含： - -- `original.pdf` — 原始 PDF 文件 -- `translated-.pdf` — 翻譯後的 PDF 文件 - -### 可用的目標格式 - -``` -PDFMathTranslate -├─ pdf-en （翻譯為英文） -├─ pdf-zh （翻譯為簡體中文） -├─ pdf-zh-TW （翻譯為繁體中文） -├─ pdf-ja （翻譯為日文） -├─ pdf-ko （翻譯為韓文） -├─ pdf-de （翻譯為德文） -├─ pdf-fr （翻譯為法文） -└─ ... -``` - -### 環境變數 - -| 變數 | 說明 | 預設值 | -| ------------------------------ | -------------- | ------------------------ | -| `PDFMATHTRANSLATE_SERVICE` | 翻譯服務提供商 | google | -| `PDFMATHTRANSLATE_MODELS_PATH` | 模型路徑 | /models/pdfmathtranslate | - -### 注意事項 - -- 所需模型已在 Docker build 階段預先下載 -- 不會在 runtime 隱式下載任何模型 -- 使用 Google 翻譯為預設服務（免費），可透過環境變數切換 - ---- - -## 檔案傳輸機制 - -Contents.CN 使用統一的檔案傳輸策略： - -| 檔案大小 | 傳輸方式 | 說明 | -| -------- | -------- | ------------------------ | -| ≤ 10MB | 直接傳輸 | 單一請求完成上傳/下載 | -| > 10MB | 分段傳輸 | 使用 5MB chunks 分段傳輸 | - -### 多檔輸出封裝 - -- ✅ 唯一允許格式：`.tar` -- ❌ 禁止使用：`.tar.gz`、`.tgz`、`.zip` - -### 設計原則 - -- 分段傳輸僅存在於傳輸層 -- 轉換引擎只接收完整檔案 -- 前後端使用共用傳輸模組 - ---- - -## 語言支援 - -支援 **65 種語言**，包含繁體中文、簡體中文、英文、日文、韓文等。 - -語言會根據瀏覽器設定自動偵測，也可透過右上角選單手動切換。 - -詳細說明 → [docs/i18n.md](docs/i18n.md) - ---- - -## 版本與更新 +## 🔄 更新 ```bash docker compose down @@ -283,65 +140,8 @@ docker compose pull docker compose up -d ``` -- 版本說明 → [docs/versions/](docs/versions/) -- 更新指南 → [docs/deployment/update.md](docs/deployment/update.md) -- Changelog → [CHANGELOG.md](CHANGELOG.md) - --- -## API Server（選用） - -如需以程式整合方式使用 ConvertX 的轉檔功能，可啟用 **API Server**。 - -> ⚠️ API Server 為**選用功能**，不影響現有 Web UI 的使用。若只使用網頁介面，無需任何額外設定。 - -### 功能特點 - -- 🔐 **JWT 認證** — 安全的 API 存取控制 -- 🌐 **REST + GraphQL** — 雙協議支援，滿足不同整合需求 -- 🔍 **智慧建議** — 轉換失敗時自動推薦替代引擎 -- 🛠️ **20+ 轉換引擎** — 與 Web UI 共用完整轉換器套件 - -### 快速啟用 - -```bash -# 同時啟動 Web UI 與 API Server -docker compose --profile api up -d -``` - -| 服務 | 端口 | 說明 | -| ---------- | ---- | -------------- | -| Web UI | 3000 | 網頁介面 | -| API Server | 3001 | REST & GraphQL | - -### API 文件 - -詳細的 API 規格與使用說明： - -- 📘 [API Server README](api-server/README.md) -- 📗 [API 規格文件](api-server/docs/API_SPEC.md) -- 📙 [架構說明](api-server/docs/ARCHITECTURE.md) - ---- - -## 進階文件 - -| 文件 | 說明 | -| -------------------------------------- | ------------------------- | -| [環境變數](docs/config/environment.md) | 所有可用參數 | -| [安全性設定](docs/config/security.md) | HTTP_ALLOWED、TRUST_PROXY | -| [反向代理](docs/deployment.md) | Nginx / Traefik / Caddy | -| [Docker 進階](docs/docker.md) | 自訂 Build | -| [FAQ](docs/faq.md) | 疑難排解 | - ---- - -## 預覽 - -![ConvertX-CN Preview](images/preview.png) - ---- - -## License +## 📄 License [MIT](LICENSE) | 基於 [C4illin/ConvertX](https://github.com/C4illin/ConvertX) diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..1219b0b --- /dev/null +++ b/docs/README.md @@ -0,0 +1,172 @@ +# ConvertX-CN 文件中心 + +歡迎來到 ConvertX-CN 文件！選擇您的角色快速找到所需資訊。 + +--- + +## 🚀 快速入門 + +剛開始使用？從這裡開始： + +1. **[概覽](getting-started/overview.md)** — 了解 ConvertX-CN 是什麼 +2. **[快速開始](getting-started/quick-start.md)** — 5 分鐘內完成部署 +3. **[常見問題](getting-started/faq.md)** — 解決常見問題 + +--- + +## 👤 使用者指南 + +適合一般使用者： + +| 文件 | 說明 | +| ------------------------------------------ | -------------------- | +| [快速開始](getting-started/quick-start.md) | 最快部署方式 | +| [支援的轉換器](features/converters.md) | 所有可用的轉換格式 | +| [OCR 功能](features/ocr.md) | 光學字元辨識 | +| [翻譯功能](features/translation.md) | PDF 翻譯（保留公式） | +| [多語言介面](features/i18n.md) | 切換介面語言 | +| [常見問題](getting-started/faq.md) | FAQ | + +--- + +## 🛠️ 系統管理員指南 + +適合部署與維護人員： + +### 部署 + +| 文件 | 說明 | +| --------------------------------------- | --------------------------- | +| [Docker 部署](deployment/docker.md) | Docker Run & Docker Compose | +| [反向代理](deployment/reverse-proxy.md) | Nginx / Traefik / Caddy | +| [範例配置](samples/README.md) | 可直接使用的配置檔 | + +### 配置 + +| 文件 | 說明 | +| -------------------------------------------------- | ------------------ | +| [環境變數](configuration/environment-variables.md) | 所有可用設定 | +| [安全性設定](configuration/security.md) | HTTPS、認證、防護 | +| [清理與限制](configuration/limits-and-cleanup.md) | 自動清理、資源限制 | + +--- + +## 👩‍💻 開發者指南 + +適合貢獻者與擴充開發： + +### 開發 + +| 文件 | 說明 | +| -------------------------------------------- | -------------- | +| [專案結構](development/project-structure.md) | 程式碼結構說明 | +| [本地開發](development/local-development.md) | 開發環境設定 | +| [貢獻指南](development/contribution.md) | 如何參與專案 | + +### API + +| 文件 | 說明 | +| ---------------------------- | ------------------ | +| [API 總覽](api/overview.md) | REST & GraphQL API | +| [API 端點](api/endpoints.md) | 詳細端點說明 | + +### 測試 + +| 文件 | 說明 | +| ------------------------------------ | -------------- | +| [測試策略](testing/test-strategy.md) | 測試類型與方法 | +| [CI/CD](testing/ci-cd.md) | 持續整合設定 | +| [E2E 測試](testing/e2e-tests.md) | 端對端測試 | + +--- + +## 📁 文件結構 + +``` +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 設定 +``` + +--- + +## 🔗 快速連結 + +- 📦 [GitHub Repo](https://github.com/pi-docket/ConvertX-CN) +- 🐛 [Issues](https://github.com/pi-docket/ConvertX-CN/issues) +- 💬 [Discussions](https://github.com/pi-docket/ConvertX-CN/discussions) +- 📝 [Changelog](../CHANGELOG.md) +- 📄 [License](../LICENSE) + +--- + +## 📖 閱讀路徑建議 + +### 我是新手 + +1. [概覽](getting-started/overview.md) +2. [快速開始](getting-started/quick-start.md) +3. [支援的轉換器](features/converters.md) + +### 我要部署到生產環境 + +1. [Docker 部署](deployment/docker.md) +2. [反向代理](deployment/reverse-proxy.md) +3. [安全性設定](configuration/security.md) +4. [環境變數](configuration/environment-variables.md) + +### 我想參與開發 + +1. [專案結構](development/project-structure.md) +2. [本地開發](development/local-development.md) +3. [貢獻指南](development/contribution.md) +4. [測試策略](testing/test-strategy.md) + +--- + +## 🌐 多語言文件 + +此文件以繁體中文為主，我們也提供其他語言版本： + +| 語言 | 說明 | 狀態 | +| -------------------------------- | --------------------- | --------- | +| [English](i18n/en/README.md) | English documentation | 🔄 進行中 | +| [简体中文](i18n/zh-CN/README.md) | 简体中文文档 | 📋 規劃中 | +| [日本語](i18n/ja/README.md) | 日本語ドキュメント | 📋 規劃中 | + +> 📝 **想幫忙翻譯？** 請參閱 [翻譯指南](i18n/README.md) + +--- + +> 💡 **找不到您需要的資訊？** 歡迎到 [GitHub Discussions](https://github.com/pi-docket/ConvertX-CN/discussions) 發問！ diff --git a/docs/advanced-usage.md b/docs/advanced-usage.md index 813855e..0470f31 100644 --- a/docs/advanced-usage.md +++ b/docs/advanced-usage.md @@ -1,5 +1,16 @@ # 進階用法 +> ⚠️ **此文件已遷移** +> +> 本文件內容已整合至新的文件結構，請參閱： +> +> - 🐳 [Docker 部署（含硬體加速）](deployment/docker.md) +> - 🔧 [反向代理設定](deployment/reverse-proxy.md) +> +> 此文件將在未來版本中移除。 + +--- + ## 硬體加速 ### NVIDIA GPU (CUDA/NVENC) diff --git a/docs/api/endpoints.md b/docs/api/endpoints.md new file mode 100644 index 0000000..e386f29 --- /dev/null +++ b/docs/api/endpoints.md @@ -0,0 +1,261 @@ +# API 端點 + +本文件列出 ConvertX API Server 的所有可用端點。 + +--- + +## REST API + +Base URL: `http://localhost:3001/api/v1` + +--- + +### 健康檢查 + +#### `GET /health` + +檢查 API Server 運作狀態。**不需要認證**。 + +**回應** + +```json +{ + "status": "healthy", + "version": "0.1.0", + "timestamp": "2026-01-23T10:30:00Z" +} +``` + +--- + +### 引擎管理 + +#### `GET /api/v1/engines` + +列出所有可用的轉換引擎。 + +**Headers** + +``` +Authorization: Bearer +``` + +**回應** + +```json +{ + "engines": [ + { + "id": "ffmpeg", + "name": "FFmpeg", + "description": "Audio and video conversion", + "supported_input_formats": ["mp4", "webm", "avi", ...], + "supported_output_formats": ["mp4", "webm", "mp3", ...] + }, + ... + ] +} +``` + +#### `GET /api/v1/engines/{engine_id}` + +取得特定引擎的詳細資訊。 + +**參數** + +| 參數 | 類型 | 說明 | +| --------- | ------ | ------- | +| engine_id | string | 引擎 ID | + +**回應** + +```json +{ + "id": "libreoffice", + "name": "LibreOffice", + "description": "Office document conversion", + "supported_input_formats": ["doc", "docx", "xls", ...], + "supported_output_formats": ["pdf", "odt", "txt", ...] +} +``` + +--- + +### 檔案轉換 + +#### `POST /api/v1/convert` + +上傳檔案並執行轉換。 + +**Headers** + +``` +Authorization: Bearer +Content-Type: multipart/form-data +``` + +**參數** + +| 參數 | 類型 | 必填 | 說明 | +| ------------- | ------ | ---- | ------------ | +| file | file | ✓ | 要轉換的檔案 | +| engine | string | ✓ | 轉換引擎 ID | +| output_format | string | ✓ | 目標格式 | + +**範例** + +```bash +curl -X POST \ + -H "Authorization: Bearer " \ + -F "file=@document.docx" \ + -F "engine=libreoffice" \ + -F "output_format=pdf" \ + http://localhost:3001/api/v1/convert +``` + +**成功回應** + +```json +{ + "job_id": "abc123", + "status": "completed", + "output_file": "http://localhost:3001/api/v1/files/abc123/output.pdf" +} +``` + +**失敗回應（含建議）** + +```json +{ + "error": "UNSUPPORTED_CONVERSION", + "message": "Engine 'ffmpeg' does not support .docx input", + "suggestions": [ + { + "engine": "libreoffice", + "supported_output_formats": ["pdf", "odt", "txt"] + }, + { + "engine": "pandoc", + "supported_output_formats": ["pdf", "html", "markdown"] + } + ] +} +``` + +--- + +### 檔案下載 + +#### `GET /api/v1/files/{job_id}/{filename}` + +下載轉換後的檔案。 + +**參數** + +| 參數 | 類型 | 說明 | +| -------- | ------ | -------- | +| job_id | string | 任務 ID | +| filename | string | 檔案名稱 | + +--- + +## GraphQL API + +Endpoint: `http://localhost:3001/graphql` + +--- + +### Schema 概覽 + +```graphql +type Query { + health: HealthStatus! + engines: [Engine!]! + engine(id: ID!): Engine + job(id: ID!): ConversionJob +} + +type Mutation { + convert(input: ConvertInput!): ConversionJob! +} + +type Engine { + id: ID! + name: String! + description: String! + supportedInputFormats: [String!]! + supportedOutputFormats: [String!]! +} + +type ConversionJob { + id: ID! + status: JobStatus! + inputFile: String! + outputFile: String + engine: String! + createdAt: DateTime! + completedAt: DateTime +} + +enum JobStatus { + PENDING + PROCESSING + COMPLETED + FAILED +} + +input ConvertInput { + fileId: ID! + engine: String! + outputFormat: String! +} +``` + +### 查詢範例 + +#### 列出引擎 + +```graphql +query { + engines { + id + name + supportedInputFormats + supportedOutputFormats + } +} +``` + +#### 查詢任務狀態 + +```graphql +query { + job(id: "abc123") { + id + status + outputFile + completedAt + } +} +``` + +--- + +## 錯誤代碼 + +| 錯誤碼 | HTTP 狀態 | 說明 | +| ------------------------ | --------- | ------------------ | +| `MISSING_AUTH_HEADER` | 401 | 缺少 Authorization | +| `INVALID_TOKEN` | 401 | Token 無效 | +| `TOKEN_EXPIRED` | 401 | Token 已過期 | +| `ENGINE_NOT_FOUND` | 404 | 引擎不存在 | +| `UNSUPPORTED_CONVERSION` | 400 | 不支援的轉換 | +| `FILE_TOO_LARGE` | 413 | 檔案過大 | +| `CONVERSION_FAILED` | 500 | 轉換失敗 | + +--- + +## 相關文件 + +- [API 總覽](overview.md) +- [API 規格文件](../../api-server/docs/API_SPEC.md) diff --git a/docs/api/overview.md b/docs/api/overview.md new file mode 100644 index 0000000..ff16594 --- /dev/null +++ b/docs/api/overview.md @@ -0,0 +1,128 @@ +# API 總覽 + +ConvertX-CN 提供選用的 API Server，支援 REST 和 GraphQL 兩種 API 介面。 + +--- + +## 功能特色 + +- 🔐 **JWT 認證**：安全的 API 存取控制 +- 🌐 **REST + GraphQL**：雙協議支援 +- 🔍 **智慧建議**：轉換失敗時推薦替代引擎 +- 🛠️ **20+ 轉換引擎**：與 Web UI 共用完整轉換器 + +--- + +## 快速啟用 + +API Server 是**選用功能**，不影響 Web UI 使用。 + +### 啟用方式 + +```bash +docker compose --profile api up -d +``` + +### 服務端口 + +| 服務 | 端口 | 說明 | +| ---------- | ---- | -------------- | +| Web UI | 3000 | 網頁介面 | +| API Server | 3001 | REST & GraphQL | + +--- + +## API 端點 + +### REST API + +- **Base URL**: `http://localhost:3001/api/v1` +- **Content-Type**: `application/json` 或 `multipart/form-data` + +### GraphQL API + +- **Endpoint**: `http://localhost:3001/graphql` +- **Playground**: `http://localhost:3001/graphql`（開發模式） + +--- + +## 認證 + +所有 API 請求（除健康檢查外）都需要 JWT Bearer Token： + +```http +Authorization: Bearer +``` + +### Token 結構 + +```json +{ + "sub": "user-id", + "exp": 1234567890, + "iat": 1234567890, + "email": "user@example.com", + "roles": ["user"] +} +``` + +> API Server 只負責驗證 JWT，不負責產生 JWT。Token 應由獨立的認證服務產生。 + +--- + +## 環境變數 + +| 變數 | 說明 | 預設值 | +| --------------- | ------------ | ---------------- | +| `API_HOST` | 監聽地址 | `0.0.0.0` | +| `API_PORT` | 監聽埠 | `3001` | +| `JWT_SECRET` | JWT 驗證密鑰 | （需自行設定） | +| `UPLOAD_DIR` | 上傳目錄 | `./data/uploads` | +| `OUTPUT_DIR` | 輸出目錄 | `./data/output` | +| `MAX_FILE_SIZE` | 最大檔案大小 | `104857600` | + +--- + +## 快速範例 + +### 健康檢查 + +```bash +curl http://localhost:3001/health +``` + +回應： + +```json +{ + "status": "healthy", + "version": "0.1.0", + "timestamp": "2026-01-23T10:30:00Z" +} +``` + +### 列出引擎 + +```bash +curl -H "Authorization: Bearer " \ + http://localhost:3001/api/v1/engines +``` + +### 轉換檔案 + +```bash +curl -X POST \ + -H "Authorization: Bearer " \ + -F "file=@document.docx" \ + -F "engine=libreoffice" \ + -F "output_format=pdf" \ + http://localhost:3001/api/v1/convert +``` + +--- + +## 相關文件 + +- [API 端點詳細說明](endpoints.md) +- [API 規格文件](../../api-server/docs/API_SPEC.md) +- [架構說明](../../api-server/docs/ARCHITECTURE.md) diff --git a/docs/config/environment.md b/docs/config/environment.md index b1afe4d..2968241 100644 --- a/docs/config/environment.md +++ b/docs/config/environment.md @@ -1,5 +1,17 @@ # 環境變數完整說明 +> ⚠️ **此文件已遷移** +> +> 本文件內容已整合至新的文件結構，請參閱： +> +> - ⚙️ [環境變數設定](../configuration/environment-variables.md) +> - 🔒 [安全性設定](../configuration/security.md) +> - 🧹 [清理與限制](../configuration/limits-and-cleanup.md) +> +> 此文件將在未來版本中移除。 + +--- + 本文件列出 ConvertX-CN 所有可用的環境變數設定。 --- diff --git a/docs/config/security.md b/docs/config/security.md index e2bea6e..5a2a580 100644 --- a/docs/config/security.md +++ b/docs/config/security.md @@ -1,5 +1,15 @@ # 安全性設定 +> ⚠️ **此文件已遷移** +> +> 本文件內容已整合至新的文件結構，請參閱： +> +> - 🔒 [安全性設定](../configuration/security.md) +> +> 此文件將在未來版本中移除。 + +--- + 本文件說明 ConvertX-CN 的安全性相關設定與最佳實踐。 --- diff --git a/docs/configuration/environment-variables.md b/docs/configuration/environment-variables.md new file mode 100644 index 0000000..8af9df8 --- /dev/null +++ b/docs/configuration/environment-variables.md @@ -0,0 +1,271 @@ +# 環境變數設定 + +本文件列出 ConvertX-CN 所有可用的環境變數。 + +--- + +## 快速參考 + +| 優先級 | 變數 | 說明 | 預設值 | +| ------ | -------------- | ------------ | ------------------ | +| 必填 | `JWT_SECRET` | 登入驗證金鑰 | 隨機（每次重啟變） | +| 建議 | `TZ` | 時區 | `UTC` | +| 建議 | `HTTP_ALLOWED` | 允許 HTTP | `false` | +| 可選 | `TRUST_PROXY` | 信任反向代理 | `false` | + +--- + +## 必填設定 + +### JWT_SECRET + +用於簽署登入驗證的密鑰。**強烈建議設定**。 + +| 項目 | 值 | +| ------ | ---------------------- | +| 預設值 | 每次重啟隨機產生 | +| 建議值 | 至少 32 字元的隨機字串 | + +不設定的話，每次容器重啟後所有使用者都需要重新登入。 + +**產生方式：** + +```bash +# Linux / macOS +openssl rand -hex 32 + +# Windows PowerShell +-join ((1..32) | ForEach-Object { '{0:x2}' -f (Get-Random -Max 256) }) +``` + +--- + +## 網路與安全 + +### HTTP_ALLOWED + +允許非 HTTPS 連線。 + +| 項目 | 值 | +| ------ | ------- | +| 預設值 | `false` | + +| 情境 | 設定值 | +| --------------------- | ------- | +| 本地測試 (localhost) | `true` | +| 有 HTTPS | `false` | +| 無 HTTPS 但需遠端存取 | `true` | + +> ⚠️ 設為 `false` 但用 HTTP 存取會導致「登入後又被導回登入頁」 + +### TRUST_PROXY + +信任反向代理的 headers。 + +| 項目 | 值 | +| ------ | ------- | +| 預設值 | `false` | + +| 情境 | 設定值 | +| ---------------------------- | ------- | +| 直接存取容器 | `false` | +| 透過 Nginx / Traefik / Caddy | `true` | +| 透過 Cloudflare Tunnel | `true` | + +### ACCOUNT_REGISTRATION + +是否允許註冊新帳號。 + +| 項目 | 值 | +| ------ | ------ | +| 預設值 | `true` | + +建議建立管理員帳號後改為 `false`。 + +### ALLOW_UNAUTHENTICATED + +是否允許未登入使用轉換功能。 + +| 項目 | 值 | +| ------ | ------- | +| 預設值 | `false` | + +> ⚠️ 設為 `true` 有安全風險：任何人都可使用伺服器資源 + +--- + +## 一般設定 + +### TZ + +時區設定，影響日期顯示。 + +| 項目 | 值 | +| ------ | ----- | +| 預設值 | `UTC` | + +常用值： + +| 地區 | 值 | +| ---- | ---------------- | +| 台灣 | `Asia/Taipei` | +| 中國 | `Asia/Shanghai` | +| 香港 | `Asia/Hong_Kong` | +| 日本 | `Asia/Tokyo` | + +### AUTO_DELETE_EVERY_N_HOURS + +自動刪除超過 N 小時的檔案。 + +| 項目 | 值 | +| ------ | ---- | +| 預設值 | `24` | +| 停用 | `0` | + +--- + +## 介面設定 + +### WEBROOT + +子路徑部署前綴。 + +| 項目 | 值 | +| ------ | --- | +| 預設值 | 空 | + +若透過 `https://example.com/convertx/` 存取： + +```yaml +- WEBROOT=/convertx +``` + +### HIDE_HISTORY + +隱藏歷史紀錄頁面。 + +| 項目 | 值 | +| ------ | ------- | +| 預設值 | `false` | + +### LANGUAGE + +介面語言。 + +| 項目 | 值 | +| ------ | ------ | +| 預設值 | `auto` | + +設為特定語言代碼（如 `zh-TW`）可強制使用該語言。 + +--- + +## 轉換設定 + +### MAX_CONVERT_PROCESS + +最大同時轉換數。 + +| 項目 | 值 | +| ------ | ------------- | +| 預設值 | `0`（無限制） | + +限制同時進行的轉換任務數量，避免伺服器過載。 + +### FFMPEG_ARGS + +FFmpeg 輸入參數，用於硬體加速。 + +```yaml +# NVIDIA GPU +- FFMPEG_ARGS=-hwaccel cuda + +# Intel QSV +- FFMPEG_ARGS=-hwaccel qsv + +# AMD VAAPI +- FFMPEG_ARGS=-hwaccel vaapi +``` + +### FFMPEG_OUTPUT_ARGS + +FFmpeg 輸出參數。 + +```yaml +# 使用 NVIDIA 編碼器 +- FFMPEG_OUTPUT_ARGS=-c:v h264_nvenc -preset fast +``` + +--- + +## PDFMathTranslate 設定 + +### PDFMATHTRANSLATE_SERVICE + +翻譯服務提供商。 + +| 項目 | 值 | +| ------ | -------- | +| 預設值 | `google` | + +可選值：`google`, `deepl`, `openai` 等 + +### PDFMATHTRANSLATE_MODELS_PATH + +模型路徑。 + +| 項目 | 值 | +| ------ | -------------------------- | +| 預設值 | `/models/pdfmathtranslate` | + +--- + +## 情境範例 + +### 開發環境 + +```yaml +environment: + - TZ=Asia/Taipei + - HTTP_ALLOWED=true + - ACCOUNT_REGISTRATION=true +``` + +### 生產環境 + +```yaml +environment: + - JWT_SECRET=your-very-long-and-random-secret-key-change-me + - TZ=Asia/Taipei + - HTTP_ALLOWED=false + - TRUST_PROXY=true + - ACCOUNT_REGISTRATION=false + - AUTO_DELETE_EVERY_N_HOURS=24 +``` + +### 公開服務（允許匿名） + +```yaml +environment: + - ALLOW_UNAUTHENTICATED=true + - HIDE_HISTORY=true + - AUTO_DELETE_EVERY_N_HOURS=1 + - MAX_CONVERT_PROCESS=2 +``` + +### 硬體加速 + +```yaml +environment: + - JWT_SECRET=your-secret-key + - FFMPEG_ARGS=-hwaccel cuda + - FFMPEG_OUTPUT_ARGS=-c:v h264_nvenc -preset fast +``` + +--- + +## 相關文件 + +- [安全性設定](security.md) +- [Docker 部署](../deployment/docker.md) +- [反向代理設定](../deployment/reverse-proxy.md) diff --git a/docs/configuration/limits-and-cleanup.md b/docs/configuration/limits-and-cleanup.md new file mode 100644 index 0000000..fab0798 --- /dev/null +++ b/docs/configuration/limits-and-cleanup.md @@ -0,0 +1,196 @@ +# 清理與限制設定 + +本文件說明如何設定檔案自動清理與資源限制。 + +--- + +## 檔案自動清理 + +### AUTO_DELETE_EVERY_N_HOURS + +自動刪除超過指定時間的檔案。 + +| 項目 | 值 | +| ------ | ---- | +| 預設值 | `24` | +| 停用 | `0` | +| 單位 | 小時 | + +```yaml +environment: + # 每 24 小時清理一次 + - AUTO_DELETE_EVERY_N_HOURS=24 + + # 每 1 小時清理一次（公開服務建議） + - AUTO_DELETE_EVERY_N_HOURS=1 + + # 停用自動清理 + - AUTO_DELETE_EVERY_N_HOURS=0 +``` + +### 清理範圍 + +自動清理會刪除以下檔案： + +- `uploads/` 目錄中的上傳檔案 +- `output/` 目錄中的轉換結果 + +> 不會刪除資料庫 (`convertx.db`) 或使用者帳號 + +--- + +## 轉換限制 + +### MAX_CONVERT_PROCESS + +限制同時進行的轉換任務數量。 + +| 項目 | 值 | +| ------ | ------------- | +| 預設值 | `0`（無限制） | + +```yaml +environment: + # 最多同時 2 個轉換任務 + - MAX_CONVERT_PROCESS=2 + + # 無限制 + - MAX_CONVERT_PROCESS=0 +``` + +#### 使用建議 + +| 情境 | 建議值 | +| ------------ | ------ | +| 個人使用 | 無限制 | +| 小型團隊 | 4-8 | +| 公開服務 | 2-4 | +| 資源受限環境 | 1-2 | + +--- + +## 記憶體限制 + +### Docker 記憶體限制 + +```yaml +services: + convertx: + deploy: + resources: + limits: + memory: 4G + reservations: + memory: 2G +``` + +### 建議配置 + +| 記憶體 | 適用情境 | +| ------ | ------------- | +| 2 GB | 基本轉換 | +| 4 GB | 一般使用 | +| 8 GB | 大檔案轉換 | +| 16 GB | 影片轉換、OCR | + +--- + +## CPU 限制 + +### Docker CPU 限制 + +```yaml +services: + convertx: + deploy: + resources: + limits: + cpus: "2" +``` + +### 建議配置 + +| CPU 核心 | 適用情境 | +| -------- | ------------ | +| 1 | 最小需求 | +| 2 | 一般使用 | +| 4+ | 多人同時使用 | + +--- + +## 磁碟空間管理 + +### 監控磁碟使用 + +```bash +# 檢查 data 目錄大小 +du -sh ./data + +# 檢查各子目錄 +du -sh ./data/* +``` + +### 手動清理 + +```bash +# 清理舊檔案（超過 7 天） +find ./data/uploads -mtime +7 -delete +find ./data/output -mtime +7 -delete +``` + +### 設定清理排程 + +```bash +# 每天凌晨 3 點清理超過 7 天的檔案 +0 3 * * * find /path/to/data/uploads -mtime +7 -delete +0 3 * * * find /path/to/data/output -mtime +7 -delete +``` + +--- + +## 情境範例 + +### 個人使用 + +```yaml +environment: + - AUTO_DELETE_EVERY_N_HOURS=168 # 一週 + - MAX_CONVERT_PROCESS=0 # 無限制 +``` + +### 小型團隊 + +```yaml +environment: + - AUTO_DELETE_EVERY_N_HOURS=24 # 一天 + - MAX_CONVERT_PROCESS=4 + +deploy: + resources: + limits: + memory: 4G +``` + +### 公開服務 + +```yaml +environment: + - AUTO_DELETE_EVERY_N_HOURS=1 # 一小時 + - MAX_CONVERT_PROCESS=2 + - ALLOW_UNAUTHENTICATED=true + - HIDE_HISTORY=true + +deploy: + resources: + limits: + memory: 4G + cpus: "2" +``` + +--- + +## 相關文件 + +- [環境變數設定](environment-variables.md) +- [安全性設定](security.md) +- [Docker 部署](../deployment/docker.md) diff --git a/docs/configuration/security.md b/docs/configuration/security.md new file mode 100644 index 0000000..45ca1ec --- /dev/null +++ b/docs/configuration/security.md @@ -0,0 +1,219 @@ +# 安全性設定 + +本文件說明 ConvertX-CN 的安全性設定與最佳實踐。 + +--- + +## Cookie 與登入安全 + +### HTTP_ALLOWED + +控制是否允許非 HTTPS 連線。 + +```yaml +- HTTP_ALLOWED=true # 允許 HTTP（不安全，僅測試用） +- HTTP_ALLOWED=false # 僅允許 HTTPS（預設） +``` + +#### 運作原理 + +當 `HTTP_ALLOWED=false` 時，Cookie 會設定 `Secure` 屬性，只在 HTTPS 連線下傳送。 + +若實際用 HTTP 存取： + +- 瀏覽器不會傳送 Cookie +- 每次請求都像未登入 +- 造成「登入後又被踢回登入頁」 + +#### 設定建議 + +| 情境 | 設定值 | +| ------------------ | ------- | +| `localhost` 測試 | `true` | +| 區網 IP 測試 | `true` | +| 有 HTTPS 憑證 | `false` | +| 透過反向代理 HTTPS | `false` | + +--- + +### TRUST_PROXY + +是否信任反向代理傳來的 headers。 + +```yaml +- TRUST_PROXY=true # 信任 X-Forwarded-* headers +- TRUST_PROXY=false # 不信任（預設） +``` + +#### 運作原理 + +當請求經過反向代理時： + +- 原始連線：使用者 → Nginx (HTTPS) → ConvertX (HTTP) +- 沒有 TRUST_PROXY：ConvertX 看到的是 HTTP 連線 +- 有 TRUST_PROXY：ConvertX 讀取 `X-Forwarded-Proto: https`，知道原始是 HTTPS + +#### 設定建議 + +| 情境 | 設定值 | +| ---------------------------- | ------- | +| 直接存取容器（無 Proxy） | `false` | +| 透過 Nginx / Traefik / Caddy | `true` | +| 透過 Cloudflare Tunnel | `true` | + +> ⚠️ **安全注意**：只在確實有反向代理時才設為 `true`。若直接暴露容器且設為 `true`，攻擊者可偽造 headers。 + +--- + +## 帳號安全 + +### ACCOUNT_REGISTRATION + +```yaml +- ACCOUNT_REGISTRATION=true # 開放註冊 +- ACCOUNT_REGISTRATION=false # 關閉註冊 +``` + +#### 建議流程 + +1. 首次部署設為 `true`（或不設定） +2. 註冊管理員帳號 +3. 改為 `false` +4. 重啟容器 + +### JWT_SECRET + +```yaml +- JWT_SECRET=your-secret-key-at-least-32-chars +``` + +#### 重要性 + +- 用於簽署登入 Token +- 不設定：每次重啟產生新密鑰，所有人被登出 +- 設定固定值：登入狀態跨重啟保留 + +#### 產生方式 + +```bash +# Linux / macOS +openssl rand -hex 32 + +# 輸出範例：a1b2c3d4e5f6789...（64 字元） +``` + +--- + +## 公開服務安全 + +### ALLOW_UNAUTHENTICATED + +```yaml +- ALLOW_UNAUTHENTICATED=true # 允許未登入使用 +- ALLOW_UNAUTHENTICATED=false # 必須登入（預設） +``` + +#### 風險 + +設為 `true` 時： + +- 任何人可使用轉換功能 +- 消耗伺服器 CPU / 記憶體 / 磁碟 +- 可能被惡意利用 + +#### 緩解措施 + +若需要公開服務，建議： + +```yaml +environment: + - ALLOW_UNAUTHENTICATED=true + - AUTO_DELETE_EVERY_N_HOURS=1 # 頻繁清理 + - HIDE_HISTORY=true # 隱藏歷史 + - MAX_CONVERT_PROCESS=2 # 限制同時轉換數 +``` + +--- + +## 網路安全 + +### 防火牆 + +只開放必要的埠： + +```bash +# UFW (Ubuntu) +sudo ufw allow 3000/tcp + +# 或只允許特定 IP +sudo ufw allow from 192.168.1.0/24 to any port 3000 +``` + +### 只允許本機存取 + +```yaml +ports: + - "127.0.0.1:3000:3000" # 只有本機可存取 +``` + +搭配反向代理提供對外服務。 + +### 限制上傳大小 + +在反向代理層限制： + +```nginx +# Nginx +client_max_body_size 100M; +``` + +--- + +## 資料安全 + +### 定期清理 + +```yaml +- AUTO_DELETE_EVERY_N_HOURS=24 # 每 24 小時清理 +``` + +### 備份 + +```bash +# 定期備份資料 +0 2 * * * tar -czvf /backup/convertx-$(date +\%Y\%m\%d).tar.gz /path/to/data +``` + +### 權限設定 + +```bash +# 限制資料夾權限 +chmod 700 ./data +``` + +--- + +## 安全檢查清單 + +### 部署前 + +- [ ] 設定固定的 `JWT_SECRET` +- [ ] 關閉 `ACCOUNT_REGISTRATION`（如果不需要公開註冊） +- [ ] 設定 `TRUST_PROXY=true`（如果使用反向代理） +- [ ] 設定 `HTTP_ALLOWED=false`（如果有 HTTPS） + +### 部署後 + +- [ ] 確認只有必要的埠對外開放 +- [ ] 確認反向代理有正確設定 +- [ ] 確認 HTTPS 憑證有效 +- [ ] 設定定期備份 +- [ ] 設定定期清理 + +--- + +## 相關文件 + +- [環境變數設定](environment-variables.md) +- [反向代理設定](../deployment/reverse-proxy.md) +- [Docker 部署](../deployment/docker.md) diff --git a/docs/converters.md b/docs/converters.md index 649b2cc..8855731 100644 --- a/docs/converters.md +++ b/docs/converters.md @@ -1,5 +1,17 @@ # 支援的轉換器 +> ⚠️ **此文件已遷移** +> +> 本文件內容已整合至新的文件結構，請參閱： +> +> - 🔌 [轉換器完整說明](features/converters.md) +> - 📊 [OCR 功能](features/ocr.md) +> - 🌐 [翻譯功能](features/translation.md) +> +> 此文件將在未來版本中移除。 + +--- + ConvertX-CN 完整版已內建以下所有轉換器，開箱即用。 ## 轉換器列表 diff --git a/docs/deployment.md b/docs/deployment.md index 1e063a3..2247385 100644 --- a/docs/deployment.md +++ b/docs/deployment.md @@ -1,5 +1,17 @@ # 進階部署指南 +> ⚠️ **此文件已遷移** +> +> 本文件內容已整合至新的文件結構，請參閱： +> +> - 🐳 [Docker 部署](deployment/docker.md) +> - 🔧 [反向代理設定](deployment/reverse-proxy.md) +> - 🔒 [安全性設定](configuration/security.md) +> +> 此文件將在未來版本中移除。 + +--- + 本文件說明如何在生產環境中部署 ConvertX-CN，包括 Reverse Proxy、HTTPS、安全性設定等。 --- diff --git a/docs/deployment/docker.md b/docs/deployment/docker.md new file mode 100644 index 0000000..8bbc039 --- /dev/null +++ b/docs/deployment/docker.md @@ -0,0 +1,255 @@ +# Docker 部署指南 + +本文件說明如何使用 Docker 部署 ConvertX-CN。 + +--- + +## Docker Image 版本 + +### 官方預建版（推薦） + +| Tag | 說明 | +| ----------------------------- | ---------- | +| `convertx/convertx-cn:latest` | 最新穩定版 | +| `convertx/convertx-cn:v0.1.x` | 指定版本號 | + +**內建功能：** + +- ✅ 核心轉換工具（FFmpeg、LibreOffice、ImageMagick 等） +- ✅ OCR 支援：英文、繁/簡中文、日文、韓文、德文、法文 +- ✅ 字型：Noto CJK、Liberation、自訂中文字型 +- ✅ TexLive（支援 CJK/德/法） + +**Image 大小：約 4-6 GB** + +### 完整版（自行 Build） + +使用 `Dockerfile.full` 自行建構，適合需要： + +- 65 種 OCR 語言 +- 完整 TexLive +- 額外字型套件 + +```bash +docker build -f Dockerfile.full -t convertx-cn-full . +``` + +> ⚠️ 注意：Image 大小可能超過 **10GB**，Build 時間約 **30-60 分鐘** + +--- + +## Docker Run + +### 基本啟動 + +```bash +docker run -d \ + --name convertx-cn \ + --restart unless-stopped \ + -p 3000:3000 \ + -v ./data:/app/data \ + -e TZ=Asia/Taipei \ + -e JWT_SECRET=你的隨機字串至少32字元 \ + convertx/convertx-cn:latest +``` + +### 參數說明 + +| 參數 | 說明 | +| -------------------------- | ---------- | +| `-d` | 背景執行 | +| `--name convertx-cn` | 容器名稱 | +| `--restart unless-stopped` | 自動重啟 | +| `-p 3000:3000` | 連接埠映射 | +| `-v ./data:/app/data` | 資料持久化 | +| `-e TZ=Asia/Taipei` | 時區設定 | + +### 進階選項 + +```bash +docker run -d \ + --name convertx-cn \ + --restart unless-stopped \ + -p 3000:3000 \ + -v ./data:/app/data \ + -e TZ=Asia/Taipei \ + -e JWT_SECRET=你的隨機字串 \ + -e ACCOUNT_REGISTRATION=false \ + -e HTTP_ALLOWED=true \ + -e AUTO_DELETE_EVERY_N_HOURS=24 \ + convertx/convertx-cn:latest +``` + +--- + +## 資料持久化 + +### Volume 結構 + +``` +./data/ +├── convertx.db # SQLite 資料庫 +├── uploads/ # 上傳的原始檔案 +└── output/ # 轉換後的檔案 +``` + +### 建立資料夾 + +**重要**：請務必先建立資料夾，否則 Docker 會建立匿名 volume。 + +```bash +# Linux / macOS +mkdir -p ~/convertx-cn/data + +# Windows PowerShell +mkdir C:\convertx-cn\data +``` + +### 備份與還原 + +```bash +# 備份 +tar -czvf convertx-backup-$(date +%Y%m%d).tar.gz ./data + +# 還原 +tar -xzvf convertx-backup-20260120.tar.gz +``` + +--- + +## 硬體加速 + +### NVIDIA GPU (CUDA/NVENC) + +1. 安裝 [NVIDIA Container Toolkit](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/install-guide.html) + +2. Docker Compose 配置： + +```yaml +services: + convertx: + image: convertx/convertx-cn:latest + deploy: + resources: + reservations: + devices: + - driver: nvidia + count: all + capabilities: [gpu] + environment: + - FFMPEG_ARGS=-hwaccel cuda -hwaccel_output_format cuda + - FFMPEG_OUTPUT_ARGS=-c:v h264_nvenc -preset fast +``` + +### Intel Quick Sync Video (QSV) + +```yaml +services: + convertx: + image: convertx/convertx-cn:latest + devices: + - /dev/dri:/dev/dri + environment: + - FFMPEG_ARGS=-hwaccel qsv + - FFMPEG_OUTPUT_ARGS=-c:v h264_qsv -preset faster +``` + +### AMD VAAPI + +```yaml +services: + convertx: + image: convertx/convertx-cn:latest + devices: + - /dev/dri:/dev/dri + environment: + - FFMPEG_ARGS=-hwaccel vaapi -hwaccel_device /dev/dri/renderD128 + - FFMPEG_OUTPUT_ARGS=-c:v h264_vaapi +``` + +--- + +## 資源限制 + +### 記憶體限制 + +```yaml +services: + convertx: + deploy: + resources: + limits: + memory: 4G + reservations: + memory: 2G +``` + +### CPU 限制 + +```yaml +services: + convertx: + deploy: + resources: + limits: + cpus: "2" +``` + +--- + +## 版本更新 + +```bash +# 拉取最新版本 +docker pull convertx/convertx-cn:latest + +# 停止並移除舊容器 +docker stop convertx-cn +docker rm convertx-cn + +# 重新啟動（使用相同的參數） +docker run -d \ + --name convertx-cn \ + # ... 其他參數 +``` + +或使用 Docker Compose： + +```bash +docker compose pull +docker compose up -d +``` + +--- + +## 疑難排解 + +### 查看日誌 + +```bash +docker logs convertx-cn +docker logs -f convertx-cn # 持續追蹤 +``` + +### 進入容器 + +```bash +docker exec -it convertx-cn /bin/bash +``` + +### 常見問題 + +| 問題 | 解決方法 | +| ----------- | ------------------------------ | +| 啟動失敗 | 檢查日誌 `docker logs` | +| Port 被占用 | 改用其他 port `-p 8080:3000` | +| 權限錯誤 | `chmod -R 777 ./data` | +| 記憶體不足 | 增加記憶體限制或減少同時轉換數 | + +--- + +## 相關文件 + +- [Docker Compose 詳解](docker-compose.md) +- [反向代理設定](reverse-proxy.md) +- [環境變數設定](../configuration/environment-variables.md) diff --git a/docs/deployment/reverse-proxy.md b/docs/deployment/reverse-proxy.md new file mode 100644 index 0000000..9ccbb87 --- /dev/null +++ b/docs/deployment/reverse-proxy.md @@ -0,0 +1,287 @@ +# 反向代理設定 + +本文件說明如何在 Nginx、Traefik、Caddy 等反向代理後部署 ConvertX-CN。 + +--- + +## 必要環境變數 + +透過反向代理存取時，請設定： + +```yaml +environment: + - TRUST_PROXY=true # 信任 X-Forwarded-* headers + - HTTP_ALLOWED=false # Proxy 已處理 HTTPS +``` + +--- + +## 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 + +### Docker Labels 方式 + +```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=true" + - "traefik.http.routers.convertx.tls.certresolver=letsencrypt" + - "traefik.http.services.convertx.loadbalancer.server.port=3000" + networks: + - traefik-network + +networks: + traefik-network: + external: true +``` + +### 動態配置檔 + +```yaml +# traefik/dynamic/convertx.yml +http: + routers: + convertx: + rule: "Host(`convertx.example.com`)" + service: convertx + entryPoints: + - websecure + tls: + certResolver: letsencrypt + + services: + convertx: + loadBalancer: + servers: + - url: "http://127.0.0.1:3000" +``` + +--- + +## Caddy + +### 基本配置 + +``` +convertx.example.com { + reverse_proxy localhost:3000 { + header_up X-Real-IP {remote_host} + header_up X-Forwarded-Proto {scheme} + } + + request_body { + max_size 500MB + } +} +``` + +### 子路徑部署 + +``` +example.com { + handle_path /convertx/* { + reverse_proxy localhost:3000 + } +} +``` + +記得設定環境變數： + +```yaml +environment: + - WEBROOT=/convertx +``` + +--- + +## Cloudflare Tunnel + +### 1. 建立 Tunnel + +```bash +cloudflared tunnel create convertx +``` + +### 2. 配置 + +```yaml +# ~/.cloudflared/config.yml +tunnel: +credentials-file: ~/.cloudflared/.json + +ingress: + - hostname: convertx.example.com + service: http://localhost:3000 + - service: http_status:404 +``` + +### 3. 啟動 + +```bash +cloudflared tunnel run convertx +``` + +### 4. 環境變數 + +```yaml +environment: + - TRUST_PROXY=true + - HTTP_ALLOWED=false +``` + +--- + +## 子路徑部署 + +如需在子路徑部署（如 `https://example.com/convertx`）： + +### 1. 設定環境變數 + +```yaml +environment: + - WEBROOT=/convertx +``` + +### 2. Nginx 配置 + +```nginx +location /convertx/ { + proxy_pass http://localhost:3000/; + # ... 其他 proxy 設定 +} +``` + +### 3. Caddy 配置 + +``` +example.com { + handle_path /convertx/* { + reverse_proxy localhost:3000 + } +} +``` + +--- + +## HTTPS 憑證 + +### Let's Encrypt（推薦） + +使用 Certbot 自動取得憑證： + +```bash +sudo apt install certbot python3-certbot-nginx +sudo certbot --nginx -d convertx.example.com +``` + +### 自簽憑證（測試用） + +```bash +openssl req -x509 -nodes -days 365 -newkey rsa:2048 \ + -keyout /etc/nginx/ssl/convertx.key \ + -out /etc/nginx/ssl/convertx.crt +``` + +--- + +## 疑難排解 + +### 登入後被踢回登入頁 + +1. 確認 `TRUST_PROXY=true` +2. 確認反向代理正確傳送 `X-Forwarded-Proto` header + +### 上傳檔案失敗 + +1. 調高 `client_max_body_size`（Nginx） +2. 調高 `request_body max_size`（Caddy） +3. 調高超時設定 + +### WebSocket 連線失敗 + +確認反向代理正確處理 WebSocket： + +```nginx +proxy_set_header Upgrade $http_upgrade; +proxy_set_header Connection "upgrade"; +``` + +--- + +## 相關文件 + +- [Docker 部署](docker.md) +- [安全性設定](../configuration/security.md) +- [環境變數](../configuration/environment-variables.md) diff --git a/docs/development/contribution.md b/docs/development/contribution.md new file mode 100644 index 0000000..cc9383f --- /dev/null +++ b/docs/development/contribution.md @@ -0,0 +1,192 @@ +# 貢獻指南 + +感謝您有興趣貢獻 ConvertX-CN！本文件說明如何參與專案開發。 + +--- + +## 貢獻方式 + +### 🐛 回報問題 + +1. 前往 [GitHub Issues](https://github.com/pi-docket/ConvertX-CN/issues) +2. 點擊 "New Issue" +3. 選擇適當的 Issue 模板 +4. 填寫詳細資訊 + +### 💡 功能建議 + +1. 先搜尋是否已有類似提議 +2. 開一個新的 Issue 說明您的想法 +3. 等待討論與回饋 + +### 🔧 提交程式碼 + +1. Fork 專案 +2. 建立功能分支 +3. 進行修改 +4. 提交 Pull Request + +--- + +## 開發流程 + +### 1. Fork 與 Clone + +```bash +# Fork 專案後 +git clone https://github.com/YOUR_USERNAME/ConvertX-CN.git +cd ConvertX-CN +``` + +### 2. 建立分支 + +```bash +# 功能分支 +git checkout -b feature/my-feature + +# 修復分支 +git checkout -b fix/bug-description +``` + +### 3. 安裝依賴 + +```bash +bun install +``` + +### 4. 進行修改 + +遵循現有的程式碼風格與結構。 + +### 5. 測試 + +```bash +# 執行測試 +bun run test + +# 檢查格式 +bun run lint +bun run format:check +``` + +### 6. 提交 + +```bash +git add . +git commit -m "feat: add new feature" +``` + +### 7. 推送與 PR + +```bash +git push origin feature/my-feature +``` + +然後在 GitHub 上建立 Pull Request。 + +--- + +## Commit 訊息規範 + +使用 [Conventional Commits](https://www.conventionalcommits.org/) 格式： + +| 類型 | 說明 | +| -------- | ------------------ | +| feat | 新功能 | +| fix | 修復 Bug | +| docs | 文件修改 | +| style | 格式調整 | +| refactor | 重構 | +| test | 測試相關 | +| chore | 雜項（建構、工具） | + +**範例：** + +``` +feat: add Japanese OCR support +fix: resolve login redirect issue +docs: update deployment guide +``` + +--- + +## 程式碼規範 + +### TypeScript + +- 使用 ESLint 與 Prettier +- 類型定義盡量明確 +- 避免 `any` + +### Rust（API Server） + +- 使用 `rustfmt` 格式化 +- 使用 `clippy` 檢查 + +### 文件 + +- 使用 Markdown +- 繁體中文為主 + +--- + +## Pull Request 指南 + +### PR 標題 + +使用 Conventional Commits 格式。 + +### PR 描述 + +- 說明修改的目的 +- 列出主要變更 +- 附上相關 Issue 連結 + +### 檢查清單 + +- [ ] 已測試功能正常 +- [ ] 已通過 lint 檢查 +- [ ] 已更新相關文件（如需要） +- [ ] Commit 訊息符合規範 + +--- + +## 貢獻領域 + +### 歡迎的貢獻 + +- 🐛 Bug 修復 +- 🌐 翻譯改進 +- 📖 文件完善 +- ✨ 新功能 +- ⚡ 效能優化 +- 🧪 測試覆蓋 + +### 貢獻翻譯 + +1. 複製 `src/locales/en.json` +2. 重命名為語言代碼 `xx.json` +3. 翻譯所有文字 +4. 在 `src/i18n/index.ts` 註冊 +5. 提交 PR + +--- + +## 社群 + +- 📝 [GitHub Issues](https://github.com/pi-docket/ConvertX-CN/issues) +- 💬 [GitHub Discussions](https://github.com/pi-docket/ConvertX-CN/discussions) + +--- + +## 行為準則 + +請遵守 [Contributor Covenant](https://www.contributor-covenant.org/) 行為準則。 + +--- + +## 相關文件 + +- [專案結構](project-structure.md) +- [本地開發](local-development.md) +- [測試策略](../testing/test-strategy.md) diff --git a/docs/development/local-development.md b/docs/development/local-development.md new file mode 100644 index 0000000..5be02db --- /dev/null +++ b/docs/development/local-development.md @@ -0,0 +1,207 @@ +# 本地開發 + +本文件說明如何在本地環境進行 ConvertX-CN 開發。 + +--- + +## 環境需求 + +- **Node.js** 20+ 或 **Bun** 1.0+ +- **Docker**（用於測試） +- **Git** + +### 可選 + +- **Rust** 1.75+（開發 API Server） +- 轉換工具（FFmpeg、ImageMagick 等） + +--- + +## 快速開始 + +### 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 run dev +``` + +開啟 `http://localhost:3000` + +--- + +## 開發工具 + +### 程式碼格式化 + +```bash +# Prettier +bun run format + +# ESLint +bun run lint +``` + +### 類型檢查 + +```bash +bun run typecheck +``` + +### 建構 + +```bash +bun run build +``` + +--- + +## 目錄說明 + +| 目錄 | 說明 | +| ------------- | ---------- | +| `src/` | 前端原始碼 | +| `public/` | 靜態資源 | +| `api-server/` | API Server | +| `tests/` | 測試檔案 | +| `docs/` | 文件 | +| `scripts/` | 腳本 | + +--- + +## 常見開發任務 + +### 新增轉換器 + +1. 在 `src/converters/` 建立新檔案 +2. 定義輸入/輸出格式 +3. 在 `src/converters/main.ts` 註冊 + +```typescript +// src/converters/myconverter.ts +export const myConverter: Converter = { + id: "myconverter", + name: "My Converter", + inputFormats: ["abc", "xyz"], + outputFormats: ["pdf", "txt"], + convert: async (input, output, format) => { + // 轉換邏輯 + }, +}; +``` + +### 新增翻譯 + +1. 在 `src/locales/` 新增或修改翻譯檔 +2. 在 `src/i18n/index.ts` 註冊（如果是新語言） + +```json +// src/locales/xx.json +{ + "title": "ConvertX-CN", + "upload": "上傳", + ... +} +``` + +### 修改樣式 + +TailwindCSS 設定在 `tailwind.config.js`。 + +```bash +# 重新生成 CSS +bun run build:css +``` + +--- + +## API Server 開發 + +### 環境設定 + +```bash +cd api-server +``` + +### 建構 + +```bash +cargo build +``` + +### 執行 + +```bash +cargo run +``` + +### 測試 + +```bash +cargo test +``` + +--- + +## Docker 開發 + +### 建構本地映像 + +```bash +docker build -t convertx-cn-dev . +``` + +### 使用本地映像 + +```yaml +# docker-compose.yml +services: + convertx: + image: convertx-cn-dev + # ... +``` + +--- + +## 偵錯 + +### 前端偵錯 + +使用瀏覽器開發者工具（F12）。 + +### 後端偵錯 + +```bash +# 詳細日誌 +DEBUG=* bun run dev +``` + +### API Server 偵錯 + +```bash +RUST_LOG=debug cargo run +``` + +--- + +## 相關文件 + +- [專案結構](project-structure.md) +- [貢獻指南](contribution.md) +- [測試策略](../testing/test-strategy.md) diff --git a/docs/development/project-structure.md b/docs/development/project-structure.md new file mode 100644 index 0000000..81a5928 --- /dev/null +++ b/docs/development/project-structure.md @@ -0,0 +1,179 @@ +# 專案結構 + +本文件說明 ConvertX-CN 的程式碼結構與架構。 + +--- + +## 目錄結構 + +``` +ConvertX-CN/ +├── src/ # 前端原始碼 +│ ├── index.tsx # 主入口 +│ ├── main.css # 主樣式 +│ ├── components/ # React 元件 +│ ├── converters/ # 轉換器定義 +│ ├── db/ # 資料庫相關 +│ ├── helpers/ # 工具函數 +│ ├── i18n/ # 國際化 +│ ├── icons/ # 圖示元件 +│ ├── locales/ # 翻譯檔案 +│ ├── pages/ # 頁面元件 +│ ├── theme/ # 主題相關 +│ └── transfer/ # 檔案傳輸 +├── public/ # 靜態資源 +├── api-server/ # Rust API Server（選用） +│ ├── src/ # Rust 原始碼 +│ ├── docs/ # API 文件 +│ └── tests/ # 測試 +├── docs/ # 文件 +├── tests/ # 測試 +├── scripts/ # 腳本 +├── data/ # 資料目錄（runtime） +├── Dockerfile # Docker 建構檔 +├── compose.yaml # Docker Compose +└── package.json # Node.js 依賴 +``` + +--- + +## 技術棧 + +### 前端 + +| 技術 | 用途 | +| ----------- | -------- | +| Bun | Runtime | +| Elysia | Web 框架 | +| React | UI 元件 | +| TailwindCSS | 樣式 | +| TypeScript | 類型安全 | + +### 後端 (Web UI) + +| 技術 | 用途 | +| ------ | -------- | +| Bun | Runtime | +| Elysia | Web 框架 | +| SQLite | 資料庫 | + +### API Server（選用） + +| 技術 | 用途 | +| ------------- | -------- | +| Rust | 語言 | +| Axum | Web 框架 | +| async-graphql | GraphQL | + +--- + +## 核心模組 + +### src/converters/ + +定義所有轉換器的設定與格式支援。 + +``` +converters/ +├── main.ts # 轉換器主邏輯 +├── types.ts # 類型定義 +├── ffmpeg.ts # FFmpeg 設定 +├── imagemagick.ts # ImageMagick 設定 +├── libreoffice.ts # LibreOffice 設定 +├── pandoc.ts # Pandoc 設定 +├── calibre.ts # Calibre 設定 +└── ... +``` + +### src/i18n/ + +國際化模組，支援 65 種語言。 + +``` +i18n/ +├── index.ts # i18n 初始化 +└── service.ts # 語言服務 +``` + +### src/locales/ + +翻譯檔案，每個語言一個 JSON 檔案。 + +``` +locales/ +├── en.json # 英文 +├── zh-TW.json # 繁體中文 +├── zh-CN.json # 簡體中文 +├── ja.json # 日文 +└── ... +``` + +### src/transfer/ + +檔案傳輸模組，處理上傳與下載。 + +``` +transfer/ +├── upload.ts # 上傳邏輯 +├── download.ts # 下載邏輯 +└── chunked.ts # 分段傳輸 +``` + +--- + +## API Server 結構 + +``` +api-server/ +├── src/ +│ ├── main.rs # 入口 +│ ├── lib.rs # 模組定義 +│ ├── config.rs # 設定 +│ ├── auth.rs # JWT 認證 +│ ├── engine.rs # 引擎管理 +│ ├── conversion.rs# 轉換邏輯 +│ ├── rest.rs # REST API +│ ├── graphql.rs # GraphQL API +│ ├── models.rs # 資料模型 +│ └── error.rs # 錯誤處理 +├── tests/ +│ ├── api_tests.rs +│ ├── graphql_tests.rs +│ └── integration_tests.rs +└── docs/ + ├── API_SPEC.md + └── ARCHITECTURE.md +``` + +--- + +## 資料流 + +### 檔案轉換流程 + +``` +1. 使用者上傳檔案 + ↓ +2. 儲存到 data/uploads/ + ↓ +3. 呼叫對應轉換器 + ↓ +4. 輸出到 data/output/ + ↓ +5. 使用者下載結果 +``` + +### 檔案傳輸策略 + +| 檔案大小 | 傳輸方式 | 說明 | +| -------- | -------- | ------------ | +| ≤ 10MB | 直接傳輸 | 單一請求完成 | +| > 10MB | 分段傳輸 | 5MB chunks | + +--- + +## 相關文件 + +- [本地開發](local-development.md) +- [貢獻指南](contribution.md) +- [測試策略](../testing/test-strategy.md) diff --git a/docs/docker.md b/docs/docker.md index 7448e9c..9bdfc1d 100644 --- a/docs/docker.md +++ b/docs/docker.md @@ -1,5 +1,16 @@ # Docker 配置指南 +> ⚠️ **此文件已遷移** +> +> 本文件內容已整合至新的文件結構，請參閱： +> +> - 📦 [Docker 部署指南](deployment/docker.md) +> - 🔧 [反向代理設定](deployment/reverse-proxy.md) +> +> 此文件將在未來版本中移除。 + +--- + ## Docker Image 版本說明 ConvertX-CN 提供兩種 Docker Image 選項： diff --git a/docs/faq.md b/docs/faq.md index 8c3b88c..21f1e72 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -1,5 +1,15 @@ # 常見問題 FAQ +> ⚠️ **此文件已遷移** +> +> 本文件內容已整合至新的文件結構，請參閱： +> +> - ❓ [常見問題 FAQ](getting-started/faq.md) +> +> 此文件將在未來版本中移除。 + +--- + ## 🔐 登入與帳號 ### Q: 如何註冊帳號？ diff --git a/docs/features/converters.md b/docs/features/converters.md new file mode 100644 index 0000000..d05291c --- /dev/null +++ b/docs/features/converters.md @@ -0,0 +1,223 @@ +# 支援的轉換器 + +ConvertX-CN 完整版已內建 20+ 種轉換器，支援 1000+ 種格式。 + +--- + +## 轉換器總覽 + +| 轉換器 | 用途 | 輸入格式 | 輸出格式 | +| ---------------- | ------------ | -------- | -------- | +| FFmpeg | 影音 | ~472 | ~199 | +| ImageMagick | 圖片 | 245 | 183 | +| GraphicsMagick | 圖片 | 167 | 130 | +| Vips | 高效圖片處理 | 45 | 23 | +| LibreOffice | 文件 | 41 | 22 | +| Pandoc | 文件 | 43 | 65 | +| Calibre | 電子書 | 26 | 19 | +| Inkscape | 向量圖形 | 7 | 17 | +| libjxl | JPEG XL | 11 | 11 | +| libheif | HEIF | 2 | 4 | +| Assimp | 3D 模型 | 77 | 23 | +| Potrace | 點陣轉向量 | 4 | 11 | +| VTracer | 點陣轉向量 | 8 | 1 | +| resvg | SVG | 1 | 1 | +| XeLaTeX | LaTeX | 1 | 1 | +| dvisvgm | 向量圖形 | 4 | 2 | +| Dasel | 資料檔案 | 5 | 4 | +| msgconvert | Outlook | 1 | 1 | +| VCF to CSV | 聯絡人 | 1 | 1 | +| Markitdown | 文件 | 6 | 1 | +| MinerU | PDF → MD | 1 | 2 | +| PDFMathTranslate | PDF 翻譯 | 1 | 15+ | + +--- + +## 影音轉換 + +### FFmpeg + +最強大的影音轉換工具，支援幾乎所有影音格式。 + +**常見輸入格式：** + +- 影片：MP4, MKV, AVI, MOV, WebM, FLV, WMV... +- 音訊：MP3, WAV, FLAC, AAC, OGG, M4A... + +**常見輸出格式：** + +- 影片：MP4, WebM, MKV, GIF... +- 音訊：MP3, WAV, FLAC, AAC... + +**硬體加速：** + +```yaml +environment: + - FFMPEG_ARGS=-hwaccel cuda + - FFMPEG_OUTPUT_ARGS=-c:v h264_nvenc +``` + +--- + +## 圖片處理 + +### ImageMagick + +通用圖片處理工具，支援 200+ 種格式。 + +**支援格式：** + +- 點陣圖：PNG, JPG, GIF, BMP, TIFF, WebP... +- RAW：CR2, NEF, ARW, DNG... +- 其他：PSD, PDF, EPS... + +### Vips + +高效能圖片處理，適合大型圖片。 + +**優勢：** + +- 記憶體使用效率高 +- 處理速度快 +- 適合批次處理 + +### 向量圖形 + +| 工具 | 用途 | +| -------- | -------------- | +| Inkscape | SVG 編輯與轉換 | +| Potrace | 點陣圖轉向量 | +| VTracer | 照片轉向量 | +| resvg | SVG 渲染 | + +--- + +## 文件轉換 + +### LibreOffice + +辦公文件轉換引擎。 + +**輸入格式：** + +- Microsoft Office：DOC, DOCX, XLS, XLSX, PPT, PPTX +- OpenDocument：ODT, ODS, ODP +- 其他：RTF, TXT, CSV + +**輸出格式：** + +- PDF, DOCX, ODT, TXT, HTML, EPUB... + +### Pandoc + +標記語言文件轉換。 + +**輸入格式：** + +- Markdown, reStructuredText, Org-mode +- HTML, LaTeX, EPUB +- Word, ODT + +**輸出格式：** + +- PDF, DOCX, HTML, LaTeX +- EPUB, Markdown, 純文字 + +### Calibre + +電子書轉換專家。 + +**輸入格式：** + +- EPUB, MOBI, AZW, AZW3 +- PDF, HTML, TXT +- CBZ, CBR（漫畫） + +**輸出格式：** + +- EPUB, MOBI, AZW3 +- PDF, HTML, TXT + +--- + +## 進階功能 + +### MinerU + +將 PDF 轉換為結構化 Markdown。 + +**輸出模式：** + +- `md-t`：表格以 Markdown 呈現 +- `md-i`：表格以圖片呈現 + +**輸出格式：** `.tar` 封裝 + +### PDFMathTranslate + +翻譯 PDF 同時保留數學公式與排版。 + +**支援目標語言：** + +- 英文 (pdf-en) +- 繁體中文 (pdf-zh-TW) +- 簡體中文 (pdf-zh) +- 日文 (pdf-ja) +- 韓文 (pdf-ko) +- 德文、法文等 + +**特色：** + +- 保留數學公式 +- 保留圖表 +- 保留排版 + +**環境變數：** + +```yaml +- PDFMATHTRANSLATE_SERVICE=google # 翻譯服務 +``` + +### OCR (Tesseract) + +光學字元辨識，將圖片文字轉為可編輯文字。 + +**內建語言：** + +- 繁體中文、簡體中文 +- 日文、韓文 +- 英文、德文、法文 + +--- + +## 內建依賴 + +ConvertX-CN 完整版已預載： + +| 類別 | 內建內容 | +| ------------ | -------------------------------------------- | +| **文件轉換** | LibreOffice (headless)、Pandoc | +| **LaTeX** | TexLive Full | +| **OCR** | Tesseract + 繁/簡中、日、韓、英、德語言包 | +| **CJK 字型** | Noto CJK、Noto Emoji、微軟核心字型、標楷體 | +| **影音轉換** | FFmpeg、ImageMagick、GraphicsMagick | +| **向量圖形** | Inkscape、Potrace、VTracer、resvg | +| **電子書** | Calibre | +| **其他** | Ghostscript、MuPDF、Poppler、libheif、libjxl | + +--- + +## 新增轉換器 + +如需新增轉換器支援，歡迎： + +1. 📝 [提交 Issue](https://github.com/pi-docket/ConvertX-CN/issues) +2. 🔧 [發送 Pull Request](https://github.com/pi-docket/ConvertX-CN/pulls) + +--- + +## 相關文件 + +- [OCR 功能](ocr.md) +- [翻譯功能](translation.md) +- [Docker 部署](../deployment/docker.md) diff --git a/docs/features/i18n.md b/docs/features/i18n.md new file mode 100644 index 0000000..1c1cc62 --- /dev/null +++ b/docs/features/i18n.md @@ -0,0 +1,132 @@ +# 多語言支援（i18n） + +ConvertX-CN 支援 **65 種語言**，提供完整的多語言介面體驗。 + +--- + +## 語言切換 + +### 方法一：介面切換 + +1. 點擊右上角語言圖示 🌐 +2. 從下拉選單選擇語言 +3. 頁面自動更新 + +語言偏好會儲存在 Cookie 中。 + +### 方法二：URL 參數 + +``` +http://localhost:3000/?lang=ja +``` + +### 方法三：瀏覽器設定 + +系統會自動偵測瀏覽器的語言設定。 + +--- + +## 語言優先順序 + +1. Cookie 中儲存的語言偏好 +2. URL 參數 `?lang=xx` +3. 瀏覽器 `Accept-Language` header +4. 預設語言（繁體中文） + +--- + +## 支援語言列表 + +### 東亞語言（5 種） + +| 代碼 | 語言 | 原生名稱 | +| ------- | -------- | -------- | +| `zh-TW` | 繁體中文 | 繁體中文 | +| `zh-CN` | 簡體中文 | 简体中文 | +| `en` | 英文 | English | +| `ja` | 日文 | 日本語 | +| `ko` | 韓文 | 한국어 | + +### 西歐語言（10 種） + +| 代碼 | 語言 | 原生名稱 | +| ---- | ---------- | ---------- | +| `de` | 德文 | Deutsch | +| `fr` | 法文 | Français | +| `es` | 西班牙文 | Español | +| `it` | 義大利文 | Italiano | +| `pt` | 葡萄牙文 | Português | +| `nl` | 荷蘭文 | Nederlands | +| `ca` | 加泰隆尼亞 | Català | +| `eu` | 巴斯克文 | Euskara | +| `gl` | 加利西亞文 | Galego | +| `mt` | 馬爾他文 | Malti | + +### 北歐語言（5 種） + +| 代碼 | 語言 | 原生名稱 | +| ---- | ------ | -------- | +| `sv` | 瑞典文 | Svenska | +| `da` | 丹麥文 | Dansk | +| `fi` | 芬蘭文 | Suomi | +| `no` | 挪威文 | Norsk | +| `is` | 冰島文 | Íslenska | + +### 東歐語言（12 種） + +| 代碼 | 語言 | 原生名稱 | +| ---- | ------------ | ----------- | +| `ru` | 俄文 | Русский | +| `pl` | 波蘭文 | Polski | +| `uk` | 烏克蘭文 | Українська | +| `cs` | 捷克文 | Čeština | +| `hu` | 匈牙利文 | Magyar | +| `ro` | 羅馬尼亞文 | Română | +| `bg` | 保加利亞文 | Български | +| `hr` | 克羅埃西亞文 | Hrvatski | +| `sk` | 斯洛伐克文 | Slovenčina | +| `sl` | 斯洛維尼亞文 | Slovenščina | +| `sr` | 塞爾維亞文 | Српски | +| `mk` | 馬其頓文 | Македонски | + +### 其他語言 + +詳見完整語言列表（共 65 種），包含： + +- 中東語言（阿拉伯文、希伯來文、波斯文、土耳其文） +- 南亞語言（印地文、孟加拉文、泰米爾文等） +- 東南亞語言（泰文、越南文、印尼文等） +- 非洲語言（斯瓦希里文、祖魯文等） + +--- + +## 貢獻翻譯 + +歡迎協助改進翻譯！ + +### 步驟 + +1. 複製 `src/locales/en.json` +2. 重命名為 `xx.json`（語言代碼） +3. 翻譯所有文字 +4. 在 `src/i18n/index.ts` 中註冊 +5. 提交 Pull Request + +### 翻譯檔案格式 + +```json +{ + "title": "ConvertX-CN", + "description": "檔案轉換服務", + "upload": "上傳檔案", + "convert": "開始轉換", + ... +} +``` + +--- + +## 相關文件 + +- [貢獻指南](../development/contribution.md) +- [專案結構](../development/project-structure.md) diff --git a/docs/features/ocr.md b/docs/features/ocr.md new file mode 100644 index 0000000..f0260d3 --- /dev/null +++ b/docs/features/ocr.md @@ -0,0 +1,117 @@ +# OCR 功能 + +ConvertX-CN 內建 Tesseract OCR，可將圖片中的文字轉換為可編輯文字。 + +--- + +## 內建語言 + +ConvertX-CN 完整版內建以下 OCR 語言： + +| 語言 | 代碼 | +| -------- | --------- | +| 繁體中文 | `chi_tra` | +| 簡體中文 | `chi_sim` | +| 英文 | `eng` | +| 日文 | `jpn` | +| 韓文 | `kor` | +| 德文 | `deu` | +| 法文 | `fra` | + +--- + +## 使用方式 + +### 圖片 → 文字 + +1. 上傳圖片（PNG, JPG, TIFF 等） +2. 選擇目標格式 `txt` 或 `pdf`（可搜尋） +3. 進行轉換 + +### PDF → 可搜尋 PDF + +1. 上傳掃描版 PDF +2. 選擇 OCR 處理 +3. 獲得可搜尋的 PDF + +--- + +## 支援的輸入格式 + +- **點陣圖**：PNG, JPG, JPEG, TIFF, BMP, GIF +- **文件**：PDF（掃描版） +- **其他**：WebP, PNM, PBM + +--- + +## 輸出格式 + +| 格式 | 說明 | +| ---- | --------------- | +| TXT | 純文字 | +| PDF | 可搜尋 PDF | +| HOCR | HTML + 座標資訊 | + +--- + +## 最佳實踐 + +### 提高辨識準確度 + +1. **解析度**：至少 300 DPI +2. **對比度**：文字與背景對比清晰 +3. **傾斜校正**：確保文字水平 +4. **雜訊去除**：去除背景雜訊 + +### 處理多語言文件 + +Tesseract 可同時辨識多種語言，但準確度可能下降。 + +建議： + +- 單一語言文件使用單一語言包 +- 中英混合使用 `chi_tra+eng` + +--- + +## 新增語言 + +### 方法一：自訂 Dockerfile + +```dockerfile +# 在 Dockerfile.full 中取消註解 +RUN apt-get update && apt-get install -y --no-install-recommends \ + tesseract-ocr-spa \ # 西班牙文 + tesseract-ocr-ita \ # 義大利文 + && rm -rf /var/lib/apt/lists/* +``` + +### 方法二：掛載語言包 + +```yaml +volumes: + - ./tessdata:/usr/share/tesseract-ocr/5/tessdata +``` + +下載語言包：https://github.com/tesseract-ocr/tessdata_best + +--- + +## 可選語言包 + +| 區域 | 語言 | +| ------ | ------------------------------ | +| 西歐 | 西班牙文、義大利文、葡萄牙文 | +| 北歐 | 瑞典文、丹麥文、挪威文、芬蘭文 | +| 東歐 | 俄文、波蘭文、捷克文、匈牙利文 | +| 中東 | 阿拉伯文、希伯來文、土耳其文 | +| 南亞 | 印地文、孟加拉文、泰米爾文 | +| 東南亞 | 泰文、越南文、印尼文 | + +--- + +## 相關文件 + +- [支援的轉換器](converters.md) +- [翻譯功能](translation.md) +- [Docker 部署](../deployment/docker.md) diff --git a/docs/features/translation.md b/docs/features/translation.md new file mode 100644 index 0000000..dd5fc00 --- /dev/null +++ b/docs/features/translation.md @@ -0,0 +1,118 @@ +# 翻譯功能 + +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) diff --git a/docs/getting-started.md b/docs/getting-started.md index 0443cc0..306998b 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -1,5 +1,17 @@ # 快速開始 +> ⚠️ **此文件已遷移** +> +> 本文件內容已整合至新的文件結構，請參閱： +> +> - 📖 [概覽](getting-started/overview.md) +> - 🚀 [快速開始](getting-started/quick-start.md) +> - ❓ [常見問題](getting-started/faq.md) +> +> 此文件將在未來版本中移除。 + +--- + > 本文件提供完整部署步驟。若只需最快啟動，請參考 [README](../README.md)。 --- diff --git a/docs/getting-started/faq.md b/docs/getting-started/faq.md new file mode 100644 index 0000000..5523313 --- /dev/null +++ b/docs/getting-started/faq.md @@ -0,0 +1,192 @@ +# 常見問題 FAQ + +--- + +## 🔐 登入與帳號 + +### Q: 如何註冊帳號？ + +首次訪問 ConvertX-CN 時： + +1. 開啟 `http://localhost:3000` +2. 點擊右上角 **Register** +3. 輸入 Email 和密碼 +4. 完成！系統會自動登入 + +> ✅ **預設開放註冊**，無需設定任何環境變數 + +### Q: 可以關閉公開註冊嗎？ + +可以。如果您想限制只有現有用戶可使用： + +```yaml +environment: + - ACCOUNT_REGISTRATION=false +``` + +> ⚠️ 請確保您已經有至少一個帳號，否則將無法登入 + +### Q: 忘記密碼怎麼辦？ + +目前版本尚未提供密碼重設功能。您可以： + +1. 刪除 `data/convertx.db` +2. 重新啟動容器 +3. 重新註冊 + +> ⚠️ 這會刪除所有用戶資料和轉換歷史 + +### Q: 登入後又被踢回登入頁？ + +這通常是 Cookie 設定問題。請檢查： + +1. **沒有 HTTPS 但 HTTP_ALLOWED=false** + + ```yaml + - HTTP_ALLOWED=true # 允許 HTTP 連線 + ``` + +2. **使用反向代理但沒設定 TRUST_PROXY** + + ```yaml + - TRUST_PROXY=true # 信任反向代理 + ``` + +3. **沒有設定 JWT_SECRET** + ```yaml + - JWT_SECRET=固定的隨機字串 + ``` + +--- + +## 🐳 Docker 相關 + +### Q: 為什麼 Image 這麼大（4-6 GB）？ + +ConvertX-CN 是「完整版」，內建： + +- LibreOffice（文件轉換） +- TexLive（LaTeX 支援） +- FFmpeg（影音轉換） +- Tesseract + 多語言 OCR +- CJK 字型 + +如果您只需要基本功能，可使用原作者的輕量版：`ghcr.io/c4illin/convertx:latest` + +### Q: Docker 啟動失敗？ + +常見原因： + +1. **Port 被占用**：改用其他 port，如 `-p 3001:3000` +2. **磁碟空間不足**：Image 需約 6GB +3. **權限問題**：確保 `./data` 資料夾有寫入權限 + +```bash +chmod -R 777 ./data +``` + +### Q: 資料存在哪裡？ + +所有資料存放在掛載的 `/app/data` 目錄： + +``` +./data/ +├── convertx.db # SQLite 資料庫 +├── uploads/ # 上傳的原始檔案 +└── output/ # 轉換後的檔案 +``` + +### Q: 如何備份資料？ + +直接備份 `./data` 資料夾： + +```bash +tar -czvf convertx-backup.tar.gz ./data +``` + +### Q: 如何更新版本？ + +```bash +docker compose pull +docker compose up -d +``` + +--- + +## 🌍 語言相關 + +### Q: 如何切換介面語言？ + +1. 點擊右上角語言圖示 🌐 +2. 從下拉選單選擇語言 +3. 頁面自動更新 + +語言偏好會儲存在 Cookie 中。 + +### Q: 支援哪些語言？ + +目前支援 65 種語言，包含： + +- 繁體中文、簡體中文 +- 日文、韓文 +- 英文、德文、法文 +- 更多詳見 [多語言支援](../features/i18n.md) + +--- + +## 📄 轉換相關 + +### Q: 支援哪些格式？ + +1000+ 種格式，詳見 [支援的轉換器](../features/converters.md) + +### Q: 轉換失敗怎麼辦？ + +1. 檢查檔案是否損壞 +2. 檢查容器日誌：`docker logs convertx-cn` +3. 嘗試不同的轉換引擎 + +### Q: 檔案大小有限制嗎？ + +預設無限制，但可透過反向代理設定限制： + +```nginx +client_max_body_size 500M; +``` + +### Q: 轉換很慢怎麼辦？ + +1. 增加容器記憶體限制 +2. 考慮使用硬體加速（GPU） +3. 限制同時轉換數量： + ```yaml + - MAX_CONVERT_PROCESS=2 + ``` + +--- + +## 🔧 進階問題 + +### Q: 如何使用反向代理？ + +詳見 [反向代理設定](../deployment/reverse-proxy.md) + +### Q: 如何啟用硬體加速？ + +詳見 [進階配置 - 硬體加速](../deployment/docker.md#硬體加速) + +### Q: 如何啟用 API Server？ + +```bash +docker compose --profile api up -d +``` + +詳見 [API 文件](../api/overview.md) + +--- + +## 還有問題？ + +- 📖 查看 [完整文件](../README.md) +- 🐛 回報問題：[GitHub Issues](https://github.com/pi-docket/ConvertX-CN/issues) +- 💬 討論區：[GitHub Discussions](https://github.com/pi-docket/ConvertX-CN/discussions) diff --git a/docs/getting-started/overview.md b/docs/getting-started/overview.md new file mode 100644 index 0000000..bb7d35c --- /dev/null +++ b/docs/getting-started/overview.md @@ -0,0 +1,83 @@ +# ConvertX-CN 概覽 + +ConvertX-CN 是一個功能完整的自託管檔案轉換平台，支援 1000+ 種格式轉換。 + +--- + +## 什麼是 ConvertX-CN？ + +ConvertX-CN 是 fork 自 [C4illin/ConvertX](https://github.com/C4illin/ConvertX) 的增強版本，針對中文使用者與亞洲地區需求進行優化： + +- **完整的轉換能力**：整合 20+ 種轉換引擎 +- **中文優化**：內建 CJK 字型、OCR 語言包 +- **一鍵部署**：Docker 容器化，無需安裝依賴 +- **多語言介面**：支援 65 種語言 + +--- + +## 核心功能 + +### 📄 文件轉換 + +| 引擎 | 用途 | 格式數 | +| ----------- | ------------ | ------ | +| LibreOffice | 辦公文件 | 60+ | +| Pandoc | 標記語言文件 | 100+ | +| Calibre | 電子書 | 40+ | +| XeLaTeX | LaTeX 文件 | 1 | + +### 🖼️ 圖片處理 + +| 引擎 | 用途 | 格式數 | +| ----------- | ------------ | ------ | +| ImageMagick | 圖片轉換 | 200+ | +| Vips | 高效圖片處理 | 45+ | +| Inkscape | 向量圖形 | 20+ | +| Potrace | 點陣轉向量 | 11 | + +### 🎬 影音轉換 + +| 引擎 | 用途 | 格式數 | +| ------ | -------- | ------ | +| FFmpeg | 影音轉換 | 400+ | + +### 🔬 進階功能 + +| 引擎 | 用途 | +| ---------------- | ---------------- | +| MinerU | PDF → Markdown | +| PDFMathTranslate | PDF 公式翻譯保留 | +| Tesseract OCR | 光學字元辨識 | + +--- + +## 系統需求 + +| 需求 | 最低 | 建議 | +| -------- | ------ | ------ | +| Docker | 20.10+ | 24.0+ | +| RAM | 4 GB | 8 GB | +| 磁碟空間 | 10 GB | 20 GB | +| CPU | 2 核心 | 4 核心 | + +--- + +## 與原版差異 + +| 功能 | ConvertX | ConvertX-CN | +| -------- | -------- | -------------------- | +| 鏡像大小 | ~2 GB | ~4-6 GB | +| OCR 語言 | 英文 | 中日韓英德法 | +| CJK 字型 | ❌ | ✅ Noto CJK + 標楷體 | +| TexLive | 基本 | 完整 | +| 繁中介面 | ❌ | ✅ 預設 | +| MinerU | ❌ | ✅ | +| PDF 翻譯 | ❌ | ✅ PDFMathTranslate | + +--- + +## 下一步 + +- 🚀 [快速開始](quick-start.md) — 5 分鐘內完成部署 +- ❓ [常見問題](faq.md) — 解決常見問題 +- 📦 [Docker 部署](../deployment/docker.md) — 詳細部署指南 diff --git a/docs/getting-started/quick-start.md b/docs/getting-started/quick-start.md new file mode 100644 index 0000000..162c9de --- /dev/null +++ b/docs/getting-started/quick-start.md @@ -0,0 +1,144 @@ +# 快速開始 + +5 分鐘內完成 ConvertX-CN 部署。 + +--- + +## 前置需求 + +- Docker 20.10+（[安裝指南](https://docs.docker.com/get-docker/)） +- 4GB+ 記憶體 +- 10GB+ 磁碟空間 + +--- + +## 方法一：Docker Run（最快） + +### 1. 建立資料夾 + +```bash +# Linux / macOS +mkdir -p ~/convertx-cn/data && cd ~/convertx-cn + +# Windows PowerShell +mkdir C:\convertx-cn\data; 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=你的隨機字串至少32字元 \ + convertx/convertx-cn:latest +``` + +### 3. 開始使用 + +開啟瀏覽器訪問：`http://localhost:3000` + +1. 點擊右上角 **Register** 註冊帳號 +2. 輸入 Email 和密碼 +3. 完成！開始轉換檔案 + +--- + +## 方法二：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=請更換為一個長且隨機的字串 +``` + +### 3. 啟動服務 + +```bash +docker compose up -d +``` + +--- + +## 驗證安裝 + +### 檢查容器狀態 + +```bash +docker ps +# 應該看到 convertx-cn 容器正在運行 + +docker logs convertx-cn +# 應該看到 "🦊 Elysia is running at http://localhost:3000" +``` + +### 健康檢查 + +```bash +curl http://localhost:3000/healthcheck +# 應該返回 "OK" +``` + +--- + +## 首次設定 + +### 建立帳號 + +首次訪問時，系統會顯示註冊頁面。第一個註冊的帳號即為管理員。 + +### 關閉公開註冊 + +如果只有您使用，建議關閉公開註冊： + +```yaml +environment: + - ACCOUNT_REGISTRATION=false +``` + +--- + +## 常見啟動問題 + +| 問題 | 解決方法 | +| ------------------ | ---------------------------------------------- | +| Port 被占用 | 改用其他 port，如 `-p 8080:3000` | +| 登入後被踢回登入頁 | 加上 `HTTP_ALLOWED=true` 或 `TRUST_PROXY=true` | +| 重啟後被登出 | 設定固定的 `JWT_SECRET` | +| 重啟後資料消失 | 確認 `./data:/app/data` 且資料夾存在 | +| 權限錯誤 | 執行 `chmod -R 777 ./data` | + +--- + +## 下一步 + +- 📖 [Docker 詳細配置](../deployment/docker.md) +- ⚙️ [環境變數設定](../configuration/environment-variables.md) +- 🔒 [安全性設定](../configuration/security.md) +- 🔧 [反向代理設定](../deployment/reverse-proxy.md) diff --git a/docs/i18n.md b/docs/i18n.md index 7ccc683..cd7e88a 100644 --- a/docs/i18n.md +++ b/docs/i18n.md @@ -1,5 +1,15 @@ # 多語言支援（i18n） +> ⚠️ **此文件已遷移** +> +> 本文件內容已整合至新的文件結構，請參閱： +> +> - 🌐 [多語言介面支援](features/i18n.md) +> +> 此文件將在未來版本中移除。 + +--- + ConvertX-CN 支援 **65 種語言**，是目前最完整的多語言檔案轉換服務。 --- diff --git a/docs/i18n/README.md b/docs/i18n/README.md new file mode 100644 index 0000000..63abfc4 --- /dev/null +++ b/docs/i18n/README.md @@ -0,0 +1,164 @@ +# 多語言文件支援（Internationalization） + +本目錄包含 ConvertX-CN 文件的多語言翻譯版本。 + +--- + +## 支援語言 + +| 語言代碼 | 語言 | 狀態 | 維護者 | +| -------- | -------- | ----------- | -------- | +| `zh-TW` | 繁體中文 | ✅ 主要語言 | 核心團隊 | +| `en` | English | 🚧 進行中 | 待招募 | +| `zh-CN` | 简体中文 | 📋 計畫中 | 待招募 | +| `ja` | 日本語 | 📋 計畫中 | 待招募 | + +--- + +## 目錄結構 + +``` +docs/ +├── README.md # 繁體中文（主要語言） +├── getting-started/ # 繁體中文文件 +├── deployment/ +├── configuration/ +├── ... +└── i18n/ # 多語言翻譯 + ├── README.md # 本文件 + ├── en/ # English + │ ├── README.md + │ ├── getting-started/ + │ └── ... + ├── zh-CN/ # 简体中文 + │ └── ... + └── ja/ # 日本語 + └── ... +``` + +--- + +## 翻譯指南 + +### 翻譯優先順序 + +1. **核心文件**（優先翻譯） + - `README.md`（文件總覽） + - `getting-started/quick-start.md` + - `getting-started/faq.md` + +2. **重要文件** + - `deployment/docker.md` + - `configuration/environment-variables.md` + - `features/converters.md` + +3. **進階文件** + - 其他所有文件 + +### 翻譯規範 + +1. **保持結構一致**：翻譯後的檔案結構應與原文相同 +2. **保留技術術語**：專有名詞可保留英文（如 Docker、API） +3. **更新連結**：確保所有連結指向正確的翻譯版本 +4. **標註翻譯狀態**：在文件開頭標註翻譯版本與日期 + +### 翻譯檔案範本 + +```markdown +# 文件標題 + +> 🌐 **翻譯資訊** +> +> - 原文：[繁體中文版](../../getting-started/quick-start.md) +> - 翻譯版本：v0.1.0 +> - 最後更新：2026-01-23 +> - 翻譯者：@username + +--- + +（翻譯內容） +``` + +--- + +## 如何貢獻翻譯 + +### 1. 選擇要翻譯的文件 + +查看 [翻譯進度追蹤](#翻譯進度追蹤) 確認哪些文件需要翻譯。 + +### 2. Fork 專案 + +```bash +git clone https://github.com/YOUR_USERNAME/ConvertX-CN.git +cd ConvertX-CN +``` + +### 3. 建立翻譯檔案 + +```bash +# 例如：翻譯 quick-start.md 為英文 +mkdir -p docs/i18n/en/getting-started +cp docs/getting-started/quick-start.md docs/i18n/en/getting-started/ +``` + +### 4. 進行翻譯 + +編輯檔案，翻譯內容並加上翻譯資訊標頭。 + +### 5. 提交 Pull Request + +```bash +git add . +git commit -m "docs(i18n): add English translation for quick-start.md" +git push origin feature/en-quick-start +``` + +--- + +## 翻譯進度追蹤 + +### English (en) + +| 文件 | 狀態 | 翻譯者 | +| -------------------------------------- | --------- | ------ | +| README.md | 🚧 進行中 | - | +| getting-started/overview.md | ⬜ 未開始 | - | +| getting-started/quick-start.md | ⬜ 未開始 | - | +| getting-started/faq.md | ⬜ 未開始 | - | +| deployment/docker.md | ⬜ 未開始 | - | +| deployment/reverse-proxy.md | ⬜ 未開始 | - | +| configuration/environment-variables.md | ⬜ 未開始 | - | +| configuration/security.md | ⬜ 未開始 | - | +| features/converters.md | ⬜ 未開始 | - | + +**圖例：** ✅ 完成 | 🚧 進行中 | ⬜ 未開始 + +--- + +## 語言切換 + +### 在文件中加入語言切換 + +每個翻譯文件的開頭可以加入語言切換連結： + +```markdown +> 🌐 **Language / 語言** +> [繁體中文](../../README.md) | [English](README.md) | [简体中文](../zh-CN/README.md) +``` + +--- + +## 相關資源 + +- [貢獻指南](../development/contribution.md) +- [GitHub Issues - 翻譯](https://github.com/pi-docket/ConvertX-CN/labels/translation) +- [Discussions - 翻譯討論](https://github.com/pi-docket/ConvertX-CN/discussions/categories/translations) + +--- + +## 致謝 + +感謝所有翻譯貢獻者！ + + diff --git a/docs/i18n/en/README.md b/docs/i18n/en/README.md new file mode 100644 index 0000000..279466e --- /dev/null +++ b/docs/i18n/en/README.md @@ -0,0 +1,95 @@ +# ConvertX-CN Documentation + +> 🌐 **Language / 語言** +> [繁體中文](../../README.md) | **English** | [简体中文](../zh-CN/README.md) + +> 🌐 **Translation Info** +> +> - Original: [繁體中文版](../../README.md) +> - Translation Version: v0.1.0 +> - Last Updated: 2026-01-23 +> - Status: 🚧 In Progress + +--- + +Welcome to ConvertX-CN Documentation! Choose your role to find the information you need. + +--- + +## 🚀 Quick Start + +New to ConvertX-CN? Start here: + +1. **[Overview](getting-started/overview.md)** — What is ConvertX-CN +2. **[Quick Start](getting-started/quick-start.md)** — Deploy in 5 minutes +3. **[FAQ](getting-started/faq.md)** — Common questions + +--- + +## 👤 User Guide + +For general users: + +| Document | Description | +| ---------------------------------------------- | ------------------------------------ | +| [Quick Start](getting-started/quick-start.md) | Fastest deployment method | +| [Supported Converters](features/converters.md) | All available formats | +| [OCR](features/ocr.md) | Optical Character Recognition | +| [Translation](features/translation.md) | PDF translation (preserves formulas) | +| [Languages](features/i18n.md) | Interface language settings | +| [FAQ](getting-started/faq.md) | Frequently Asked Questions | + +--- + +## 🛠️ Administrator Guide + +For deployment and maintenance: + +### Deployment + +| Document | Description | +| -------------------------------------------- | --------------------------- | +| [Docker Deployment](deployment/docker.md) | Docker Run & Docker Compose | +| [Reverse Proxy](deployment/reverse-proxy.md) | Nginx / Traefik / Caddy | +| [Sample Configs](samples/README.md) | Ready-to-use configurations | + +### Configuration + +| Document | Description | +| --------------------------------------------------------------- | --------------------------------- | +| [Environment Variables](configuration/environment-variables.md) | All available settings | +| [Security](configuration/security.md) | HTTPS, authentication, protection | +| [Cleanup & Limits](configuration/limits-and-cleanup.md) | Auto cleanup, resource limits | + +--- + +## 👩‍💻 Developer Guide + +For contributors and extension development: + +### Development + +| Document | Description | +| ----------------------------------------------------- | --------------------- | +| [Project Structure](development/project-structure.md) | Code structure | +| [Local Development](development/local-development.md) | Dev environment setup | +| [Contribution Guide](development/contribution.md) | How to contribute | + +### API + +| Document | Description | +| --------------------------------- | ------------------ | +| [API Overview](api/overview.md) | REST & GraphQL API | +| [API Endpoints](api/endpoints.md) | Endpoint details | + +--- + +## 🔗 Quick Links + +- 📦 [GitHub Repo](https://github.com/pi-docket/ConvertX-CN) +- 🐛 [Issues](https://github.com/pi-docket/ConvertX-CN/issues) +- 💬 [Discussions](https://github.com/pi-docket/ConvertX-CN/discussions) + +--- + +> 💡 **Can't find what you need?** Ask in [GitHub Discussions](https://github.com/pi-docket/ConvertX-CN/discussions)! diff --git a/docs/i18n/en/getting-started/quick-start.md b/docs/i18n/en/getting-started/quick-start.md new file mode 100644 index 0000000..cf0f960 --- /dev/null +++ b/docs/i18n/en/getting-started/quick-start.md @@ -0,0 +1,139 @@ +# Quick Start + +> 🌐 **Language / 語言** +> [繁體中文](../../getting-started/quick-start.md) | **English** | [简体中文](../zh-CN/getting-started/quick-start.md) + +> 🌐 **Translation Info** +> +> - Original: [繁體中文版](../../getting-started/quick-start.md) +> - Translation Version: v0.1.0 +> - Last Updated: 2026-01-23 +> - Status: 🚧 In Progress + +--- + +Deploy ConvertX-CN in 5 minutes. + +--- + +## Prerequisites + +- Docker 20.10+ ([Install Guide](https://docs.docker.com/get-docker/)) +- 4GB+ RAM +- 10GB+ Disk Space + +--- + +## Method 1: Docker Run (Fastest) + +### 1. Create Data Folder + +```bash +# Linux / macOS +mkdir -p ~/convertx-cn/data && cd ~/convertx-cn + +# Windows PowerShell +mkdir C:\convertx-cn\data; cd C:\convertx-cn + +# Windows CMD +mkdir C:\convertx-cn\data +cd C:\convertx-cn +``` + +### 2. Start Container + +```bash +docker run -d \ + --name convertx-cn \ + --restart unless-stopped \ + -p 3000:3000 \ + -v ./data:/app/data \ + -e TZ=Asia/Taipei \ + -e JWT_SECRET=your-random-string-at-least-32-chars \ + convertx/convertx-cn:latest +``` + +### 3. Start Using + +Open browser: `http://localhost:3000` + +1. Click **Register** in the top right corner +2. Enter Email and Password +3. Done! Start converting files + +--- + +## Method 2: Docker Compose (Recommended) + +### 1. Create Project Folder + +```bash +mkdir -p ~/convertx-cn && cd ~/convertx-cn +``` + +### 2. Create Configuration File + +Create `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=please-replace-with-a-long-random-string +``` + +### 3. Start Service + +```bash +docker compose up -d +``` + +--- + +## Verify Installation + +### Check Container Status + +```bash +docker ps +# Should see convertx-cn container running + +docker logs convertx-cn +# Should see "🦊 Elysia is running at http://localhost:3000" +``` + +### Health Check + +```bash +curl http://localhost:3000/healthcheck +# Should return "OK" +``` + +--- + +## Common Startup Issues + +| Issue | Solution | +| ------------------------------- | --------------------------------------------- | +| Port already in use | Use another port, e.g., `-p 8080:3000` | +| Redirected to login after login | Add `HTTP_ALLOWED=true` or `TRUST_PROXY=true` | +| Logged out after restart | Set a fixed `JWT_SECRET` | +| Data lost after restart | Confirm `./data:/app/data` and folder exists | +| Permission error | Run `chmod -R 777 ./data` | + +--- + +## Next Steps + +- 📖 [Docker Configuration](../deployment/docker.md) +- ⚙️ [Environment Variables](../configuration/environment-variables.md) +- 🔒 [Security Settings](../configuration/security.md) +- 🔧 [Reverse Proxy Setup](../deployment/reverse-proxy.md) diff --git a/docs/i18n/ja/README.md b/docs/i18n/ja/README.md new file mode 100644 index 0000000..21ace58 --- /dev/null +++ b/docs/i18n/ja/README.md @@ -0,0 +1,95 @@ +# ConvertX-CN ドキュメント + +> 🌐 **Language / 語言** +> [繁體中文](../../README.md) | [English](../en/README.md) | [简体中文](../zh-CN/README.md) | **日本語** + +> 🌐 **翻訳情報** +> +> - 原文：[繁體中文版](../../README.md) +> - 翻訳バージョン：v0.1.0 +> - 最終更新：2026-01-23 +> - ステータス：📋 計画中 + +--- + +ConvertX-CN ドキュメントへようこそ！役割を選択して必要な情報を見つけてください。 + +--- + +## 🚀 クイックスタート + +初めての方はこちらから： + +1. **[概要](getting-started/overview.md)** — ConvertX-CN とは +2. **[クイックスタート](getting-started/quick-start.md)** — 5分でデプロイ +3. **[FAQ](getting-started/faq.md)** — よくある質問 + +--- + +## 👤 ユーザーガイド + +一般ユーザー向け： + +| ドキュメント | 説明 | +| -------------------------------------------------- | ------------------- | +| [クイックスタート](getting-started/quick-start.md) | 最速デプロイ方法 | +| [対応コンバーター](features/converters.md) | 利用可能な変換形式 | +| [OCR機能](features/ocr.md) | 光学文字認識 | +| [翻訳機能](features/translation.md) | PDF翻訳（数式保持） | +| [多言語インターフェース](features/i18n.md) | 言語設定 | +| [FAQ](getting-started/faq.md) | よくある質問 | + +--- + +## 🛠️ 管理者ガイド + +デプロイと運用担当者向け： + +### デプロイ + +| ドキュメント | 説明 | +| ----------------------------------------------- | --------------------------- | +| [Dockerデプロイ](deployment/docker.md) | Docker Run & Docker Compose | +| [リバースプロキシ](deployment/reverse-proxy.md) | Nginx / Traefik / Caddy | +| [設定サンプル](samples/README.md) | すぐ使える設定ファイル | + +### 設定 + +| ドキュメント | 説明 | +| ----------------------------------------------------------- | ---------------------- | +| [環境変数](configuration/environment-variables.md) | 全設定項目 | +| [セキュリティ](configuration/security.md) | HTTPS、認証、保護 | +| [クリーンアップと制限](configuration/limits-and-cleanup.md) | 自動削除、リソース制限 | + +--- + +## 👩‍💻 開発者ガイド + +コントリビューターと拡張開発向け： + +### 開発 + +| ドキュメント | 説明 | +| --------------------------------------------------------- | ------------ | +| [プロジェクト構造](development/project-structure.md) | コード構造 | +| [ローカル開発](development/local-development.md) | 開発環境設定 | +| [コントリビューションガイド](development/contribution.md) | 貢献方法 | + +### API + +| ドキュメント | 説明 | +| ------------------------------------- | ------------------ | +| [API概要](api/overview.md) | REST & GraphQL API | +| [APIエンドポイント](api/endpoints.md) | エンドポイント詳細 | + +--- + +## 🔗 クイックリンク + +- 📦 [GitHub Repo](https://github.com/pi-docket/ConvertX-CN) +- 🐛 [Issues](https://github.com/pi-docket/ConvertX-CN/issues) +- 💬 [Discussions](https://github.com/pi-docket/ConvertX-CN/discussions) + +--- + +> 💡 **必要な情報が見つかりませんか？** [GitHub Discussions](https://github.com/pi-docket/ConvertX-CN/discussions) で質問してください！ diff --git a/docs/i18n/zh-CN/README.md b/docs/i18n/zh-CN/README.md new file mode 100644 index 0000000..46b4d65 --- /dev/null +++ b/docs/i18n/zh-CN/README.md @@ -0,0 +1,95 @@ +# ConvertX-CN 文档中心 + +> 🌐 **Language / 語言** +> [繁體中文](../../README.md) | [English](../en/README.md) | **简体中文** + +> 🌐 **翻译信息** +> +> - 原文：[繁體中文版](../../README.md) +> - 翻译版本：v0.1.0 +> - 最后更新：2026-01-23 +> - 状态：📋 计划中 + +--- + +欢迎来到 ConvertX-CN 文档！选择您的角色快速找到所需信息。 + +--- + +## 🚀 快速入门 + +刚开始使用？从这里开始： + +1. **[概览](getting-started/overview.md)** — 了解 ConvertX-CN 是什么 +2. **[快速开始](getting-started/quick-start.md)** — 5 分钟内完成部署 +3. **[常见问题](getting-started/faq.md)** — 解决常见问题 + +--- + +## 👤 用户指南 + +适合一般用户： + +| 文档 | 说明 | +| ------------------------------------------ | -------------------- | +| [快速开始](getting-started/quick-start.md) | 最快部署方式 | +| [支持的转换器](features/converters.md) | 所有可用的转换格式 | +| [OCR 功能](features/ocr.md) | 光学字符识别 | +| [翻译功能](features/translation.md) | PDF 翻译（保留公式） | +| [多语言界面](features/i18n.md) | 切换界面语言 | +| [常见问题](getting-started/faq.md) | FAQ | + +--- + +## 🛠️ 系统管理员指南 + +适合部署与维护人员： + +### 部署 + +| 文档 | 说明 | +| --------------------------------------- | --------------------------- | +| [Docker 部署](deployment/docker.md) | Docker Run & Docker Compose | +| [反向代理](deployment/reverse-proxy.md) | Nginx / Traefik / Caddy | +| [示例配置](samples/README.md) | 可直接使用的配置文件 | + +### 配置 + +| 文档 | 说明 | +| -------------------------------------------------- | ------------------ | +| [环境变量](configuration/environment-variables.md) | 所有可用设置 | +| [安全性设置](configuration/security.md) | HTTPS、认证、防护 | +| [清理与限制](configuration/limits-and-cleanup.md) | 自动清理、资源限制 | + +--- + +## 👩‍💻 开发者指南 + +适合贡献者与扩展开发： + +### 开发 + +| 文档 | 说明 | +| -------------------------------------------- | ------------ | +| [项目结构](development/project-structure.md) | 代码结构说明 | +| [本地开发](development/local-development.md) | 开发环境设置 | +| [贡献指南](development/contribution.md) | 如何参与项目 | + +### API + +| 文档 | 说明 | +| ---------------------------- | ------------------ | +| [API 概览](api/overview.md) | REST & GraphQL API | +| [API 端点](api/endpoints.md) | 详细端点说明 | + +--- + +## 🔗 快速链接 + +- 📦 [GitHub Repo](https://github.com/pi-docket/ConvertX-CN) +- 🐛 [Issues](https://github.com/pi-docket/ConvertX-CN/issues) +- 💬 [Discussions](https://github.com/pi-docket/ConvertX-CN/discussions) + +--- + +> 💡 **找不到您需要的信息？** 欢迎到 [GitHub Discussions](https://github.com/pi-docket/ConvertX-CN/discussions) 发问！ diff --git a/docs/samples/README.md b/docs/samples/README.md new file mode 100644 index 0000000..0acb7a1 --- /dev/null +++ b/docs/samples/README.md @@ -0,0 +1,54 @@ +# Docker Compose 範例與配置 + +本目錄提供各種場景的 Docker Compose 範例配置。 + +--- + +## 範例檔案 + +| 檔案 | 用途 | 說明 | +| -------------------------- | ---------- | ---------------- | +| `compose.minimal.yml` | 快速啟動 | 最精簡配置 | +| `compose.production.yml` | 生產環境 | 包含安全設定 | +| `compose.with-traefik.yml` | 反向代理 | Traefik 整合 | +| `nginx.example.conf` | Nginx 設定 | 反向代理設定範例 | + +--- + +## 如何使用 + +### 1. 下載範例 + +```bash +# 下載最小配置 +curl -O https://raw.githubusercontent.com/pi-docket/ConvertX-CN/main/docs/samples/compose.minimal.yml + +# 重命名 +mv compose.minimal.yml docker-compose.yml +``` + +### 2. 修改設定 + +```bash +# 編輯配置 +nano docker-compose.yml + +# 重點修改： +# - JWT_SECRET +# - TZ +``` + +### 3. 啟動 + +```bash +mkdir -p data +docker compose up -d +``` + +--- + +## 相關文件 + +- [Docker 部署](../deployment/docker.md) +- [環境變數](../configuration/environment-variables.md) +- [反向代理](../deployment/reverse-proxy.md) diff --git a/docs/samples/compose.minimal.yml b/docs/samples/compose.minimal.yml new file mode 100644 index 0000000..b5d01d5 --- /dev/null +++ b/docs/samples/compose.minimal.yml @@ -0,0 +1,15 @@ +# ConvertX-CN 最小配置 +# 適用於：快速測試、個人使用 + +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字元 diff --git a/docs/samples/compose.production.yml b/docs/samples/compose.production.yml new file mode 100644 index 0000000..cafc0e2 --- /dev/null +++ b/docs/samples/compose.production.yml @@ -0,0 +1,46 @@ +# ConvertX-CN 生產環境配置 +# 適用於：正式部署 + +services: + convertx: + image: convertx/convertx-cn:latest + container_name: convertx-cn + restart: unless-stopped + ports: + - "127.0.0.1:3000:3000" # 只允許本機存取，透過反向代理對外 + volumes: + - ./data:/app/data + environment: + # 必填：登入驗證金鑰（至少 32 字元） + - JWT_SECRET=${JWT_SECRET:?請設定 JWT_SECRET} + + # 時區 + - TZ=Asia/Taipei + + # 安全性設定 + - HTTP_ALLOWED=false # 禁止 HTTP（使用 HTTPS） + - TRUST_PROXY=true # 信任反向代理 + - ACCOUNT_REGISTRATION=false # 關閉公開註冊 + + # 清理設定 + - AUTO_DELETE_EVERY_N_HOURS=24 + + deploy: + resources: + limits: + memory: 4G + reservations: + memory: 2G + + healthcheck: + test: ["CMD", "curl", "-f", "http://localhost:3000/healthcheck"] + interval: 30s + timeout: 10s + retries: 3 + start_period: 60s + + logging: + driver: json-file + options: + max-size: "10m" + max-file: "3" diff --git a/docs/samples/compose.with-traefik.yml b/docs/samples/compose.with-traefik.yml new file mode 100644 index 0000000..49677b8 --- /dev/null +++ b/docs/samples/compose.with-traefik.yml @@ -0,0 +1,37 @@ +# ConvertX-CN + Traefik 配置 +# 適用於：使用 Traefik 作為反向代理 + +services: + convertx: + image: convertx/convertx-cn:latest + container_name: convertx-cn + restart: unless-stopped + volumes: + - ./data:/app/data + environment: + - JWT_SECRET=${JWT_SECRET:?請設定 JWT_SECRET} + - TZ=Asia/Taipei + - HTTP_ALLOWED=false + - TRUST_PROXY=true + - ACCOUNT_REGISTRATION=false + labels: + - "traefik.enable=true" + # HTTP 路由 + - "traefik.http.routers.convertx.rule=Host(`convertx.example.com`)" + - "traefik.http.routers.convertx.entrypoints=web" + - "traefik.http.routers.convertx.middlewares=https-redirect" + # HTTPS 路由 + - "traefik.http.routers.convertx-secure.rule=Host(`convertx.example.com`)" + - "traefik.http.routers.convertx-secure.entrypoints=websecure" + - "traefik.http.routers.convertx-secure.tls=true" + - "traefik.http.routers.convertx-secure.tls.certresolver=letsencrypt" + # 服務 + - "traefik.http.services.convertx.loadbalancer.server.port=3000" + # 中間件 + - "traefik.http.middlewares.https-redirect.redirectscheme.scheme=https" + networks: + - traefik-network + +networks: + traefik-network: + external: true diff --git a/docs/samples/nginx.example.conf b/docs/samples/nginx.example.conf new file mode 100644 index 0000000..2c9306c --- /dev/null +++ b/docs/samples/nginx.example.conf @@ -0,0 +1,71 @@ +# ConvertX-CN Nginx 反向代理配置範例 +# 檔案位置：/etc/nginx/sites-available/convertx + +# HTTP → HTTPS 重導向 +server { + listen 80; + listen [::]:80; + server_name convertx.example.com; + + # Let's Encrypt 驗證 + location /.well-known/acme-challenge/ { + root /var/www/certbot; + } + + # 重導向到 HTTPS + location / { + return 301 https://$server_name$request_uri; + } +} + +# HTTPS 伺服器 +server { + listen 443 ssl http2; + 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:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384; + ssl_session_cache shared:SSL:10m; + ssl_session_timeout 10m; + + # 安全 Headers + add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always; + add_header X-Content-Type-Options nosniff; + add_header X-Frame-Options DENY; + add_header X-XSS-Protection "1; mode=block"; + + # 檔案上傳大小限制（依需求調整） + client_max_body_size 500M; + + # 上傳超時設定（大檔案需要） + proxy_connect_timeout 300s; + proxy_send_timeout 300s; + proxy_read_timeout 300s; + + # 主要位置 + 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"; + + # 緩衝設定 + proxy_buffering off; + proxy_request_buffering off; + } +} diff --git a/docs/testing/ci-cd.md b/docs/testing/ci-cd.md new file mode 100644 index 0000000..a36529b --- /dev/null +++ b/docs/testing/ci-cd.md @@ -0,0 +1,148 @@ +# CI/CD + +本文件說明 ConvertX-CN 的持續整合與持續部署設定。 + +--- + +## GitHub Actions + +### 測試工作流 + +每次 Push 和 Pull Request 自動執行： + +```yaml +# .github/workflows/test.yml +name: Test + +on: + push: + branches: [main] + pull_request: + branches: [main] + +jobs: + test: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + + - name: Setup Bun + uses: oven-sh/setup-bun@v1 + + - name: Install dependencies + run: bun install + + - name: Run lint + run: bun run lint + + - name: Run tests + run: bun run test +``` + +### Docker 建構工作流 + +標籤推送時自動建構並發布 Docker 映像： + +```yaml +# .github/workflows/docker.yml +name: Docker Build + +on: + push: + tags: + - "v*" + +jobs: + build: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + + - name: Login to Docker Hub + uses: docker/login-action@v3 + with: + username: ${{ secrets.DOCKER_USERNAME }} + password: ${{ secrets.DOCKER_TOKEN }} + + - name: Build and push + uses: docker/build-push-action@v5 + with: + push: true + tags: | + convertx/convertx-cn:latest + convertx/convertx-cn:${{ github.ref_name }} +``` + +--- + +## 工作流程 + +### 開發流程 + +``` +1. 開發者提交 PR + ↓ +2. 自動執行測試 + ↓ +3. 通過 Review + ↓ +4. 合併到 main +``` + +### 發布流程 + +``` +1. 建立版本標籤 (v0.1.x) + ↓ +2. 自動建構 Docker 映像 + ↓ +3. 推送到 Docker Hub + ↓ +4. 更新 latest 標籤 +``` + +--- + +## 環境變數 + +### 測試環境 + +| 變數 | 說明 | +| ---------- | ----------- | +| `CI` | CI 環境標記 | +| `NODE_ENV` | `test` | + +### Docker 建構 + +| 變數 | 說明 | +| ----------------- | ---------------- | +| `DOCKER_USERNAME` | Docker Hub 帳號 | +| `DOCKER_TOKEN` | Docker Hub Token | + +--- + +## 本地模擬 CI + +### 執行完整檢查 + +```bash +# 模擬 CI 流程 +bun run lint +bun run typecheck +bun run test +bun run build +``` + +### 建構 Docker 映像 + +```bash +docker build -t convertx-cn-test . +``` + +--- + +## 相關文件 + +- [測試策略](test-strategy.md) +- [E2E 測試](e2e-tests.md) +- [貢獻指南](../development/contribution.md) diff --git a/docs/testing/e2e-tests.md b/docs/testing/e2e-tests.md new file mode 100644 index 0000000..4db7b68 --- /dev/null +++ b/docs/testing/e2e-tests.md @@ -0,0 +1,181 @@ +# E2E 測試 + +本文件說明如何執行與撰寫 ConvertX-CN 的端對端測試。 + +--- + +## 概述 + +E2E 測試模擬真實使用者操作，驗證完整的使用流程。 + +### 測試範圍 + +- ✅ 檔案上傳 +- ✅ 格式轉換 +- ✅ 檔案下載 +- ✅ 使用者認證 +- ✅ 歷史記錄 + +--- + +## 執行測試 + +### 前置條件 + +1. 啟動 ConvertX-CN 服務 +2. 確保 Docker 可用 + +### 執行命令 + +```bash +# 執行所有 E2E 測試 +bun run test:e2e + +# 使用腳本 +./scripts/run-e2e-tests.sh + +# 指定測試檔案 +bun run test:e2e tests/e2e/upload.test.ts +``` + +### 使用 Docker + +```bash +# 啟動測試環境 +docker compose -f compose.test.yml up -d + +# 執行測試 +bun run test:e2e + +# 清理 +docker compose -f compose.test.yml down +``` + +--- + +## 測試結構 + +``` +tests/e2e/ +├── upload.test.ts # 上傳測試 +├── convert.test.ts # 轉換測試 +├── download.test.ts # 下載測試 +├── auth.test.ts # 認證測試 +└── fixtures/ # 測試資料 + ├── sample.docx + ├── sample.pdf + └── sample.png +``` + +--- + +## 撰寫測試 + +### 基本範例 + +```typescript +// tests/e2e/upload.test.ts +import { test, expect } from "@playwright/test"; + +test.describe("File Upload", () => { + test.beforeEach(async ({ page }) => { + await page.goto("/"); + }); + + test("should upload a file", async ({ page }) => { + // 選擇檔案 + const fileInput = page.locator('input[type="file"]'); + await fileInput.setInputFiles("tests/e2e/fixtures/sample.docx"); + + // 驗證檔案名稱顯示 + await expect(page.locator(".file-name")).toContainText("sample.docx"); + }); +}); +``` + +### 轉換測試 + +```typescript +// tests/e2e/convert.test.ts +test("should convert docx to pdf", async ({ page }) => { + // 上傳檔案 + await page.setInputFiles('input[type="file"]', "tests/e2e/fixtures/sample.docx"); + + // 選擇目標格式 + await page.selectOption("#output-format", "pdf"); + + // 點擊轉換 + await page.click("#convert-button"); + + // 等待完成 + await expect(page.locator(".status")).toContainText("完成", { timeout: 60000 }); +}); +``` + +### 認證測試 + +```typescript +// tests/e2e/auth.test.ts +test("should login successfully", async ({ page }) => { + await page.goto("/login"); + + await page.fill("#email", "test@example.com"); + await page.fill("#password", "password123"); + await page.click("#login-button"); + + await expect(page).toHaveURL("/"); + await expect(page.locator(".user-menu")).toBeVisible(); +}); +``` + +--- + +## 設定 + +### Playwright 設定 + +```typescript +// playwright.config.ts +import { defineConfig } from "@playwright/test"; + +export default defineConfig({ + testDir: "./tests/e2e", + timeout: 60000, + use: { + baseURL: "http://localhost:3000", + screenshot: "only-on-failure", + video: "retain-on-failure", + }, +}); +``` + +--- + +## 除錯 + +### 互動模式 + +```bash +bun run test:e2e --debug +``` + +### 檢視報告 + +```bash +bun run test:e2e --reporter=html +npx playwright show-report +``` + +### 錄製測試 + +```bash +npx playwright codegen http://localhost:3000 +``` + +--- + +## 相關文件 + +- [測試策略](test-strategy.md) +- [CI/CD](ci-cd.md) +- [本地開發](../development/local-development.md) diff --git a/docs/testing/test-strategy.md b/docs/testing/test-strategy.md new file mode 100644 index 0000000..dc6fc4e --- /dev/null +++ b/docs/testing/test-strategy.md @@ -0,0 +1,211 @@ +# 測試策略 + +本文件說明 ConvertX-CN 的測試策略與方法。 + +--- + +## 測試類型 + +### 單元測試 + +測試獨立的函數與模組。 + +**涵蓋範圍：** + +- 轉換器邏輯 +- 工具函數 +- 資料處理 + +### 整合測試 + +測試模組之間的協作。 + +**涵蓋範圍：** + +- API 端點 +- 資料庫操作 +- 檔案處理 + +### E2E 測試 + +模擬使用者操作的完整流程測試。 + +**涵蓋範圍：** + +- 上傳檔案 +- 轉換流程 +- 下載結果 + +--- + +## 執行測試 + +### 前端測試 + +```bash +# 執行所有測試 +bun run test + +# 監視模式 +bun run test:watch + +# 覆蓋率報告 +bun run test:coverage +``` + +### API Server 測試（Rust） + +```bash +cd api-server + +# 執行所有測試 +cargo test + +# 詳細輸出 +cargo test -- --nocapture +``` + +### E2E 測試 + +```bash +# 執行 E2E 測試 +bun run test:e2e + +# 或使用腳本 +./scripts/run-e2e-tests.sh +``` + +--- + +## 測試結構 + +``` +tests/ +├── converters/ # 轉換器測試 +├── e2e/ # 端對端測試 +└── transfer/ # 傳輸模組測試 + +api-server/tests/ +├── api_tests.rs # REST API 測試 +├── graphql_tests.rs # GraphQL 測試 +└── integration_tests.rs # 整合測試 +``` + +--- + +## 測試範例 + +### 前端單元測試 + +```typescript +// tests/converters/ffmpeg.test.ts +import { describe, it, expect } from "bun:test"; +import { ffmpegConverter } from "../../src/converters/ffmpeg"; + +describe("FFmpeg Converter", () => { + it("should support mp4 input", () => { + expect(ffmpegConverter.inputFormats).toContain("mp4"); + }); + + it("should support webm output", () => { + expect(ffmpegConverter.outputFormats).toContain("webm"); + }); +}); +``` + +### API 整合測試 + +```rust +// api-server/tests/api_tests.rs +#[tokio::test] +async fn test_health_endpoint() { + let response = client.get("/health").send().await.unwrap(); + assert_eq!(response.status(), StatusCode::OK); +} +``` + +### E2E 測試 + +```typescript +// tests/e2e/upload.test.ts +import { test, expect } from "@playwright/test"; + +test("should upload and convert file", async ({ page }) => { + await page.goto("/"); + + // 上傳檔案 + await page.setInputFiles("#file-input", "test.docx"); + + // 選擇格式 + await page.selectOption("#format", "pdf"); + + // 點擊轉換 + await page.click("#convert-button"); + + // 驗證結果 + await expect(page.locator(".download-link")).toBeVisible(); +}); +``` + +--- + +## 測試資料 + +### 測試檔案 + +放置在 `tests/fixtures/` 目錄： + +``` +tests/fixtures/ +├── documents/ +│ ├── sample.docx +│ ├── sample.pdf +│ └── sample.txt +├── images/ +│ ├── sample.png +│ └── sample.jpg +└── audio/ + └── sample.mp3 +``` + +### Mock 資料 + +使用 Mock 避免依賴外部服務： + +```typescript +import { mock } from "bun:test"; + +const mockConverter = mock(() => ({ + convert: async () => "output.pdf", +})); +``` + +--- + +## 持續整合 + +### GitHub Actions + +```yaml +# .github/workflows/test.yml +name: Test + +on: [push, pull_request] + +jobs: + test: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: oven-sh/setup-bun@v1 + - run: bun install + - run: bun run test +``` + +--- + +## 相關文件 + +- [CI/CD](ci-cd.md) +- [E2E 測試](e2e-tests.md) +- [本地開發](../development/local-development.md) diff --git a/docs/url-id-and-storage.md b/docs/url-id-and-storage.md index 51b4086..bec1322 100644 --- a/docs/url-id-and-storage.md +++ b/docs/url-id-and-storage.md @@ -1,5 +1,16 @@ # URL ID 與儲存機制 +> ⚠️ **此文件已遷移** +> +> 本文件內容已整合至新的文件結構，請參閱： +> +> - 🛠️ [專案結構](development/project-structure.md) +> - 🐳 [Docker 部署](deployment/docker.md) +> +> 此文件將在未來版本中移除。 + +--- + ## 檔案儲存結構 ConvertX-CN 使用以下目錄結構儲存檔案：