Elijah/convertor
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Refactor Docker Compose examples and documentation

Browse source 
- Updated README.md to include new example files for minimal and production configurations with detailed instructions.
- Added compose.production-alt.example.yml for an annotated production setup.
- Introduced new example files: compose.minimal.example.yml, compose.production.example.yml, nginx.example.conf, and traefik.example.yml for better clarity and usability.
- Removed outdated configuration files and consolidated documentation for OCR language support.
- Adjusted Nginx and Traefik configurations to reflect best practices and added necessary comments for user guidance.
- Minor formatting and consistency improvements across documentation files.
This commit is contained in:
Your Name 2026-01-24 00:36:58 +08:00
parent f6b45627e0
commit 8a84caa503
14 changed files with 175 additions and 821 deletions
Download patch file Download diff file Expand all files Collapse all files

81
docs/Docker組合配置/README.md
View file

@ -4,45 +4,68 @@
## 範例檔案
| 檔案 | 適用情境 | 說明 |
| ------------------------------------------------ | ----------- | --------------------- |
| [compose.minimal.yml](compose.minimal.yml) | Docker 老手 | 最精簡的可用配置 |
| [compose.production.yml](compose.production.yml) | 生產環境 | 含 Reverse Proxy 設定 |
| [compose.reference.yml](compose.reference.yml) | 參考文件 | 所有設定的完整參考 |
| 檔案 | 適用情境 | 說明 |
| ------------------------------------------------------------------------ | ----------- | --------------------- |
| [compose.minimal.yml](compose.minimal.yml) | Docker 老手 | 最精簡的可用配置 |
| [compose.production.yml](compose.production.yml) | 生產環境 | 含 Reverse Proxy 設定 |
| [compose.production-alt.example.yml](compose.production-alt.example.yml) | 生產環境 | 詳細註解版本 |
| [compose.reference.yml](compose.reference.yml) | 參考文件 | 所有設定的完整參考 |
| [compose.ocr-languages.yml](compose.ocr-languages.yml) | OCR 擴展 | 安裝額外 OCR 語言包 |
| [OCR語言擴展.md](OCR語言擴展.md) | 詳細指南 | OCR 語言擴展完整說明 |
## 快速選擇
| 你是... | 使用 |
| ------------ | ----------------------------- |
| 新手 | [README 主頁](../說明文件.md) |
| Docker 熟手 | compose.minimal.yml |
| 生產環境 | compose.production.yml |
| 查詢所有選項 | compose.reference.yml |
| 你是... | 使用 |
| ----------------- | -------------------------------------------- |
| 新手 | [README 主頁](../說明文件.md) |
| Docker 熟手 | compose.minimal.yml |
| 生產環境 | compose.production.yml |
| 查詢所有選項 | compose.reference.yml |
| 需要更多 OCR 語言 | [OCR語言擴展.md](OCR語言擴展.md)（詳細指南） |
## 如何使用
## 快速開始
### 最小配置
```bash
# 下載範例
curl -O https://raw.githubusercontent.com/pi-docket/ConvertX-CN/main/docs/docker-compose/compose.minimal.yml
# 1. 複製範例
cp compose.minimal.yml docker-compose.yml
# 重命名
mv compose.minimal.yml docker-compose.yml
# 建立 data 資料夾
# 2. 建立資料夾
mkdir -p data
# 修改 JWT_SECRET
nano docker-compose.yml
# 3. 修改以下欄位：
# - JWT_SECRET（至少 32 字元隨機字串）
# 啟動
# 4. 啟動
docker compose up -d
```
### 生產環境
```bash
# 1. 複製範例
cp compose.production.yml docker-compose.yml
# 2. 建立資料夾
mkdir -p data
# 3. 修改以下欄位：
# - JWT_SECRET（至少 32 字元隨機字串）
# 4. 啟動
docker compose up -d
```
> 💡 產生隨機 JWT_SECRET：`openssl rand -hex 32`
## 相關文件
- [Docker Compose 詳解](../部署指南/Docker組合.md)
- [環境變數說明](../配置設定/環境變數.md)
- [版本選擇指南](../版本/)
- [Docker 部署指南](../部署指南/Docker部署.md)
- [反向代理設定](../部署指南/反向代理.md)
### 我要部署到正式環境
@ -56,8 +79,16 @@ docker compose up -d
參考 [compose.reference.yml](compose.reference.yml)，包含所有環境變數的說明。
## 相關文件
### 我需要更多 OCR 語言支援
- [環境變數完整說明](../配置設定/環境變數.md)
- [Docker 部署指南](../部署指南/Docker部署.md)
- [反向代理設定](../部署指南/反向代理.md)
參考 [OCR語言擴展.md](OCR語言擴展.md)，這是完整的 OCR 語言擴展指南，包含：
- 三種擴展方法的詳細說明與比較
- 完整的 compose.yaml 範例配置
- 50+ 種可用語言包列表
- 語言包下載與驗證方法
- 常見問題解答
> 💡 內建 OCR 語言：英文、繁體中文、簡體中文、日文、韓文、德文、法文
>
> 翻譯引擎支援 15 種語言，但 OCR 預設只內建 8 種

2
docs/Docker組合配置/compose.ocr-languages.yml
View file

@ -24,7 +24,7 @@ services:
# =========================================================================
# 使用自訂 entrypoint 安裝額外語言包
# =========================================================================
entrypoint: [ "/bin/sh", "-c" ]
entrypoint: ["/bin/sh", "-c"]
command:
- |
echo "📦 正在安裝額外 OCR 語言包..."

20
docs/Docker組合配置/生產環境配置.yml → docs/Docker組合配置/compose.production-alt.example.yml
View file

@ -1,15 +1,19 @@
# ==============================================================================
# ConvertX-CN 生產環境 Docker Compose
# ConvertX-CN 生產環境 Docker Compose（詳細註解版）
#
# 適用情境：
# - 透過 Reverse Proxy（Nginx / Traefik / Caddy）存取
# - 已設定 HTTPS
# - 需要限制註冊與存取
#
# ⚠️ 使用前請確認：
# 1. 已建立 data 資料夾
# 2. 已將 JWT_SECRET 改成你自己的值
# 3. 已設定好 Reverse Proxy
# 使用方式：
# 1. cp compose.production-alt.example.yml docker-compose.yml
# 2. mkdir -p data
# 3. 修改 JWT_SECRET（必填）
# 4. docker compose up -d
#
# 必須修改的欄位：
# - JWT_SECRET
# ==============================================================================
services:
@ -28,9 +32,9 @@ services:
environment:
# === 必填設定 ===
# 🔐 JWT 密鑰：請務必改成你自己的隨機字串（至少 32 字元）
# 可用 openssl rand -hex 32 產生
- JWT_SECRET=change-me-to-a-very-long-random-string-at-least-32-characters
# ⚠️ JWT 密鑰：請務必改成你自己的隨機字串（至少 32 字元）
# 產生方式：openssl rand -hex 32
- JWT_SECRET=YOUR_JWT_SECRET_HERE
# === 安全設定 ===
# 關閉註冊（首次帳號仍可建立）

74
docs/Docker組合配置/說明文件.md
View file

@ -1,74 +0,0 @@
# Docker Compose 範例檔案
本資料夾提供不同情境的 Docker Compose 範例。
## 範例檔案
| 檔案 | 適用情境 | 說明 |
| ------------------------------------------------------ | ----------- | --------------------- |
| [compose.minimal.yml](compose.minimal.yml) | Docker 老手 | 最精簡的可用配置 |
| [compose.production.yml](compose.production.yml) | 生產環境 | 含 Reverse Proxy 設定 |
| [compose.reference.yml](compose.reference.yml) | 參考文件 | 所有設定的完整參考 |
| [compose.ocr-languages.yml](compose.ocr-languages.yml) | OCR 擴展 | 安裝額外 OCR 語言包 |
| [OCR語言擴展.md](OCR語言擴展.md) | 詳細指南 | OCR 語言擴展完整說明 |
## 快速選擇
| 你是... | 使用 |
| ----------------- | -------------------------------------------- |
| 新手 | [README 主頁](../說明文件.md) |
| Docker 熟手 | compose.minimal.yml |
| 生產環境 | compose.production.yml |
| 查詢所有選項 | compose.reference.yml |
| 需要更多 OCR 語言 | [OCR語言擴展.md](OCR語言擴展.md)（詳細指南） |
## 如何使用
```bash
# 下載範例
curl -O https://raw.githubusercontent.com/pi-docket/ConvertX-CN/main/docs/Docker組合配置/compose.minimal.yml
# 重命名
mv compose.minimal.yml docker-compose.yml
# 建立 data 資料夾
mkdir -p data
# 修改 JWT_SECRET
nano docker-compose.yml
# 啟動
docker compose up -d
```
## 相關文件
- [Docker Compose 詳解](../部署指南/Docker組合.md)
- [環境變數說明](../配置設定/環境變數.md)
- [版本選擇指南](../版本/)
### 我要部署到正式環境
使用 [compose.production.yml](compose.production.yml)，包含：
- Reverse Proxy 設定說明
- 安全性設定建議
- HTTPS 配置範例
### 我想了解所有設定
參考 [compose.reference.yml](compose.reference.yml)，包含所有環境變數的說明。
### 我需要更多 OCR 語言支援
參考 [OCR語言擴展.md](OCR語言擴展.md)，這是完整的 OCR 語言擴展指南，包含：
- 三種擴展方法的詳細說明與比較
- 完整的 compose.yaml 範例配置
- 50+ 種可用語言包列表
- 語言包下載與驗證方法
- 常見問題解答
> 💡 內建 OCR 語言：英文、繁體中文、簡體中文、日文、韓文、德文、法文
>
> 翻譯引擎支援 15 種語言，但 OCR 預設只內建 8 種

23
docs/範例配置/compose.minimal.example.yml Normal file
View file

@ -0,0 +1,23 @@
# ConvertX-CN 最小配置
# 適用於：快速測試、個人使用
#
# 使用方式：
# 1. cp compose.minimal.example.yml docker-compose.yml
# 2. mkdir -p data
# 3. 修改 JWT_SECRET（必填）
# 4. docker compose up -d
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
# ⚠️ 必填：請更換為長且隨機的字串（至少 32 字元）
# 產生方式：openssl rand -hex 32
- JWT_SECRET=YOUR_JWT_SECRET_HERE

2
docs/範例配置/compose.ocr-languages.yml
View file

@ -24,7 +24,7 @@ services:
# =========================================================================
# 使用自訂 entrypoint 安裝額外語言包
# =========================================================================
entrypoint: [ "/bin/sh", "-c" ]
entrypoint: ["/bin/sh", "-c"]
command:
- |
echo "📦 正在安裝額外 OCR 語言包..."

16
docs/範例配置/生產環境配置.yml → docs/範例配置/compose.production.example.yml
View file

@ -1,5 +1,14 @@
# ConvertX-CN 生產環境配置
# 適用於：正式部署
# 適用於：正式部署（搭配反向代理）
#
# 使用方式：
# 1. cp compose.production.example.yml docker-compose.yml
# 2. mkdir -p data
# 3. 修改 JWT_SECRET（必填）
# 4. docker compose up -d
#
# 必須修改的欄位：
# - JWT_SECRET
services:
convertx:
@ -11,8 +20,9 @@ services:
volumes:
- ./data:/app/data
environment:
# 必填：登入驗證金鑰（至少 32 字元）
- JWT_SECRET=${JWT_SECRET:?請設定 JWT_SECRET}
# ⚠️ 必填：請更換為長且隨機的字串（至少 32 字元）
# 產生方式：openssl rand -hex 32
- JWT_SECRET=YOUR_JWT_SECRET_HERE
# 時區
- TZ=Asia/Taipei

17
docs/範例配置/Nginx範例配置.conf → docs/範例配置/nginx.example.conf
View file

@ -1,11 +1,20 @@
# ConvertX-CN Nginx 反向代理配置範例
# 檔案位置：/etc/nginx/sites-available/convertx
#
# 使用方式：
# 1. 複製到 /etc/nginx/sites-available/convertx
# 2. 將 YOUR_DOMAIN_HERE 替換為你的網域
# 3. ln -s /etc/nginx/sites-available/convertx /etc/nginx/sites-enabled/
# 4. sudo nginx -t && sudo systemctl reload nginx
#
# 必須修改的欄位：
# - YOUR_DOMAIN_HERE（共 5 處）
# HTTP → HTTPS 重導向
server {
listen 80;
listen [::]:80;
server_name convertx.example.com;
server_name YOUR_DOMAIN_HERE;
# Let's Encrypt 驗證
location /.well-known/acme-challenge/ {
@ -22,11 +31,11 @@ server {
server {
listen 443 ssl http2;
listen [::]:443 ssl http2;
server_name convertx.example.com;
server_name YOUR_DOMAIN_HERE;
# SSL 憑證（Let's Encrypt）
ssl_certificate /etc/letsencrypt/live/convertx.example.com/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/convertx.example.com/privkey.pem;
ssl_certificate /etc/letsencrypt/live/YOUR_DOMAIN_HERE/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/YOUR_DOMAIN_HERE/privkey.pem;
# SSL 設定（安全強化）
ssl_protocols TLSv1.2 TLSv1.3;

18
docs/範例配置/Traefik配置.yml → docs/範例配置/traefik.example.yml
View file

@ -1,5 +1,16 @@
# ConvertX-CN + Traefik 配置
# 適用於：使用 Traefik 作為反向代理
#
# 使用方式：
# 1. 確保已有 Traefik 服務且建立 traefik-network
# 2. 複製此檔案並重命名為 docker-compose.yml
# 3. 將 YOUR_DOMAIN_HERE 替換為你的網域
# 4. 將 YOUR_JWT_SECRET_HERE 替換為隨機字串
# 5. docker compose up -d
#
# 必須修改的欄位：
# - YOUR_JWT_SECRET_HERE
# - YOUR_DOMAIN_HERE（共 2 處）
services:
convertx:
@ -9,7 +20,8 @@ services:
volumes:
- ./data:/app/data
environment:
- JWT_SECRET=${JWT_SECRET:?請設定 JWT_SECRET}
# ⚠️ 必填：請更換為長且隨機的字串（至少 32 字元）
- JWT_SECRET=YOUR_JWT_SECRET_HERE
- TZ=Asia/Taipei
- HTTP_ALLOWED=false
- TRUST_PROXY=true
@ -17,11 +29,11 @@ services:
labels:
- "traefik.enable=true"
# HTTP 路由
- "traefik.http.routers.convertx.rule=Host(`convertx.example.com`)"
- "traefik.http.routers.convertx.rule=Host(`YOUR_DOMAIN_HERE`)"
- "traefik.http.routers.convertx.entrypoints=web"
- "traefik.http.routers.convertx.middlewares=https-redirect"
# HTTPS 路由
- "traefik.http.routers.convertx-secure.rule=Host(`convertx.example.com`)"
- "traefik.http.routers.convertx-secure.rule=Host(`YOUR_DOMAIN_HERE`)"
- "traefik.http.routers.convertx-secure.entrypoints=websecure"
- "traefik.http.routers.convertx-secure.tls=true"
- "traefik.http.routers.convertx-secure.tls.certresolver=letsencrypt"

15
docs/範例配置/最小配置.yml
View file

@ -1,15 +0,0 @@
# ConvertX-CN 最小配置
# 適用於：快速測試、個人使用
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字元

65
docs/範例配置/說明文件.md
View file

@ -6,46 +6,53 @@
## 範例檔案
| 檔案 | 用途 | 說明 |
| --------------------------- | ------------ | ----------------- |
| `最小配置.yml` | 快速啟動 | 最精簡配置 |
| `生產環境配置.yml` | 生產環境 | 包含安全設定 |
| `compose.ocr-languages.yml` | OCR 語言擴展 | 安裝額外 OCR 語言 |
| `Traefik配置.yml` | 反向代理 | Traefik 整合 |
| `Nginx範例配置.conf` | Nginx 設定 | 反向代理設定範例 |
| 檔案 | 用途 | 說明 |
| -------------------------------- | ------------ | ----------------- |
| `compose.minimal.example.yml` | 快速啟動 | 最精簡配置 |
| `compose.production.example.yml` | 生產環境 | 包含安全設定 |
| `compose.ocr-languages.yml` | OCR 語言擴展 | 安裝額外 OCR 語言 |
| `traefik.example.yml` | 反向代理 | Traefik 整合 |
| `nginx.example.conf` | Nginx 設定 | 反向代理設定範例 |
---
## 如何使用
## 快速開始
### 1. 下載範例
### 最小配置（測試 / 個人使用）
```bash
# 下載最小配置
curl -O https://raw.githubusercontent.com/pi-docket/ConvertX-CN/main/docs/samples/compose.minimal.yml
# 1. 複製範例
cp compose.minimal.example.yml docker-compose.yml
# 重命名
mv compose.minimal.yml docker-compose.yml
```
### 2. 修改設定
```bash
# 編輯配置
nano docker-compose.yml
# 重點修改：
# - JWT_SECRET
# - TZ
```
### 3. 啟動
```bash
# 2. 建立資料夾
mkdir -p data
# 3. 修改以下欄位：
# - JWT_SECRET（至少 32 字元隨機字串）
# 4. 啟動
docker compose up -d
```
### 生產環境配置
```bash
# 1. 複製範例
cp compose.production.example.yml docker-compose.yml
# 2. 建立資料夾
mkdir -p data
# 3. 修改以下欄位：
# - JWT_SECRET（至少 32 字元隨機字串）
# - TZ（時區，預設 Asia/Taipei）
# 4. 啟動
docker compose up -d
```
> 💡 產生隨機 JWT_SECRET：`openssl rand -hex 32`
---
## 相關文件

8
docs/說明文件.md
View file

@ -113,10 +113,10 @@ docs/
│ ├── 本地開發.md
│ └── 貢獻指南.md
└── 範例配置/
├── 最小配置.yml
├── 生產環境配置.yml
├── Traefik配置.yml
└── Nginx範例配置.conf
├── compose.minimal.example.yml
├── compose.production.example.yml
├── traefik.example.yml
└── nginx.example.conf
```
---