diff --git a/README.md b/README.md index 6b2b1fa..405ed02 100644 --- a/README.md +++ b/README.md @@ -25,14 +25,14 @@ ## 📚 文件 -完整文件請參閱 **[文件中心](docs/README.md)** +完整文件請參閱 **[文件中心](docs/說明文件.md)** | 分類 | 連結 | | ----------- | -------------------------------------------------------------------------------------------------------- | | 🚀 快速入門 | [概覽](docs/快速入門/概覽.md) · [快速開始](docs/快速入門/快速開始.md) · [FAQ](docs/快速入門/常見問題.md) | | 🐳 部署指南 | [Docker](docs/部署指南/Docker.md) · [反向代理](docs/部署指南/反向代理.md) | | ⚙️ 配置設定 | [環境變數](docs/配置設定/環境變數.md) · [安全性](docs/配置設定/安全性.md) | -| 🔌 功能說明 | [轉換器](docs/功能說明/轉換器.md) · [OCR](docs/功能說明/OCR.md) · [翻譯](docs/功能說明/翻譯.md) | +| 🔌 功能說明 | [轉換器](docs/功能說明/轉換器.md) · [OCR](docs/功能說明/OCR.md) · [翻譯](docs/功能說明/翻譯功能.md) | | 🔗 API | [API 總覽](docs/API/總覽.md) · [端點說明](docs/API/端點.md) | | 👩‍💻 開發 | [專案結構](docs/開發指南/專案結構.md) · [貢獻指南](docs/開發指南/貢獻指南.md) | diff --git a/docs/API/端點.md b/docs/API/端點.md index e386f29..e988b5a 100644 --- a/docs/API/端點.md +++ b/docs/API/端點.md @@ -257,5 +257,5 @@ query { ## 相關文件 -- [API 總覽](overview.md) +- [API 總覽](總覽.md) - [API 規格文件](../../api-server/docs/API_SPEC.md) diff --git a/docs/docker-compose/README.md b/docs/Docker組合配置/README.md similarity index 67% rename from docs/docker-compose/README.md rename to docs/Docker組合配置/README.md index 602445e..c62bd2f 100644 --- a/docs/docker-compose/README.md +++ b/docs/Docker組合配置/README.md @@ -12,12 +12,12 @@ ## 快速選擇 -| 你是... | 使用 | -| ------------ | ------------------------------ | -| 新手 | [README 主頁](../../README.md) | -| Docker 熟手 | compose.minimal.yml | -| 生產環境 | compose.production.yml | -| 查詢所有選項 | compose.reference.yml | +| 你是... | 使用 | +| ------------ | ----------------------------- | +| 新手 | [README 主頁](../說明文件.md) | +| Docker 熟手 | compose.minimal.yml | +| 生產環境 | compose.production.yml | +| 查詢所有選項 | compose.reference.yml | ## 如何使用 @@ -40,9 +40,9 @@ docker compose up -d ## 相關文件 -- [Docker Compose 詳解](../deployment/docker-compose.md) -- [環境變數說明](../config/environment.md) -- [版本選擇指南](../versions/) +- [Docker Compose 詳解](../部署指南/Docker組合.md) +- [環境變數說明](../配置設定/環境變數.md) +- [版本選擇指南](../版本/) ### 我要部署到正式環境 @@ -58,6 +58,6 @@ docker compose up -d ## 相關文件 -- [環境變數完整說明](../environment-variables.md) -- [進階部署指南](../deployment.md) -- [Docker 進階配置](../docker.md) +- [環境變數完整說明](../環境變數總覽.md) +- [進階部署指南](../部署總覽.md) +- [Docker 進階配置](../Docker說明.md) diff --git a/docs/docker-compose/compose.minimal.yml b/docs/Docker組合配置/compose.minimal.yml similarity index 100% rename from docs/docker-compose/compose.minimal.yml rename to docs/Docker組合配置/compose.minimal.yml diff --git a/docs/docker-compose/compose.production.yml b/docs/Docker組合配置/compose.production.yml similarity index 100% rename from docs/docker-compose/compose.production.yml rename to docs/Docker組合配置/compose.production.yml diff --git a/docs/docker-compose/compose.reference.yml b/docs/Docker組合配置/compose.reference.yml similarity index 100% rename from docs/docker-compose/compose.reference.yml rename to docs/Docker組合配置/compose.reference.yml diff --git a/docs/Docker組合配置/生產環境配置.yml b/docs/Docker組合配置/生產環境配置.yml new file mode 100644 index 0000000..a96e64e --- /dev/null +++ b/docs/Docker組合配置/生產環境配置.yml @@ -0,0 +1,87 @@ +# ============================================================================== +# ConvertX-CN 生產環境 Docker Compose +# +# 適用情境: +# - 透過 Reverse Proxy(Nginx / Traefik / Caddy)存取 +# - 已設定 HTTPS +# - 需要限制註冊與存取 +# +# ⚠️ 使用前請確認: +# 1. 已建立 data 資料夾 +# 2. 已將 JWT_SECRET 改成你自己的值 +# 3. 已設定好 Reverse Proxy +# ============================================================================== + +services: + convertx: + image: convertx/convertx-cn:latest + container_name: convertx-cn + restart: unless-stopped + + # 生產環境通常只監聽 localhost,由 Reverse Proxy 轉發 + # 若需要直接對外,改為 "3000:3000" + ports: + - "127.0.0.1:3000:3000" + + volumes: + - ./data:/app/data + + environment: + # === 必填設定 === + # 🔐 JWT 密鑰:請務必改成你自己的隨機字串(至少 32 字元) + # 可用 openssl rand -hex 32 產生 + - JWT_SECRET=change-me-to-a-very-long-random-string-at-least-32-characters + + # === 安全設定 === + # 關閉註冊(首次帳號仍可建立) + - ACCOUNT_REGISTRATION=false + + # 不允許 HTTP(要求 HTTPS) + - HTTP_ALLOWED=false + + # 信任 Reverse Proxy 的 X-Forwarded-* headers + - TRUST_PROXY=true + + # 必須登入才能使用 + - ALLOW_UNAUTHENTICATED=false + + # === 時區與清理 === + - TZ=Asia/Taipei + - AUTO_DELETE_EVERY_N_HOURS=24 + + # === 可選:子路徑部署 === + # 若透過 https://example.com/convertx/ 存取,取消下行註解 + # - WEBROOT=/convertx + +# ============================================================================== +# Reverse Proxy 設定範例 +# ============================================================================== +# +# Nginx 範例: +# ------------- +# server { +# listen 443 ssl http2; +# server_name example.com; +# +# location / { +# proxy_pass http://127.0.0.1:3000; +# proxy_set_header Host $host; +# proxy_set_header X-Real-IP $remote_addr; +# proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; +# proxy_set_header X-Forwarded-Proto $scheme; +# +# # 檔案上傳大小限制 +# client_max_body_size 500M; +# } +# } +# +# Traefik 範例(labels): +# ------------------------ +# labels: +# - "traefik.enable=true" +# - "traefik.http.routers.convertx.rule=Host(`convertx.example.com`)" +# - "traefik.http.routers.convertx.tls=true" +# - "traefik.http.routers.convertx.tls.certresolver=letsencrypt" +# - "traefik.http.services.convertx.loadbalancer.server.port=3000" +# +# ============================================================================== diff --git a/docs/Docker組合配置/說明文件.md b/docs/Docker組合配置/說明文件.md new file mode 100644 index 0000000..83edfd1 --- /dev/null +++ b/docs/Docker組合配置/說明文件.md @@ -0,0 +1,57 @@ +# 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) | 參考文件 | 所有設定的完整參考 | + +## 快速選擇 + +| 你是... | 使用 | +| ------------ | ----------------------------- | +| 新手 | [README 主頁](../說明文件.md) | +| Docker 熟手 | compose.minimal.yml | +| 生產環境 | compose.production.yml | +| 查詢所有選項 | compose.reference.yml | + +## 如何使用 + +```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),包含所有環境變數的說明。 diff --git a/docs/docker.md b/docs/Docker說明.md similarity index 98% rename from docs/docker.md rename to docs/Docker說明.md index 7de52ff..658cfa7 100644 --- a/docs/docker.md +++ b/docs/Docker說明.md @@ -4,7 +4,7 @@ > > 本文件內容已整合至新的文件結構,請參閱: > -> - 📦 [Docker 部署指南](部署指南/Docker.md) +> - 📦 [Docker 部署指南](部署指南/Docker部署.md) > - 🔧 [反向代理設定](部署指南/反向代理.md) > > 此文件將在未來版本中移除。 diff --git a/docs/config/environment.md b/docs/config/environment.md deleted file mode 100644 index 207a24e..0000000 --- a/docs/config/environment.md +++ /dev/null @@ -1,249 +0,0 @@ -# 環境變數完整說明 - -> ⚠️ **此文件已遷移** -> -> 本文件內容已整合至新的文件結構,請參閱: -> -> - ⚙️ [環境變數設定](../配置設定/環境變數.md) -> - 🔒 [安全性設定](../配置設定/安全性.md) -> - 🧹 [清理與限制](../配置設定/清理與限制.md) -> -> 此文件將在未來版本中移除。 - ---- - -本文件列出 ConvertX-CN 所有可用的環境變數設定。 - ---- - -## 快速參考 - -| 優先級 | 變數 | 說明 | 預設值 | -| ------ | -------------- | ------------ | ------------------ | -| 必填 | `JWT_SECRET` | 登入驗證金鑰 | 隨機(每次重啟變) | -| 建議 | `TZ` | 時區 | `UTC` | -| 建議 | `HTTP_ALLOWED` | 允許 HTTP | `false` | -| 可選 | `TRUST_PROXY` | 信任反向代理 | `false` | -| 可選 | 其他 | 依需求設定 | - | - ---- - -## 必填設定 - -### JWT_SECRET - -用於簽署登入驗證的密鑰。 - -| 項目 | 值 | -| ------ | ---------------------- | -| 預設值 | 每次重啟隨機產生 | -| 建議值 | 至少 32 字元的隨機字串 | - -不設定的話,每次容器重啟後所有使用者都需要重新登入。 - -產生方式: - -```bash -openssl rand -hex 32 -``` - ---- - -## 網路與安全 - -### HTTP_ALLOWED - -允許非 HTTPS 連線。 - -| 項目 | 值 | -| ------ | ------- | -| 預設值 | `false` | - -| 情境 | 設定值 | -| --------------------- | ------- | -| 本地測試 (localhost) | `true` | -| 有 HTTPS | `false` | -| 無 HTTPS 但需遠端存取 | `true` | - -設為 `false` 但用 HTTP 存取會導致「登入後又被導回登入頁」。 - -### TRUST_PROXY - -信任反向代理的 headers(`X-Forwarded-Proto` 等)。 - -| 項目 | 值 | -| ------ | ------- | -| 預設值 | `false` | - -| 情境 | 設定值 | -| ---------------------------- | ------- | -| 直接存取容器 | `false` | -| 透過 Nginx / Traefik / Caddy | `true` | - -詳見 [安全性設定](security.md)。 - -### 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 - -日期格式語言(BCP 47 格式)。 - -| 項目 | 值 | -| ------ | ---- | -| 預設值 | `en` | - ---- - -## 轉換設定 - -### MAX_CONVERT_PROCESS - -最大同時轉換任務數。 - -| 項目 | 值 | -| ------ | ------------- | -| 預設值 | `0`(無限制) | - -### FFMPEG_ARGS - -FFmpeg 輸入參數(硬體加速等)。 - -| 項目 | 值 | -| ------ | --- | -| 預設值 | 空 | - -```yaml -# NVIDIA GPU -- FFMPEG_ARGS=-hwaccel cuda - -# Intel QSV -- FFMPEG_ARGS=-hwaccel qsv -``` - -### FFMPEG_OUTPUT_ARGS - -FFmpeg 輸出參數。 - -| 項目 | 值 | -| ------ | --- | -| 預設值 | 空 | - -```yaml -- FFMPEG_OUTPUT_ARGS=-preset veryfast -``` - ---- - -## 情境範例 - -### 開發環境 - -```yaml -environment: - - TZ=Asia/Taipei - - HTTP_ALLOWED=true - - ACCOUNT_REGISTRATION=true -``` - -### 生產環境 - -```yaml -environment: - - TZ=Asia/Taipei - - JWT_SECRET=your-production-secret-at-least-32-chars - - 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 -``` - ---- - -## 相關文件 - -- [安全性設定](security.md) -- [進階部署](../deployment.md) -- [Docker Compose 詳解](../deployment/docker-compose.md) diff --git a/docs/config/security.md b/docs/config/security.md deleted file mode 100644 index 5d253a5..0000000 --- a/docs/config/security.md +++ /dev/null @@ -1,218 +0,0 @@ -# 安全性設定 - -> ⚠️ **此文件已遷移** -> -> 本文件內容已整合至新的文件結構,請參閱: -> -> - 🔒 [安全性設定](../配置設定/安全性.md) -> -> 此文件將在未來版本中移除。 - ---- - -本文件說明 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 -# 僅允許特定 IP 存取 -ufw allow from 192.168.1.0/24 to any port 3000 -``` - -### 只允許本地存取 - -若透過反向代理,可限制容器只監聽 localhost: - -```yaml -ports: - - "127.0.0.1:3000:3000" -``` - -這樣只有本機的反向代理可以存取,外部無法直接連線。 - ---- - -## 設定範例 - -### 最小安全配置(本地測試) - -```yaml -environment: - - HTTP_ALLOWED=true -``` - -### 標準安全配置(生產環境) - -```yaml -environment: - - JWT_SECRET=your-production-secret - - HTTP_ALLOWED=false - - TRUST_PROXY=true - - ACCOUNT_REGISTRATION=false -``` - -### 高安全配置(敏感環境) - -```yaml -services: - convertx: - ports: - - "127.0.0.1:3000:3000" # 只允許本地 - environment: - - JWT_SECRET=your-very-long-random-secret - - HTTP_ALLOWED=false - - TRUST_PROXY=true - - ACCOUNT_REGISTRATION=false - - ALLOW_UNAUTHENTICATED=false - - AUTO_DELETE_EVERY_N_HOURS=1 -``` - ---- - -## 相關文件 - -- [環境變數完整說明](environment.md) -- [反向代理設定](../deployment.md) -- [Docker Compose 詳解](../deployment/docker-compose.md) diff --git a/docs/功能說明/OCR.md b/docs/功能說明/OCR.md index f19fa94..aac0db5 100644 --- a/docs/功能說明/OCR.md +++ b/docs/功能說明/OCR.md @@ -148,5 +148,5 @@ volumes: ## 相關文件 - [支援的轉換器](轉換器.md) -- [翻譯功能](翻譯.md) -- [Docker 部署](../部署指南/Docker.md) +- [翻譯功能](翻譯功能.md) +- [Docker 部署](../部署指南/Docker部署.md) diff --git a/docs/功能說明/多語言.md b/docs/功能說明/多語言介面.md similarity index 100% rename from docs/功能說明/多語言.md rename to docs/功能說明/多語言介面.md diff --git a/docs/功能說明/翻譯.md b/docs/功能說明/翻譯功能.md similarity index 100% rename from docs/功能說明/翻譯.md rename to docs/功能說明/翻譯功能.md diff --git a/docs/功能說明/轉換器.md b/docs/功能說明/轉換器.md index d05291c..10c9efe 100644 --- a/docs/功能說明/轉換器.md +++ b/docs/功能說明/轉換器.md @@ -218,6 +218,6 @@ ConvertX-CN 完整版已預載: ## 相關文件 -- [OCR 功能](ocr.md) -- [翻譯功能](translation.md) -- [Docker 部署](../deployment/docker.md) +- [OCR 功能](OCR.md) +- [翻譯功能](翻譯功能.md) +- [Docker 部署](../部署指南/Docker部署.md) diff --git a/docs/i18n.md b/docs/國際化說明.md similarity index 99% rename from docs/i18n.md rename to docs/國際化說明.md index e889ec9..82f0c18 100644 --- a/docs/i18n.md +++ b/docs/國際化說明.md @@ -4,7 +4,7 @@ > > 本文件內容已整合至新的文件結構,請參閱: > -> - 🌐 [多語言介面支援](功能說明/多語言.md) +> - 🌐 [多語言介面支援](功能說明/多語言介面.md) > > 此文件將在未來版本中移除。 diff --git a/docs/i18n/en/getting-started/quick-start.md b/docs/多語言/en/Getting-Started/Quick-Start.md similarity index 100% rename from docs/i18n/en/getting-started/quick-start.md rename to docs/多語言/en/Getting-Started/Quick-Start.md diff --git a/docs/i18n/en/README.md b/docs/多語言/en/Overview.md similarity index 90% rename from docs/i18n/en/README.md rename to docs/多語言/en/Overview.md index 279466e..7148c11 100644 --- a/docs/i18n/en/README.md +++ b/docs/多語言/en/Overview.md @@ -1,15 +1,20 @@ # ConvertX-CN Documentation > 🌐 **Language / 語言** -> [繁體中文](../../README.md) | **English** | [简体中文](../zh-CN/README.md) +> [繁體中文](../../說明文件.md) | **English** | [简体中文](../zh-CN/概述.md) > 🌐 **Translation Info** > -> - Original: [繁體中文版](../../README.md) +> - Original: [繁體中文版](../../說明文件.md) > - Translation Version: v0.1.0 > - Last Updated: 2026-01-23 > - Status: 🚧 In Progress +> ⚠️ **Translation Notice** +> +> This is a work-in-progress translation. Many links point to pages that haven't been translated yet. +> For complete documentation, please refer to the [繁體中文版](../../說明文件.md). + --- Welcome to ConvertX-CN Documentation! Choose your role to find the information you need. diff --git a/docs/i18n/ja/README.md b/docs/多語言/ja/概要.md similarity index 89% rename from docs/i18n/ja/README.md rename to docs/多語言/ja/概要.md index 21ace58..f204d7b 100644 --- a/docs/i18n/ja/README.md +++ b/docs/多語言/ja/概要.md @@ -1,15 +1,20 @@ # ConvertX-CN ドキュメント > 🌐 **Language / 語言** -> [繁體中文](../../README.md) | [English](../en/README.md) | [简体中文](../zh-CN/README.md) | **日本語** +> [繁體中文](../../說明文件.md) | [English](../en/Overview.md) | [简体中文](../zh-CN/概述.md) | **日本語** > 🌐 **翻訳情報** > -> - 原文:[繁體中文版](../../README.md) +> - 原文:[繁體中文版](../../說明文件.md) > - 翻訳バージョン:v0.1.0 > - 最終更新:2026-01-23 > - ステータス:📋 計画中 +> ⚠️ **翻訳について** +> +> この翻訳は進行中です。多くのリンクはまだ翻訳されていないページを指しています。 +> 完全なドキュメントは [繁體中文版](../../說明文件.md) をご覧ください。 + --- ConvertX-CN ドキュメントへようこそ!役割を選択して必要な情報を見つけてください。 diff --git a/docs/i18n/zh-CN/README.md b/docs/多語言/zh-CN/概述.md similarity index 91% rename from docs/i18n/zh-CN/README.md rename to docs/多語言/zh-CN/概述.md index 46b4d65..87f6226 100644 --- a/docs/i18n/zh-CN/README.md +++ b/docs/多語言/zh-CN/概述.md @@ -1,15 +1,20 @@ # ConvertX-CN 文档中心 > 🌐 **Language / 語言** -> [繁體中文](../../README.md) | [English](../en/README.md) | **简体中文** +> [繁體中文](../../說明文件.md) | [English](../en/Overview.md) | **简体中文** > 🌐 **翻译信息** > -> - 原文:[繁體中文版](../../README.md) +> - 原文:[繁體中文版](../../說明文件.md) > - 翻译版本:v0.1.0 > - 最后更新:2026-01-23 > - 状态:📋 计划中 +> ⚠️ **翻译说明** +> +> 此翻译正在进行中,许多链接指向尚未翻译的页面。 +> 完整文档请参阅 [繁體中文版](../../說明文件.md)。 + --- 欢迎来到 ConvertX-CN 文档!选择您的角色快速找到所需信息。 diff --git a/docs/i18n/README.md b/docs/多語言/翻譯指南.md similarity index 96% rename from docs/i18n/README.md rename to docs/多語言/翻譯指南.md index 63abfc4..89156fe 100644 --- a/docs/i18n/README.md +++ b/docs/多語言/翻譯指南.md @@ -144,14 +144,14 @@ git push origin feature/en-quick-start ```markdown > 🌐 **Language / 語言** -> [繁體中文](../../README.md) | [English](README.md) | [简体中文](../zh-CN/README.md) +> [繁體中文](../../說明文件.md) | [English](en/Overview.md) | [简体中文](zh-CN/概述.md) ``` --- ## 相關資源 -- [貢獻指南](../development/contribution.md) +- [貢獻指南](../開發指南/貢獻指南.md) - [GitHub Issues - 翻譯](https://github.com/pi-docket/ConvertX-CN/labels/translation) - [Discussions - 翻譯討論](https://github.com/pi-docket/ConvertX-CN/discussions/categories/translations) diff --git a/docs/faq.md b/docs/常見問題總覽.md similarity index 100% rename from docs/faq.md rename to docs/常見問題總覽.md diff --git a/docs/快速入門/常見問題.md b/docs/快速入門/常見問題.md index 7ed43e4..7eb166d 100644 --- a/docs/快速入門/常見問題.md +++ b/docs/快速入門/常見問題.md @@ -130,7 +130,7 @@ docker compose up -d - 繁體中文、簡體中文 - 日文、韓文 - 英文、德文、法文 -- 更多詳見 [多語言支援](../功能說明/多語言.md) +- 更多詳見 [多語言支援](../功能說明/多語言介面.md) --- @@ -173,7 +173,7 @@ client_max_body_size 500M; ### Q: 如何啟用硬體加速? -詳見 [進階配置 - 硬體加速](../部署指南/Docker.md#硬體加速) +詳見 [進階配置 - 硬體加速](../部署指南/Docker部署.md#硬體加速) ### Q: 如何啟用 API Server? @@ -187,6 +187,6 @@ docker compose --profile api up -d ## 還有問題? -- 📖 查看 [完整文件](../README.md) +- 📖 查看 [完整文件](../說明文件.md) - 🐛 回報問題:[GitHub Issues](https://github.com/pi-docket/ConvertX-CN/issues) - 💬 討論區:[GitHub Discussions](https://github.com/pi-docket/ConvertX-CN/discussions) diff --git a/docs/快速入門/快速開始.md b/docs/快速入門/快速開始.md index 6145447..c6abb5c 100644 --- a/docs/快速入門/快速開始.md +++ b/docs/快速入門/快速開始.md @@ -138,7 +138,7 @@ environment: ## 下一步 -- 📖 [Docker 詳細配置](../部署指南/Docker.md) +- 📖 [Docker 詳細配置](../部署指南/Docker部署.md) - ⚙️ [環境變數設定](../配置設定/環境變數.md) - 🔒 [安全性設定](../配置設定/安全性.md) - 🔧 [反向代理設定](../部署指南/反向代理.md) diff --git a/docs/快速入門/概覽.md b/docs/快速入門/概覽.md index fb3d279..9945c7e 100644 --- a/docs/快速入門/概覽.md +++ b/docs/快速入門/概覽.md @@ -80,4 +80,4 @@ ConvertX-CN 是 fork 自 [C4illin/ConvertX](https://github.com/C4illin/ConvertX) - 🚀 [快速開始](快速開始.md) — 5 分鐘內完成部署 - ❓ [常見問題](常見問題.md) — 解決常見問題 -- 📦 [Docker 部署](../部署指南/Docker.md) — 詳細部署指南 +- 📦 [Docker 部署](../部署指南/Docker部署.md) — 詳細部署指南 diff --git a/docs/getting-started.md b/docs/快速入門總覽.md similarity index 91% rename from docs/getting-started.md rename to docs/快速入門總覽.md index ac0aab6..880174c 100644 --- a/docs/getting-started.md +++ b/docs/快速入門總覽.md @@ -12,7 +12,7 @@ --- -> 本文件提供完整部署步驟。若只需最快啟動,請參考 [README](../README.md)。 +> 本文件提供完整部署步驟。若只需最快啟動,請參考 [說明文件](說明文件.md)。 --- @@ -177,7 +177,7 @@ deploy: ## 下一步 -- 📖 [Docker 配置](docker.md) - 進階 Docker 設定 -- ⚙️ [環境變數](environment-variables.md) - 所有可用設定 -- 🔧 [進階用法](advanced-usage.md) - 硬體加速、反向代理 -- 🌍 [多語言](i18n.md) - 語言設定與自訂 +- 📖 [Docker 配置](Docker說明.md) - 進階 Docker 設定 +- ⚙️ [環境變數](環境變數總覽.md) - 所有可用設定 +- 🔧 [進階用法](進階用法.md) - 硬體加速、反向代理 +- 🌍 [多語言](國際化說明.md) - 語言設定與自訂 diff --git a/docs/測試/測試策略.md b/docs/測試/測試策略.md index dc6fc4e..d45c78c 100644 --- a/docs/測試/測試策略.md +++ b/docs/測試/測試策略.md @@ -206,6 +206,6 @@ jobs: ## 相關文件 -- [CI/CD](ci-cd.md) -- [E2E 測試](e2e-tests.md) -- [本地開發](../development/local-development.md) +- [CI/CD](CI-CD.md) +- [E2E 測試](E2E測試.md) +- [本地開發](../開發指南/本地開發.md) diff --git a/docs/versions/pinned-version.md b/docs/版本/指定版本.md similarity index 92% rename from docs/versions/pinned-version.md rename to docs/版本/指定版本.md index cf60512..5574a75 100644 --- a/docs/versions/pinned-version.md +++ b/docs/版本/指定版本.md @@ -67,7 +67,7 @@ docker compose pull docker compose up -d ``` -詳見 [版本更新指南](../deployment/update.md)。 +詳見 [版本更新指南](../部署指南/版本更新.md)。 --- @@ -115,6 +115,6 @@ services: ## 相關文件 -- [使用 latest 標籤](latest.md) -- [版本更新指南](../deployment/update.md) +- [使用 latest 標籤](最新版.md) +- [版本更新指南](../部署指南/版本更新.md) - [Changelog](../../CHANGELOG.md) diff --git a/docs/versions/latest.md b/docs/版本/最新版.md similarity index 92% rename from docs/versions/latest.md rename to docs/版本/最新版.md index 0582771..21c0809 100644 --- a/docs/versions/latest.md +++ b/docs/版本/最新版.md @@ -74,7 +74,7 @@ image: convertx/convertx-cn:latest image: convertx/convertx-cn:v0.1.9 ``` -詳見 [指定版本部署](pinned-version.md)。 +詳見 [指定版本部署](指定版本.md)。 --- @@ -100,6 +100,6 @@ docker inspect convertx/convertx-cn:latest | grep -i version ## 相關文件 -- [指定版本部署](pinned-version.md) -- [版本更新指南](../deployment/update.md) +- [指定版本部署](指定版本.md) +- [版本更新指南](../部署指南/版本更新.md) - [GitHub Releases](https://github.com/pi-docket/ConvertX-CN/releases) diff --git a/docs/versions/README.md b/docs/版本/說明文件.md similarity index 73% rename from docs/versions/README.md rename to docs/版本/說明文件.md index 6fd6c37..4fa4b05 100644 --- a/docs/versions/README.md +++ b/docs/版本/說明文件.md @@ -17,8 +17,8 @@ ## 文件列表 -- [使用 latest 標籤](latest.md) - 自動更新的優缺點 -- [指定版本部署](pinned-version.md) - 生產環境推薦做法 +- [使用 latest 標籤](最新版.md) - 自動更新的優缺點 +- [指定版本部署](指定版本.md) - 生產環境推薦做法 --- @@ -26,4 +26,4 @@ - [GitHub Releases](https://github.com/pi-docket/ConvertX-CN/releases) - [Changelog](../../CHANGELOG.md) -- [版本更新指南](../deployment/update.md) +- [版本更新指南](../部署指南/版本更新.md) diff --git a/docs/environment-variables.md b/docs/環境變數總覽.md similarity index 88% rename from docs/environment-variables.md rename to docs/環境變數總覽.md index 43f02b0..53c2642 100644 --- a/docs/environment-variables.md +++ b/docs/環境變數總覽.md @@ -1,12 +1,12 @@ # 環境變數設定 -> 📦 本文件已遷移至新位置,請參閱:[docs/config/environment.md](config/environment.md) +> 📦 本文件已遷移至新位置,請參閱:[docs/config/environment.md](配置設定/環境變數.md) --- ## 快速參考 -完整說明請參考 [環境變數完整說明](config/environment.md)。 +完整說明請參考 [環境變數完整說明](配置設定/環境變數.md)。 | 優先級 | 變數 | 說明 | | ------ | -------------- | ------------- | @@ -19,9 +19,9 @@ ## 相關文件 -- [環境變數完整說明](config/environment.md) -- [安全性設定](config/security.md) -- [進階部署指南](deployment.md) +- [環境變數完整說明](配置設定/環境變數.md) +- [安全性設定](配置設定/安全性.md) +- [進階部署指南](部署總覽.md) --- @@ -152,9 +152,9 @@ environment: ## 相關文件 -- [進階部署指南](deployment.md) -- [Docker Compose 範例](docker-compose/) -- [常見問題](faq.md) +- [進階部署指南](部署總覽.md) +- [Docker Compose 範例](Docker組合配置/) +- [常見問題](快速入門/常見問題.md) ### 帶硬體加速 diff --git a/docs/範例/nginx.example.conf b/docs/範例配置/Nginx範例配置.conf similarity index 100% rename from docs/範例/nginx.example.conf rename to docs/範例配置/Nginx範例配置.conf diff --git a/docs/範例/compose.with-traefik.yml b/docs/範例配置/Traefik配置.yml similarity index 100% rename from docs/範例/compose.with-traefik.yml rename to docs/範例配置/Traefik配置.yml diff --git a/docs/範例/compose.minimal.yml b/docs/範例配置/最小配置.yml similarity index 100% rename from docs/範例/compose.minimal.yml rename to docs/範例配置/最小配置.yml diff --git a/docs/範例/compose.production.yml b/docs/範例配置/生產環境配置.yml similarity index 100% rename from docs/範例/compose.production.yml rename to docs/範例配置/生產環境配置.yml diff --git a/docs/範例/README.md b/docs/範例配置/說明文件.md similarity index 95% rename from docs/範例/README.md rename to docs/範例配置/說明文件.md index f129bd7..fcda7cf 100644 --- a/docs/範例/README.md +++ b/docs/範例配置/說明文件.md @@ -49,6 +49,6 @@ docker compose up -d ## 相關文件 -- [Docker 部署](../部署指南/Docker.md) +- [Docker 部署](../部署指南/Docker部署.md) - [環境變數](../配置設定/環境變數.md) - [反向代理](../部署指南/反向代理.md) diff --git a/docs/url-id-and-storage.md b/docs/網址ID與儲存.md similarity index 98% rename from docs/url-id-and-storage.md rename to docs/網址ID與儲存.md index 936ae68..b31e503 100644 --- a/docs/url-id-and-storage.md +++ b/docs/網址ID與儲存.md @@ -5,7 +5,7 @@ > 本文件內容已整合至新的文件結構,請參閱: > > - 🛠️ [專案結構](開發指南/專案結構.md) -> - 🐳 [Docker 部署](部署指南/Docker.md) +> - 🐳 [Docker 部署](部署指南/Docker部署.md) > > 此文件將在未來版本中移除。 diff --git a/docs/README.md b/docs/說明文件.md similarity index 68% rename from docs/README.md rename to docs/說明文件.md index cc7d6ee..0936f1b 100644 --- a/docs/README.md +++ b/docs/說明文件.md @@ -18,14 +18,14 @@ 適合一般使用者: -| 文件 | 說明 | -| ---------------------------------- | -------------------- | -| [快速開始](快速入門/快速開始.md) | 最快部署方式 | -| [支援的轉換器](功能說明/轉換器.md) | 所有可用的轉換格式 | -| [OCR 功能](功能說明/OCR.md) | 光學字元辨識 | -| [翻譯功能](功能說明/翻譯.md) | PDF 翻譯(保留公式) | -| [多語言介面](功能說明/多語言.md) | 切換介面語言 | -| [常見問題](快速入門/常見問題.md) | FAQ | +| 文件 | 說明 | +| ------------------------------------ | -------------------- | +| [快速開始](快速入門/快速開始.md) | 最快部署方式 | +| [支援的轉換器](功能說明/轉換器.md) | 所有可用的轉換格式 | +| [OCR 功能](功能說明/OCR.md) | 光學字元辨識 | +| [翻譯功能](功能說明/翻譯功能.md) | PDF 翻譯(保留公式) | +| [多語言介面](功能說明/多語言介面.md) | 切換介面語言 | +| [常見問題](快速入門/常見問題.md) | FAQ | --- @@ -35,11 +35,11 @@ ### 部署 -| 文件 | 說明 | -| --------------------------------- | --------------------------- | -| [Docker 部署](部署指南/Docker.md) | Docker Run & Docker Compose | -| [反向代理](部署指南/反向代理.md) | Nginx / Traefik / Caddy | -| [範例配置](範例/README.md) | 可直接使用的配置檔 | +| 文件 | 說明 | +| ------------------------------------- | --------------------------- | +| [Docker 部署](部署指南/Docker部署.md) | Docker Run & Docker Compose | +| [反向代理](部署指南/反向代理.md) | Nginx / Traefik / Caddy | +| [範例配置](範例配置/說明文件.md) | 可直接使用的配置檔 | ### 配置 @@ -84,13 +84,13 @@ ``` docs/ -├── README.md ← 您在這裡 +├── 說明文件.md ← 您在這裡 ├── 快速入門/ │ ├── 概覽.md │ ├── 快速開始.md │ └── 常見問題.md ├── 部署指南/ -│ ├── Docker.md +│ ├── Docker部署.md │ └── 反向代理.md ├── 配置設定/ │ ├── 環境變數.md @@ -98,9 +98,9 @@ docs/ │ └── 清理與限制.md ├── 功能說明/ │ ├── 轉換器.md -│ ├── 翻譯.md +│ ├── 翻譯功能.md │ ├── OCR.md -│ └── 多語言.md +│ └── 多語言介面.md ├── API/ │ ├── 總覽.md │ └── 端點.md @@ -112,11 +112,11 @@ docs/ │ ├── 專案結構.md │ ├── 本地開發.md │ └── 貢獻指南.md -└── 範例/ - ├── compose.minimal.yml - ├── compose.production.yml - ├── compose.with-traefik.yml - └── nginx.example.conf +└── 範例配置/ + ├── 最小配置.yml + ├── 生產環境配置.yml + ├── Traefik配置.yml + └── Nginx範例配置.conf ``` --- @@ -141,7 +141,7 @@ docs/ ### 我要部署到生產環境 -1. [Docker 部署](部署指南/Docker.md) +1. [Docker 部署](部署指南/Docker部署.md) 2. [反向代理](部署指南/反向代理.md) 3. [安全性設定](配置設定/安全性.md) 4. [環境變數](配置設定/環境變數.md) @@ -161,11 +161,11 @@ docs/ | 語言 | 說明 | 狀態 | | -------------------------------- | --------------------- | --------- | -| [English](i18n/en/README.md) | English documentation | 🔄 進行中 | -| [简体中文](i18n/zh-CN/README.md) | 简体中文文档 | 📋 規劃中 | -| [日本語](i18n/ja/README.md) | 日本語ドキュメント | 📋 規劃中 | +| [English](多語言/en/Overview.md) | English documentation | 🔄 進行中 | +| [简体中文](多語言/zh-CN/概述.md) | 简体中文文档 | 📋 規劃中 | +| [日本語](多語言/ja/概要.md) | 日本語ドキュメント | 📋 規劃中 | -> 📝 **想幫忙翻譯?** 請參閱 [翻譯指南](i18n/README.md) +> 📝 **想幫忙翻譯?** 請參閱 [翻譯指南](多語言/翻譯指南.md) --- diff --git a/docs/converters.md b/docs/轉換器總覽.md similarity index 98% rename from docs/converters.md rename to docs/轉換器總覽.md index f3d78c7..5af9f85 100644 --- a/docs/converters.md +++ b/docs/轉換器總覽.md @@ -6,7 +6,7 @@ > > - 🔌 [轉換器完整說明](功能說明/轉換器.md) > - 📊 [OCR 功能](功能說明/OCR.md) -> - 🌐 [翻譯功能](功能說明/翻譯.md) +> - 🌐 [翻譯功能](功能說明/翻譯功能.md) > > 此文件將在未來版本中移除。 diff --git a/docs/advanced-usage.md b/docs/進階用法.md similarity index 98% rename from docs/advanced-usage.md rename to docs/進階用法.md index 3211541..0edb852 100644 --- a/docs/advanced-usage.md +++ b/docs/進階用法.md @@ -4,7 +4,7 @@ > > 本文件內容已整合至新的文件結構,請參閱: > -> - 🐳 [Docker 部署(含硬體加速)](部署指南/Docker.md) +> - 🐳 [Docker 部署(含硬體加速)](部署指南/Docker部署.md) > - 🔧 [反向代理設定](部署指南/反向代理.md) > > 此文件將在未來版本中移除。 @@ -134,7 +134,7 @@ convert.example.com { ### Traefik -參考 [docker.md](docker.md#使用-traefik-反向代理) 中的 Traefik 配置。 +參考 [Docker說明.md](Docker說明.md#使用-traefik-反向代理) 中的 Traefik 配置。 --- diff --git a/docs/部署指南/Docker.md b/docs/部署指南/Docker.md index 5ab5c0e..5a23539 100644 --- a/docs/部署指南/Docker.md +++ b/docs/部署指南/Docker.md @@ -268,6 +268,6 @@ docker exec -it convertx-cn /bin/bash ## 相關文件 -- [Docker Compose 詳解](docker-compose.md) +- [Docker Compose 詳解](Docker組合.md) - [反向代理設定](反向代理.md) - [環境變數設定](../配置設定/環境變數.md) diff --git a/docs/部署指南/docker-compose.md b/docs/部署指南/Docker組合.md similarity index 96% rename from docs/部署指南/docker-compose.md rename to docs/部署指南/Docker組合.md index 37d00bc..687d347 100644 --- a/docs/部署指南/docker-compose.md +++ b/docs/部署指南/Docker組合.md @@ -33,7 +33,7 @@ image: convertx/convertx-cn:v0.1.9 # 指定版本 - `latest`:自動獲取最新版本,適合測試環境 - 指定版本:適合生產環境,避免意外升級 -詳見 [版本選擇指南](../versions/)。 +詳見 [版本選擇指南](../版本/)。 --- @@ -156,7 +156,7 @@ healthcheck: ## 完整範例 -請參考 [Docker Compose 範例資料夾](../docker-compose/): +請參考 [Docker Compose 範例資料夾](../Docker組合配置/): - `compose.minimal.yml` - 最精簡設定 - `compose.production.yml` - 生產環境 diff --git a/docs/部署指南/Docker部署.md b/docs/部署指南/Docker部署.md new file mode 100644 index 0000000..5a23539 --- /dev/null +++ b/docs/部署指南/Docker部署.md @@ -0,0 +1,273 @@ +# Docker 部署指南 + +本文件說明如何使用 Docker 部署 ConvertX-CN。 + +--- + +## Docker Image 版本 + +### 官方預建版(推薦) + +| Tag | 說明 | +| ----------------------------- | ---------- | +| `convertx/convertx-cn:latest` | 最新穩定版 | +| `convertx/convertx-cn:v0.1.x` | 指定版本號 | + +**內建功能:** + +- ✅ 核心轉換工具(FFmpeg、LibreOffice、ImageMagick 等) +- ✅ OCR 支援:英文、繁/簡中文、日文、韓文、德文、法文 +- ✅ 字型:Noto CJK、Liberation、自訂中文字型 +- ✅ TexLive(支援 CJK/德/法) + +**Image 大小:約 4-6 GB** + +### 完整版(自行 Build) + +使用 `Dockerfile.full` 自行建構,適合需要: + +- 65 種 OCR 語言 +- 完整 TexLive +- 額外字型套件 + +```bash +docker build -f Dockerfile.full -t convertx-cn-full . +``` + +> ⚠️ 注意:Image 大小可能超過 **10GB**,Build 時間約 **30-60 分鐘** + +--- + +## Docker Run + +### 基本啟動 + +```bash +docker run -d \ + --name convertx-cn \ + --restart unless-stopped \ + -p 3000:3000 \ + -v ./data:/app/data \ + -e TZ=Asia/Taipei \ + -e JWT_SECRET=你的隨機字串至少32字元 \ + convertx/convertx-cn:latest +``` + +### 參數說明 + +| 參數 | 說明 | +| -------------------------- | ---------- | +| `-d` | 背景執行 | +| `--name convertx-cn` | 容器名稱 | +| `--restart unless-stopped` | 自動重啟 | +| `-p 3000:3000` | 連接埠映射 | +| `-v ./data:/app/data` | 資料持久化 | +| `-e TZ=Asia/Taipei` | 時區設定 | + +### 進階選項 + +```bash +docker run -d \ + --name convertx-cn \ + --restart unless-stopped \ + -p 3000:3000 \ + -v ./data:/app/data \ + -e TZ=Asia/Taipei \ + -e JWT_SECRET=你的隨機字串 \ + -e ACCOUNT_REGISTRATION=false \ + -e HTTP_ALLOWED=true \ + -e AUTO_DELETE_EVERY_N_HOURS=24 \ + convertx/convertx-cn:latest +``` + +--- + +## 資料持久化 + +### Volume 結構 + +``` +./data/ +├── convertx.db # SQLite 資料庫 +├── uploads/ # 上傳的原始檔案 +└── output/ # 轉換後的檔案 +``` + +### 建立資料夾 + +**重要**:請務必先建立資料夾,否則 Docker 會建立匿名 volume。 + +**Linux / macOS:** + +```bash +mkdir -p ~/convertx-cn/data +``` + +**Windows PowerShell:** + +```powershell +mkdir C:\convertx-cn\data +``` + +### 備份與還原 + +**備份:** + +```bash +tar -czvf convertx-backup-$(date +%Y%m%d).tar.gz ./data +``` + +**還原:** + +```bash +tar -xzvf convertx-backup-20260120.tar.gz +``` + +--- + +## 硬體加速 + +### NVIDIA GPU (CUDA/NVENC) + +1. 安裝 [NVIDIA Container Toolkit](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/install-guide.html) + +2. Docker Compose 配置: + +```yaml +services: + convertx: + image: convertx/convertx-cn:latest + deploy: + resources: + reservations: + devices: + - driver: nvidia + count: all + capabilities: [gpu] + environment: + - FFMPEG_ARGS=-hwaccel cuda -hwaccel_output_format cuda + - FFMPEG_OUTPUT_ARGS=-c:v h264_nvenc -preset fast +``` + +### Intel Quick Sync Video (QSV) + +```yaml +services: + convertx: + image: convertx/convertx-cn:latest + devices: + - /dev/dri:/dev/dri + environment: + - FFMPEG_ARGS=-hwaccel qsv + - FFMPEG_OUTPUT_ARGS=-c:v h264_qsv -preset faster +``` + +### AMD VAAPI + +```yaml +services: + convertx: + image: convertx/convertx-cn:latest + devices: + - /dev/dri:/dev/dri + environment: + - FFMPEG_ARGS=-hwaccel vaapi -hwaccel_device /dev/dri/renderD128 + - FFMPEG_OUTPUT_ARGS=-c:v h264_vaapi +``` + +--- + +## 資源限制 + +### 記憶體限制 + +```yaml +services: + convertx: + deploy: + resources: + limits: + memory: 4G + reservations: + memory: 2G +``` + +### CPU 限制 + +```yaml +services: + convertx: + deploy: + resources: + limits: + cpus: "2" +``` + +--- + +## 版本更新 + +**1. 拉取最新版本:** + +```bash +docker pull convertx/convertx-cn:latest +``` + +**2. 停止並移除舊容器:** + +```bash +docker stop convertx-cn +docker rm convertx-cn +``` + +**3. 重新啟動(使用相同的參數):** + +```bash +docker run -d --name convertx-cn ... +``` + +或使用 Docker Compose: + +```bash +docker compose pull +docker compose up -d +``` + +--- + +## 疑難排解 + +### 查看日誌 + +```bash +docker logs convertx-cn +``` + +持續追蹤日誌: + +```bash +docker logs -f convertx-cn +``` + +### 進入容器 + +```bash +docker exec -it convertx-cn /bin/bash +``` + +### 常見問題 + +| 問題 | 解決方法 | +| ----------- | ------------------------------ | +| 啟動失敗 | 檢查日誌 `docker logs` | +| Port 被占用 | 改用其他 port `-p 8080:3000` | +| 權限錯誤 | `chmod -R 777 ./data` | +| 記憶體不足 | 增加記憶體限制或減少同時轉換數 | + +--- + +## 相關文件 + +- [Docker Compose 詳解](Docker組合.md) +- [反向代理設定](反向代理.md) +- [環境變數設定](../配置設定/環境變數.md) diff --git a/docs/部署指南/反向代理.md b/docs/部署指南/反向代理.md index 98ec1b7..c1c871b 100644 --- a/docs/部署指南/反向代理.md +++ b/docs/部署指南/反向代理.md @@ -285,6 +285,6 @@ proxy_set_header Connection "upgrade"; ## 相關文件 -- [Docker 部署](docker.md) -- [安全性設定](../configuration/security.md) -- [環境變數](../configuration/environment-variables.md) +- [Docker 部署](Docker部署.md) +- [安全性設定](../配置設定/安全性.md) +- [環境變數](../配置設定/環境變數.md) diff --git a/docs/部署指南/quickstart.md b/docs/部署指南/快速開始.md similarity index 98% rename from docs/部署指南/quickstart.md rename to docs/部署指南/快速開始.md index 7322a6e..2070a18 100644 --- a/docs/部署指南/quickstart.md +++ b/docs/部署指南/快速開始.md @@ -129,4 +129,4 @@ docker compose logs -f # Ctrl+C 退出 - [環境變數完整說明](../配置設定/環境變數.md) - [反向代理與 HTTPS](反向代理.md) -- [版本更新方法](update.md) +- [版本更新方法](版本更新.md) diff --git a/docs/部署指南/update.md b/docs/部署指南/版本更新.md similarity index 98% rename from docs/部署指南/update.md rename to docs/部署指南/版本更新.md index 1b99004..2d162b6 100644 --- a/docs/部署指南/update.md +++ b/docs/部署指南/版本更新.md @@ -141,6 +141,6 @@ services: ## 相關文件 -- [版本選擇指南](../versions/) +- [版本選擇指南](../版本/) - [GitHub Releases](https://github.com/pi-docket/ConvertX-CN/releases) - [Changelog](../../CHANGELOG.md) diff --git a/docs/deployment.md b/docs/部署總覽.md similarity index 97% rename from docs/deployment.md rename to docs/部署總覽.md index d9655a7..3e96951 100644 --- a/docs/deployment.md +++ b/docs/部署總覽.md @@ -4,7 +4,7 @@ > > 本文件內容已整合至新的文件結構,請參閱: > -> - 🐳 [Docker 部署](部署指南/Docker.md) +> - 🐳 [Docker 部署](部署指南/Docker部署.md) > - 🔧 [反向代理設定](部署指南/反向代理.md) > - 🔒 [安全性設定](配置設定/安全性.md) > @@ -389,6 +389,6 @@ docker compose start ## 相關文件 -- [環境變數完整說明](environment-variables.md) -- [Docker Compose 範例](docker-compose/) -- [常見問題](faq.md) +- [環境變數完整說明](配置設定/環境變數.md) +- [Docker Compose 範例](Docker組合配置/) +- [常見問題](快速入門/常見問題.md) diff --git a/docs/配置設定/安全性.md b/docs/配置設定/安全性.md index 2f32107..b434406 100644 --- a/docs/配置設定/安全性.md +++ b/docs/配置設定/安全性.md @@ -254,4 +254,4 @@ chmod 700 ./data - [環境變數設定](環境變數.md) - [反向代理設定](../部署指南/反向代理.md) -- [Docker 部署](../部署指南/Docker.md) +- [Docker 部署](../部署指南/Docker部署.md) diff --git a/docs/配置設定/清理與限制.md b/docs/配置設定/清理與限制.md index 437eea8..07d8fff 100644 --- a/docs/配置設定/清理與限制.md +++ b/docs/配置設定/清理與限制.md @@ -196,4 +196,4 @@ deploy: - [環境變數設定](環境變數.md) - [安全性設定](安全性.md) -- [Docker 部署](../部署指南/Docker.md) +- [Docker 部署](../部署指南/Docker部署.md) diff --git a/docs/配置設定/環境變數.md b/docs/配置設定/環境變數.md index 8af9df8..2cea573 100644 --- a/docs/配置設定/環境變數.md +++ b/docs/配置設定/環境變數.md @@ -266,6 +266,6 @@ environment: ## 相關文件 -- [安全性設定](security.md) -- [Docker 部署](../deployment/docker.md) -- [反向代理設定](../deployment/reverse-proxy.md) +- [安全性設定](安全性.md) +- [Docker 部署](../部署指南/Docker部署.md) +- [反向代理設定](../部署指南/反向代理.md) diff --git a/docs/開發指南/本地開發.md b/docs/開發指南/本地開發.md index 5be02db..84a6144 100644 --- a/docs/開發指南/本地開發.md +++ b/docs/開發指南/本地開發.md @@ -202,6 +202,6 @@ RUST_LOG=debug cargo run ## 相關文件 -- [專案結構](project-structure.md) -- [貢獻指南](contribution.md) -- [測試策略](../testing/test-strategy.md) +- [專案結構](專案結構.md) +- [貢獻指南](貢獻指南.md) +- [測試策略](../測試/測試策略.md)