Your Name 5322f85721 feat: 實作全域檔案傳輸機制與 .tar 封裝規範

## 主要變更

### 新增全域檔案傳輸模組 (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（僅傳輸層處理）

2026-01-21 13:58:01 +08:00

6.9 KiB

Raw Blame History

ConvertX-CN

開箱即用的全功能檔案轉換服務 — 一個 Docker 命令，5 分鐘部署完成

為什麼選擇 ConvertX-CN？

支援 1000+ 格式（影音、圖片、文件、電子書）
已內建 LibreOffice、FFmpeg、Pandoc 等 20+ 轉換器
預載中日韓字型與 OCR 語言包
支援 65 種介面語言

線上示範

想先試用再部署？歡迎使用我們的示範站：

🔗 https://convertx-cn.bioailab.qzz.io

項目	內容
範例帳號	admin@example.com
範例密碼	admin

⚠️ 示範站僅供測試，請勿上傳敏感檔案。資料可能定期清除。

快速啟動（Docker Run）

1. 建立資料夾

mkdir -p ~/convertx-cn/data && cd ~/convertx-cn

2. 啟動容器

JWT_SECRET=請改成你自己的隨機字串至少32字元

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. 開啟瀏覽器

  http://localhost:3000

首次下載約 4-6 GB，請耐心等待。

Docker Compose（推薦）

1. 建立專案資料夾

Linux / macOS

mkdir -p ~/convertx-cn && cd ~/convertx-cn

Windows PowerShell

mkdir C:\convertx-cn; cd C:\convertx-cn

Windows CMD

mkdir C:\convertx-cn
cd C:\convertx-cn

2. 建立 docker-compose.yml（在專案資料夾下）

範例內容（請修改 JWT_SECRET=請改成你自己的隨機字串至少32字元）：

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. 啟動：

docker compose up -d

更多範例 → 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

常見問題

問題	解法
登入後又被踢回登入頁	加上 `HTTP_ALLOWED=true` 或 `TRUST_PROXY=true`
重啟後資料消失	確認 `./data:/app/data` 且資料夾存在
重啟後被登出	設定固定的 `JWT_SECRET`

更多問題 → docs/faq.md

支援格式

轉換器	用途	格式數
FFmpeg	影音	400+
ImageMagick	圖片	200+
LibreOffice	文件	60+
Pandoc	文件	100+
Calibre	電子書	40+
Inkscape	向量圖	20+
MinerU	文件→MD	2

完整列表 → 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

版本與更新

docker compose down
docker compose pull
docker compose up -d

版本說明 → docs/versions/
更新指南 → docs/deployment/update.md
Changelog → CHANGELOG.md

API Server（選用）

如需以程式整合方式使用 ConvertX 的轉檔功能，可啟用 API Server。

⚠️ API Server 為選用功能，不影響現有 Web UI 的使用。若只使用網頁介面，無需任何額外設定。

功能特點

🔐 JWT 認證 — 安全的 API 存取控制
🌐 REST + GraphQL — 雙協議支援，滿足不同整合需求
🔍 智慧建議 — 轉換失敗時自動推薦替代引擎
🛠️ 20+ 轉換引擎 — 與 Web UI 共用完整轉換器套件

快速啟用

# 同時啟動 Web UI 與 API Server
docker compose --profile api up -d

服務	端口	說明
Web UI	3000	網頁介面
API Server	3001	REST & GraphQL

API 文件

詳細的 API 規格與使用說明：

進階文件

文件	說明
環境變數	所有可用參數
安全性設定	HTTP_ALLOWED、TRUST_PROXY
反向代理	Nginx / Traefik / Caddy
Docker 進階	自訂 Build
FAQ	疑難排解

預覽

License

MIT | 基於 C4illin/ConvertX

6.9 KiB Raw Blame History Unescape Escape