![ConvertX-CN](images/logo.png)

# ConvertX-CN

**開箱即用的全功能檔案轉換服務** | **Self-hosted File Converter - Full Edition**

[![Docker](https://github.com/pi-docket/ConvertX-CN/actions/workflows/release.yml/badge.svg)](https://github.com/pi-docket/ConvertX-CN/actions/workflows/release.yml)
[![Docker Pulls](https://img.shields.io/docker/pulls/convertx/convertx-cn?style=flat&logo=docker&label=Docker%20Hub)](https://hub.docker.com/r/convertx/convertx-cn)
[![GitHub Release](https://img.shields.io/github/v/release/pi-docket/ConvertX-CN)](https://github.com/pi-docket/ConvertX-CN/releases)
[![License](https://img.shields.io/github/license/pi-docket/ConvertX-CN)](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"`

---

## � 如何更新 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`，頁面底部會顯示版本號。

---

## �🔧 進階設定

更多進階設定請參考：[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/) | 各種情境的範例檔案         |

---

## 📸 預覽

![ConvertX-CN Preview](images/preview.png)

---

## 🛠️ 開發者資訊

```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>