新增錯誤排查與支援文件，提供常見問題解決方案；新增開發與貢獻指南，說明專案結構與開發流程；新增授權說明文件，詳述AGPL-3.0授權條款及第三方元件使用情況。
This commit is contained in:
Your Name
parent
11d751250b
commit
caecb2e001
13 changed files with 3269 additions and 369 deletions
229
docs/01-快速開始.md
Normal file
229
docs/01-快速開始.md
Normal file
|
|
@ -0,0 +1,229 @@
|
|||
# 快速開始
|
||||
|
||||
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)
|
||||
Loading…
Add table
Add a link
Reference in a new issue