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

Refactor documentation structure: migrate and consolidate multiple files into new organization, update links and references for clarity and accessibility.

Browse source
This commit is contained in:
Your Name 2026-01-23 22:24:26 +08:00
parent 034cc44c25
commit 5a2aac1a66
10 changed files with 5 additions and 1864 deletions
Download patch file Download diff file Expand all files Collapse all files

6
docs/Docker組合配置/README.md
View file

@ -58,6 +58,6 @@ docker compose up -d
## 相關文件
- [環境變數完整說明](../環境變數總覽.md)
- [進階部署指南](../部署總覽.md)
- [Docker 進階配置](../Docker說明.md)
- [環境變數完整說明](../配置設定/環境變數.md)
- [Docker 部署指南](../部署指南/Docker部署.md)
- [反向代理設定](../部署指南/反向代理.md)

296
docs/Docker說明.md
View file

@ -1,296 +0,0 @@
# Docker 配置指南
> ⚠️ **此文件已遷移**
>
> 本文件內容已整合至新的文件結構，請參閱：
>
> - 📦 [Docker 部署指南](部署指南/Docker部署.md)
> - 🔧 [反向代理設定](部署指南/反向代理.md)
>
> 此文件將在未來版本中移除。
---
## Docker Image 版本說明
ConvertX-CN 提供兩種 Docker Image 選項：
### 1. 官方 Image（推薦）
從 Docker Hub 拉取的預建 Image，適合大多數使用者。
| Tag | 說明 |
| ----------------------------- | ---------- |
| `convertx/convertx-cn:latest` | 最新穩定版 |
| `convertx/convertx-cn:v0.1.9` | 指定版本號 |
**內建功能：**
- ✅ 核心轉換工具（FFmpeg、LibreOffice、ImageMagick 等）
- ✅ OCR 支援：英文、繁/簡中文、日文、韓文、德文、法文
- ✅ 字型：Noto CJK、Liberation、自訂中文字型
- ✅ TexLive 最小集合（支援 CJK/德/法）
**Image 大小：約 4-6 GB**
### 2. 完整版（自行 Build）
使用 `Dockerfile.full` 自行建構，適合需要：
- 65 種 OCR 語言
- 完整 TexLive
- 額外字型套件
**⚠️ 注意事項：**
- Image 大小可能超過 **10GB**
- Build 時間約 **30-60 分鐘**
- 需要自行維護更新
```bash
# 自行建構完整版
docker build -f Dockerfile.full -t convertx-cn-full .
```
---
## 自訂 Build 指南（進階使用者）
如果官方 Image 不符合需求，可以使用 `Dockerfile.full` 自行建構：
### 步驟
1. **複製 Dockerfile.full**
```bash
cp Dockerfile.full Dockerfile.custom
```
2. **取消註解需要的功能**
- 編輯 `Dockerfile.custom`
- 找到需要的功能區塊
- 移除 `#` 註解符號
3. **建構 Image**
```bash
docker build -f Dockerfile.custom -t convertx-cn-custom .
```
### 可選功能
| 功能 | 預估大小 | 說明 |
| --------------- | -------- | ---------------- |
| 完整 TexLive | +3GB | 完整 LaTeX 支援 |
| 全部 OCR 語言 | +2GB | 65 種語言辨識 |
| Noto Extra 字型 | +500MB | 全球語言字型 |
| 歐洲 OCR 語言 | +200MB | 25 種歐洲語言 |
| 中東/南亞 OCR | +150MB | 阿拉伯、印度語系 |
| 東南亞 OCR | +100MB | 泰、越、印尼等 |
### 範例：僅加入西班牙文 OCR
```dockerfile
# 在 Dockerfile.full 中取消以下註解：
RUN apt-get update && apt-get install -y --no-install-recommends \
tesseract-ocr-spa \
&& rm -rf /var/lib/apt/lists/*
```
---
## Docker Run
基本啟動命令：
```bash
docker run -d \
--name convertx-cn \
-p 3000:3000 \
-v ./data:/app/data \
-e TZ=Asia/Taipei \
-e ACCOUNT_REGISTRATION=true \
convertx/convertx-cn:latest
```
### 參數說明
| 參數 | 說明 |
| --------------------- | ---------- |
| `-d` | 背景執行 |
| `--name convertx-cn` | 容器名稱 |
| `-p 3000:3000` | 連接埠映射 |
| `-v ./data:/app/data` | 資料持久化 |
| `-e TZ=Asia/Taipei` | 時區設定 |
---
## Docker Compose
### 基本配置
```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=your-very-long-random-secret-key
- ACCOUNT_REGISTRATION=true
```
### 生產環境配置
```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=${JWT_SECRET}
- ACCOUNT_REGISTRATION=false
- HTTP_ALLOWED=false
- AUTO_DELETE_EVERY_N_HOURS=24
deploy:
resources:
limits:
memory: 4G
reservations:
memory: 2G
```
### 使用 Traefik 反向代理
```yaml
services:
convertx:
image: convertx/convertx-cn:latest
container_name: convertx-cn
restart: unless-stopped
volumes:
- ./data:/app/data
environment:
- TZ=Asia/Taipei
- JWT_SECRET=${JWT_SECRET}
- ACCOUNT_REGISTRATION=false
labels:
- "traefik.enable=true"
- "traefik.http.routers.convertx.rule=Host(`convert.example.com`)"
- "traefik.http.routers.convertx.entrypoints=websecure"
- "traefik.http.routers.convertx.tls.certresolver=letsencrypt"
- "traefik.http.services.convertx.loadbalancer.server.port=3000"
networks:
- traefik
networks:
traefik:
external: true
```
---
## 資料持久化
### Volume 結構
```
./data/
├── uploads/ # 上傳的原始檔案
├── output/ # 轉換後的檔案
└── convertx.db # SQLite 資料庫
```
### 備份
```bash
# 備份資料
docker cp convertx-cn:/app/data ./backup-$(date +%Y%m%d)
# 還原資料
docker cp ./backup-20240101/. convertx-cn:/app/data/
```
---
## 更新
### Docker Compose
```bash
docker compose pull
docker compose up -d
```
### Docker Run
```bash
docker pull convertx/convertx-cn:latest
docker stop convertx-cn
docker rm convertx-cn
docker run -d ... # 使用原本的參數
```
---
## 健康檢查
ConvertX-CN 提供健康檢查端點：
```bash
curl http://localhost:3000/healthcheck
```
可在 Docker Compose 中配置：
```yaml
services:
convertx:
# ...
healthcheck:
test: ["CMD", "curl", "-f", "http://localhost:3000/healthcheck"]
interval: 30s
timeout: 10s
retries: 3
```
---
## 故障排除
### 記憶體不足
如果遇到 OOM（記憶體不足），請增加容器記憶體限制：
```yaml
deploy:
resources:
limits:
memory: 8G
```
### 連接埠衝突
如果 3000 埠被占用，可更改映射：
```bash
-p 8080:3000 # 使用 8080 埠
```
### 權限問題
確保 data 目錄有正確權限：
```bash
chmod -R 777 ./data
```

280
docs/國際化說明.md
View file

@ -1,280 +0,0 @@
# 多語言支援（i18n）
> ⚠️ **此文件已遷移**
>
> 本文件內容已整合至新的文件結構，請參閱：
>
> - 🌐 [多語言介面支援](功能說明/多語言介面.md)
>
> 此文件將在未來版本中移除。
---
ConvertX-CN 支援 **65 種語言**，是目前最完整的多語言檔案轉換服務。
---
## 支援語言列表
### 東亞語言（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` | 馬其頓文 | Македонски |
### 波羅的海語言（3 種）
| 代碼 | 語言 | 原生名稱 |
| ---- | ---------- | -------- |
| `lt` | 立陶宛文 | Lietuvių |
| `lv` | 拉脫維亞文 | Latviešu |
| `et` | 愛沙尼亞文 | Eesti |
### 其他歐洲語言（4 種）
| 代碼 | 語言 | 原生名稱 |
| ---- | ------------ | -------- |
| `el` | 希臘文 | Ελληνικά |
| `sq` | 阿爾巴尼亞文 | Shqip |
| `ga` | 愛爾蘭文 | Gaeilge |
| `cy` | 威爾斯文 | Cymraeg |
### 中東語言（4 種）
| 代碼 | 語言 | 原生名稱 |
| ---- | -------- | -------- |
| `ar` | 阿拉伯文 | العربية |
| `he` | 希伯來文 | עברית |
| `fa` | 波斯文 | فارسی |
| `tr` | 土耳其文 | Türkçe |
### 南亞語言（10 種）
| 代碼 | 語言 | 原生名稱 |
| ---- | ------------ | -------- |
| `hi` | 印地文 | हिन्दी |
| `bn` | 孟加拉文 | বাংলা |
| `ta` | 泰米爾文 | தமிழ் |
| `te` | 泰盧固文 | తెలుగు |
| `mr` | 馬拉地文 | मराठी |
| `gu` | 古吉拉特文 | ગુજરાતી |
| `kn` | 卡納達文 | ಕನ್ನಡ |
| `ml` | 馬拉雅拉姆文 | മലയാളം |
| `ne` | 尼泊爾文 | नेपाली |
| `si` | 僧伽羅文 | සිංහල |
### 東南亞語言（8 種）
| 代碼 | 語言 | 原生名稱 |
| ----- | -------- | ---------------- |
| `th` | 泰文 | ไทย |
| `vi` | 越南文 | Tiếng Việt |
| `id` | 印尼文 | Bahasa Indonesia |
| `ms` | 馬來文 | Bahasa Melayu |
| `fil` | 菲律賓文 | Filipino |
| `my` | 緬甸文 | မြန်မာ |
| `km` | 高棉文 | ខ្មែរ |
| `lo` | 寮文 | ລາວ |
### 非洲語言（4 種）
| 代碼 | 語言 | 原生名稱 |
| ---- | ---------- | --------- |
| `af` | 南非語 | Afrikaans |
| `sw` | 斯瓦希里文 | Kiswahili |
| `am` | 阿姆哈拉文 | አማርኛ |
| `zu` | 祖魯文 | isiZulu |
---
## 語言切換
### 方法一：介面切換
1. 在網站右上角的導航列找到語言圖示（🌐）
2. 點擊後選擇偏好語言
3. 語言偏好會自動保存到 Cookie 中
### 方法二：URL 參數
```
http://localhost:3000/?lang=ja
```
### 方法三：瀏覽器設定
ConvertX-CN 會自動偵測瀏覽器的語言設定。
---
## 自動偵測
首次訪問時，系統會根據以下優先順序選擇語言：
1. Cookie 中儲存的語言偏好
2. URL 參數中的 `lang` 值
3. 瀏覽器的 `Accept-Language` 標頭
4. 預設語言（繁體中文 `zh-TW`）
---
## 新增語言
如要添加新語言支援，請按以下步驟：
### 1. 建立翻譯檔案
在 `src/locales/` 目錄新增語言檔案，例如 `xx.json`：
```json
{
"common": {
"appName": "ConvertX-CN",
"poweredBy": "Powered by",
"version": "v{version}",
"loading": "...",
...
},
"nav": {
"history": "...",
"account": "...",
...
},
...
}
```
### 2. 在 index.ts 中註冊
編輯 `src/i18n/index.ts`：
```typescript
// 導入新語言檔案
import xx from "../locales/xx.json";
// 在 SupportedLocale 類型中添加
export type SupportedLocale = "en" | "zh-TW" | ... | "xx";
// 在 supportedLocales 陣列中添加
export const supportedLocales: LocaleConfig[] = [
// ...
{ code: "xx", name: "Language Name", nativeName: "原生名稱" },
];
// 在 translations 物件中註冊
const translations: Record<SupportedLocale, TranslationData> = {
// ...
xx: xx as TranslationData,
};
```
### 3. 測試
```bash
bun run dev
# 訪問 http://localhost:3000/?lang=xx
```
---
## 語言選擇器 UI 規範
為確保語言切換體驗一致，ConvertX-CN 的語言選擇器遵循以下規範：
### 視覺設計
| 項目 | 規範 |
| ------------ | ----------------------------- |
| 圖示大小 | 與旁邊文字高度一致（h-6 w-6） |
| 下拉選單背景 | 完全不透明（bg-neutral-800） |
| 捲動條 | 明確可見的 scrollbar 樣式 |
| 最大高度 | 320px，超過則顯示捲動條 |
### 行為規範
- Setup / Login / 主頁使用同一套語言選擇器組件
- 語言切換後自動重新載入頁面
- 語言偏好儲存於 Cookie，跨頁面保持一致
- 預設根據瀏覽器語言自動偵測
### 已知問題修復（v0.1.9）
- 語言圖示尺寸過小 → 已修復
- 下拉選單半透明 → 已修復
- 捲動條不明顯 → 已新增 scrollbar 樣式
---
## 翻譯 Fallback
如果某個翻譯鍵缺失，系統會：
1. 嘗試使用英文（`en`）翻譯
2. 如果英文也缺失，顯示鍵名（如 `nav.history`）
---
## 貢獻翻譯
歡迎提交 Pull Request 來新增或改進翻譯！
### 翻譯指南
1. **完整翻譯**：確保所有鍵都有翻譯
2. **保留佔位符**：`{version}`、`{count}` 等佔位符不要翻譯
3. **自然表達**：使用該語言的自然表達方式
4. **一致性**：同一個詞在不同地方使用相同翻譯
5. **測試**：在實際介面中測試翻譯效果
### 提交流程
1. Fork 此專案
2. 建立新語言檔案或修改現有翻譯
3. 測試確認無誤
4. 提交 Pull Request

164
docs/常見問題總覽.md
View file

@ -1,164 +0,0 @@
# 常見問題 FAQ
> ⚠️ **此文件已遷移**
>
> 本文件內容已整合至新的文件結構，請參閱：
>
> - ❓ [常見問題 FAQ](快速入門/常見問題.md)
>
> 此文件將在未來版本中移除。
---
## 🔐 登入與帳號
### 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. 重新註冊
> ⚠️ 這會刪除所有用戶資料和轉換歷史
---
## 🐳 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` 目錄：
- `convertx.db` - SQLite 資料庫
- `uploads/` - 上傳的原始檔案
- `output/` - 轉換後的檔案
---
## 🌍 語言相關
### Q: 如何切換語言？
1. 點擊右上角語言圖示 🌐
2. 從下拉選單選擇語言
3. 頁面自動更新
語言偏好會儲存在 Cookie 中。
### Q: 支援哪些語言？
目前支援 65 種語言，詳見 [i18n.md](i18n.md)
### Q: 如何貢獻翻譯？
1. 複製 `src/locales/en.json`
2. 重命名為 `xx.json`（語言代碼）
3. 翻譯所有文字
4. 在 `src/i18n/index.ts` 中註冊
5. 提交 Pull Request
---
## 📄 轉換相關
### Q: 支援哪些格式？
ConvertX-CN 支援數百種格式，包括：
- **影音**：MP4, AVI, MKV, MP3, WAV 等
- **圖片**：PNG, JPG, WEBP, SVG, PDF 等
- **文件**：DOCX, PDF, XLSX, PPTX 等
- **電子書**：EPUB, MOBI, AZW3 等
完整列表見 [converters.md](converters.md)
### Q: 轉換失敗怎麼辦？
1. 檢查檔案是否損壞
2. 確認格式組合是否支援
3. 查看容器 logs：
```bash
docker logs convertx-cn
```
### Q: 檔案大小有限制嗎？
預設無硬性限制，但大檔案：
- 上傳需要更長時間
- 轉換可能耗用大量記憶體
建議為容器分配足夠的記憶體資源。
---
## 🔧 進階問題
### Q: 可以使用 HTTPS 嗎？
可以。推薦使用反向代理（如 Traefik、Nginx）處理 SSL。
詳見 [advanced-usage.md](advanced-usage.md)
### Q: 如何備份資料？
```bash
# 備份
docker cp convertx-cn:/app/data ./backup
# 還原
docker cp ./backup/. convertx-cn:/app/data
```
### Q: 有 API 文件嗎？
目前尚未提供正式的 API 文件。如有 API 需求，歡迎開 Issue 討論。

183
docs/快速入門總覽.md
View file

@ -1,183 +0,0 @@
# 快速開始
> ⚠️ **此文件已遷移**
>
> 本文件內容已整合至新的文件結構，請參閱：
>
> - 📖 [概覽](快速入門/概覽.md)
> - 🚀 [快速開始](快速入門/快速開始.md)
> - ❓ [常見問題](快速入門/常見問題.md)
>
> 此文件將在未來版本中移除。
---
> 本文件提供完整部署步驟。若只需最快啟動，請參考 [說明文件](說明文件.md)。
---
## 系統需求
| 需求 | 最低 | 建議 |
| -------- | ------ | ------ |
| Docker | 20.10+ | 24.0+ |
| RAM | 4 GB | 8 GB |
| 磁碟空間 | 10 GB | 20 GB |
| CPU | 2 核心 | 4 核心 |
---
## 事前準備
建立資料夾（重要）：
```bash
mkdir -p ~/convertx-cn/data && cd ~/convertx-cn
```
> `data` 資料夾是主機上的實體資料夾，用於存放上傳檔案與轉換結果。
---
## 最快方式：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
```
開啟瀏覽器訪問 `http://localhost:3000`：
1. 點擊右上角 **Register** 註冊帳號
2. 輸入 Email 和密碼
3. 完成！開始使用
---
## 推薦方式：Docker Compose
### 1. 建立配置檔
建立 `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=請更換為一個長且隨機的字串
- HTTP_ALLOWED=false
- AUTO_DELETE_EVERY_N_HOURS=24
```
### 2. 啟動服務
```bash
docker compose up -d
```
### 3. 開始使用
1. 開啟瀏覽器訪問 `http://localhost:3000`
2. 點擊「Register」建立帳號
3. 登入後即可開始轉換檔案！
---
## 首次設定
### 建立管理員帳號
首次訪問時，ConvertX-CN 會顯示設定頁面，讓您建立第一個帳號。此帳號即為管理員。
### 註冊功能
- `ACCOUNT_REGISTRATION=true`：允許其他人註冊
- `ACCOUNT_REGISTRATION=false`：停用註冊（單人使用）
---
## 驗證安裝
### 檢查容器狀態
```bash
docker ps
# 應該看到 convertx-cn 容器正在運行
docker logs convertx-cn
# 應該看到 "🦊 Elysia is running at http://localhost:3000"
```
### 健康檢查
```bash
curl http://localhost:3000/healthcheck
# 應該返回 "OK"
```
---
## 更新版本
```bash
# Docker Compose
docker compose pull
docker compose up -d
# 或 Docker Run
docker pull convertx/convertx-cn:latest
docker stop convertx-cn
docker rm convertx-cn
# 然後重新執行 docker run 指令
```
---
## 常見問題
### 無法訪問頁面
1. 確認容器正在運行：`docker ps`
2. 檢查連接埠是否被占用：`netstat -an | grep 3000`
3. 查看錯誤日誌：`docker logs convertx-cn`
### 權限錯誤
```bash
# 確保 data 目錄有正確權限
chmod -R 777 ./data
```
### 記憶體不足
ConvertX-CN 內建完整依賴，建議至少 4GB RAM。可透過 Docker 限制記憶體使用：
```yaml
deploy:
resources:
limits:
memory: 4G
```
---
## 下一步
- 📖 [Docker 配置](Docker說明.md) - 進階 Docker 設定
- ⚙️ [環境變數](環境變數總覽.md) - 所有可用設定
- 🔧 [進階用法](進階用法.md) - 硬體加速、反向代理
- 🌍 [多語言](國際化說明.md) - 語言設定與自訂

4
docs/環境變數總覽.md
View file

@ -21,7 +21,7 @@
- [環境變數完整說明](配置設定/環境變數.md)
- [安全性設定](配置設定/安全性.md)
- [進階部署指南](部署總覽.md)
- [Docker 部署指南](部署指南/Docker部署.md)
---
@ -152,7 +152,7 @@ environment:
## 相關文件
- [進階部署指南](部署總覽.md)
- [Docker 部署指南](部署指南/Docker部署.md)
- [Docker Compose 範例](Docker組合配置/)
- [常見問題](快速入門/常見問題.md)

193
docs/網址ID與儲存.md
View file

@ -1,193 +0,0 @@
# URL ID 與儲存機制
> ⚠️ **此文件已遷移**
>
> 本文件內容已整合至新的文件結構，請參閱：
>
> - 🛠️ [專案結構](開發指南/專案結構.md)
> - 🐳 [Docker 部署](部署指南/Docker部署.md)
>
> 此文件將在未來版本中移除。
---
## 檔案儲存結構
ConvertX-CN 使用以下目錄結構儲存檔案：
```
/app/data/
├── convertx.db # SQLite 資料庫
├── uploads/ # 上傳的原始檔案
│ └── {user_id}/
│ └── {job_id}/
│ ├── file1.docx
│ └── file2.pdf
└── output/ # 轉換後的檔案
└── {user_id}/
└── {job_id}/
├── file1.pdf
└── file2.txt
```
---
## Job ID 說明
每次轉換任務都會產生一個唯一的 Job ID，用於：
- 追蹤轉換進度
- 組織檔案儲存
- 生成下載連結
### Job ID 格式
Job ID 是一個 UUID v4 格式的字串，例如：
```
550e8400-e29b-41d4-a716-446655440000
```
---
## URL 結構
### 結果頁面
```
/results/{job_id}
```
例如：
```
http://localhost:3000/results/550e8400-e29b-41d4-a716-446655440000
```
### 下載單一檔案
```
/download/{user_id}/{job_id}/{filename}
```
### 下載所有檔案（Tar）
```
/archive/{job_id}
```
---
## 資料持久化
### Docker Volume 映射
為了確保資料不會在容器重啟後遺失，請務必映射 `/app/data` 目錄：
```yaml
volumes:
- ./data:/app/data
```
或使用 Named Volume：
```yaml
volumes:
- convertx-data:/app/data
volumes:
convertx-data:
```
---
## 自動清理
ConvertX-CN 會根據 `AUTO_DELETE_EVERY_N_HOURS` 設定自動清理過期檔案。
### 清理邏輯
1. 系統每 N 小時執行一次清理
2. 刪除建立時間超過 N 小時的 Job
3. 同時刪除對應的上傳檔案和輸出檔案
4. 資料庫記錄也會被清除
### 設定範例
```yaml
# 每 24 小時清理一次
- AUTO_DELETE_EVERY_N_HOURS=24
# 每 1 小時清理一次（公開服務建議）
- AUTO_DELETE_EVERY_N_HOURS=1
# 停用自動清理
- AUTO_DELETE_EVERY_N_HOURS=0
```
---
## 資料庫
ConvertX-CN 使用 SQLite 作為資料庫，儲存於 `/app/data/convertx.db`。
### 資料表結構
#### users
| 欄位 | 類型 | 說明 |
| -------- | ------- | --------- |
| id | INTEGER | 使用者 ID |
| email | TEXT | 電子郵件 |
| password | TEXT | 密碼雜湊 |
#### jobs
| 欄位 | 類型 | 說明 |
| ------------ | ------- | --------- |
| id | TEXT | Job UUID |
| user_id | INTEGER | 使用者 ID |
| num_files | INTEGER | 檔案數量 |
| date_created | TEXT | 建立時間 |
#### file_names
| 欄位 | 類型 | 說明 |
| ---------------- | ------- | -------- |
| id | INTEGER | 檔案 ID |
| job_id | TEXT | Job UUID |
| input_file_name | TEXT | 原始檔名 |
| output_file_name | TEXT | 輸出檔名 |
| status | TEXT | 轉換狀態 |
---
## 備份與還原
### 備份
```bash
# 備份整個 data 目錄
tar -czvf convertx-backup-$(date +%Y%m%d).tar.gz ./data
# 僅備份資料庫
cp ./data/convertx.db ./backup-convertx-$(date +%Y%m%d).db
```
### 還原
```bash
# 還原整個 data 目錄
tar -xzvf convertx-backup-20240101.tar.gz
# 還原資料庫
cp ./backup-convertx-20240101.db ./data/convertx.db
```
---
## 注意事項
1. **權限問題**：確保 Docker 容器有權限寫入 data 目錄
2. **磁碟空間**：大量轉換可能佔用大量磁碟空間，建議設定自動清理
3. **資料安全**：敏感文件轉換後建議手動刪除或縮短保留時間

61
docs/轉換器總覽.md
View file

@ -1,61 +0,0 @@
# 支援的轉換器
> ⚠️ **此文件已遷移**
>
> 本文件內容已整合至新的文件結構，請參閱：
>
> - 🔌 [轉換器完整說明](功能說明/轉換器.md)
> - 📊 [OCR 功能](功能說明/OCR.md)
> - 🌐 [翻譯功能](功能說明/翻譯功能.md)
>
> 此文件將在未來版本中移除。
---
ConvertX-CN 完整版已內建以下所有轉換器，開箱即用。
## 轉換器列表
| 轉換器 | 用途 | 輸入格式數 | 輸出格式數 |
| --------------------------------------------------------------- | ---------- | ---------- | ---------- |
| [Inkscape](https://inkscape.org/) | 向量圖形 | 7 | 17 |
| [libjxl](https://github.com/libjxl/libjxl) | JPEG XL | 11 | 11 |
| [resvg](https://github.com/RazrFalcon/resvg) | SVG | 1 | 1 |
| [Vips](https://github.com/libvips/libvips) | 圖片 | 45 | 23 |
| [libheif](https://github.com/strukturag/libheif) | HEIF | 2 | 4 |
| [XeLaTeX](https://tug.org/xetex/) | LaTeX | 1 | 1 |
| [Calibre](https://calibre-ebook.com/) | 電子書 | 26 | 19 |
| [LibreOffice](https://www.libreoffice.org/) | 文件 | 41 | 22 |
| [Dasel](https://github.com/TomWright/dasel) | 資料檔案 | 5 | 4 |
| [Pandoc](https://pandoc.org/) | 文件 | 43 | 65 |
| [msgconvert](https://github.com/mvz/email-outlook-message-perl) | Outlook | 1 | 1 |
| VCF to CSV | 聯絡人 | 1 | 1 |
| [dvisvgm](https://dvisvgm.de/) | 向量圖形 | 4 | 2 |
| [ImageMagick](https://imagemagick.org/) | 圖片 | 245 | 183 |
| [GraphicsMagick](http://www.graphicsmagick.org/) | 圖片 | 167 | 130 |
| [Assimp](https://github.com/assimp/assimp) | 3D 模型 | 77 | 23 |
| [FFmpeg](https://ffmpeg.org/) | 影音 | ~472 | ~199 |
| [Potrace](https://potrace.sourceforge.net/) | 點陣轉向量 | 4 | 11 |
| [VTracer](https://github.com/visioncortex/vtracer) | 點陣轉向量 | 8 | 1 |
| [Markitdown](https://github.com/microsoft/markitdown) | 文件 | 6 | 1 |
> 註：FFmpeg 的格式數量包含部分重複格式。
## 內建依賴
ConvertX-CN 完整版已預載：
| 類別 | 內建內容 |
| ------------ | ---------------------------------------------------------------- |
| **文件轉換** | LibreOffice (headless)、Pandoc |
| **LaTeX** | TexLive Full（完整版，支援所有 LaTeX 需求） |
| **OCR 識別** | Tesseract OCR + 繁體中文、簡體中文、日文、韓文、英文、德文語言包 |
| **CJK 字型** | Noto CJK（中日韓）、Noto Emoji、微軟核心字型、標楷體 |
| **影音轉換** | FFmpeg、ImageMagick、GraphicsMagick |
| **向量圖形** | Inkscape、Potrace、VTracer、resvg |
| **電子書** | Calibre |
| **其他** | Ghostscript、MuPDF、Poppler、libheif、libjxl 等 |
## 新增轉換器
如需新增轉換器支援，請至 [GitHub Issues](https://github.com/pi-docket/ConvertX-CN/issues) 提出需求或直接發送 Pull Request。

288
docs/進階用法.md
View file

@ -1,288 +0,0 @@
# 進階用法
> ⚠️ **此文件已遷移**
>
> 本文件內容已整合至新的文件結構，請參閱：
>
> - 🐳 [Docker 部署（含硬體加速）](部署指南/Docker部署.md)
> - 🔧 [反向代理設定](部署指南/反向代理.md)
>
> 此文件將在未來版本中移除。
---
## 硬體加速
### NVIDIA GPU (CUDA/NVENC)
#### 1. 安裝 NVIDIA Container Toolkit
```bash
# Ubuntu/Debian
curl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey | sudo gpg --dearmor -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg
curl -s -L https://nvidia.github.io/libnvidia-container/stable/deb/nvidia-container-toolkit.list | \
sed 's#deb https://#deb [signed-by=/usr/share/keyrings/nvidia-container-toolkit-keyring.gpg] https://#g' | \
sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list
sudo apt-get update
sudo apt-get install -y nvidia-container-toolkit
sudo nvidia-ctk runtime configure --runtime=docker
sudo systemctl restart docker
```
#### 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
```
---
## 反向代理
### Nginx
```nginx
server {
listen 80;
server_name convert.example.com;
return 301 https://$server_name$request_uri;
}
server {
listen 443 ssl http2;
server_name convert.example.com;
ssl_certificate /etc/nginx/ssl/cert.pem;
ssl_certificate_key /etc/nginx/ssl/key.pem;
client_max_body_size 0; # 無檔案大小限制
location / {
proxy_pass http://localhost:3000;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection 'upgrade';
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;
proxy_cache_bypass $http_upgrade;
# 長時間連線支援（大檔案轉換）
proxy_read_timeout 3600s;
proxy_send_timeout 3600s;
}
}
```
### Caddy
```
convert.example.com {
reverse_proxy localhost:3000 {
header_up X-Real-IP {remote_host}
header_up X-Forwarded-Proto {scheme}
}
request_body {
max_size 0 # 無限制
}
}
```
### Traefik
參考 [Docker說明.md](Docker說明.md#使用-traefik-反向代理) 中的 Traefik 配置。
---
## 子路徑部署
如果需要在子路徑部署（如 `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
}
}
```
---
## 限制同時轉換數
防止伺服器過載：
```yaml
environment:
- MAX_CONVERT_PROCESS=4 # 最多同時 4 個轉換任務
```
---
## 匿名模式
允許不登入即可使用：
```yaml
environment:
- ALLOW_UNAUTHENTICATED=true
- HIDE_HISTORY=true # 建議同時隱藏歷史
- AUTO_DELETE_EVERY_N_HOURS=1 # 快速清理
```
---
## 高可用部署
### 多容器部署
ConvertX-CN 支援多容器部署，但需注意：
1. **共享儲存**：所有容器需存取相同的 `/app/data` 目錄
2. **資料庫鎖定**：SQLite 在高併發下可能有問題
3. **JWT Secret**：所有容器需使用相同的 `JWT_SECRET`
```yaml
services:
convertx-1:
image: convertx/convertx-cn:latest
volumes:
- shared-data:/app/data
environment:
- JWT_SECRET=${JWT_SECRET}
convertx-2:
image: convertx/convertx-cn:latest
volumes:
- shared-data:/app/data
environment:
- JWT_SECRET=${JWT_SECRET}
nginx:
image: nginx:alpine
ports:
- "80:80"
volumes:
- ./nginx.conf:/etc/nginx/nginx.conf
volumes:
shared-data:
driver: local
driver_opts:
type: nfs
o: addr=nfs-server,rw
device: ":/path/to/shared/data"
```
---
## 效能調優
### 記憶體限制
```yaml
deploy:
resources:
limits:
memory: 8G
reservations:
memory: 2G
```
### CPU 限制
```yaml
deploy:
resources:
limits:
cpus: "4"
reservations:
cpus: "1"
```
---
## 日誌管理
### 查看日誌
```bash
docker logs convertx-cn
docker logs -f convertx-cn # 即時追蹤
docker logs --tail 100 convertx-cn # 最後 100 行
```
### 日誌輪轉
```yaml
services:
convertx:
# ...
logging:
driver: "json-file"
options:
max-size: "10m"
max-file: "3"
```

394
docs/部署總覽.md
View file

@ -1,394 +0,0 @@
# 進階部署指南
> ⚠️ **此文件已遷移**
>
> 本文件內容已整合至新的文件結構，請參閱：
>
> - 🐳 [Docker 部署](部署指南/Docker部署.md)
> - 🔧 [反向代理設定](部署指南/反向代理.md)
> - 🔒 [安全性設定](配置設定/安全性.md)
>
> 此文件將在未來版本中移除。
---
本文件說明如何在生產環境中部署 ConvertX-CN，包括 Reverse Proxy、HTTPS、安全性設定等。
---
## 目錄
- [部署前檢查清單](#部署前檢查清單)
- [Reverse Proxy 設定](#reverse-proxy-設定)
- [Nginx](#nginx)
- [Traefik](#traefik)
- [Caddy](#caddy)
- [HTTPS 設定](#https-設定)
- [安全性建議](#安全性建議)
- [子路徑部署](#子路徑部署)
- [效能調整](#效能調整)
- [備份與還原](#備份與還原)
---
## 部署前檢查清單
在部署到生產環境前，請確認以下項目：
- [ ] 已建立 `data` 資料夾（實體資料夾，非匿名 volume）
- [ ] 已設定固定的 `JWT_SECRET`（至少 32 字元）
- [ ] 已關閉 `ACCOUNT_REGISTRATION`（或確認要開放註冊）
- [ ] 已設定 `TRUST_PROXY=true`（若使用 Reverse Proxy）
- [ ] 已設定 `HTTP_ALLOWED=false`（若有 HTTPS）
- [ ] 已設定防火牆規則
- [ ] 已設定定期備份
---
## Reverse Proxy 設定
### 重要環境變數
透過 Reverse Proxy 存取時，請設定：
```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;
# 強制跳轉 HTTPS
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 300s;
proxy_send_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";
}
}
```
### 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=your-secret-key
- 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
```
# Caddyfile
convertx.example.com {
reverse_proxy 127.0.0.1:3000
# 檔案上傳大小限制
request_body {
max_size 500MB
}
}
```
Caddy 會自動處理 HTTPS 憑證。
---
## HTTPS 設定
### Let's Encrypt（推薦）
使用 Certbot 取得免費憑證：
```bash
# 安裝 Certbot
sudo apt install certbot python3-certbot-nginx
# 取得憑證（Nginx）
sudo certbot --nginx -d convertx.example.com
# 自動續約測試
sudo certbot renew --dry-run
```
### 自簽憑證（測試用）
```bash
# 產生自簽憑證
openssl req -x509 -nodes -days 365 -newkey rsa:2048 \
-keyout /etc/ssl/private/convertx.key \
-out /etc/ssl/certs/convertx.crt \
-subj "/CN=convertx.example.com"
```
---
## 安全性建議
### 1. 環境變數設定
```yaml
environment:
# 必須設定固定值
- JWT_SECRET=使用 openssl rand -hex 32 產生
# 關閉不需要的功能
- ACCOUNT_REGISTRATION=false
- ALLOW_UNAUTHENTICATED=false
- HTTP_ALLOWED=false
# 定期清理檔案
- AUTO_DELETE_EVERY_N_HOURS=24
```
### 2. 防火牆設定
```bash
# 只開放 80 和 443
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw enable
# 不要直接開放 3000 埠
```
### 3. Docker 網路隔離
```yaml
services:
convertx:
# 只監聽 localhost
ports:
- "127.0.0.1:3000:3000"
```
### 4. 資源限制
```yaml
services:
convertx:
deploy:
resources:
limits:
cpus: "4"
memory: 8G
reservations:
cpus: "1"
memory: 2G
```
---
## 子路徑部署
若需要在子路徑部署（如 `https://example.com/convertx/`）：
### 環境變數
```yaml
environment:
- WEBROOT=/convertx
```
### Nginx 設定
```nginx
location /convertx/ {
proxy_pass http://127.0.0.1:3000/;
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;
}
```
---
## 效能調整
### 1. 限制同時轉換數
```yaml
environment:
- MAX_CONVERT_PROCESS=4
```
### 2. FFmpeg 硬體加速
```yaml
environment:
# NVIDIA GPU
- FFMPEG_ARGS=-hwaccel cuda
# Intel QSV
- FFMPEG_ARGS=-hwaccel qsv
# AMD VAAPI
- FFMPEG_ARGS=-hwaccel vaapi
```
### 3. 容器資源限制
見上方「資源限制」區塊。
---
## 備份與還原
### 備份
```bash
# 停止容器
docker compose stop
# 備份 data 資料夾
tar -czvf convertx-backup-$(date +%Y%m%d).tar.gz data/
# 重新啟動
docker compose start
```
### 自動備份腳本
```bash
#!/bin/bash
# /opt/scripts/backup-convertx.sh
BACKUP_DIR="/opt/backups/convertx"
DATA_DIR="/opt/convertx/data"
KEEP_DAYS=7
# 建立備份
mkdir -p $BACKUP_DIR
tar -czvf "$BACKUP_DIR/convertx-$(date +%Y%m%d).tar.gz" -C $(dirname $DATA_DIR) $(basename $DATA_DIR)
# 清理舊備份
find $BACKUP_DIR -name "convertx-*.tar.gz" -mtime +$KEEP_DAYS -delete
```
加入 crontab：
```bash
# 每天凌晨 3 點備份
0 3 * * * /opt/scripts/backup-convertx.sh
```
### 還原
```bash
# 停止容器
docker compose stop
# 還原 data 資料夾
tar -xzvf convertx-backup-20260120.tar.gz
# 重新啟動
docker compose start
```
---
## 常見問題
### 問題：Reverse Proxy 後登入失敗
**解決方案**：設定 `TRUST_PROXY=true`
### 問題：上傳大檔案失敗
**解決方案**：調整 Nginx 的 `client_max_body_size`
### 問題：轉換超時
**解決方案**：調整 Nginx 的 `proxy_read_timeout`
---
## 相關文件
- [環境變數完整說明](配置設定/環境變數.md)
- [Docker Compose 範例](Docker組合配置/)
- [常見問題](快速入門/常見問題.md)