a45a049fe2
✨ Features: - 全頁拖曳上傳：檔案可拖曳到頁面任何位置上傳 - 原本的上傳框視覺效果保持不變 🌍 i18n: - 刪除任務的 confirm/alert 訊息改用 i18n - 隨語言切換即時更新顯示內容 📚 Documentation: - README 新增「如何更新 ConvertX-CN 版本」章節 - 新增 deployment.md（Reverse Proxy、HTTPS） - 新增 Docker Compose 範例分層 - 更新 environment-variables.md
404 lines
12 KiB
Markdown
404 lines
12 KiB
Markdown
|
||
|
||
# ConvertX-CN
|
||
|
||
**開箱即用的全功能檔案轉換服務** | **Self-hosted File Converter - Full Edition**
|
||
|
||
[](https://github.com/pi-docket/ConvertX-CN/actions/workflows/release.yml)
|
||
[](https://hub.docker.com/r/convertx/convertx-cn)
|
||
[](https://github.com/pi-docket/ConvertX-CN/releases)
|
||
[](LICENSE)
|
||
|
||
---
|
||
|
||
## ✨ 什麼是 ConvertX-CN？
|
||
|
||
ConvertX-CN 是基於 [C4illin/ConvertX](https://github.com/C4illin/ConvertX) 的**完整版 Fork**，專為中文使用者優化，並預載所有轉換依賴。
|
||
|
||
> 🎉 **一鍵部署，無需額外配置**
|
||
> 使用者 **不需要自己寫 Dockerfile**，直接 `docker run` 或 `docker compose up` 即可使用。
|
||
|
||
### 主要特色
|
||
|
||
| 特色 | 說明 |
|
||
| ------------------- | -------------------------------------------------- |
|
||
| 🌍 **65+ 語言支援** | 繁體中文、簡體中文、英文、日文、韓文等 65 種語言 |
|
||
| 📦 **完整內建** | LibreOffice、FFmpeg、Pandoc、Calibre 等 20+ 轉換器 |
|
||
| 🎨 **CJK 字型** | Noto CJK、微軟核心字型、標楷體等中日韓字型 |
|
||
| 🔤 **OCR 支援** | Tesseract + 多語言語言包 |
|
||
| ⚡ **LaTeX 完整版** | TexLive Full，支援所有 LaTeX 需求 |
|
||
| 🐳 **開箱即用** | 一個 Docker 命令即可啟動 |
|
||
|
||
---
|
||
|
||
## 📚 關於本文件
|
||
|
||
> **📖 本 README 定位為「新手教學入口」**
|
||
>
|
||
> 我們的 `docker-compose.yml` 範例**刻意保留完整註解**，而非極簡化：
|
||
>
|
||
> - ✅ 讓第一次用 Docker 的人也能成功部署
|
||
> - ✅ 透過註解說明每個設定的意義與風險
|
||
> - ✅ 避免新手踩雷（登入失敗、資料遺失等）
|
||
>
|
||
> 如果你是 Docker 老手，可直接使用 [精簡版範例](docs/docker-compose/compose.minimal.yml)。
|
||
|
||
---
|
||
|
||
## 🚀 新手完整部署教學（一步一步）
|
||
|
||
> ⚠️ **請務必按順序執行，不要跳過任何步驟！**
|
||
|
||
### 步驟 1：安裝 Docker
|
||
|
||
如果尚未安裝 Docker，請先安裝：
|
||
|
||
- **Windows / macOS**: 下載 [Docker Desktop](https://www.docker.com/products/docker-desktop/)
|
||
- **Linux**: 執行 `curl -fsSL https://get.docker.com | sh`
|
||
|
||
### 步驟 2：建立 data 資料夾（⚠️ 非常重要）
|
||
|
||
> 🚨 **這一步絕對不能跳過！**
|
||
>
|
||
> `data` 資料夾是用來存放：
|
||
>
|
||
> - 📁 上傳的檔案
|
||
> - 📁 轉換後的結果
|
||
> - 📁 使用者資料與設定
|
||
>
|
||
> **如果不先建立這個資料夾**，Docker 可能會建立「匿名 volume」，導致：
|
||
>
|
||
> - ❌ 容器刪除後資料全部消失
|
||
> - ❌ 無法在主機上找到轉換結果
|
||
> - ❌ 難以備份與遷移
|
||
|
||
**請根據你的作業系統執行對應指令：**
|
||
|
||
#### Linux / macOS
|
||
|
||
```bash
|
||
# 建立專案資料夾（可自訂位置）
|
||
mkdir -p ~/convertx-cn
|
||
cd ~/convertx-cn
|
||
|
||
# 建立 data 資料夾
|
||
mkdir -p data
|
||
|
||
# 確認資料夾已建立
|
||
ls -la
|
||
# 應該看到 data 資料夾
|
||
```
|
||
|
||
#### Windows（PowerShell）
|
||
|
||
```powershell
|
||
# 建立專案資料夾（可自訂位置）
|
||
mkdir C:\convertx-cn
|
||
cd C:\convertx-cn
|
||
|
||
# 建立 data 資料夾
|
||
mkdir data
|
||
|
||
# 確認資料夾已建立
|
||
dir
|
||
# 應該看到 data 資料夾
|
||
```
|
||
|
||
#### Windows（CMD）
|
||
|
||
```cmd
|
||
:: 建立專案資料夾（可自訂位置）
|
||
mkdir C:\convertx-cn
|
||
cd C:\convertx-cn
|
||
|
||
:: 建立 data 資料夾
|
||
mkdir data
|
||
|
||
:: 確認資料夾已建立
|
||
dir
|
||
:: 應該看到 data 資料夾
|
||
```
|
||
|
||
### 步驟 3：建立 docker-compose.yml
|
||
|
||
在剛才建立的資料夾中，建立 `docker-compose.yml` 檔案：
|
||
|
||
```yaml
|
||
# ==============================================================================
|
||
# ConvertX-CN 新手教學版 docker-compose.yml
|
||
#
|
||
# 📚 這份範例刻意保留完整註解，讓第一次用 Docker 的人也能成功部署
|
||
# ==============================================================================
|
||
|
||
services:
|
||
convertx:
|
||
# ===== 映像檔設定 =====
|
||
# convertx-cn 是完整版，已內建所有轉換工具（約 4-6 GB）
|
||
image: convertx/convertx-cn:latest
|
||
container_name: convertx-cn
|
||
restart: unless-stopped
|
||
|
||
# ===== 連接埠設定 =====
|
||
# 格式：「主機埠號:容器埠號」
|
||
# 若 3000 埠已被佔用，可改為 3001:3000、8080:3000 等
|
||
ports:
|
||
- "3000:3000"
|
||
|
||
# ===== 資料儲存（⚠️ 非常重要）=====
|
||
# ./data 是你主機上的實體資料夾
|
||
# /app/data 是容器內的路徑
|
||
#
|
||
# 🚨 注意事項：
|
||
# 1. 請務必先建立 data 資料夾（見上方步驟 2）
|
||
# 2. 這裡存放：上傳檔案、轉換結果、使用者資料
|
||
# 3. 若改用 Docker volume（如 convertx_data:/app/data），
|
||
# 資料會存在 Docker 內部，較難直接存取
|
||
volumes:
|
||
- ./data:/app/data
|
||
|
||
# ===== 環境變數設定 =====
|
||
environment:
|
||
# --- 時區設定 ---
|
||
# 影響檔案時間戳記與日期顯示
|
||
- TZ=Asia/Taipei
|
||
|
||
# --- JWT 密鑰（🔐 建議設定）---
|
||
# 用於使用者登入驗證的加密金鑰
|
||
# ⚠️ 若不設定：每次重啟容器後所有人都會被登出
|
||
# ⚠️ 正式使用請改成你自己的隨機字串！
|
||
- JWT_SECRET=請改成你自己的長隨機字串-至少32個字元
|
||
|
||
# --- 帳號註冊 ---
|
||
# true = 允許任何人註冊新帳號
|
||
# false = 關閉註冊（建議正式使用時設為 false）
|
||
# 💡 首次建立的帳號不受此限制
|
||
- ACCOUNT_REGISTRATION=true
|
||
|
||
# --- HTTP 存取設定 ---
|
||
# true = 允許非 HTTPS 連線（⚠️ 不安全，僅本地測試用）
|
||
# false = 必須 HTTPS（Cookie 才會正常運作）
|
||
#
|
||
# 🏠 本地測試（localhost）：設為 true
|
||
# 🌐 遠端部署（有 HTTPS）：設為 false
|
||
- HTTP_ALLOWED=true
|
||
|
||
# --- Reverse Proxy 設定 ---
|
||
# 若你透過 Nginx / Traefik / Cloudflare 等存取，設為 true
|
||
# 讓應用正確判斷連線是否為 HTTPS
|
||
- TRUST_PROXY=false
|
||
|
||
# --- 未登入存取 ---
|
||
# true = 允許未登入使用轉換功能（⚠️ 公開服務才開）
|
||
# false = 必須登入才能使用
|
||
- ALLOW_UNAUTHENTICATED=false
|
||
|
||
# --- 自動清理 ---
|
||
# 自動刪除超過 N 小時的轉換檔案（0 = 不自動刪除）
|
||
- AUTO_DELETE_EVERY_N_HOURS=24
|
||
```
|
||
|
||
### 步驟 4：啟動服務
|
||
|
||
```bash
|
||
# 啟動（首次會下載映像檔，約 4-6 GB，請耐心等待）
|
||
docker compose up -d
|
||
|
||
# 查看執行狀態
|
||
docker compose ps
|
||
|
||
# 查看 log（確認沒有錯誤）
|
||
docker compose logs -f
|
||
# 按 Ctrl+C 可退出 log 查看
|
||
```
|
||
|
||
### 步驟 5：開啟瀏覽器使用
|
||
|
||
1. 開啟瀏覽器，訪問 `http://localhost:3000`
|
||
2. 點擊 **Register** 註冊第一個帳號
|
||
3. 登入後即可開始轉換檔案！
|
||
|
||
> ✅ **首次註冊的帳號會自動成為管理員**
|
||
|
||
---
|
||
|
||
## ⚠️ 新手常見問題與解決方案
|
||
|
||
### 問題 1：登入後又被導回登入頁
|
||
|
||
**原因**：Cookie 無法正確設定（常見於遠端部署）
|
||
|
||
**解決方案**：
|
||
|
||
- 若使用 HTTP（無 HTTPS）：設定 `HTTP_ALLOWED=true`
|
||
- 若透過 Reverse Proxy：設定 `TRUST_PROXY=true`
|
||
|
||
### 問題 2：重啟容器後資料消失
|
||
|
||
**原因**：沒有正確掛載 volume
|
||
|
||
**解決方案**：
|
||
|
||
1. 確認已建立 `data` 資料夾
|
||
2. 確認 docker-compose.yml 中有 `./data:/app/data`
|
||
3. 不要使用 `docker run` 時忘記加 `-v ./data:/app/data`
|
||
|
||
### 問題 3：重啟後所有人被登出
|
||
|
||
**原因**：沒有設定 `JWT_SECRET`
|
||
|
||
**解決方案**：設定固定的 `JWT_SECRET` 環境變數
|
||
|
||
### 問題 4：3000 埠被佔用
|
||
|
||
**解決方案**：改用其他埠號，如 `"8080:3000"`
|
||
|
||
---
|
||
|
||
## <20> 如何更新 ConvertX-CN 版本
|
||
|
||
> 當有新版本發布時，請依照以下步驟更新。
|
||
|
||
### 使用 Docker Compose 更新（推薦）
|
||
|
||
```bash
|
||
# 1. 進入你的 ConvertX-CN 專案資料夾
|
||
cd ~/convertx-cn # 或你當初建立的位置
|
||
|
||
# 2. 停止目前執行中的服務
|
||
docker compose down
|
||
|
||
# 3. 拉取最新的映像檔
|
||
docker compose pull
|
||
|
||
# 4. 重新啟動服務
|
||
docker compose up -d
|
||
|
||
# 5. 確認版本（查看 log）
|
||
docker compose logs | head -20
|
||
```
|
||
|
||
### 更新到指定版本
|
||
|
||
如果你想更新到特定版本（例如 v0.1.9），請修改 `docker-compose.yml`：
|
||
|
||
```yaml
|
||
services:
|
||
convertx:
|
||
image: convertx/convertx-cn:v0.1.9 # 改成指定版本
|
||
```
|
||
|
||
然後執行：
|
||
|
||
```bash
|
||
docker compose down
|
||
docker compose pull
|
||
docker compose up -d
|
||
```
|
||
|
||
### 驗證更新成功
|
||
|
||
開啟瀏覽器訪問 `http://localhost:3000`，頁面底部會顯示版本號。
|
||
|
||
---
|
||
|
||
## <20>🔧 進階設定
|
||
|
||
更多進階設定請參考：[docs/environment-variables.md](docs/environment-variables.md)
|
||
|
||
---
|
||
|
||
## 🌍 語言支援
|
||
|
||
ConvertX-CN 支援 **65 種語言**，包括：
|
||
|
||
| 區域 | 語言 |
|
||
| ------------- | ------------------------------------------------ |
|
||
| **東亞** | 繁體中文（預設）、简体中文、日本語、한국어 |
|
||
| **歐洲** | English, Deutsch, Français, Español, Italiano 等 |
|
||
| **中東/南亞** | العربية, עברית, हिन्दी, தமிழ் 等 |
|
||
| **東南亞** | ไทย, Tiếng Việt, Bahasa Indonesia 等 |
|
||
|
||
語言會根據瀏覽器設定自動偵測，也可透過右上角選單手動切換。
|
||
|
||
---
|
||
|
||
## 📦 內建轉換器
|
||
|
||
| 轉換器 | 用途 | 支援格式數 |
|
||
| ----------- | ------ | ---------- |
|
||
| FFmpeg | 影音 | 400+ |
|
||
| ImageMagick | 圖片 | 200+ |
|
||
| LibreOffice | 文件 | 60+ |
|
||
| Pandoc | 文件 | 100+ |
|
||
| Calibre | 電子書 | 40+ |
|
||
| Inkscape | 向量圖 | 20+ |
|
||
|
||
完整列表 → [docs/converters.md](docs/converters.md)
|
||
|
||
---
|
||
|
||
## 🐳 Docker Image 資訊
|
||
|
||
| Tag | 說明 |
|
||
| ----------------------------- | ---------- |
|
||
| `convertx/convertx-cn:latest` | 最新穩定版 |
|
||
| `convertx/convertx-cn:v0.1.9` | 指定版本 |
|
||
|
||
> ⚠️ **首次下載說明**
|
||
> 由於內建完整依賴（LibreOffice、TexLive 等），映像檔約 **4-6 GB**。
|
||
> 首次 `docker pull` 需要較長時間，請耐心等待。
|
||
|
||
---
|
||
|
||
## 📖 更多文件
|
||
|
||
| 文件 | 說明 |
|
||
| ---------------------------------------------- | -------------------------- |
|
||
| [⚙️ 環境變數](docs/environment-variables.md) | 所有環境變數完整說明 |
|
||
| [🚀 進階部署](docs/deployment.md) | Reverse Proxy、HTTPS、生產 |
|
||
| [🐳 Docker 進階](docs/docker.md) | 自訂 Build、Image 說明 |
|
||
| [📦 轉換器列表](docs/converters.md) | 支援的格式完整列表 |
|
||
| [❓ 常見問題](docs/faq.md) | 更多疑難排解 |
|
||
| [📁 Docker Compose 範例](docs/docker-compose/) | 各種情境的範例檔案 |
|
||
|
||
---
|
||
|
||
## 📸 預覽
|
||
|
||
|
||
|
||
---
|
||
|
||
## 🛠️ 開發者資訊
|
||
|
||
```bash
|
||
# 安裝依賴
|
||
bun install
|
||
|
||
# 開發模式
|
||
bun run dev
|
||
|
||
# 建構
|
||
bun run build
|
||
```
|
||
|
||
歡迎 Pull Request！請使用 [Conventional Commits](https://www.conventionalcommits.org/) 格式。
|
||
|
||
---
|
||
|
||
## 🙏 致謝
|
||
|
||
本專案基於 [C4illin/ConvertX](https://github.com/C4illin/ConvertX) 開發。
|
||
|
||
---
|
||
|
||
## 📜 License
|
||
|
||
[MIT License](LICENSE)
|
||
|
||
---
|
||
|
||
<p align="center">
|
||
<b>Powered by ConvertX-CN</b><br>
|
||
<a href="https://github.com/pi-docket/ConvertX-CN">https://github.com/pi-docket/ConvertX-CN</a>
|
||
</p>
|