convertor/docs/01-快速開始.md

快速開始

5 分鐘內完成 ConvertX-CN 部署，開始轉換檔案。

---

目錄

• 前置需求
• Docker Run（最快）
• Docker Compose（推薦）
• 首次登入
• 範例：轉換檔案
• 下一步

---

前置需求

需求	最低規格	建議規格
Docker	20.10+	24.0+
記憶體	4 GB	8 GB
磁碟空間	10 GB	30 GB
作業系統	Linux / macOS / Windows	Linux

💡 提示：Windows 使用者請確保已安裝 Docker Desktop

---

Docker Run（最快）

步驟 1：建立資料夾

# Linux / macOS
mkdir -p ~/convertx-cn/data && cd ~/convertx-cn

# Windows PowerShell
mkdir C:\convertx-cn\data -Force; cd C:\convertx-cn

# Windows CMD
mkdir C:\convertx-cn\data
cd C:\convertx-cn

步驟 2：啟動容器

docker run -d \
  --name convertx-cn \
  --restart unless-stopped \
  -p 3000:3000 \
  -v ./data:/app/data \
  -e TZ=Asia/Taipei \
  -e JWT_SECRET=Xk9mPqL2vN7wR4tY6uI8oA3sD5fG1hJ0 \
  convertx/convertx-cn:latest

⚠️ 安全提醒：正式環境請更換 JWT_SECRET 為自己的隨機字串（至少 32 字元）

步驟 3：開始使用

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

---

Docker Compose（推薦）

步驟 1：建立專案資料夾

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

步驟 2：建立配置檔

建立 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=請更換為一個長且隨機的字串至少32字元

步驟 3：啟動服務

docker compose up -d

步驟 4：驗證安裝

# 檢查容器狀態
docker ps

# 查看日誌
docker logs convertx-cn

應該看到類似輸出：

🦊 Elysia is running at http://localhost:3000

---

首次登入

1. 開啟瀏覽器，訪問 http://localhost:3000

2. 點擊右上角 Register（註冊）

3. 輸入您的 Email 和密碼

4. 完成註冊後自動登入

登入流程圖示

┌─────────────────────────────────────────────────────────────┐
│                    ConvertX-CN                               │
│                                                              │
│   ┌──────────────────────────────────────────────────────┐  │
│   │                                                       │  │
│   │     📧 Email: user@example.com                        │  │
│   │                                                       │  │
│   │     🔒 Password: ••••••••••                          │  │
│   │                                                       │  │
│   │     [ Register ]  [ Login ]                          │  │
│   │                                                       │  │
│   └──────────────────────────────────────────────────────┘  │
│                                                              │
└─────────────────────────────────────────────────────────────┘

---

範例：轉換檔案

範例 1：Word 轉 PDF

1. 點擊「選擇檔案」或拖放 .docx 檔案
2. 選擇輸出格式：PDF
3. 點擊「轉換」
4. 下載轉換後的 PDF 檔案

輸入：

report.docx (Microsoft Word 文件)

輸出：

report.pdf (PDF 文件)

範例 2：影片轉換

1. 上傳 .mov 影片檔案
2. 選擇輸出格式：MP4
3. 點擊「轉換」

輸入：

video.mov (QuickTime 影片, 500 MB)

輸出：

video.mp4 (MP4 影片, 壓縮後約 200 MB)

範例 3：PDF 翻譯（保留公式）

1. 上傳學術論文 PDF
2. 選擇「PDF 翻譯」功能
3. 選擇目標語言：繁體中文
4. 點擊「翻譯」

輸入：

paper.pdf (英文學術論文，含數學公式)

輸出：

paper_translated.pdf (中文翻譯，公式與排版保留)

---

常見問題快查

問題	解決方法
登入後被踢回登入頁	加上 HTTP_ALLOWED=true 或 TRUST_PROXY=true
重啟後資料消失	確認 ./data:/app/data 且資料夾存在
重啟後被登出	設定固定的 JWT_SECRET
中文顯示亂碼	使用一般版或 Full 版（含完整字型）
轉換時間過長	增加容器記憶體限制或升級硬體

📖 更多問題請參閱 06-錯誤排查與支援

---

下一步

需求	推薦閱讀
詳細部署設定	02-部署指南
環境變數設定	03-環境變數與設定
了解所有功能	04-功能總覽
API 整合	05-API文件

---

⬆️ 回到頂部 | 📚 回到目錄