# 快速開始

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

---

## 目錄

- [前置需求](#前置需求)
- [Docker Run（最快）](#docker-run最快)
- [Docker Compose（推薦）](#docker-compose推薦)
- [首次登入](#首次登入)
- [範例：轉換檔案](#範例轉換檔案)
- [下一步](#下一步)

---

## 前置需求

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

> 💡 **提示**：Windows 使用者請確保已安裝 [Docker Desktop](https://docs.docker.com/desktop/install/windows-install/)

---

## Docker Run（最快）

### 步驟 1：建立資料夾

```bash
# 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：啟動容器

```bash
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：建立專案資料夾

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

### 步驟 2：建立配置檔

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

### 步驟 3：啟動服務

```bash
docker compose up -d
```

### 步驟 4：驗證安裝

```bash
# 檢查容器狀態
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-錯誤排查與支援](06-錯誤排查與支援.md)

---

## 下一步

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

---

[⬆️ 回到頂部](#快速開始) | [📚 回到目錄](00-專案總覽.md)