feat(i18n): add multilingual support with translations for English, Japanese, and Simplified Chinese
- Create README.md for internationalization (i18n) documentation - Add English translation for main README and quick start guide - Add Japanese translation for main README - Add Simplified Chinese translation for main README - Introduce sample Docker Compose configurations for various deployment scenarios - Implement CI/CD documentation for testing and deployment workflows - Establish end-to-end testing guidelines and strategies - Create test strategy documentation outlining unit, integration, and E2E tests
This commit is contained in:
Your Name
parent
b3b382d1e0
commit
da856d89ff
42 changed files with 4901 additions and 263 deletions
271
docs/configuration/environment-variables.md
Normal file
271
docs/configuration/environment-variables.md
Normal file
|
|
@ -0,0 +1,271 @@
|
|||
# 環境變數設定
|
||||
|
||||
本文件列出 ConvertX-CN 所有可用的環境變數。
|
||||
|
||||
---
|
||||
|
||||
## 快速參考
|
||||
|
||||
| 優先級 | 變數 | 說明 | 預設值 |
|
||||
| ------ | -------------- | ------------ | ------------------ |
|
||||
| 必填 | `JWT_SECRET` | 登入驗證金鑰 | 隨機（每次重啟變） |
|
||||
| 建議 | `TZ` | 時區 | `UTC` |
|
||||
| 建議 | `HTTP_ALLOWED` | 允許 HTTP | `false` |
|
||||
| 可選 | `TRUST_PROXY` | 信任反向代理 | `false` |
|
||||
|
||||
---
|
||||
|
||||
## 必填設定
|
||||
|
||||
### JWT_SECRET
|
||||
|
||||
用於簽署登入驗證的密鑰。**強烈建議設定**。
|
||||
|
||||
| 項目 | 值 |
|
||||
| ------ | ---------------------- |
|
||||
| 預設值 | 每次重啟隨機產生 |
|
||||
| 建議值 | 至少 32 字元的隨機字串 |
|
||||
|
||||
不設定的話，每次容器重啟後所有使用者都需要重新登入。
|
||||
|
||||
**產生方式：**
|
||||
|
||||
```bash
|
||||
# Linux / macOS
|
||||
openssl rand -hex 32
|
||||
|
||||
# Windows PowerShell
|
||||
-join ((1..32) | ForEach-Object { '{0:x2}' -f (Get-Random -Max 256) })
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 網路與安全
|
||||
|
||||
### HTTP_ALLOWED
|
||||
|
||||
允許非 HTTPS 連線。
|
||||
|
||||
| 項目 | 值 |
|
||||
| ------ | ------- |
|
||||
| 預設值 | `false` |
|
||||
|
||||
| 情境 | 設定值 |
|
||||
| --------------------- | ------- |
|
||||
| 本地測試 (localhost) | `true` |
|
||||
| 有 HTTPS | `false` |
|
||||
| 無 HTTPS 但需遠端存取 | `true` |
|
||||
|
||||
> ⚠️ 設為 `false` 但用 HTTP 存取會導致「登入後又被導回登入頁」
|
||||
|
||||
### TRUST_PROXY
|
||||
|
||||
信任反向代理的 headers。
|
||||
|
||||
| 項目 | 值 |
|
||||
| ------ | ------- |
|
||||
| 預設值 | `false` |
|
||||
|
||||
| 情境 | 設定值 |
|
||||
| ---------------------------- | ------- |
|
||||
| 直接存取容器 | `false` |
|
||||
| 透過 Nginx / Traefik / Caddy | `true` |
|
||||
| 透過 Cloudflare Tunnel | `true` |
|
||||
|
||||
### ACCOUNT_REGISTRATION
|
||||
|
||||
是否允許註冊新帳號。
|
||||
|
||||
| 項目 | 值 |
|
||||
| ------ | ------ |
|
||||
| 預設值 | `true` |
|
||||
|
||||
建議建立管理員帳號後改為 `false`。
|
||||
|
||||
### ALLOW_UNAUTHENTICATED
|
||||
|
||||
是否允許未登入使用轉換功能。
|
||||
|
||||
| 項目 | 值 |
|
||||
| ------ | ------- |
|
||||
| 預設值 | `false` |
|
||||
|
||||
> ⚠️ 設為 `true` 有安全風險：任何人都可使用伺服器資源
|
||||
|
||||
---
|
||||
|
||||
## 一般設定
|
||||
|
||||
### TZ
|
||||
|
||||
時區設定，影響日期顯示。
|
||||
|
||||
| 項目 | 值 |
|
||||
| ------ | ----- |
|
||||
| 預設值 | `UTC` |
|
||||
|
||||
常用值：
|
||||
|
||||
| 地區 | 值 |
|
||||
| ---- | ---------------- |
|
||||
| 台灣 | `Asia/Taipei` |
|
||||
| 中國 | `Asia/Shanghai` |
|
||||
| 香港 | `Asia/Hong_Kong` |
|
||||
| 日本 | `Asia/Tokyo` |
|
||||
|
||||
### AUTO_DELETE_EVERY_N_HOURS
|
||||
|
||||
自動刪除超過 N 小時的檔案。
|
||||
|
||||
| 項目 | 值 |
|
||||
| ------ | ---- |
|
||||
| 預設值 | `24` |
|
||||
| 停用 | `0` |
|
||||
|
||||
---
|
||||
|
||||
## 介面設定
|
||||
|
||||
### WEBROOT
|
||||
|
||||
子路徑部署前綴。
|
||||
|
||||
| 項目 | 值 |
|
||||
| ------ | --- |
|
||||
| 預設值 | 空 |
|
||||
|
||||
若透過 `https://example.com/convertx/` 存取：
|
||||
|
||||
```yaml
|
||||
- WEBROOT=/convertx
|
||||
```
|
||||
|
||||
### HIDE_HISTORY
|
||||
|
||||
隱藏歷史紀錄頁面。
|
||||
|
||||
| 項目 | 值 |
|
||||
| ------ | ------- |
|
||||
| 預設值 | `false` |
|
||||
|
||||
### LANGUAGE
|
||||
|
||||
介面語言。
|
||||
|
||||
| 項目 | 值 |
|
||||
| ------ | ------ |
|
||||
| 預設值 | `auto` |
|
||||
|
||||
設為特定語言代碼（如 `zh-TW`）可強制使用該語言。
|
||||
|
||||
---
|
||||
|
||||
## 轉換設定
|
||||
|
||||
### MAX_CONVERT_PROCESS
|
||||
|
||||
最大同時轉換數。
|
||||
|
||||
| 項目 | 值 |
|
||||
| ------ | ------------- |
|
||||
| 預設值 | `0`（無限制） |
|
||||
|
||||
限制同時進行的轉換任務數量，避免伺服器過載。
|
||||
|
||||
### FFMPEG_ARGS
|
||||
|
||||
FFmpeg 輸入參數，用於硬體加速。
|
||||
|
||||
```yaml
|
||||
# NVIDIA GPU
|
||||
- FFMPEG_ARGS=-hwaccel cuda
|
||||
|
||||
# Intel QSV
|
||||
- FFMPEG_ARGS=-hwaccel qsv
|
||||
|
||||
# AMD VAAPI
|
||||
- FFMPEG_ARGS=-hwaccel vaapi
|
||||
```
|
||||
|
||||
### FFMPEG_OUTPUT_ARGS
|
||||
|
||||
FFmpeg 輸出參數。
|
||||
|
||||
```yaml
|
||||
# 使用 NVIDIA 編碼器
|
||||
- FFMPEG_OUTPUT_ARGS=-c:v h264_nvenc -preset fast
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## PDFMathTranslate 設定
|
||||
|
||||
### PDFMATHTRANSLATE_SERVICE
|
||||
|
||||
翻譯服務提供商。
|
||||
|
||||
| 項目 | 值 |
|
||||
| ------ | -------- |
|
||||
| 預設值 | `google` |
|
||||
|
||||
可選值：`google`, `deepl`, `openai` 等
|
||||
|
||||
### PDFMATHTRANSLATE_MODELS_PATH
|
||||
|
||||
模型路徑。
|
||||
|
||||
| 項目 | 值 |
|
||||
| ------ | -------------------------- |
|
||||
| 預設值 | `/models/pdfmathtranslate` |
|
||||
|
||||
---
|
||||
|
||||
## 情境範例
|
||||
|
||||
### 開發環境
|
||||
|
||||
```yaml
|
||||
environment:
|
||||
- TZ=Asia/Taipei
|
||||
- HTTP_ALLOWED=true
|
||||
- ACCOUNT_REGISTRATION=true
|
||||
```
|
||||
|
||||
### 生產環境
|
||||
|
||||
```yaml
|
||||
environment:
|
||||
- JWT_SECRET=your-very-long-and-random-secret-key-change-me
|
||||
- TZ=Asia/Taipei
|
||||
- HTTP_ALLOWED=false
|
||||
- TRUST_PROXY=true
|
||||
- ACCOUNT_REGISTRATION=false
|
||||
- AUTO_DELETE_EVERY_N_HOURS=24
|
||||
```
|
||||
|
||||
### 公開服務（允許匿名）
|
||||
|
||||
```yaml
|
||||
environment:
|
||||
- ALLOW_UNAUTHENTICATED=true
|
||||
- HIDE_HISTORY=true
|
||||
- AUTO_DELETE_EVERY_N_HOURS=1
|
||||
- MAX_CONVERT_PROCESS=2
|
||||
```
|
||||
|
||||
### 硬體加速
|
||||
|
||||
```yaml
|
||||
environment:
|
||||
- JWT_SECRET=your-secret-key
|
||||
- FFMPEG_ARGS=-hwaccel cuda
|
||||
- FFMPEG_OUTPUT_ARGS=-c:v h264_nvenc -preset fast
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 相關文件
|
||||
|
||||
- [安全性設定](security.md)
|
||||
- [Docker 部署](../deployment/docker.md)
|
||||
- [反向代理設定](../deployment/reverse-proxy.md)
|
||||
196
docs/configuration/limits-and-cleanup.md
Normal file
196
docs/configuration/limits-and-cleanup.md
Normal file
|
|
@ -0,0 +1,196 @@
|
|||
# 清理與限制設定
|
||||
|
||||
本文件說明如何設定檔案自動清理與資源限制。
|
||||
|
||||
---
|
||||
|
||||
## 檔案自動清理
|
||||
|
||||
### AUTO_DELETE_EVERY_N_HOURS
|
||||
|
||||
自動刪除超過指定時間的檔案。
|
||||
|
||||
| 項目 | 值 |
|
||||
| ------ | ---- |
|
||||
| 預設值 | `24` |
|
||||
| 停用 | `0` |
|
||||
| 單位 | 小時 |
|
||||
|
||||
```yaml
|
||||
environment:
|
||||
# 每 24 小時清理一次
|
||||
- AUTO_DELETE_EVERY_N_HOURS=24
|
||||
|
||||
# 每 1 小時清理一次（公開服務建議）
|
||||
- AUTO_DELETE_EVERY_N_HOURS=1
|
||||
|
||||
# 停用自動清理
|
||||
- AUTO_DELETE_EVERY_N_HOURS=0
|
||||
```
|
||||
|
||||
### 清理範圍
|
||||
|
||||
自動清理會刪除以下檔案：
|
||||
|
||||
- `uploads/` 目錄中的上傳檔案
|
||||
- `output/` 目錄中的轉換結果
|
||||
|
||||
> 不會刪除資料庫 (`convertx.db`) 或使用者帳號
|
||||
|
||||
---
|
||||
|
||||
## 轉換限制
|
||||
|
||||
### MAX_CONVERT_PROCESS
|
||||
|
||||
限制同時進行的轉換任務數量。
|
||||
|
||||
| 項目 | 值 |
|
||||
| ------ | ------------- |
|
||||
| 預設值 | `0`（無限制） |
|
||||
|
||||
```yaml
|
||||
environment:
|
||||
# 最多同時 2 個轉換任務
|
||||
- MAX_CONVERT_PROCESS=2
|
||||
|
||||
# 無限制
|
||||
- MAX_CONVERT_PROCESS=0
|
||||
```
|
||||
|
||||
#### 使用建議
|
||||
|
||||
| 情境 | 建議值 |
|
||||
| ------------ | ------ |
|
||||
| 個人使用 | 無限制 |
|
||||
| 小型團隊 | 4-8 |
|
||||
| 公開服務 | 2-4 |
|
||||
| 資源受限環境 | 1-2 |
|
||||
|
||||
---
|
||||
|
||||
## 記憶體限制
|
||||
|
||||
### Docker 記憶體限制
|
||||
|
||||
```yaml
|
||||
services:
|
||||
convertx:
|
||||
deploy:
|
||||
resources:
|
||||
limits:
|
||||
memory: 4G
|
||||
reservations:
|
||||
memory: 2G
|
||||
```
|
||||
|
||||
### 建議配置
|
||||
|
||||
| 記憶體 | 適用情境 |
|
||||
| ------ | ------------- |
|
||||
| 2 GB | 基本轉換 |
|
||||
| 4 GB | 一般使用 |
|
||||
| 8 GB | 大檔案轉換 |
|
||||
| 16 GB | 影片轉換、OCR |
|
||||
|
||||
---
|
||||
|
||||
## CPU 限制
|
||||
|
||||
### Docker CPU 限制
|
||||
|
||||
```yaml
|
||||
services:
|
||||
convertx:
|
||||
deploy:
|
||||
resources:
|
||||
limits:
|
||||
cpus: "2"
|
||||
```
|
||||
|
||||
### 建議配置
|
||||
|
||||
| CPU 核心 | 適用情境 |
|
||||
| -------- | ------------ |
|
||||
| 1 | 最小需求 |
|
||||
| 2 | 一般使用 |
|
||||
| 4+ | 多人同時使用 |
|
||||
|
||||
---
|
||||
|
||||
## 磁碟空間管理
|
||||
|
||||
### 監控磁碟使用
|
||||
|
||||
```bash
|
||||
# 檢查 data 目錄大小
|
||||
du -sh ./data
|
||||
|
||||
# 檢查各子目錄
|
||||
du -sh ./data/*
|
||||
```
|
||||
|
||||
### 手動清理
|
||||
|
||||
```bash
|
||||
# 清理舊檔案（超過 7 天）
|
||||
find ./data/uploads -mtime +7 -delete
|
||||
find ./data/output -mtime +7 -delete
|
||||
```
|
||||
|
||||
### 設定清理排程
|
||||
|
||||
```bash
|
||||
# 每天凌晨 3 點清理超過 7 天的檔案
|
||||
0 3 * * * find /path/to/data/uploads -mtime +7 -delete
|
||||
0 3 * * * find /path/to/data/output -mtime +7 -delete
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 情境範例
|
||||
|
||||
### 個人使用
|
||||
|
||||
```yaml
|
||||
environment:
|
||||
- AUTO_DELETE_EVERY_N_HOURS=168 # 一週
|
||||
- MAX_CONVERT_PROCESS=0 # 無限制
|
||||
```
|
||||
|
||||
### 小型團隊
|
||||
|
||||
```yaml
|
||||
environment:
|
||||
- AUTO_DELETE_EVERY_N_HOURS=24 # 一天
|
||||
- MAX_CONVERT_PROCESS=4
|
||||
|
||||
deploy:
|
||||
resources:
|
||||
limits:
|
||||
memory: 4G
|
||||
```
|
||||
|
||||
### 公開服務
|
||||
|
||||
```yaml
|
||||
environment:
|
||||
- AUTO_DELETE_EVERY_N_HOURS=1 # 一小時
|
||||
- MAX_CONVERT_PROCESS=2
|
||||
- ALLOW_UNAUTHENTICATED=true
|
||||
- HIDE_HISTORY=true
|
||||
|
||||
deploy:
|
||||
resources:
|
||||
limits:
|
||||
memory: 4G
|
||||
cpus: "2"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 相關文件
|
||||
|
||||
- [環境變數設定](environment-variables.md)
|
||||
- [安全性設定](security.md)
|
||||
- [Docker 部署](../deployment/docker.md)
|
||||
219
docs/configuration/security.md
Normal file
219
docs/configuration/security.md
Normal file
|
|
@ -0,0 +1,219 @@
|
|||
# 安全性設定
|
||||
|
||||
本文件說明 ConvertX-CN 的安全性設定與最佳實踐。
|
||||
|
||||
---
|
||||
|
||||
## Cookie 與登入安全
|
||||
|
||||
### HTTP_ALLOWED
|
||||
|
||||
控制是否允許非 HTTPS 連線。
|
||||
|
||||
```yaml
|
||||
- HTTP_ALLOWED=true # 允許 HTTP（不安全，僅測試用）
|
||||
- HTTP_ALLOWED=false # 僅允許 HTTPS（預設）
|
||||
```
|
||||
|
||||
#### 運作原理
|
||||
|
||||
當 `HTTP_ALLOWED=false` 時，Cookie 會設定 `Secure` 屬性，只在 HTTPS 連線下傳送。
|
||||
|
||||
若實際用 HTTP 存取：
|
||||
|
||||
- 瀏覽器不會傳送 Cookie
|
||||
- 每次請求都像未登入
|
||||
- 造成「登入後又被踢回登入頁」
|
||||
|
||||
#### 設定建議
|
||||
|
||||
| 情境 | 設定值 |
|
||||
| ------------------ | ------- |
|
||||
| `localhost` 測試 | `true` |
|
||||
| 區網 IP 測試 | `true` |
|
||||
| 有 HTTPS 憑證 | `false` |
|
||||
| 透過反向代理 HTTPS | `false` |
|
||||
|
||||
---
|
||||
|
||||
### TRUST_PROXY
|
||||
|
||||
是否信任反向代理傳來的 headers。
|
||||
|
||||
```yaml
|
||||
- TRUST_PROXY=true # 信任 X-Forwarded-* headers
|
||||
- TRUST_PROXY=false # 不信任（預設）
|
||||
```
|
||||
|
||||
#### 運作原理
|
||||
|
||||
當請求經過反向代理時：
|
||||
|
||||
- 原始連線：使用者 → Nginx (HTTPS) → ConvertX (HTTP)
|
||||
- 沒有 TRUST_PROXY：ConvertX 看到的是 HTTP 連線
|
||||
- 有 TRUST_PROXY：ConvertX 讀取 `X-Forwarded-Proto: https`，知道原始是 HTTPS
|
||||
|
||||
#### 設定建議
|
||||
|
||||
| 情境 | 設定值 |
|
||||
| ---------------------------- | ------- |
|
||||
| 直接存取容器（無 Proxy） | `false` |
|
||||
| 透過 Nginx / Traefik / Caddy | `true` |
|
||||
| 透過 Cloudflare Tunnel | `true` |
|
||||
|
||||
> ⚠️ **安全注意**：只在確實有反向代理時才設為 `true`。若直接暴露容器且設為 `true`，攻擊者可偽造 headers。
|
||||
|
||||
---
|
||||
|
||||
## 帳號安全
|
||||
|
||||
### ACCOUNT_REGISTRATION
|
||||
|
||||
```yaml
|
||||
- ACCOUNT_REGISTRATION=true # 開放註冊
|
||||
- ACCOUNT_REGISTRATION=false # 關閉註冊
|
||||
```
|
||||
|
||||
#### 建議流程
|
||||
|
||||
1. 首次部署設為 `true`（或不設定）
|
||||
2. 註冊管理員帳號
|
||||
3. 改為 `false`
|
||||
4. 重啟容器
|
||||
|
||||
### JWT_SECRET
|
||||
|
||||
```yaml
|
||||
- JWT_SECRET=your-secret-key-at-least-32-chars
|
||||
```
|
||||
|
||||
#### 重要性
|
||||
|
||||
- 用於簽署登入 Token
|
||||
- 不設定：每次重啟產生新密鑰，所有人被登出
|
||||
- 設定固定值：登入狀態跨重啟保留
|
||||
|
||||
#### 產生方式
|
||||
|
||||
```bash
|
||||
# Linux / macOS
|
||||
openssl rand -hex 32
|
||||
|
||||
# 輸出範例：a1b2c3d4e5f6789...（64 字元）
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 公開服務安全
|
||||
|
||||
### ALLOW_UNAUTHENTICATED
|
||||
|
||||
```yaml
|
||||
- ALLOW_UNAUTHENTICATED=true # 允許未登入使用
|
||||
- ALLOW_UNAUTHENTICATED=false # 必須登入（預設）
|
||||
```
|
||||
|
||||
#### 風險
|
||||
|
||||
設為 `true` 時：
|
||||
|
||||
- 任何人可使用轉換功能
|
||||
- 消耗伺服器 CPU / 記憶體 / 磁碟
|
||||
- 可能被惡意利用
|
||||
|
||||
#### 緩解措施
|
||||
|
||||
若需要公開服務，建議：
|
||||
|
||||
```yaml
|
||||
environment:
|
||||
- ALLOW_UNAUTHENTICATED=true
|
||||
- AUTO_DELETE_EVERY_N_HOURS=1 # 頻繁清理
|
||||
- HIDE_HISTORY=true # 隱藏歷史
|
||||
- MAX_CONVERT_PROCESS=2 # 限制同時轉換數
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 網路安全
|
||||
|
||||
### 防火牆
|
||||
|
||||
只開放必要的埠：
|
||||
|
||||
```bash
|
||||
# UFW (Ubuntu)
|
||||
sudo ufw allow 3000/tcp
|
||||
|
||||
# 或只允許特定 IP
|
||||
sudo ufw allow from 192.168.1.0/24 to any port 3000
|
||||
```
|
||||
|
||||
### 只允許本機存取
|
||||
|
||||
```yaml
|
||||
ports:
|
||||
- "127.0.0.1:3000:3000" # 只有本機可存取
|
||||
```
|
||||
|
||||
搭配反向代理提供對外服務。
|
||||
|
||||
### 限制上傳大小
|
||||
|
||||
在反向代理層限制：
|
||||
|
||||
```nginx
|
||||
# Nginx
|
||||
client_max_body_size 100M;
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 資料安全
|
||||
|
||||
### 定期清理
|
||||
|
||||
```yaml
|
||||
- AUTO_DELETE_EVERY_N_HOURS=24 # 每 24 小時清理
|
||||
```
|
||||
|
||||
### 備份
|
||||
|
||||
```bash
|
||||
# 定期備份資料
|
||||
0 2 * * * tar -czvf /backup/convertx-$(date +\%Y\%m\%d).tar.gz /path/to/data
|
||||
```
|
||||
|
||||
### 權限設定
|
||||
|
||||
```bash
|
||||
# 限制資料夾權限
|
||||
chmod 700 ./data
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 安全檢查清單
|
||||
|
||||
### 部署前
|
||||
|
||||
- [ ] 設定固定的 `JWT_SECRET`
|
||||
- [ ] 關閉 `ACCOUNT_REGISTRATION`（如果不需要公開註冊）
|
||||
- [ ] 設定 `TRUST_PROXY=true`（如果使用反向代理）
|
||||
- [ ] 設定 `HTTP_ALLOWED=false`（如果有 HTTPS）
|
||||
|
||||
### 部署後
|
||||
|
||||
- [ ] 確認只有必要的埠對外開放
|
||||
- [ ] 確認反向代理有正確設定
|
||||
- [ ] 確認 HTTPS 憑證有效
|
||||
- [ ] 設定定期備份
|
||||
- [ ] 設定定期清理
|
||||
|
||||
---
|
||||
|
||||
## 相關文件
|
||||
|
||||
- [環境變數設定](environment-variables.md)
|
||||
- [反向代理設定](../deployment/reverse-proxy.md)
|
||||
- [Docker 部署](../deployment/docker.md)
|
||||
Loading…
Add table
Add a link
Reference in a new issue