e5ca364563
- Add MinerU converter engine (src/converters/mineru.ts) - Support md-t (table as Markdown) and md-i (table as image) output formats - Input formats: pdf, ppt, pptx, xls, xlsx, doc, docx - Output as ZIP archive containing Markdown and images - Update Dockerfile to install magic-pdf via pipx - Add zip utility for archive creation - Update normalizeFiletype to map md-t/md-i to zip extension - Add comprehensive tests for MinerU converter - Update README with MinerU documentation
264 lines
6.4 KiB
Markdown
264 lines
6.4 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 內建 MinerU 轉換引擎，可將文件轉換為 Markdown。
|
||
|
||
- md-t
|
||
- md-i
|
||
|
||
輸出格式為 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)
|