convertor/docs/getting-started.md

快速開始

本文件提供完整部署步驟。若只需最快啟動，請參考 README。

---

系統需求

需求	最低	建議
Docker	20.10+	24.0+
RAM	4 GB	8 GB
磁碟空間	10 GB	20 GB
CPU	2 核心	4 核心

---

事前準備

建立資料夾（重要）：

mkdir -p ~/convertx-cn/data && cd ~/convertx-cn

data 資料夾是主機上的實體資料夾，用於存放上傳檔案與轉換結果。

---

最快方式：Docker Run

docker run -d \
  --name convertx-cn \
  --restart unless-stopped \
  -p 3000:3000 \
  -v ./data:/app/data \
  -e TZ=Asia/Taipei \
  -e JWT_SECRET=你的隨機字串至少32字元 \
  convertx/convertx-cn:latest

開啟瀏覽器訪問 http://localhost:3000：

1. 點擊右上角 Register 註冊帳號
2. 輸入 Email 和密碼
3. 完成！開始使用

---

推薦方式：Docker Compose

1. 建立配置檔

建立 docker-compose.yml：

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=請更換為一個長且隨機的字串
      - HTTP_ALLOWED=false
      - AUTO_DELETE_EVERY_N_HOURS=24

2. 啟動服務

docker compose up -d

3. 開始使用

1. 開啟瀏覽器訪問 http://localhost:3000
2. 點擊「Register」建立帳號
3. 登入後即可開始轉換檔案！

---

首次設定

建立管理員帳號

首次訪問時，ConvertX-CN 會顯示設定頁面，讓您建立第一個帳號。此帳號即為管理員。

註冊功能

• ACCOUNT_REGISTRATION=true：允許其他人註冊
• ACCOUNT_REGISTRATION=false：停用註冊（單人使用）

---

驗證安裝

檢查容器狀態

docker ps
# 應該看到 convertx-cn 容器正在運行

docker logs convertx-cn
# 應該看到 "🦊 Elysia is running at http://localhost:3000"

健康檢查

curl http://localhost:3000/healthcheck
# 應該返回 "OK"

---

更新版本

# Docker Compose
docker compose pull
docker compose up -d

# 或 Docker Run
docker pull convertx/convertx-cn:latest
docker stop convertx-cn
docker rm convertx-cn
# 然後重新執行 docker run 指令

---

常見問題

無法訪問頁面

1. 確認容器正在運行：docker ps
2. 檢查連接埠是否被占用：netstat -an | grep 3000
3. 查看錯誤日誌：docker logs convertx-cn

權限錯誤

# 確保 data 目錄有正確權限
chmod -R 777 ./data

記憶體不足

ConvertX-CN 內建完整依賴，建議至少 4GB RAM。可透過 Docker 限制記憶體使用：

deploy:
  resources:
    limits:
      memory: 4G

---

下一步

• 📖 Docker 配置 - 進階 Docker 設定
• ⚙️ 環境變數 - 所有可用設定
• 🔧 進階用法 - 硬體加速、反向代理
• 🌍 多語言 - 語言設定與自訂