feat: v0.1.9 - Setup 頁面 i18n + 語言選擇器 UI 修復 + 文件重構
✨ Features: - 全頁拖曳上傳：檔案可拖曳到頁面任何位置 - Setup 頁面新增語言選擇器 🐛 Bug Fixes: - 語言 icon 尺寸修復（h-5→h-6） - Dropdown 背景完全不透明 - 新增 scrollbar 樣式 🌍 i18n: - 所有 confirm/alert 訊息國際化 - Setup 頁面 i18n 完整化 📚 Documentation: - README 精簡為開箱即用版本 - 新增 docs/deployment/, docs/config/, docs/versions/
This commit is contained in:
Your Name
parent
a45a049fe2
commit
d563682753
14 changed files with 1305 additions and 594 deletions
377
README.md
377
README.md
|
|
@ -2,403 +2,110 @@
|
|||
|
||||
# ConvertX-CN
|
||||
|
||||
**開箱即用的全功能檔案轉換服務** | **Self-hosted File Converter - Full Edition**
|
||||
**開箱即用的全功能檔案轉換服務** — 5 分鐘完成部署
|
||||
|
||||
[](https://github.com/pi-docket/ConvertX-CN/actions/workflows/release.yml)
|
||||
[](https://hub.docker.com/r/convertx/convertx-cn)
|
||||
[](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 命令即可啟動 |
|
||||
自架的檔案轉換服務，支援 **1000+ 格式**，包含影音、圖片、文件、電子書等。
|
||||
已內建 LibreOffice、FFmpeg、Pandoc 等 20+ 轉換器與中日韓字型，**一個 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
|
||||
### 1. 建立資料夾
|
||||
|
||||
```bash
|
||||
# 建立專案資料夾（可自訂位置）
|
||||
mkdir -p ~/convertx-cn
|
||||
cd ~/convertx-cn
|
||||
|
||||
# 建立 data 資料夾
|
||||
mkdir -p data
|
||||
|
||||
# 確認資料夾已建立
|
||||
ls -la
|
||||
# 應該看到 data 資料夾
|
||||
mkdir -p ~/convertx-cn/data && cd ~/convertx-cn
|
||||
```
|
||||
|
||||
#### Windows（PowerShell）
|
||||
> Windows 請用 `mkdir C:\convertx-cn\data` 並 `cd C:\convertx-cn`
|
||||
|
||||
```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` 檔案：
|
||||
### 2. 建立 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
|
||||
- JWT_SECRET=請改成你自己的隨機字串至少32字元
|
||||
```
|
||||
|
||||
### 步驟 4：啟動服務
|
||||
| 參數 | 說明 | 必要 |
|
||||
| ------------ | ---------------------------------- | ---- |
|
||||
| `./data` | 存放檔案的資料夾，必須先建立 | ✅ |
|
||||
| `JWT_SECRET` | 登入驗證金鑰，不設會每次重啟被登出 | ✅ |
|
||||
| `TZ` | 時區（預設 UTC） | — |
|
||||
|
||||
### 3. 啟動
|
||||
|
||||
```bash
|
||||
# 啟動（首次會下載映像檔，約 4-6 GB，請耐心等待）
|
||||
docker compose up -d
|
||||
|
||||
# 查看執行狀態
|
||||
docker compose ps
|
||||
|
||||
# 查看 log（確認沒有錯誤）
|
||||
docker compose logs -f
|
||||
# 按 Ctrl+C 可退出 log 查看
|
||||
```
|
||||
|
||||
### 步驟 5：開啟瀏覽器使用
|
||||
首次下載約 4-6 GB，需等待幾分鐘。
|
||||
|
||||
1. 開啟瀏覽器，訪問 `http://localhost:3000`
|
||||
2. 點擊 **Register** 註冊第一個帳號
|
||||
3. 登入後即可開始轉換檔案！
|
||||
### 4. 使用
|
||||
|
||||
> ✅ **首次註冊的帳號會自動成為管理員**
|
||||
開啟 `http://localhost:3000`，註冊帳號即可使用。
|
||||
|
||||
---
|
||||
|
||||
## ⚠️ 新手常見問題與解決方案
|
||||
## 常見問題
|
||||
|
||||
### 問題 1：登入後又被導回登入頁
|
||||
| 問題 | 解法 |
|
||||
| -------------------- | --------------------------------------------------------------------- |
|
||||
| 登入後又被踢回登入頁 | 設定 `HTTP_ALLOWED=true`（本地測試）或 `TRUST_PROXY=true`（反向代理） |
|
||||
| 重啟後資料消失 | 確認 `./data:/app/data` 且資料夾存在 |
|
||||
| 重啟後被登出 | 設定固定的 `JWT_SECRET` |
|
||||
|
||||
**原因**：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"`
|
||||
更多問題 → [docs/faq.md](docs/faq.md)
|
||||
|
||||
---
|
||||
|
||||
## <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
|
||||
cd ~/convertx-cn
|
||||
docker compose down
|
||||
docker compose pull
|
||||
docker compose up -d
|
||||
```
|
||||
|
||||
### 驗證更新成功
|
||||
|
||||
開啟瀏覽器訪問 `http://localhost:3000`，頁面底部會顯示版本號。
|
||||
詳細說明 → [docs/deployment/update.md](docs/deployment/update.md)
|
||||
|
||||
---
|
||||
|
||||
## <20>🔧 進階設定
|
||||
## 進階設定
|
||||
|
||||
更多進階設定請參考：[docs/environment-variables.md](docs/environment-variables.md)
|
||||
| 需求 | 文件 |
|
||||
| ------------------- | -------------------------------------------------------- |
|
||||
| 完整環境變數 | [docs/config/environment.md](docs/config/environment.md) |
|
||||
| 反向代理 / HTTPS | [docs/deployment.md](docs/deployment.md) |
|
||||
| 安全性設定 | [docs/config/security.md](docs/config/security.md) |
|
||||
| Docker Compose 範例 | [docs/docker-compose/](docs/docker-compose/) |
|
||||
| 版本選擇指南 | [docs/versions/](docs/versions/) |
|
||||
|
||||
---
|
||||
|
||||
## 🌍 語言支援
|
||||
|
||||
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/) | 各種情境的範例檔案 |
|
||||
|
||||
---
|
||||
|
||||
## 📸 預覽
|
||||
## 預覽
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
## 🛠️ 開發者資訊
|
||||
## License
|
||||
|
||||
```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>
|
||||
[MIT](LICENSE) | 基於 [C4illin/ConvertX](https://github.com/C4illin/ConvertX)
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue