5322f85721
## 主要變更 ### 新增全域檔案傳輸模組 (src/transfer/) - constants.ts: 定義傳輸常數（10MB 門檻、5MB chunk 大小） - types.ts: 傳輸類型定義 - uploadManager.ts: 後端上傳管理器（支援直傳與 chunk） - downloadManager.ts: 後端下載管理器（支援直傳與 chunk） - archiveManager.ts: 封裝管理器（僅允許 .tar） - index.ts: 統一匯出 ### 新增 API 端點 - uploadChunk.tsx: Chunk 上傳 API - downloadChunk.tsx: Chunk 下載 API ### 前端更新 - public/script.js: 整合智慧傳輸策略（≤10MB 直傳，>10MB chunk） - public/transfer.js: 前端傳輸管理模組 ### 轉換器更新 - mineru.ts: 改用 .tar 格式（不壓縮），禁止 .tar.gz - download.tsx: 使用統一的封裝管理器 ### 測試 - tests/transfer/: 完整傳輸機制測試套件 - tests/converters/mineru.test.ts: 更新以符合 .tar 規範 ### 文件 - README.md: 新增檔案傳輸機制說明 ## 設計原則 - 檔案 ≤10MB：直接傳輸 - 檔案 >10MB：使用 5MB chunks 分段傳輸 - 多檔輸出：僅允許 .tar 封裝（禁止 .tar.gz/.zip） - 引擎層不感知 chunk（僅傳輸層處理）
286 lines
6.9 KiB
Markdown
286 lines
6.9 KiB
Markdown
|
||
|
||
# ConvertX-CN
|
||
|
||
**開箱即用的全功能檔案轉換服務** — 一個 Docker 命令，5 分鐘部署完成
|
||
|
||
[](https://hub.docker.com/r/convertx/convertx-cn)
|
||
[](https://github.com/pi-docket/ConvertX-CN/releases)
|
||
|
||
---
|
||
|
||
## 為什麼選擇 ConvertX-CN？
|
||
|
||
- 支援 **1000+ 格式**（影音、圖片、文件、電子書）
|
||
- 已內建 LibreOffice、FFmpeg、Pandoc 等 20+ 轉換器
|
||
- 預載中日韓字型與 OCR 語言包
|
||
- 支援 65 種介面語言
|
||
|
||
---
|
||
|
||
## 線上示範
|
||
|
||
想先試用再部署？歡迎使用我們的示範站：
|
||
|
||
🔗 **https://convertx-cn.bioailab.qzz.io**
|
||
|
||
| 項目 | 內容 |
|
||
| -------- | ----------------- |
|
||
| 範例帳號 | admin@example.com |
|
||
| 範例密碼 | admin |
|
||
|
||
> ⚠️ 示範站僅供測試，請勿上傳敏感檔案。資料可能定期清除。
|
||
|
||
---
|
||
|
||
## 快速啟動（Docker Run）
|
||
|
||
### 1. 建立資料夾
|
||
|
||
```bash
|
||
mkdir -p ~/convertx-cn/data && cd ~/convertx-cn
|
||
```
|
||
|
||
### 2. 啟動容器
|
||
|
||
JWT_SECRET=請改成你自己的隨機字串至少32字元
|
||
|
||
```bash
|
||
docker run -d \
|
||
--name convertx-cn \
|
||
--restart unless-stopped \
|
||
-p 3000:3000 \
|
||
-v ./data:/app/data \
|
||
-e TZ=Asia/Taipei \
|
||
-e JWT_SECRET=e78a2da4-135f-06a8-fa46-17ef7990f5d1 \
|
||
convertx/convertx-cn:latest
|
||
```
|
||
|
||
### 3. 開啟瀏覽器
|
||
|
||
```bash
|
||
http://localhost:3000
|
||
```
|
||
|
||
> 首次下載約 4-6 GB，請耐心等待。
|
||
|
||
---
|
||
|
||
## Docker Compose（推薦）
|
||
|
||
### 1. 建立專案資料夾
|
||
|
||
### Linux / macOS
|
||
|
||
```bash
|
||
mkdir -p ~/convertx-cn && cd ~/convertx-cn
|
||
```
|
||
|
||
### Windows PowerShell
|
||
|
||
```bash
|
||
mkdir C:\convertx-cn; cd C:\convertx-cn
|
||
```
|
||
|
||
### Windows CMD
|
||
|
||
```bash
|
||
mkdir C:\convertx-cn
|
||
cd C:\convertx-cn
|
||
```
|
||
|
||
### 2. 建立 docker-compose.yml（在專案資料夾下）
|
||
|
||
- 範例內容（請修改 JWT_SECRET=請改成你自己的隨機字串至少32字元）：
|
||
|
||
```yaml
|
||
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=e78a2da4-135f-06a8-fa46-17ef7990f5d1
|
||
```
|
||
|
||
### 3. 啟動：
|
||
|
||
```bash
|
||
docker compose up -d
|
||
```
|
||
|
||
更多範例 → [docs/docker-compose/](docs/docker-compose/)
|
||
|
||
---
|
||
|
||
## 重要：資料夾說明
|
||
|
||
`./data` 是你**主機上的實體資料夾**，用於存放上傳檔案、轉換結果與使用者資料。
|
||
|
||
| 作業系統 | 建立指令 |
|
||
| ------------- | ----------------------------- |
|
||
| Linux / macOS | `mkdir -p ~/convertx-cn/data` |
|
||
| Windows (PS) | `mkdir C:\convertx-cn\data` |
|
||
| Windows (CMD) | `mkdir C:\convertx-cn\data` |
|
||
|
||
> 若不先建立，Docker 會建立匿名 volume，導致資料難以存取或備份。
|
||
|
||
---
|
||
|
||
## 必要參數
|
||
|
||
| 參數 | 說明 |
|
||
| ------------ | ---------------------------------- |
|
||
| `./data` | 主機資料夾，必須先建立 |
|
||
| `JWT_SECRET` | 登入驗證金鑰，不設會每次重啟被登出 |
|
||
|
||
其他環境變數 → [docs/config/environment.md](docs/config/environment.md)
|
||
|
||
---
|
||
|
||
## 常見問題
|
||
|
||
| 問題 | 解法 |
|
||
| -------------------- | ---------------------------------------------- |
|
||
| 登入後又被踢回登入頁 | 加上 `HTTP_ALLOWED=true` 或 `TRUST_PROXY=true` |
|
||
| 重啟後資料消失 | 確認 `./data:/app/data` 且資料夾存在 |
|
||
| 重啟後被登出 | 設定固定的 `JWT_SECRET` |
|
||
|
||
更多問題 → [docs/faq.md](docs/faq.md)
|
||
|
||
---
|
||
|
||
## 支援格式
|
||
|
||
| 轉換器 | 用途 | 格式數 |
|
||
| ----------- | ------- | ------ |
|
||
| FFmpeg | 影音 | 400+ |
|
||
| ImageMagick | 圖片 | 200+ |
|
||
| LibreOffice | 文件 | 60+ |
|
||
| Pandoc | 文件 | 100+ |
|
||
| Calibre | 電子書 | 40+ |
|
||
| Inkscape | 向量圖 | 20+ |
|
||
| MinerU | 文件→MD | 2 |
|
||
|
||
完整列表 → [docs/converters.md](docs/converters.md)
|
||
|
||
---
|
||
|
||
## MinerU
|
||
|
||
ConvertX 內建文件轉換引擎。
|
||
|
||
- md-t（表格以 Markdown 呈現）
|
||
- md-i（表格以圖片呈現）
|
||
|
||
輸出格式：.tar（不壓縮封裝）
|
||
|
||
---
|
||
|
||
## 檔案傳輸機制
|
||
|
||
Contents.CN 使用統一的檔案傳輸策略：
|
||
|
||
| 檔案大小 | 傳輸方式 | 說明 |
|
||
| -------- | -------- | ---- |
|
||
| ≤ 10MB | 直接傳輸 | 單一請求完成上傳/下載 |
|
||
| > 10MB | 分段傳輸 | 使用 5MB chunks 分段傳輸 |
|
||
|
||
### 多檔輸出封裝
|
||
|
||
- ✅ 唯一允許格式：`.tar`
|
||
- ❌ 禁止使用：`.tar.gz`、`.tgz`、`.zip`
|
||
|
||
### 設計原則
|
||
|
||
- 分段傳輸僅存在於傳輸層
|
||
- 轉換引擎只接收完整檔案
|
||
- 前後端使用共用傳輸模組
|
||
|
||
---
|
||
|
||
## 語言支援
|
||
|
||
支援 **65 種語言**，包含繁體中文、簡體中文、英文、日文、韓文等。
|
||
|
||
語言會根據瀏覽器設定自動偵測，也可透過右上角選單手動切換。
|
||
|
||
詳細說明 → [docs/i18n.md](docs/i18n.md)
|
||
|
||
---
|
||
|
||
## 版本與更新
|
||
|
||
```bash
|
||
docker compose down
|
||
docker compose pull
|
||
docker compose up -d
|
||
```
|
||
|
||
- 版本說明 → [docs/versions/](docs/versions/)
|
||
- 更新指南 → [docs/deployment/update.md](docs/deployment/update.md)
|
||
- Changelog → [CHANGELOG.md](CHANGELOG.md)
|
||
|
||
---
|
||
|
||
## API Server（選用）
|
||
|
||
如需以程式整合方式使用 ConvertX 的轉檔功能，可啟用 **API Server**。
|
||
|
||
> ⚠️ API Server 為**選用功能**，不影響現有 Web UI 的使用。若只使用網頁介面，無需任何額外設定。
|
||
|
||
### 功能特點
|
||
|
||
- 🔐 **JWT 認證** — 安全的 API 存取控制
|
||
- 🌐 **REST + GraphQL** — 雙協議支援，滿足不同整合需求
|
||
- 🔍 **智慧建議** — 轉換失敗時自動推薦替代引擎
|
||
- 🛠️ **20+ 轉換引擎** — 與 Web UI 共用完整轉換器套件
|
||
|
||
### 快速啟用
|
||
|
||
```bash
|
||
# 同時啟動 Web UI 與 API Server
|
||
docker compose --profile api up -d
|
||
```
|
||
|
||
| 服務 | 端口 | 說明 |
|
||
| ---------- | ---- | -------------- |
|
||
| Web UI | 3000 | 網頁介面 |
|
||
| API Server | 3001 | REST & GraphQL |
|
||
|
||
### API 文件
|
||
|
||
詳細的 API 規格與使用說明：
|
||
|
||
- 📘 [API Server README](api-server/README.md)
|
||
- 📗 [API 規格文件](api-server/docs/API_SPEC.md)
|
||
- 📙 [架構說明](api-server/docs/ARCHITECTURE.md)
|
||
|
||
---
|
||
|
||
## 進階文件
|
||
|
||
| 文件 | 說明 |
|
||
| -------------------------------------- | ------------------------- |
|
||
| [環境變數](docs/config/environment.md) | 所有可用參數 |
|
||
| [安全性設定](docs/config/security.md) | HTTP_ALLOWED、TRUST_PROXY |
|
||
| [反向代理](docs/deployment.md) | Nginx / Traefik / Caddy |
|
||
| [Docker 進階](docs/docker.md) | 自訂 Build |
|
||
| [FAQ](docs/faq.md) | 疑難排解 |
|
||
|
||
---
|
||
|
||
## 預覽
|
||
|
||
|
||
|
||
---
|
||
|
||
## License
|
||
|
||
[MIT](LICENSE) | 基於 [C4illin/ConvertX](https://github.com/C4illin/ConvertX)
|