diff --git a/docs/Docker組合配置/README.md b/docs/Docker組合配置/README.md index c62bd2f..a32693a 100644 --- a/docs/Docker組合配置/README.md +++ b/docs/Docker組合配置/README.md @@ -58,6 +58,6 @@ docker compose up -d ## 相關文件 -- [環境變數完整說明](../環境變數總覽.md) -- [進階部署指南](../部署總覽.md) -- [Docker 進階配置](../Docker說明.md) +- [環境變數完整說明](../配置設定/環境變數.md) +- [Docker 部署指南](../部署指南/Docker部署.md) +- [反向代理設定](../部署指南/反向代理.md) diff --git a/docs/Docker說明.md b/docs/Docker說明.md deleted file mode 100644 index 658cfa7..0000000 --- a/docs/Docker說明.md +++ /dev/null @@ -1,296 +0,0 @@ -# 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 -``` diff --git a/docs/國際化說明.md b/docs/國際化說明.md deleted file mode 100644 index 82f0c18..0000000 --- a/docs/國際化說明.md +++ /dev/null @@ -1,280 +0,0 @@ -# 多語言支援（i18n） - -> ⚠️ **此文件已遷移** -> -> 本文件內容已整合至新的文件結構，請參閱： -> -> - 🌐 [多語言介面支援](功能說明/多語言介面.md) -> -> 此文件將在未來版本中移除。 - ---- - -ConvertX-CN 支援 **65 種語言**，是目前最完整的多語言檔案轉換服務。 - ---- - -## 支援語言列表 - -### 東亞語言（5 種） - -| 代碼 | 語言 | 原生名稱 | -| ------- | ---------------- | -------- | -| `zh-TW` | 繁體中文（預設） | 繁體中文 | -| `zh-CN` | 簡體中文 | 简体中文 | -| `en` | 英文 | English | -| `ja` | 日文 | 日本語 | -| `ko` | 韓文 | 한국어 | - -### 西歐語言（10 種） - -| 代碼 | 語言 | 原生名稱 | -| ---- | ------------ | ---------- | -| `de` | 德文 | Deutsch | -| `fr` | 法文 | Français | -| `es` | 西班牙文 | Español | -| `it` | 義大利文 | Italiano | -| `pt` | 葡萄牙文 | Português | -| `nl` | 荷蘭文 | Nederlands | -| `ca` | 加泰隆尼亞文 | Català | -| `eu` | 巴斯克文 | Euskara | -| `gl` | 加利西亞文 | Galego | -| `mt` | 馬爾他文 | Malti | - -### 北歐語言（5 種） - -| 代碼 | 語言 | 原生名稱 | -| ---- | ------ | -------- | -| `sv` | 瑞典文 | Svenska | -| `da` | 丹麥文 | Dansk | -| `fi` | 芬蘭文 | Suomi | -| `no` | 挪威文 | Norsk | -| `is` | 冰島文 | Íslenska | - -### 東歐語言（12 種） - -| 代碼 | 語言 | 原生名稱 | -| ---- | ------------ | ----------- | -| `ru` | 俄文 | Русский | -| `pl` | 波蘭文 | Polski | -| `uk` | 烏克蘭文 | Українська | -| `cs` | 捷克文 | Čeština | -| `hu` | 匈牙利文 | Magyar | -| `ro` | 羅馬尼亞文 | Română | -| `bg` | 保加利亞文 | Български | -| `hr` | 克羅埃西亞文 | Hrvatski | -| `sk` | 斯洛伐克文 | Slovenčina | -| `sl` | 斯洛維尼亞文 | Slovenščina | -| `sr` | 塞爾維亞文 | Српски | -| `mk` | 馬其頓文 | Македонски | - -### 波羅的海語言（3 種） - -| 代碼 | 語言 | 原生名稱 | -| ---- | ---------- | -------- | -| `lt` | 立陶宛文 | Lietuvių | -| `lv` | 拉脫維亞文 | Latviešu | -| `et` | 愛沙尼亞文 | Eesti | - -### 其他歐洲語言（4 種） - -| 代碼 | 語言 | 原生名稱 | -| ---- | ------------ | -------- | -| `el` | 希臘文 | Ελληνικά | -| `sq` | 阿爾巴尼亞文 | Shqip | -| `ga` | 愛爾蘭文 | Gaeilge | -| `cy` | 威爾斯文 | Cymraeg | - -### 中東語言（4 種） - -| 代碼 | 語言 | 原生名稱 | -| ---- | -------- | -------- | -| `ar` | 阿拉伯文 | العربية | -| `he` | 希伯來文 | עברית | -| `fa` | 波斯文 | فارسی | -| `tr` | 土耳其文 | Türkçe | - -### 南亞語言（10 種） - -| 代碼 | 語言 | 原生名稱 | -| ---- | ------------ | -------- | -| `hi` | 印地文 | हिन्दी | -| `bn` | 孟加拉文 | বাংলা | -| `ta` | 泰米爾文 | தமிழ் | -| `te` | 泰盧固文 | తెలుగు | -| `mr` | 馬拉地文 | मराठी | -| `gu` | 古吉拉特文 | ગુજરાતી | -| `kn` | 卡納達文 | ಕನ್ನಡ | -| `ml` | 馬拉雅拉姆文 | മലയാളം | -| `ne` | 尼泊爾文 | नेपाली | -| `si` | 僧伽羅文 | සිංහල | - -### 東南亞語言（8 種） - -| 代碼 | 語言 | 原生名稱 | -| ----- | -------- | ---------------- | -| `th` | 泰文 | ไทย | -| `vi` | 越南文 | Tiếng Việt | -| `id` | 印尼文 | Bahasa Indonesia | -| `ms` | 馬來文 | Bahasa Melayu | -| `fil` | 菲律賓文 | Filipino | -| `my` | 緬甸文 | မြန်မာ | -| `km` | 高棉文 | ខ្មែរ | -| `lo` | 寮文 | ລາວ | - -### 非洲語言（4 種） - -| 代碼 | 語言 | 原生名稱 | -| ---- | ---------- | --------- | -| `af` | 南非語 | Afrikaans | -| `sw` | 斯瓦希里文 | Kiswahili | -| `am` | 阿姆哈拉文 | አማርኛ | -| `zu` | 祖魯文 | isiZulu | - ---- - -## 語言切換 - -### 方法一：介面切換 - -1. 在網站右上角的導航列找到語言圖示（🌐） -2. 點擊後選擇偏好語言 -3. 語言偏好會自動保存到 Cookie 中 - -### 方法二：URL 參數 - -``` -http://localhost:3000/?lang=ja -``` - -### 方法三：瀏覽器設定 - -ConvertX-CN 會自動偵測瀏覽器的語言設定。 - ---- - -## 自動偵測 - -首次訪問時，系統會根據以下優先順序選擇語言： - -1. Cookie 中儲存的語言偏好 -2. URL 參數中的 `lang` 值 -3. 瀏覽器的 `Accept-Language` 標頭 -4. 預設語言（繁體中文 `zh-TW`） - ---- - -## 新增語言 - -如要添加新語言支援，請按以下步驟： - -### 1. 建立翻譯檔案 - -在 `src/locales/` 目錄新增語言檔案，例如 `xx.json`： - -```json -{ - "common": { - "appName": "ConvertX-CN", - "poweredBy": "Powered by", - "version": "v{version}", - "loading": "...", - ... - }, - "nav": { - "history": "...", - "account": "...", - ... - }, - ... -} -``` - -### 2. 在 index.ts 中註冊 - -編輯 `src/i18n/index.ts`： - -```typescript -// 導入新語言檔案 -import xx from "../locales/xx.json"; - -// 在 SupportedLocale 類型中添加 -export type SupportedLocale = "en" | "zh-TW" | ... | "xx"; - -// 在 supportedLocales 陣列中添加 -export const supportedLocales: LocaleConfig[] = [ - // ... - { code: "xx", name: "Language Name", nativeName: "原生名稱" }, -]; - -// 在 translations 物件中註冊 -const translations: Record = { - // ... - xx: xx as TranslationData, -}; -``` - -### 3. 測試 - -```bash -bun run dev -# 訪問 http://localhost:3000/?lang=xx -``` - ---- - -## 語言選擇器 UI 規範 - -為確保語言切換體驗一致，ConvertX-CN 的語言選擇器遵循以下規範： - -### 視覺設計 - -| 項目 | 規範 | -| ------------ | ----------------------------- | -| 圖示大小 | 與旁邊文字高度一致（h-6 w-6） | -| 下拉選單背景 | 完全不透明（bg-neutral-800） | -| 捲動條 | 明確可見的 scrollbar 樣式 | -| 最大高度 | 320px，超過則顯示捲動條 | - -### 行為規範 - -- Setup / Login / 主頁使用同一套語言選擇器組件 -- 語言切換後自動重新載入頁面 -- 語言偏好儲存於 Cookie，跨頁面保持一致 -- 預設根據瀏覽器語言自動偵測 - -### 已知問題修復（v0.1.9） - -- 語言圖示尺寸過小 → 已修復 -- 下拉選單半透明 → 已修復 -- 捲動條不明顯 → 已新增 scrollbar 樣式 - ---- - -## 翻譯 Fallback - -如果某個翻譯鍵缺失，系統會： - -1. 嘗試使用英文（`en`）翻譯 -2. 如果英文也缺失，顯示鍵名（如 `nav.history`） - ---- - -## 貢獻翻譯 - -歡迎提交 Pull Request 來新增或改進翻譯！ - -### 翻譯指南 - -1. **完整翻譯**：確保所有鍵都有翻譯 -2. **保留佔位符**：`{version}`、`{count}` 等佔位符不要翻譯 -3. **自然表達**：使用該語言的自然表達方式 -4. **一致性**：同一個詞在不同地方使用相同翻譯 -5. **測試**：在實際介面中測試翻譯效果 - -### 提交流程 - -1. Fork 此專案 -2. 建立新語言檔案或修改現有翻譯 -3. 測試確認無誤 -4. 提交 Pull Request diff --git a/docs/常見問題總覽.md b/docs/常見問題總覽.md deleted file mode 100644 index 7cba0dc..0000000 --- a/docs/常見問題總覽.md +++ /dev/null @@ -1,164 +0,0 @@ -# 常見問題 FAQ - -> ⚠️ **此文件已遷移** -> -> 本文件內容已整合至新的文件結構，請參閱： -> -> - ❓ [常見問題 FAQ](快速入門/常見問題.md) -> -> 此文件將在未來版本中移除。 - ---- - -## 🔐 登入與帳號 - -### Q: 如何註冊帳號？ - -首次訪問 ConvertX-CN 時： - -1. 開啟 `http://localhost:3000` -2. 點擊右上角 **Register** -3. 輸入 Email 和密碼 -4. 完成！系統會自動登入 - -> ✅ **預設開放註冊**，無需設定任何環境變數 - -### Q: 可以關閉公開註冊嗎？ - -可以。如果您想限制只有現有用戶可使用： - -```yaml -environment: - - ACCOUNT_REGISTRATION=false -``` - -> ⚠️ 請確保您已經有至少一個帳號，否則將無法登入 - -### Q: 忘記密碼怎麼辦？ - -目前版本尚未提供密碼重設功能。您可以： - -1. 刪除 `data/convertx.db` -2. 重新啟動容器 -3. 重新註冊 - -> ⚠️ 這會刪除所有用戶資料和轉換歷史 - ---- - -## 🐳 Docker 相關 - -### Q: 為什麼 Image 這麼大（4-6 GB）？ - -ConvertX-CN 是「完整版」，內建： - -- LibreOffice（文件轉換） -- TexLive（LaTeX 支援） -- FFmpeg（影音轉換） -- Tesseract + 多語言 OCR -- CJK 字型 - -如果您只需要基本功能，可使用原作者的輕量版： - -- `ghcr.io/c4illin/convertx:latest` - -### Q: Docker 啟動失敗？ - -常見原因： - -1. **Port 被占用**：改用其他 port，如 `-p 3001:3000` -2. **磁碟空間不足**：Image 需約 6GB -3. **權限問題**：確保 `./data` 資料夾有寫入權限 - -```bash -chmod -R 777 ./data -``` - -### Q: 資料存在哪裡？ - -所有資料存放在掛載的 `/app/data` 目錄： - -- `convertx.db` - SQLite 資料庫 -- `uploads/` - 上傳的原始檔案 -- `output/` - 轉換後的檔案 - ---- - -## 🌍 語言相關 - -### Q: 如何切換語言？ - -1. 點擊右上角語言圖示 🌐 -2. 從下拉選單選擇語言 -3. 頁面自動更新 - -語言偏好會儲存在 Cookie 中。 - -### Q: 支援哪些語言？ - -目前支援 65 種語言，詳見 [i18n.md](i18n.md) - -### Q: 如何貢獻翻譯？ - -1. 複製 `src/locales/en.json` -2. 重命名為 `xx.json`（語言代碼） -3. 翻譯所有文字 -4. 在 `src/i18n/index.ts` 中註冊 -5. 提交 Pull Request - ---- - -## 📄 轉換相關 - -### Q: 支援哪些格式？ - -ConvertX-CN 支援數百種格式，包括： - -- **影音**：MP4, AVI, MKV, MP3, WAV 等 -- **圖片**：PNG, JPG, WEBP, SVG, PDF 等 -- **文件**：DOCX, PDF, XLSX, PPTX 等 -- **電子書**：EPUB, MOBI, AZW3 等 - -完整列表見 [converters.md](converters.md) - -### Q: 轉換失敗怎麼辦？ - -1. 檢查檔案是否損壞 -2. 確認格式組合是否支援 -3. 查看容器 logs： - ```bash - docker logs convertx-cn - ``` - -### Q: 檔案大小有限制嗎？ - -預設無硬性限制，但大檔案： - -- 上傳需要更長時間 -- 轉換可能耗用大量記憶體 - -建議為容器分配足夠的記憶體資源。 - ---- - -## 🔧 進階問題 - -### Q: 可以使用 HTTPS 嗎？ - -可以。推薦使用反向代理（如 Traefik、Nginx）處理 SSL。 - -詳見 [advanced-usage.md](advanced-usage.md) - -### Q: 如何備份資料？ - -```bash -# 備份 -docker cp convertx-cn:/app/data ./backup - -# 還原 -docker cp ./backup/. convertx-cn:/app/data -``` - -### Q: 有 API 文件嗎？ - -目前尚未提供正式的 API 文件。如有 API 需求，歡迎開 Issue 討論。 diff --git a/docs/快速入門總覽.md b/docs/快速入門總覽.md deleted file mode 100644 index 880174c..0000000 --- a/docs/快速入門總覽.md +++ /dev/null @@ -1,183 +0,0 @@ -# 快速開始 - -> ⚠️ **此文件已遷移** -> -> 本文件內容已整合至新的文件結構，請參閱： -> -> - 📖 [概覽](快速入門/概覽.md) -> - 🚀 [快速開始](快速入門/快速開始.md) -> - ❓ [常見問題](快速入門/常見問題.md) -> -> 此文件將在未來版本中移除。 - ---- - -> 本文件提供完整部署步驟。若只需最快啟動，請參考 [說明文件](說明文件.md)。 - ---- - -## 系統需求 - -| 需求 | 最低 | 建議 | -| -------- | ------ | ------ | -| Docker | 20.10+ | 24.0+ | -| RAM | 4 GB | 8 GB | -| 磁碟空間 | 10 GB | 20 GB | -| CPU | 2 核心 | 4 核心 | - ---- - -## 事前準備 - -建立資料夾（重要）： - -```bash -mkdir -p ~/convertx-cn/data && cd ~/convertx-cn -``` - -> `data` 資料夾是主機上的實體資料夾，用於存放上傳檔案與轉換結果。 - ---- - -## 最快方式：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 -``` - -開啟瀏覽器訪問 `http://localhost:3000`： - -1. 點擊右上角 **Register** 註冊帳號 -2. 輸入 Email 和密碼 -3. 完成！開始使用 - ---- - -## 推薦方式：Docker Compose - -### 1. 建立配置檔 - -建立 `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=請更換為一個長且隨機的字串 - - HTTP_ALLOWED=false - - AUTO_DELETE_EVERY_N_HOURS=24 -``` - -### 2. 啟動服務 - -```bash -docker compose up -d -``` - -### 3. 開始使用 - -1. 開啟瀏覽器訪問 `http://localhost:3000` -2. 點擊「Register」建立帳號 -3. 登入後即可開始轉換檔案！ - ---- - -## 首次設定 - -### 建立管理員帳號 - -首次訪問時，ConvertX-CN 會顯示設定頁面，讓您建立第一個帳號。此帳號即為管理員。 - -### 註冊功能 - -- `ACCOUNT_REGISTRATION=true`：允許其他人註冊 -- `ACCOUNT_REGISTRATION=false`：停用註冊（單人使用） - ---- - -## 驗證安裝 - -### 檢查容器狀態 - -```bash -docker ps -# 應該看到 convertx-cn 容器正在運行 - -docker logs convertx-cn -# 應該看到 "🦊 Elysia is running at http://localhost:3000" -``` - -### 健康檢查 - -```bash -curl http://localhost:3000/healthcheck -# 應該返回 "OK" -``` - ---- - -## 更新版本 - -```bash -# Docker Compose -docker compose pull -docker compose up -d - -# 或 Docker Run -docker pull convertx/convertx-cn:latest -docker stop convertx-cn -docker rm convertx-cn -# 然後重新執行 docker run 指令 -``` - ---- - -## 常見問題 - -### 無法訪問頁面 - -1. 確認容器正在運行：`docker ps` -2. 檢查連接埠是否被占用：`netstat -an | grep 3000` -3. 查看錯誤日誌：`docker logs convertx-cn` - -### 權限錯誤 - -```bash -# 確保 data 目錄有正確權限 -chmod -R 777 ./data -``` - -### 記憶體不足 - -ConvertX-CN 內建完整依賴，建議至少 4GB RAM。可透過 Docker 限制記憶體使用： - -```yaml -deploy: - resources: - limits: - memory: 4G -``` - ---- - -## 下一步 - -- 📖 [Docker 配置](Docker說明.md) - 進階 Docker 設定 -- ⚙️ [環境變數](環境變數總覽.md) - 所有可用設定 -- 🔧 [進階用法](進階用法.md) - 硬體加速、反向代理 -- 🌍 [多語言](國際化說明.md) - 語言設定與自訂 diff --git a/docs/環境變數總覽.md b/docs/環境變數總覽.md index 53c2642..adbca12 100644 --- a/docs/環境變數總覽.md +++ b/docs/環境變數總覽.md @@ -21,7 +21,7 @@ - [環境變數完整說明](配置設定/環境變數.md) - [安全性設定](配置設定/安全性.md) -- [進階部署指南](部署總覽.md) +- [Docker 部署指南](部署指南/Docker部署.md) --- @@ -152,7 +152,7 @@ environment: ## 相關文件 -- [進階部署指南](部署總覽.md) +- [Docker 部署指南](部署指南/Docker部署.md) - [Docker Compose 範例](Docker組合配置/) - [常見問題](快速入門/常見問題.md) diff --git a/docs/網址ID與儲存.md b/docs/網址ID與儲存.md deleted file mode 100644 index b31e503..0000000 --- a/docs/網址ID與儲存.md +++ /dev/null @@ -1,193 +0,0 @@ -# URL ID 與儲存機制 - -> ⚠️ **此文件已遷移** -> -> 本文件內容已整合至新的文件結構，請參閱： -> -> - 🛠️ [專案結構](開發指南/專案結構.md) -> - 🐳 [Docker 部署](部署指南/Docker部署.md) -> -> 此文件將在未來版本中移除。 - ---- - -## 檔案儲存結構 - -ConvertX-CN 使用以下目錄結構儲存檔案： - -``` -/app/data/ -├── convertx.db # SQLite 資料庫 -├── uploads/ # 上傳的原始檔案 -│ └── {user_id}/ -│ └── {job_id}/ -│ ├── file1.docx -│ └── file2.pdf -└── output/ # 轉換後的檔案 - └── {user_id}/ - └── {job_id}/ - ├── file1.pdf - └── file2.txt -``` - ---- - -## Job ID 說明 - -每次轉換任務都會產生一個唯一的 Job ID，用於： - -- 追蹤轉換進度 -- 組織檔案儲存 -- 生成下載連結 - -### Job ID 格式 - -Job ID 是一個 UUID v4 格式的字串，例如： - -``` -550e8400-e29b-41d4-a716-446655440000 -``` - ---- - -## URL 結構 - -### 結果頁面 - -``` -/results/{job_id} -``` - -例如： - -``` -http://localhost:3000/results/550e8400-e29b-41d4-a716-446655440000 -``` - -### 下載單一檔案 - -``` -/download/{user_id}/{job_id}/{filename} -``` - -### 下載所有檔案（Tar） - -``` -/archive/{job_id} -``` - ---- - -## 資料持久化 - -### Docker Volume 映射 - -為了確保資料不會在容器重啟後遺失，請務必映射 `/app/data` 目錄： - -```yaml -volumes: - - ./data:/app/data -``` - -或使用 Named Volume： - -```yaml -volumes: - - convertx-data:/app/data - -volumes: - convertx-data: -``` - ---- - -## 自動清理 - -ConvertX-CN 會根據 `AUTO_DELETE_EVERY_N_HOURS` 設定自動清理過期檔案。 - -### 清理邏輯 - -1. 系統每 N 小時執行一次清理 -2. 刪除建立時間超過 N 小時的 Job -3. 同時刪除對應的上傳檔案和輸出檔案 -4. 資料庫記錄也會被清除 - -### 設定範例 - -```yaml -# 每 24 小時清理一次 -- AUTO_DELETE_EVERY_N_HOURS=24 - -# 每 1 小時清理一次（公開服務建議） -- AUTO_DELETE_EVERY_N_HOURS=1 - -# 停用自動清理 -- AUTO_DELETE_EVERY_N_HOURS=0 -``` - ---- - -## 資料庫 - -ConvertX-CN 使用 SQLite 作為資料庫，儲存於 `/app/data/convertx.db`。 - -### 資料表結構 - -#### users - -| 欄位 | 類型 | 說明 | -| -------- | ------- | --------- | -| id | INTEGER | 使用者 ID | -| email | TEXT | 電子郵件 | -| password | TEXT | 密碼雜湊 | - -#### jobs - -| 欄位 | 類型 | 說明 | -| ------------ | ------- | --------- | -| id | TEXT | Job UUID | -| user_id | INTEGER | 使用者 ID | -| num_files | INTEGER | 檔案數量 | -| date_created | TEXT | 建立時間 | - -#### file_names - -| 欄位 | 類型 | 說明 | -| ---------------- | ------- | -------- | -| id | INTEGER | 檔案 ID | -| job_id | TEXT | Job UUID | -| input_file_name | TEXT | 原始檔名 | -| output_file_name | TEXT | 輸出檔名 | -| status | TEXT | 轉換狀態 | - ---- - -## 備份與還原 - -### 備份 - -```bash -# 備份整個 data 目錄 -tar -czvf convertx-backup-$(date +%Y%m%d).tar.gz ./data - -# 僅備份資料庫 -cp ./data/convertx.db ./backup-convertx-$(date +%Y%m%d).db -``` - -### 還原 - -```bash -# 還原整個 data 目錄 -tar -xzvf convertx-backup-20240101.tar.gz - -# 還原資料庫 -cp ./backup-convertx-20240101.db ./data/convertx.db -``` - ---- - -## 注意事項 - -1. **權限問題**：確保 Docker 容器有權限寫入 data 目錄 -2. **磁碟空間**：大量轉換可能佔用大量磁碟空間，建議設定自動清理 -3. **資料安全**：敏感文件轉換後建議手動刪除或縮短保留時間 diff --git a/docs/轉換器總覽.md b/docs/轉換器總覽.md deleted file mode 100644 index 5af9f85..0000000 --- a/docs/轉換器總覽.md +++ /dev/null @@ -1,61 +0,0 @@ -# 支援的轉換器 - -> ⚠️ **此文件已遷移** -> -> 本文件內容已整合至新的文件結構，請參閱： -> -> - 🔌 [轉換器完整說明](功能說明/轉換器.md) -> - 📊 [OCR 功能](功能說明/OCR.md) -> - 🌐 [翻譯功能](功能說明/翻譯功能.md) -> -> 此文件將在未來版本中移除。 - ---- - -ConvertX-CN 完整版已內建以下所有轉換器，開箱即用。 - -## 轉換器列表 - -| 轉換器 | 用途 | 輸入格式數 | 輸出格式數 | -| --------------------------------------------------------------- | ---------- | ---------- | ---------- | -| [Inkscape](https://inkscape.org/) | 向量圖形 | 7 | 17 | -| [libjxl](https://github.com/libjxl/libjxl) | JPEG XL | 11 | 11 | -| [resvg](https://github.com/RazrFalcon/resvg) | SVG | 1 | 1 | -| [Vips](https://github.com/libvips/libvips) | 圖片 | 45 | 23 | -| [libheif](https://github.com/strukturag/libheif) | HEIF | 2 | 4 | -| [XeLaTeX](https://tug.org/xetex/) | LaTeX | 1 | 1 | -| [Calibre](https://calibre-ebook.com/) | 電子書 | 26 | 19 | -| [LibreOffice](https://www.libreoffice.org/) | 文件 | 41 | 22 | -| [Dasel](https://github.com/TomWright/dasel) | 資料檔案 | 5 | 4 | -| [Pandoc](https://pandoc.org/) | 文件 | 43 | 65 | -| [msgconvert](https://github.com/mvz/email-outlook-message-perl) | Outlook | 1 | 1 | -| VCF to CSV | 聯絡人 | 1 | 1 | -| [dvisvgm](https://dvisvgm.de/) | 向量圖形 | 4 | 2 | -| [ImageMagick](https://imagemagick.org/) | 圖片 | 245 | 183 | -| [GraphicsMagick](http://www.graphicsmagick.org/) | 圖片 | 167 | 130 | -| [Assimp](https://github.com/assimp/assimp) | 3D 模型 | 77 | 23 | -| [FFmpeg](https://ffmpeg.org/) | 影音 | ~472 | ~199 | -| [Potrace](https://potrace.sourceforge.net/) | 點陣轉向量 | 4 | 11 | -| [VTracer](https://github.com/visioncortex/vtracer) | 點陣轉向量 | 8 | 1 | -| [Markitdown](https://github.com/microsoft/markitdown) | 文件 | 6 | 1 | - -> 註：FFmpeg 的格式數量包含部分重複格式。 - -## 內建依賴 - -ConvertX-CN 完整版已預載： - -| 類別 | 內建內容 | -| ------------ | ---------------------------------------------------------------- | -| **文件轉換** | LibreOffice (headless)、Pandoc | -| **LaTeX** | TexLive Full（完整版，支援所有 LaTeX 需求） | -| **OCR 識別** | Tesseract OCR + 繁體中文、簡體中文、日文、韓文、英文、德文語言包 | -| **CJK 字型** | Noto CJK（中日韓）、Noto Emoji、微軟核心字型、標楷體 | -| **影音轉換** | FFmpeg、ImageMagick、GraphicsMagick | -| **向量圖形** | Inkscape、Potrace、VTracer、resvg | -| **電子書** | Calibre | -| **其他** | Ghostscript、MuPDF、Poppler、libheif、libjxl 等 | - -## 新增轉換器 - -如需新增轉換器支援，請至 [GitHub Issues](https://github.com/pi-docket/ConvertX-CN/issues) 提出需求或直接發送 Pull Request。 diff --git a/docs/進階用法.md b/docs/進階用法.md deleted file mode 100644 index 0edb852..0000000 --- a/docs/進階用法.md +++ /dev/null @@ -1,288 +0,0 @@ -# 進階用法 - -> ⚠️ **此文件已遷移** -> -> 本文件內容已整合至新的文件結構，請參閱： -> -> - 🐳 [Docker 部署（含硬體加速）](部署指南/Docker部署.md) -> - 🔧 [反向代理設定](部署指南/反向代理.md) -> -> 此文件將在未來版本中移除。 - ---- - -## 硬體加速 - -### NVIDIA GPU (CUDA/NVENC) - -#### 1. 安裝 NVIDIA Container Toolkit - -```bash -# Ubuntu/Debian -curl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey | sudo gpg --dearmor -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg -curl -s -L https://nvidia.github.io/libnvidia-container/stable/deb/nvidia-container-toolkit.list | \ - sed 's#deb https://#deb [signed-by=/usr/share/keyrings/nvidia-container-toolkit-keyring.gpg] https://#g' | \ - sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list -sudo apt-get update -sudo apt-get install -y nvidia-container-toolkit -sudo nvidia-ctk runtime configure --runtime=docker -sudo systemctl restart docker -``` - -#### 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 -``` - ---- - -## 反向代理 - -### Nginx - -```nginx -server { - listen 80; - server_name convert.example.com; - return 301 https://$server_name$request_uri; -} - -server { - listen 443 ssl http2; - server_name convert.example.com; - - ssl_certificate /etc/nginx/ssl/cert.pem; - ssl_certificate_key /etc/nginx/ssl/key.pem; - - client_max_body_size 0; # 無檔案大小限制 - - location / { - proxy_pass http://localhost:3000; - proxy_http_version 1.1; - proxy_set_header Upgrade $http_upgrade; - proxy_set_header Connection 'upgrade'; - 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; - proxy_cache_bypass $http_upgrade; - - # 長時間連線支援（大檔案轉換） - proxy_read_timeout 3600s; - proxy_send_timeout 3600s; - } -} -``` - -### Caddy - -``` -convert.example.com { - reverse_proxy localhost:3000 { - header_up X-Real-IP {remote_host} - header_up X-Forwarded-Proto {scheme} - } - - request_body { - max_size 0 # 無限制 - } -} -``` - -### Traefik - -參考 [Docker說明.md](Docker說明.md#使用-traefik-反向代理) 中的 Traefik 配置。 - ---- - -## 子路徑部署 - -如果需要在子路徑部署（如 `https://example.com/convertx`）： - -### 1. 設定環境變數 - -```yaml -environment: - - WEBROOT=/convertx -``` - -### 2. Nginx 配置 - -```nginx -location /convertx/ { - proxy_pass http://localhost:3000/; - # ... 其他 proxy 設定 -} -``` - -### 3. Caddy 配置 - -``` -example.com { - handle_path /convertx/* { - reverse_proxy localhost:3000 - } -} -``` - ---- - -## 限制同時轉換數 - -防止伺服器過載： - -```yaml -environment: - - MAX_CONVERT_PROCESS=4 # 最多同時 4 個轉換任務 -``` - ---- - -## 匿名模式 - -允許不登入即可使用： - -```yaml -environment: - - ALLOW_UNAUTHENTICATED=true - - HIDE_HISTORY=true # 建議同時隱藏歷史 - - AUTO_DELETE_EVERY_N_HOURS=1 # 快速清理 -``` - ---- - -## 高可用部署 - -### 多容器部署 - -ConvertX-CN 支援多容器部署，但需注意： - -1. **共享儲存**：所有容器需存取相同的 `/app/data` 目錄 -2. **資料庫鎖定**：SQLite 在高併發下可能有問題 -3. **JWT Secret**：所有容器需使用相同的 `JWT_SECRET` - -```yaml -services: - convertx-1: - image: convertx/convertx-cn:latest - volumes: - - shared-data:/app/data - environment: - - JWT_SECRET=${JWT_SECRET} - - convertx-2: - image: convertx/convertx-cn:latest - volumes: - - shared-data:/app/data - environment: - - JWT_SECRET=${JWT_SECRET} - - nginx: - image: nginx:alpine - ports: - - "80:80" - volumes: - - ./nginx.conf:/etc/nginx/nginx.conf - -volumes: - shared-data: - driver: local - driver_opts: - type: nfs - o: addr=nfs-server,rw - device: ":/path/to/shared/data" -``` - ---- - -## 效能調優 - -### 記憶體限制 - -```yaml -deploy: - resources: - limits: - memory: 8G - reservations: - memory: 2G -``` - -### CPU 限制 - -```yaml -deploy: - resources: - limits: - cpus: "4" - reservations: - cpus: "1" -``` - ---- - -## 日誌管理 - -### 查看日誌 - -```bash -docker logs convertx-cn -docker logs -f convertx-cn # 即時追蹤 -docker logs --tail 100 convertx-cn # 最後 100 行 -``` - -### 日誌輪轉 - -```yaml -services: - convertx: - # ... - logging: - driver: "json-file" - options: - max-size: "10m" - max-file: "3" -``` diff --git a/docs/部署總覽.md b/docs/部署總覽.md deleted file mode 100644 index 3e96951..0000000 --- a/docs/部署總覽.md +++ /dev/null @@ -1,394 +0,0 @@ -# 進階部署指南 - -> ⚠️ **此文件已遷移** -> -> 本文件內容已整合至新的文件結構，請參閱： -> -> - 🐳 [Docker 部署](部署指南/Docker部署.md) -> - 🔧 [反向代理設定](部署指南/反向代理.md) -> - 🔒 [安全性設定](配置設定/安全性.md) -> -> 此文件將在未來版本中移除。 - ---- - -本文件說明如何在生產環境中部署 ConvertX-CN，包括 Reverse Proxy、HTTPS、安全性設定等。 - ---- - -## 目錄 - -- [部署前檢查清單](#部署前檢查清單) -- [Reverse Proxy 設定](#reverse-proxy-設定) - - [Nginx](#nginx) - - [Traefik](#traefik) - - [Caddy](#caddy) -- [HTTPS 設定](#https-設定) -- [安全性建議](#安全性建議) -- [子路徑部署](#子路徑部署) -- [效能調整](#效能調整) -- [備份與還原](#備份與還原) - ---- - -## 部署前檢查清單 - -在部署到生產環境前，請確認以下項目： - -- [ ] 已建立 `data` 資料夾（實體資料夾，非匿名 volume） -- [ ] 已設定固定的 `JWT_SECRET`（至少 32 字元） -- [ ] 已關閉 `ACCOUNT_REGISTRATION`（或確認要開放註冊） -- [ ] 已設定 `TRUST_PROXY=true`（若使用 Reverse Proxy） -- [ ] 已設定 `HTTP_ALLOWED=false`（若有 HTTPS） -- [ ] 已設定防火牆規則 -- [ ] 已設定定期備份 - ---- - -## Reverse Proxy 設定 - -### 重要環境變數 - -透過 Reverse Proxy 存取時，請設定： - -```yaml -environment: - - TRUST_PROXY=true # 信任 X-Forwarded-* headers - - HTTP_ALLOWED=false # Proxy 已處理 HTTPS -``` - -### Nginx - -```nginx -# /etc/nginx/sites-available/convertx -server { - listen 80; - server_name convertx.example.com; - - # 強制跳轉 HTTPS - return 301 https://$server_name$request_uri; -} - -server { - listen 443 ssl http2; - server_name convertx.example.com; - - # 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 安全設定 - ssl_protocols TLSv1.2 TLSv1.3; - ssl_prefer_server_ciphers on; - ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256; - - # 檔案上傳大小限制（根據需求調整） - client_max_body_size 500M; - - # 上傳超時設定 - proxy_read_timeout 300s; - proxy_send_timeout 300s; - - location / { - proxy_pass http://127.0.0.1:3000; - proxy_http_version 1.1; - - # 必要的 headers - 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; - - # WebSocket 支援（若需要） - proxy_set_header Upgrade $http_upgrade; - proxy_set_header Connection "upgrade"; - } -} -``` - -### Traefik - -#### 使用 Docker Labels - -```yaml -# docker-compose.yml -services: - convertx: - image: convertx/convertx-cn:latest - container_name: convertx-cn - restart: unless-stopped - volumes: - - ./data:/app/data - environment: - - JWT_SECRET=your-secret-key - - TRUST_PROXY=true - - HTTP_ALLOWED=false - labels: - - "traefik.enable=true" - - "traefik.http.routers.convertx.rule=Host(`convertx.example.com`)" - - "traefik.http.routers.convertx.entrypoints=websecure" - - "traefik.http.routers.convertx.tls=true" - - "traefik.http.routers.convertx.tls.certresolver=letsencrypt" - - "traefik.http.services.convertx.loadbalancer.server.port=3000" - networks: - - traefik-network - -networks: - traefik-network: - external: true -``` - -#### 使用動態配置檔 - -```yaml -# traefik/dynamic/convertx.yml -http: - routers: - convertx: - rule: "Host(`convertx.example.com`)" - service: convertx - entryPoints: - - websecure - tls: - certResolver: letsencrypt - - services: - convertx: - loadBalancer: - servers: - - url: "http://127.0.0.1:3000" -``` - -### Caddy - -``` -# Caddyfile -convertx.example.com { - reverse_proxy 127.0.0.1:3000 - - # 檔案上傳大小限制 - request_body { - max_size 500MB - } -} -``` - -Caddy 會自動處理 HTTPS 憑證。 - ---- - -## HTTPS 設定 - -### Let's Encrypt（推薦） - -使用 Certbot 取得免費憑證： - -```bash -# 安裝 Certbot -sudo apt install certbot python3-certbot-nginx - -# 取得憑證（Nginx） -sudo certbot --nginx -d convertx.example.com - -# 自動續約測試 -sudo certbot renew --dry-run -``` - -### 自簽憑證（測試用） - -```bash -# 產生自簽憑證 -openssl req -x509 -nodes -days 365 -newkey rsa:2048 \ - -keyout /etc/ssl/private/convertx.key \ - -out /etc/ssl/certs/convertx.crt \ - -subj "/CN=convertx.example.com" -``` - ---- - -## 安全性建議 - -### 1. 環境變數設定 - -```yaml -environment: - # 必須設定固定值 - - JWT_SECRET=使用 openssl rand -hex 32 產生 - - # 關閉不需要的功能 - - ACCOUNT_REGISTRATION=false - - ALLOW_UNAUTHENTICATED=false - - HTTP_ALLOWED=false - - # 定期清理檔案 - - AUTO_DELETE_EVERY_N_HOURS=24 -``` - -### 2. 防火牆設定 - -```bash -# 只開放 80 和 443 -sudo ufw allow 80/tcp -sudo ufw allow 443/tcp -sudo ufw enable - -# 不要直接開放 3000 埠 -``` - -### 3. Docker 網路隔離 - -```yaml -services: - convertx: - # 只監聽 localhost - ports: - - "127.0.0.1:3000:3000" -``` - -### 4. 資源限制 - -```yaml -services: - convertx: - deploy: - resources: - limits: - cpus: "4" - memory: 8G - reservations: - cpus: "1" - memory: 2G -``` - ---- - -## 子路徑部署 - -若需要在子路徑部署（如 `https://example.com/convertx/`）： - -### 環境變數 - -```yaml -environment: - - WEBROOT=/convertx -``` - -### Nginx 設定 - -```nginx -location /convertx/ { - 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; -} -``` - ---- - -## 效能調整 - -### 1. 限制同時轉換數 - -```yaml -environment: - - MAX_CONVERT_PROCESS=4 -``` - -### 2. FFmpeg 硬體加速 - -```yaml -environment: - # NVIDIA GPU - - FFMPEG_ARGS=-hwaccel cuda - - # Intel QSV - - FFMPEG_ARGS=-hwaccel qsv - - # AMD VAAPI - - FFMPEG_ARGS=-hwaccel vaapi -``` - -### 3. 容器資源限制 - -見上方「資源限制」區塊。 - ---- - -## 備份與還原 - -### 備份 - -```bash -# 停止容器 -docker compose stop - -# 備份 data 資料夾 -tar -czvf convertx-backup-$(date +%Y%m%d).tar.gz data/ - -# 重新啟動 -docker compose start -``` - -### 自動備份腳本 - -```bash -#!/bin/bash -# /opt/scripts/backup-convertx.sh - -BACKUP_DIR="/opt/backups/convertx" -DATA_DIR="/opt/convertx/data" -KEEP_DAYS=7 - -# 建立備份 -mkdir -p $BACKUP_DIR -tar -czvf "$BACKUP_DIR/convertx-$(date +%Y%m%d).tar.gz" -C $(dirname $DATA_DIR) $(basename $DATA_DIR) - -# 清理舊備份 -find $BACKUP_DIR -name "convertx-*.tar.gz" -mtime +$KEEP_DAYS -delete -``` - -加入 crontab： - -```bash -# 每天凌晨 3 點備份 -0 3 * * * /opt/scripts/backup-convertx.sh -``` - -### 還原 - -```bash -# 停止容器 -docker compose stop - -# 還原 data 資料夾 -tar -xzvf convertx-backup-20260120.tar.gz - -# 重新啟動 -docker compose start -``` - ---- - -## 常見問題 - -### 問題：Reverse Proxy 後登入失敗 - -**解決方案**：設定 `TRUST_PROXY=true` - -### 問題：上傳大檔案失敗 - -**解決方案**：調整 Nginx 的 `client_max_body_size` - -### 問題：轉換超時 - -**解決方案**：調整 Nginx 的 `proxy_read_timeout` - ---- - -## 相關文件 - -- [環境變數完整說明](配置設定/環境變數.md) -- [Docker Compose 範例](Docker組合配置/) -- [常見問題](快速入門/常見問題.md)