docs: README 重構 + i18n UI 規範 + 文件連結整理
README 改動: - 新增 Docker Run 快速啟動區塊 - 重新編排為 10 個標準區塊 - 加入作業系統資料夾提醒表格 - 精簡進階設定為連結列表 - 減少 emoji 使用 docs 改動: - i18n.md 新增語言選擇器 UI 規範 - getting-started.md 去重並加入返回連結 - 標題與連結一致化
This commit is contained in:
parent
bf8784ed82
commit
1a8548ff66
3 changed files with 133 additions and 57 deletions
144
README.md
144
README.md
|
|
@ -2,42 +2,47 @@
|
||||||
|
|
||||||
# ConvertX-CN
|
# ConvertX-CN
|
||||||
|
|
||||||
**開箱即用的全功能檔案轉換服務**
|
**開箱即用的全功能檔案轉換服務** — 一個 Docker 命令,5 分鐘部署完成
|
||||||
|
|
||||||
[](https://hub.docker.com/r/convertx/convertx-cn)
|
[](https://hub.docker.com/r/convertx/convertx-cn)
|
||||||
[](https://github.com/pi-docket/ConvertX-CN/releases)
|
[](https://github.com/pi-docket/ConvertX-CN/releases)
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 這是什麼?
|
## 為什麼選擇 ConvertX-CN?
|
||||||
|
|
||||||
自架的檔案轉換服務,支援 **1000+ 格式**,包含影音、圖片、文件、電子書等。
|
- 支援 **1000+ 格式**(影音、圖片、文件、電子書)
|
||||||
已內建 LibreOffice、FFmpeg、Pandoc 等 20+ 轉換器與中日韓字型,**一個 Docker 命令就能跑**。
|
- 已內建 LibreOffice、FFmpeg、Pandoc 等 20+ 轉換器
|
||||||
|
- 預載中日韓字型與 OCR 語言包
|
||||||
|
- 支援 65 種介面語言
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 快速部署
|
## 快速啟動(Docker Run)
|
||||||
|
|
||||||
### 1. 建立資料夾
|
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
|
# 1. 建立資料夾
|
||||||
mkdir -p ~/convertx-cn/data && cd ~/convertx-cn
|
mkdir -p ~/convertx-cn/data && cd ~/convertx-cn
|
||||||
|
|
||||||
|
# 2. 啟動容器
|
||||||
docker run -d \
|
docker run -d \
|
||||||
--name convertx-cn \
|
--name convertx-cn \
|
||||||
|
--restart unless-stopped \
|
||||||
-p 3000:3000 \
|
-p 3000:3000 \
|
||||||
-v ./data:/app/data \
|
-v ./data:/app/data \
|
||||||
-e JWT_SECRET=your-secret-key-at-least-32-chars \
|
-e TZ=Asia/Taipei \
|
||||||
|
-e JWT_SECRET=請改成你自己的隨機字串至少32字元 \
|
||||||
convertx/convertx-cn:latest
|
convertx/convertx-cn:latest
|
||||||
|
|
||||||
|
# 3. 開啟瀏覽器
|
||||||
|
# http://localhost:3000
|
||||||
```
|
```
|
||||||
|
|
||||||
開啟 `http://localhost:3000` 註冊即可使用。
|
> 首次下載約 4-6 GB,請耐心等待。
|
||||||
|
|
||||||
> Windows 用戶請先 `mkdir C:\convertx-cn\data`,並將 `./data` 改為 `C:\convertx-cn\data`
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## ✅ 推薦方式(Docker Compose)
|
## Docker Compose(推薦)
|
||||||
|
|
||||||
建立 `docker-compose.yml`:
|
建立 `docker-compose.yml`:
|
||||||
|
|
||||||
|
|
@ -53,67 +58,104 @@ services:
|
||||||
- ./data:/app/data
|
- ./data:/app/data
|
||||||
environment:
|
environment:
|
||||||
- TZ=Asia/Taipei
|
- TZ=Asia/Taipei
|
||||||
- JWT_SECRET=your-secret-key-at-least-32-chars
|
- JWT_SECRET=請改成你自己的隨機字串至少32字元
|
||||||
```
|
```
|
||||||
|
|
||||||
| 參數 | 說明 | 必要 |
|
啟動:
|
||||||
| ------------ | ---------------------------------- | ---- |
|
|
||||||
| `./data` | 存放檔案的資料夾,必須先建立 | ✅ |
|
|
||||||
| `JWT_SECRET` | 登入驗證金鑰,不設會每次重啟被登出 | ✅ |
|
|
||||||
| `TZ` | 時區(預設 UTC) | — |
|
|
||||||
|
|
||||||
### 3. 啟動
|
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
docker compose up -d
|
docker compose up -d
|
||||||
```
|
```
|
||||||
|
|
||||||
| 參數 | 說明 |
|
更多範例 → [docs/docker-compose/](docs/docker-compose/)
|
||||||
| ------------ | ------------------ |
|
|
||||||
| `./data` | 資料夾,需先建立 |
|
|
||||||
| `JWT_SECRET` | 登入金鑰,必須設定 |
|
|
||||||
|
|
||||||
首次下載約 4-6 GB。
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 支援格式
|
## 重要:資料夾說明
|
||||||
|
|
||||||
| 類型 | 轉換器 | 格式數 |
|
`./data` 是你**主機上的實體資料夾**,用於存放上傳檔案、轉換結果與使用者資料。
|
||||||
| ------ | -------------------------- | ------ |
|
|
||||||
| 影音 | FFmpeg | 400+ |
|
|
||||||
| 圖片 | ImageMagick, libvips | 200+ |
|
|
||||||
| 文件 | LibreOffice, Pandoc | 150+ |
|
|
||||||
| 電子書 | Calibre | 40+ |
|
|
||||||
| 向量圖 | Inkscape, resvg, Potrace | 20+ |
|
|
||||||
| 資料 | Dasel (JSON/YAML/TOML/XML) | 10+ |
|
|
||||||
|
|
||||||
完整列表 → [docs/converters.md](docs/converters.md)
|
| 作業系統 | 建立指令 |
|
||||||
|
| ------------- | ----------------------------- |
|
||||||
|
| 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` |
|
| 登入後又被踢回登入頁 | 加上 `HTTP_ALLOWED=true` 或 `TRUST_PROXY=true` |
|
||||||
| 資料消失 | 確認 `./data:/app/data` 已掛載 |
|
| 重啟後資料消失 | 確認 `./data:/app/data` 且資料夾存在 |
|
||||||
| 重啟後登出 | 設定固定 `JWT_SECRET` |
|
| 重啟後被登出 | 設定固定的 `JWT_SECRET` |
|
||||||
|
|
||||||
更多 → [docs/faq.md](docs/faq.md)
|
更多問題 → [docs/faq.md](docs/faq.md)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 支援格式
|
||||||
|
|
||||||
|
| 轉換器 | 用途 | 格式數 |
|
||||||
|
| ----------- | ------ | ------ |
|
||||||
|
| FFmpeg | 影音 | 400+ |
|
||||||
|
| ImageMagick | 圖片 | 200+ |
|
||||||
|
| LibreOffice | 文件 | 60+ |
|
||||||
|
| Pandoc | 文件 | 100+ |
|
||||||
|
| Calibre | 電子書 | 40+ |
|
||||||
|
| Inkscape | 向量圖 | 20+ |
|
||||||
|
|
||||||
|
完整列表 → [docs/converters.md](docs/converters.md)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 語言支援
|
||||||
|
|
||||||
|
支援 **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)
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 進階文件
|
## 進階文件
|
||||||
|
|
||||||
| 主題 | 連結 |
|
| 文件 | 說明 |
|
||||||
| ---------------- | -------------------------------------------------------- |
|
| -------------------------------------- | ------------------------- |
|
||||||
| 環境變數 | [docs/config/environment.md](docs/config/environment.md) |
|
| [環境變數](docs/config/environment.md) | 所有可用參數 |
|
||||||
| 安全性設定 | [docs/config/security.md](docs/config/security.md) |
|
| [安全性設定](docs/config/security.md) | HTTP_ALLOWED、TRUST_PROXY |
|
||||||
| 反向代理 / HTTPS | [docs/deployment.md](docs/deployment.md) |
|
| [反向代理](docs/deployment.md) | Nginx / Traefik / Caddy |
|
||||||
| Docker Compose | [docs/docker-compose/](docs/docker-compose/) |
|
| [Docker 進階](docs/docker.md) | 自訂 Build |
|
||||||
| 版本選擇 | [docs/versions/](docs/versions/) |
|
| [FAQ](docs/faq.md) | 疑難排解 |
|
||||||
| 更新方法 | [docs/deployment/update.md](docs/deployment/update.md) |
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
|
|
@ -123,4 +165,6 @@ docker compose up -d
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
|
## License
|
||||||
|
|
||||||
[MIT](LICENSE) | 基於 [C4illin/ConvertX](https://github.com/C4illin/ConvertX)
|
[MIT](LICENSE) | 基於 [C4illin/ConvertX](https://github.com/C4illin/ConvertX)
|
||||||
|
|
|
||||||
|
|
@ -1,5 +1,9 @@
|
||||||
# 快速開始
|
# 快速開始
|
||||||
|
|
||||||
|
> 本文件提供完整部署步驟。若只需最快啟動,請參考 [README](../README.md)。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
## 系統需求
|
## 系統需求
|
||||||
|
|
||||||
| 需求 | 最低 | 建議 |
|
| 需求 | 最低 | 建議 |
|
||||||
|
|
@ -11,26 +15,28 @@
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 事前準備(可選)
|
## 事前準備
|
||||||
|
|
||||||
如果您想預先建立資料夾結構:
|
建立資料夾(重要):
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
mkdir -p data
|
mkdir -p ~/convertx-cn/data && cd ~/convertx-cn
|
||||||
```
|
```
|
||||||
|
|
||||||
> 💡 Docker 會自動建立 `data` 資料夾,此步驟為可選
|
> `data` 資料夾是主機上的實體資料夾,用於存放上傳檔案與轉換結果。
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 最快方式:一行指令
|
## 最快方式:Docker Run
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
docker run -d \
|
docker run -d \
|
||||||
--name convertx-cn \
|
--name convertx-cn \
|
||||||
|
--restart unless-stopped \
|
||||||
-p 3000:3000 \
|
-p 3000:3000 \
|
||||||
-v ./data:/app/data \
|
-v ./data:/app/data \
|
||||||
-e TZ=Asia/Taipei \
|
-e TZ=Asia/Taipei \
|
||||||
|
-e JWT_SECRET=你的隨機字串至少32字元 \
|
||||||
convertx/convertx-cn:latest
|
convertx/convertx-cn:latest
|
||||||
```
|
```
|
||||||
|
|
||||||
|
|
@ -40,8 +46,6 @@ docker run -d \
|
||||||
2. 輸入 Email 和密碼
|
2. 輸入 Email 和密碼
|
||||||
3. 完成!開始使用
|
3. 完成!開始使用
|
||||||
|
|
||||||
> ✅ **預設開放註冊**,無需設定環境變數
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 推薦方式:Docker Compose
|
## 推薦方式:Docker Compose
|
||||||
|
|
|
||||||
28
docs/i18n.md
28
docs/i18n.md
|
|
@ -213,6 +213,34 @@ bun run dev
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
|
## 語言選擇器 UI 規範
|
||||||
|
|
||||||
|
為確保語言切換體驗一致,ConvertX-CN 的語言選擇器遵循以下規範:
|
||||||
|
|
||||||
|
### 視覺設計
|
||||||
|
|
||||||
|
| 項目 | 規範 |
|
||||||
|
| ------------ | ----------------------------- |
|
||||||
|
| 圖示大小 | 與旁邊文字高度一致(h-6 w-6) |
|
||||||
|
| 下拉選單背景 | 完全不透明(bg-neutral-800) |
|
||||||
|
| 捲動條 | 明確可見的 scrollbar 樣式 |
|
||||||
|
| 最大高度 | 320px,超過則顯示捲動條 |
|
||||||
|
|
||||||
|
### 行為規範
|
||||||
|
|
||||||
|
- Setup / Login / 主頁使用同一套語言選擇器組件
|
||||||
|
- 語言切換後自動重新載入頁面
|
||||||
|
- 語言偏好儲存於 Cookie,跨頁面保持一致
|
||||||
|
- 預設根據瀏覽器語言自動偵測
|
||||||
|
|
||||||
|
### 已知問題修復(v0.1.9)
|
||||||
|
|
||||||
|
- 語言圖示尺寸過小 → 已修復
|
||||||
|
- 下拉選單半透明 → 已修復
|
||||||
|
- 捲動條不明顯 → 已新增 scrollbar 樣式
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
## 翻譯 Fallback
|
## 翻譯 Fallback
|
||||||
|
|
||||||
如果某個翻譯鍵缺失,系統會:
|
如果某個翻譯鍵缺失,系統會:
|
||||||
|
|
|
||||||
Loading…
Add table
Add a link
Reference in a new issue