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

feat(i18n): add multilingual support with translations for English, Japanese, and Simplified Chinese

Browse source 
- Create README.md for internationalization (i18n) documentation
- Add English translation for main README and quick start guide
- Add Japanese translation for main README
- Add Simplified Chinese translation for main README
- Introduce sample Docker Compose configurations for various deployment scenarios
- Implement CI/CD documentation for testing and deployment workflows
- Establish end-to-end testing guidelines and strategies
- Create test strategy documentation outlining unit, integration, and E2E tests
This commit is contained in:
Your Name 2026-01-23 14:32:27 +08:00
parent b3b382d1e0
commit da856d89ff
42 changed files with 4901 additions and 263 deletions
Download patch file Download diff file Expand all files Collapse all files

172
docs/README.md Normal file
View file

@ -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) 發問！

11
docs/advanced-usage.md
View file

@ -1,5 +1,16 @@
# 進階用法
> ⚠️ **此文件已遷移**
>
> 本文件內容已整合至新的文件結構，請參閱：
>
> - 🐳 [Docker 部署（含硬體加速）](deployment/docker.md)
> - 🔧 [反向代理設定](deployment/reverse-proxy.md)
>
> 此文件將在未來版本中移除。
---
## 硬體加速
### NVIDIA GPU (CUDA/NVENC)

261
docs/api/endpoints.md Normal file
View file

@ -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 <token>
```
**回應**
```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 <token>
Content-Type: multipart/form-data
```
**參數**
| 參數 | 類型 | 必填 | 說明 |
| ------------- | ------ | ---- | ------------ |
| file | file | ✓ | 要轉換的檔案 |
| engine | string | ✓ | 轉換引擎 ID |
| output_format | string | ✓ | 目標格式 |
**範例**
```bash
curl -X POST \
-H "Authorization: Bearer <token>" \
-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)

128
docs/api/overview.md Normal file
View file

@ -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 <your-jwt-token>
```
### 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 <token>" \
http://localhost:3001/api/v1/engines
```
### 轉換檔案
```bash
curl -X POST \
-H "Authorization: Bearer <token>" \
-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)

12
docs/config/environment.md
View file

@ -1,5 +1,17 @@
# 環境變數完整說明
> ⚠️ **此文件已遷移**
>
> 本文件內容已整合至新的文件結構，請參閱：
>
> - ⚙️ [環境變數設定](../configuration/environment-variables.md)
> - 🔒 [安全性設定](../configuration/security.md)
> - 🧹 [清理與限制](../configuration/limits-and-cleanup.md)
>
> 此文件將在未來版本中移除。
---
本文件列出 ConvertX-CN 所有可用的環境變數設定。
---

10
docs/config/security.md
View file

@ -1,5 +1,15 @@
# 安全性設定
> ⚠️ **此文件已遷移**
>
> 本文件內容已整合至新的文件結構，請參閱：
>
> - 🔒 [安全性設定](../configuration/security.md)
>
> 此文件將在未來版本中移除。
---
本文件說明 ConvertX-CN 的安全性相關設定與最佳實踐。
---

271
docs/configuration/environment-variables.md Normal file
View file

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

196
docs/configuration/limits-and-cleanup.md Normal file
View file

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

219
docs/configuration/security.md Normal file
View file

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

12
docs/converters.md
View file

@ -1,5 +1,17 @@
# 支援的轉換器
> ⚠️ **此文件已遷移**
>
> 本文件內容已整合至新的文件結構，請參閱：
>
> - 🔌 [轉換器完整說明](features/converters.md)
> - 📊 [OCR 功能](features/ocr.md)
> - 🌐 [翻譯功能](features/translation.md)
>
> 此文件將在未來版本中移除。
---
ConvertX-CN 完整版已內建以下所有轉換器，開箱即用。
## 轉換器列表

12
docs/deployment.md
View file

@ -1,5 +1,17 @@
# 進階部署指南
> ⚠️ **此文件已遷移**
>
> 本文件內容已整合至新的文件結構，請參閱：
>
> - 🐳 [Docker 部署](deployment/docker.md)
> - 🔧 [反向代理設定](deployment/reverse-proxy.md)
> - 🔒 [安全性設定](configuration/security.md)
>
> 此文件將在未來版本中移除。
---
本文件說明如何在生產環境中部署 ConvertX-CN，包括 Reverse Proxy、HTTPS、安全性設定等。
---

255
docs/deployment/docker.md Normal file
View file

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

287
docs/deployment/reverse-proxy.md Normal file
View file

@ -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: <tunnel-id>
credentials-file: ~/.cloudflared/<tunnel-id>.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)

192
docs/development/contribution.md Normal file
View file

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

207
docs/development/local-development.md Normal file
View file

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

179
docs/development/project-structure.md Normal file
View file

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

11
docs/docker.md
View file

@ -1,5 +1,16 @@
# Docker 配置指南
> ⚠️ **此文件已遷移**
>
> 本文件內容已整合至新的文件結構，請參閱：
>
> - 📦 [Docker 部署指南](deployment/docker.md)
> - 🔧 [反向代理設定](deployment/reverse-proxy.md)
>
> 此文件將在未來版本中移除。
---
## Docker Image 版本說明
ConvertX-CN 提供兩種 Docker Image 選項：

10
docs/faq.md
View file

@ -1,5 +1,15 @@
# 常見問題 FAQ
> ⚠️ **此文件已遷移**
>
> 本文件內容已整合至新的文件結構，請參閱：
>
> - ❓ [常見問題 FAQ](getting-started/faq.md)
>
> 此文件將在未來版本中移除。
---
## 🔐 登入與帳號
### Q: 如何註冊帳號？

223
docs/features/converters.md Normal file
View file

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

132
docs/features/i18n.md Normal file
View file

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

117
docs/features/ocr.md Normal file
View file

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

118
docs/features/translation.md Normal file
View file

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

12
docs/getting-started.md
View file

@ -1,5 +1,17 @@
# 快速開始
> ⚠️ **此文件已遷移**
>
> 本文件內容已整合至新的文件結構，請參閱：
>
> - 📖 [概覽](getting-started/overview.md)
> - 🚀 [快速開始](getting-started/quick-start.md)
> - ❓ [常見問題](getting-started/faq.md)
>
> 此文件將在未來版本中移除。
---
> 本文件提供完整部署步驟。若只需最快啟動，請參考 [README](../README.md)。
---

192
docs/getting-started/faq.md Normal file
View file

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

83
docs/getting-started/overview.md Normal file
View file

@ -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) — 詳細部署指南

144
docs/getting-started/quick-start.md Normal file
View file

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

10
docs/i18n.md
View file

@ -1,5 +1,15 @@
# 多語言支援（i18n）
> ⚠️ **此文件已遷移**
>
> 本文件內容已整合至新的文件結構，請參閱：
>
> - 🌐 [多語言介面支援](features/i18n.md)
>
> 此文件將在未來版本中移除。
---
ConvertX-CN 支援 **65 種語言**，是目前最完整的多語言檔案轉換服務。
---

164
docs/i18n/README.md Normal file
View file

@ -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)
---
## 致謝
感謝所有翻譯貢獻者！
<!-- 翻譯貢獻者名單將在此更新 -->

95
docs/i18n/en/README.md Normal file
View file

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

139
docs/i18n/en/getting-started/quick-start.md Normal file
View file

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

95
docs/i18n/ja/README.md Normal file
View file

@ -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) で質問してください！

95
docs/i18n/zh-CN/README.md Normal file
View file

@ -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) 发问！

54
docs/samples/README.md Normal file
View file

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

15
docs/samples/compose.minimal.yml Normal file
View file

@ -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字元

46
docs/samples/compose.production.yml Normal file
View file

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

37
docs/samples/compose.with-traefik.yml Normal file
View file

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

71
docs/samples/nginx.example.conf Normal file
View file

@ -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;
}
}

148
docs/testing/ci-cd.md Normal file
View file

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

181
docs/testing/e2e-tests.md Normal file
View file

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

211
docs/testing/test-strategy.md Normal file
View file

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

11
docs/url-id-and-storage.md
View file

@ -1,5 +1,16 @@
# URL ID 與儲存機制
> ⚠️ **此文件已遷移**
>
> 本文件內容已整合至新的文件結構，請參閱：
>
> - 🛠️ [專案結構](development/project-structure.md)
> - 🐳 [Docker 部署](deployment/docker.md)
>
> 此文件將在未來版本中移除。
---
## 檔案儲存結構
ConvertX-CN 使用以下目錄結構儲存檔案：