Add comprehensive documentation for ConvertX-CN deployment and configuration
- Create 指定版本部署.md to explain fixed version deployment - Create 最新版.md detailing the use of the latest tag - Create 版本選擇指南.md to guide users on version selection - Add Nginx and Traefik configuration examples for reverse proxy - Introduce minimal and production configuration examples - Develop Docker deployment guide with detailed steps - Implement quick start guide for first-time Docker users - Include version update instructions and rollback procedures - Add troubleshooting section for common issues - Enhance overall documentation structure and links for better navigation
This commit is contained in:
Your Name
parent
c2d3d13c89
commit
3f1a5e0fbf
51 changed files with 544 additions and 579 deletions
296
docs/Docker說明.md
Normal file
296
docs/Docker說明.md
Normal file
|
|
@ -0,0 +1,296 @@
|
|||
# Docker 配置指南
|
||||
|
||||
> ⚠️ **此文件已遷移**
|
||||
>
|
||||
> 本文件內容已整合至新的文件結構，請參閱：
|
||||
>
|
||||
> - 📦 [Docker 部署指南](部署指南/Docker部署.md)
|
||||
> - 🔧 [反向代理設定](部署指南/反向代理.md)
|
||||
>
|
||||
> 此文件將在未來版本中移除。
|
||||
|
||||
---
|
||||
|
||||
## Docker Image 版本說明
|
||||
|
||||
ConvertX-CN 提供兩種 Docker Image 選項：
|
||||
|
||||
### 1. 官方 Image（推薦）
|
||||
|
||||
從 Docker Hub 拉取的預建 Image，適合大多數使用者。
|
||||
|
||||
| Tag | 說明 |
|
||||
| ----------------------------- | ---------- |
|
||||
| `convertx/convertx-cn:latest` | 最新穩定版 |
|
||||
| `convertx/convertx-cn:v0.1.9` | 指定版本號 |
|
||||
|
||||
**內建功能：**
|
||||
|
||||
- ✅ 核心轉換工具（FFmpeg、LibreOffice、ImageMagick 等）
|
||||
- ✅ OCR 支援：英文、繁/簡中文、日文、韓文、德文、法文
|
||||
- ✅ 字型：Noto CJK、Liberation、自訂中文字型
|
||||
- ✅ TexLive 最小集合（支援 CJK/德/法）
|
||||
|
||||
**Image 大小：約 4-6 GB**
|
||||
|
||||
### 2. 完整版（自行 Build）
|
||||
|
||||
使用 `Dockerfile.full` 自行建構，適合需要：
|
||||
|
||||
- 65 種 OCR 語言
|
||||
- 完整 TexLive
|
||||
- 額外字型套件
|
||||
|
||||
**⚠️ 注意事項：**
|
||||
|
||||
- Image 大小可能超過 **10GB**
|
||||
- Build 時間約 **30-60 分鐘**
|
||||
- 需要自行維護更新
|
||||
|
||||
```bash
|
||||
# 自行建構完整版
|
||||
docker build -f Dockerfile.full -t convertx-cn-full .
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 自訂 Build 指南（進階使用者）
|
||||
|
||||
如果官方 Image 不符合需求，可以使用 `Dockerfile.full` 自行建構：
|
||||
|
||||
### 步驟
|
||||
|
||||
1. **複製 Dockerfile.full**
|
||||
|
||||
```bash
|
||||
cp Dockerfile.full Dockerfile.custom
|
||||
```
|
||||
|
||||
2. **取消註解需要的功能**
|
||||
- 編輯 `Dockerfile.custom`
|
||||
- 找到需要的功能區塊
|
||||
- 移除 `#` 註解符號
|
||||
|
||||
3. **建構 Image**
|
||||
```bash
|
||||
docker build -f Dockerfile.custom -t convertx-cn-custom .
|
||||
```
|
||||
|
||||
### 可選功能
|
||||
|
||||
| 功能 | 預估大小 | 說明 |
|
||||
| --------------- | -------- | ---------------- |
|
||||
| 完整 TexLive | +3GB | 完整 LaTeX 支援 |
|
||||
| 全部 OCR 語言 | +2GB | 65 種語言辨識 |
|
||||
| Noto Extra 字型 | +500MB | 全球語言字型 |
|
||||
| 歐洲 OCR 語言 | +200MB | 25 種歐洲語言 |
|
||||
| 中東/南亞 OCR | +150MB | 阿拉伯、印度語系 |
|
||||
| 東南亞 OCR | +100MB | 泰、越、印尼等 |
|
||||
|
||||
### 範例：僅加入西班牙文 OCR
|
||||
|
||||
```dockerfile
|
||||
# 在 Dockerfile.full 中取消以下註解：
|
||||
RUN apt-get update && apt-get install -y --no-install-recommends \
|
||||
tesseract-ocr-spa \
|
||||
&& rm -rf /var/lib/apt/lists/*
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Docker Run
|
||||
|
||||
基本啟動命令：
|
||||
|
||||
```bash
|
||||
docker run -d \
|
||||
--name convertx-cn \
|
||||
-p 3000:3000 \
|
||||
-v ./data:/app/data \
|
||||
-e TZ=Asia/Taipei \
|
||||
-e ACCOUNT_REGISTRATION=true \
|
||||
convertx/convertx-cn:latest
|
||||
```
|
||||
|
||||
### 參數說明
|
||||
|
||||
| 參數 | 說明 |
|
||||
| --------------------- | ---------- |
|
||||
| `-d` | 背景執行 |
|
||||
| `--name convertx-cn` | 容器名稱 |
|
||||
| `-p 3000:3000` | 連接埠映射 |
|
||||
| `-v ./data:/app/data` | 資料持久化 |
|
||||
| `-e TZ=Asia/Taipei` | 時區設定 |
|
||||
|
||||
---
|
||||
|
||||
## Docker Compose
|
||||
|
||||
### 基本配置
|
||||
|
||||
```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=your-very-long-random-secret-key
|
||||
- ACCOUNT_REGISTRATION=true
|
||||
```
|
||||
|
||||
### 生產環境配置
|
||||
|
||||
```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=${JWT_SECRET}
|
||||
- ACCOUNT_REGISTRATION=false
|
||||
- HTTP_ALLOWED=false
|
||||
- AUTO_DELETE_EVERY_N_HOURS=24
|
||||
deploy:
|
||||
resources:
|
||||
limits:
|
||||
memory: 4G
|
||||
reservations:
|
||||
memory: 2G
|
||||
```
|
||||
|
||||
### 使用 Traefik 反向代理
|
||||
|
||||
```yaml
|
||||
services:
|
||||
convertx:
|
||||
image: convertx/convertx-cn:latest
|
||||
container_name: convertx-cn
|
||||
restart: unless-stopped
|
||||
volumes:
|
||||
- ./data:/app/data
|
||||
environment:
|
||||
- TZ=Asia/Taipei
|
||||
- JWT_SECRET=${JWT_SECRET}
|
||||
- ACCOUNT_REGISTRATION=false
|
||||
labels:
|
||||
- "traefik.enable=true"
|
||||
- "traefik.http.routers.convertx.rule=Host(`convert.example.com`)"
|
||||
- "traefik.http.routers.convertx.entrypoints=websecure"
|
||||
- "traefik.http.routers.convertx.tls.certresolver=letsencrypt"
|
||||
- "traefik.http.services.convertx.loadbalancer.server.port=3000"
|
||||
networks:
|
||||
- traefik
|
||||
|
||||
networks:
|
||||
traefik:
|
||||
external: true
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 資料持久化
|
||||
|
||||
### Volume 結構
|
||||
|
||||
```
|
||||
./data/
|
||||
├── uploads/ # 上傳的原始檔案
|
||||
├── output/ # 轉換後的檔案
|
||||
└── convertx.db # SQLite 資料庫
|
||||
```
|
||||
|
||||
### 備份
|
||||
|
||||
```bash
|
||||
# 備份資料
|
||||
docker cp convertx-cn:/app/data ./backup-$(date +%Y%m%d)
|
||||
|
||||
# 還原資料
|
||||
docker cp ./backup-20240101/. convertx-cn:/app/data/
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 更新
|
||||
|
||||
### Docker Compose
|
||||
|
||||
```bash
|
||||
docker compose pull
|
||||
docker compose up -d
|
||||
```
|
||||
|
||||
### Docker Run
|
||||
|
||||
```bash
|
||||
docker pull convertx/convertx-cn:latest
|
||||
docker stop convertx-cn
|
||||
docker rm convertx-cn
|
||||
docker run -d ... # 使用原本的參數
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 健康檢查
|
||||
|
||||
ConvertX-CN 提供健康檢查端點：
|
||||
|
||||
```bash
|
||||
curl http://localhost:3000/healthcheck
|
||||
```
|
||||
|
||||
可在 Docker Compose 中配置：
|
||||
|
||||
```yaml
|
||||
services:
|
||||
convertx:
|
||||
# ...
|
||||
healthcheck:
|
||||
test: ["CMD", "curl", "-f", "http://localhost:3000/healthcheck"]
|
||||
interval: 30s
|
||||
timeout: 10s
|
||||
retries: 3
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 故障排除
|
||||
|
||||
### 記憶體不足
|
||||
|
||||
如果遇到 OOM（記憶體不足），請增加容器記憶體限制：
|
||||
|
||||
```yaml
|
||||
deploy:
|
||||
resources:
|
||||
limits:
|
||||
memory: 8G
|
||||
```
|
||||
|
||||
### 連接埠衝突
|
||||
|
||||
如果 3000 埠被占用，可更改映射：
|
||||
|
||||
```bash
|
||||
-p 8080:3000 # 使用 8080 埠
|
||||
```
|
||||
|
||||
### 權限問題
|
||||
|
||||
確保 data 目錄有正確權限：
|
||||
|
||||
```bash
|
||||
chmod -R 777 ./data
|
||||
```
|
||||
Loading…
Add table
Add a link
Reference in a new issue