Elijah/convertor
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

feat: v0.1.9 - 全頁拖曳上傳 + i18n 修正 + 文件更新

Browse source 
✨ Features:
- 全頁拖曳上傳：檔案可拖曳到頁面任何位置上傳
- 原本的上傳框視覺效果保持不變

🌍 i18n:
- 刪除任務的 confirm/alert 訊息改用 i18n
- 隨語言切換即時更新顯示內容

📚 Documentation:
- README 新增「如何更新 ConvertX-CN 版本」章節
- 新增 deployment.md（Reverse Proxy、HTTPS）
- 新增 Docker Compose 範例分層
- 更新 environment-variables.md
This commit is contained in:
Your Name 2026-01-20 15:09:30 +08:00
parent a0eccf0437
commit a45a049fe2
14 changed files with 1475 additions and 167 deletions
Download patch file Download diff file Expand all files Collapse all files

349
README.md
View file

@ -31,51 +31,279 @@ ConvertX-CN 是基於 [C4illin/ConvertX](https://github.com/C4illin/ConvertX)
---
## 🚀 快速開始
## 📚 關於本文件
### 最快方式：Docker Run
> **📖 本 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
# 1. 建立資料夾
# 建立專案資料夾（可自訂位置）
mkdir -p ~/convertx-cn
cd ~/convertx-cn
# 建立 data 資料夾
mkdir -p data
# 2. 啟動容器
docker run -d \
--name convertx-cn \
-p 3000:3000 \
-v ./data:/app/data \
-e TZ=Asia/Taipei \
convertx/convertx-cn:latest
# 確認資料夾已建立
ls -la
# 應該看到 data 資料夾
```
開啟瀏覽器訪問 `http://localhost:3000`，**直接註冊帳號**即可使用！
#### Windows（PowerShell）
> ✅ **預設開放註冊**：無需設定環境變數，首次使用直接點擊 Register 註冊
```powershell
# 建立專案資料夾（可自訂位置）
mkdir C:\convertx-cn
cd C:\convertx-cn
### 推薦方式：Docker Compose
# 建立 data 資料夾
mkdir data
建立 `docker-compose.yml`：
# 確認資料夾已建立
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:latest
container_name: convertx-cn
restart: unless-stopped
ports:
- "3000:3000"
volumes:
- ./data:/app/data
environment:
- TZ=Asia/Taipei
- JWT_SECRET=your-secret-key-change-me
image: convertx/convertx-cn:v0.1.9 # 改成指定版本
```
然後執行：
```bash
docker compose down
docker compose pull
docker compose up -d
```
📖 完整部署指南請見 → [docs/getting-started.md](docs/getting-started.md)
### 驗證更新成功
開啟瀏覽器訪問 `http://localhost:3000`，頁面底部會顯示版本號。
---
## <20>🔧 進階設定
更多進階設定請參考：[docs/environment-variables.md](docs/environment-variables.md)
---
@ -83,13 +311,12 @@ docker compose up -d
ConvertX-CN 支援 **65 種語言**，包括：
| 區域 | 語言 |
| ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **東亞** | 繁體中文（預設）、简体中文、日本語、한국어 |
| **歐洲** | English, Deutsch, Français, Español, Italiano, Português, Русский, Polski, Nederlands, Українська, Čeština, Svenska, Dansk, Suomi, Norsk, Ελληνικά, Magyar, Română, Български, Hrvatski, Slovenčina, Slovenščina, Lietuvių, Latviešu, Eesti, Српски, Català, Euskara, Galego, Íslenska, Gaeilge, Cymraeg, Malti, Македонски, Shqip |
| **中東/南亞** | العربية, עברית, فارسی, Türkçe, हिन्दी, বাংলা, தமிழ், తెలుగు, मराठी, ગુજરાતી, ಕನ್ನಡ, മലയാളം, नेपाली, සිංහල |
| **東南亞** | ไทย, Tiếng Việt, Bahasa Indonesia, Bahasa Melayu, Filipino, မြန်မာ, ខ្មែរ, ລາວ |
| **非洲** | Afrikaans, Kiswahili, አማርኛ, isiZulu |
| 區域 | 語言 |
| ------------- | ------------------------------------------------ |
| **東亞** | 繁體中文（預設）、简体中文、日本語、한국어 |
| **歐洲** | English, Deutsch, Français, Español, Italiano 等 |
| **中東/南亞** | العربية, עברית, हिन्दी, தமிழ் 等 |
| **東南亞** | ไทย, Tiếng Việt, Bahasa Indonesia 等 |
語言會根據瀏覽器設定自動偵測，也可透過右上角選單手動切換。
@ -97,42 +324,42 @@ ConvertX-CN 支援 **65 種語言**，包括：
## 📦 內建轉換器
| 轉換器 | 用途 | 輸入格式 | 輸出格式 |
| -------------- | ------- | -------- | -------- |
| FFmpeg | 影音 | ~472 | ~199 |
| ImageMagick | 圖片 | 245 | 183 |
| GraphicsMagick | 圖片 | 167 | 130 |
| LibreOffice | 文件 | 41 | 22 |
| Pandoc | 文件 | 43 | 65 |
| Calibre | 電子書 | 26 | 19 |
| Inkscape | 向量圖 | 7 | 17 |
| Assimp | 3D 模型 | 77 | 23 |
| 轉換器 | 用途 | 支援格式數 |
| ----------- | ------ | ---------- |
| FFmpeg | 影音 | 400+ |
| ImageMagick | 圖片 | 200+ |
| LibreOffice | 文件 | 60+ |
| Pandoc | 文件 | 100+ |
| Calibre | 電子書 | 40+ |
| Inkscape | 向量圖 | 20+ |
完整列表 → [docs/converters.md](docs/converters.md)
---
## 📖 文件導覽
| 文件 | 說明 |
| -------------------------------------------- | ---------------------- |
| [🚀 快速開始](docs/getting-started.md) | Docker 部署教學 |
| [🐳 Docker 配置](docs/docker.md) | 完整 Docker 設定指南 |
| [⚙️ 環境變數](docs/environment-variables.md) | 所有環境變數說明 |
| [❓ 常見問題](docs/faq.md) | FAQ 疑難排解 |
| [🌍 多語言](docs/i18n.md) | i18n 語言設定與新增 |
| [📦 轉換器列表](docs/converters.md) | 支援的轉換格式完整列表 |
---
## 🐳 Docker Image
## 🐳 Docker Image 資訊
| Tag | 說明 |
| ----------------------------- | ---------- |
| `convertx/convertx-cn:latest` | 最新穩定版 |
| `convertx/convertx-cn:v0.1.5` | 指定版本 |
| `convertx/convertx-cn:v0.1.9` | 指定版本 |
> ⚠️ 由於內建完整依賴，Image 約 4-6 GB，首次下載需較長時間。
> ⚠️ **首次下載說明**
> 由於內建完整依賴（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/) | 各種情境的範例檔案 |
---
@ -142,7 +369,7 @@ ConvertX-CN 支援 **65 種語言**，包括：
---
## 🛠️ 開發
## 🛠️ 開發者資訊
```bash
# 安裝依賴
@ -163,10 +390,6 @@ bun run build
本專案基於 [C4illin/ConvertX](https://github.com/C4illin/ConvertX) 開發。
<a href="https://github.com/C4illin/ConvertX/graphs/contributors">
<img src="https://contrib.rocks/image?repo=C4illin/ConvertX" alt="Contributors" />
</a>
---
## 📜 License