Refactor documentation for improved clarity and consistency
- Updated tables for service ports, environment variables, HTTP status codes, and error codes to enhance readability. - Streamlined JavaScript examples for file conversion and added comments for better understanding. - Enhanced troubleshooting section with clearer formatting and additional explanations. - Improved licensing section with detailed requirements and third-party component licenses. - Organized the document structure for better navigation and accessibility.
This commit is contained in:
Your Name
parent
caecb2e001
commit
394dcbec1a
11 changed files with 538 additions and 497 deletions
|
|
@ -20,38 +20,38 @@
|
|||
|
||||
### 🔒 安全性設定
|
||||
|
||||
| 變數 | 必要性 | 說明 | 預設值 | 範例 |
|
||||
|------|--------|------|--------|------|
|
||||
| `JWT_SECRET` | **必須** | Token 驗證密鑰 | 隨機（每次重啟變） | `Xk9mPqL2vN7wR4tY6uI8...` |
|
||||
| `HTTP_ALLOWED` | 否 | 是否允許 HTTP 連線 | `false` | `true` / `false` |
|
||||
| `TRUST_PROXY` | 否 | 是否信任反向代理 | `false` | `true` / `false` |
|
||||
| `ACCOUNT_REGISTRATION` | 否 | 是否允許註冊新帳號 | `true` | `true` / `false` |
|
||||
| `ALLOW_UNAUTHENTICATED` | 否 | 是否允許匿名使用 | `false` | `true` / `false` |
|
||||
| 變數 | 必要性 | 說明 | 預設值 | 範例 |
|
||||
| ----------------------- | -------- | ------------------ | ------------------ | ------------------------- |
|
||||
| `JWT_SECRET` | **必須** | Token 驗證密鑰 | 隨機（每次重啟變） | `Xk9mPqL2vN7wR4tY6uI8...` |
|
||||
| `HTTP_ALLOWED` | 否 | 是否允許 HTTP 連線 | `false` | `true` / `false` |
|
||||
| `TRUST_PROXY` | 否 | 是否信任反向代理 | `false` | `true` / `false` |
|
||||
| `ACCOUNT_REGISTRATION` | 否 | 是否允許註冊新帳號 | `true` | `true` / `false` |
|
||||
| `ALLOW_UNAUTHENTICATED` | 否 | 是否允許匿名使用 | `false` | `true` / `false` |
|
||||
|
||||
### 🌐 一般設定
|
||||
|
||||
| 變數 | 必要性 | 說明 | 預設值 | 範例 |
|
||||
|------|--------|------|--------|------|
|
||||
| `TZ` | 否 | 系統時區 | `UTC` | `Asia/Taipei` |
|
||||
| `LANGUAGE` | 否 | 介面語言 | `auto` | `zh-TW` |
|
||||
| `WEBROOT` | 否 | 子路徑前綴 | 空 | `/convertx` |
|
||||
| `HIDE_HISTORY` | 否 | 隱藏轉換歷史 | `false` | `true` / `false` |
|
||||
| 變數 | 必要性 | 說明 | 預設值 | 範例 |
|
||||
| -------------- | ------ | ------------ | ------- | ---------------- |
|
||||
| `TZ` | 否 | 系統時區 | `UTC` | `Asia/Taipei` |
|
||||
| `LANGUAGE` | 否 | 介面語言 | `auto` | `zh-TW` |
|
||||
| `WEBROOT` | 否 | 子路徑前綴 | 空 | `/convertx` |
|
||||
| `HIDE_HISTORY` | 否 | 隱藏轉換歷史 | `false` | `true` / `false` |
|
||||
|
||||
### ⚙️ 轉換設定
|
||||
|
||||
| 變數 | 必要性 | 說明 | 預設值 | 範例 |
|
||||
|------|--------|------|--------|------|
|
||||
| `AUTO_DELETE_EVERY_N_HOURS` | 否 | 自動刪除間隔（小時） | `24` | `12` |
|
||||
| `MAX_CONVERT_PROCESS` | 否 | 最大同時轉換數 | `0`（無限制） | `4` |
|
||||
| `FFMPEG_ARGS` | 否 | FFmpeg 輸入參數 | 空 | `-hwaccel cuda` |
|
||||
| `FFMPEG_OUTPUT_ARGS` | 否 | FFmpeg 輸出參數 | 空 | `-c:v h264_nvenc` |
|
||||
| 變數 | 必要性 | 說明 | 預設值 | 範例 |
|
||||
| --------------------------- | ------ | -------------------- | ------------- | ----------------- |
|
||||
| `AUTO_DELETE_EVERY_N_HOURS` | 否 | 自動刪除間隔（小時） | `24` | `12` |
|
||||
| `MAX_CONVERT_PROCESS` | 否 | 最大同時轉換數 | `0`（無限制） | `4` |
|
||||
| `FFMPEG_ARGS` | 否 | FFmpeg 輸入參數 | 空 | `-hwaccel cuda` |
|
||||
| `FFMPEG_OUTPUT_ARGS` | 否 | FFmpeg 輸出參數 | 空 | `-c:v h264_nvenc` |
|
||||
|
||||
### 📄 PDF 翻譯設定
|
||||
|
||||
| 變數 | 必要性 | 說明 | 預設值 | 範例 |
|
||||
|------|--------|------|--------|------|
|
||||
| `PDFMATHTRANSLATE_SERVICE` | 否 | 翻譯服務 | `google` | `deepl` |
|
||||
| `PDFMATHTRANSLATE_MODELS_PATH` | 否 | 模型路徑 | `/models` | `/app/models` |
|
||||
| 變數 | 必要性 | 說明 | 預設值 | 範例 |
|
||||
| ------------------------------ | ------ | -------- | --------- | ------------- |
|
||||
| `PDFMATHTRANSLATE_SERVICE` | 否 | 翻譯服務 | `google` | `deepl` |
|
||||
| `PDFMATHTRANSLATE_MODELS_PATH` | 否 | 模型路徑 | `/models` | `/app/models` |
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -61,12 +61,12 @@
|
|||
|
||||
用於簽署登入驗證的密鑰，**強烈建議在正式環境中設定**。
|
||||
|
||||
| 項目 | 說明 |
|
||||
|------|------|
|
||||
| **類型** | 字串 |
|
||||
| **預設值** | 每次重啟隨機產生 |
|
||||
| 項目 | 說明 |
|
||||
| ---------- | ---------------------- |
|
||||
| **類型** | 字串 |
|
||||
| **預設值** | 每次重啟隨機產生 |
|
||||
| **建議值** | 至少 32 字元的隨機字串 |
|
||||
| **必要性** | ⭐ 強烈建議 |
|
||||
| **必要性** | ⭐ 強烈建議 |
|
||||
|
||||
**問題**：若不設定，每次容器重啟後所有使用者都需要重新登入。
|
||||
|
||||
|
|
@ -98,77 +98,77 @@ environment:
|
|||
|
||||
控制是否允許非 HTTPS 連線。
|
||||
|
||||
| 項目 | 說明 |
|
||||
|------|------|
|
||||
| **類型** | 布林值 |
|
||||
| **預設值** | `false` |
|
||||
| 項目 | 說明 |
|
||||
| ---------- | ---------------- |
|
||||
| **類型** | 布林值 |
|
||||
| **預設值** | `false` |
|
||||
| **可選值** | `true` / `false` |
|
||||
|
||||
**使用情境**：
|
||||
|
||||
| 情境 | 建議設定 |
|
||||
|------|---------|
|
||||
| 本地測試 (localhost) | `true` |
|
||||
| 已設定 HTTPS | `false` |
|
||||
| 無 HTTPS 但需遠端存取 | `true` |
|
||||
| 情境 | 建議設定 |
|
||||
| --------------------- | -------- |
|
||||
| 本地測試 (localhost) | `true` |
|
||||
| 已設定 HTTPS | `false` |
|
||||
| 無 HTTPS 但需遠端存取 | `true` |
|
||||
|
||||
> ⚠️ **注意**：設為 `false` 但用 HTTP 存取會導致「登入後又被導回登入頁」
|
||||
|
||||
```yaml
|
||||
environment:
|
||||
- HTTP_ALLOWED=true # 本地開發時使用
|
||||
- HTTP_ALLOWED=true # 本地開發時使用
|
||||
```
|
||||
|
||||
### TRUST_PROXY
|
||||
|
||||
控制是否信任反向代理的 X-Forwarded-* headers。
|
||||
控制是否信任反向代理的 X-Forwarded-\* headers。
|
||||
|
||||
| 項目 | 說明 |
|
||||
|------|------|
|
||||
| **類型** | 布林值 |
|
||||
| **預設值** | `false` |
|
||||
| 項目 | 說明 |
|
||||
| ---------- | ---------------- |
|
||||
| **類型** | 布林值 |
|
||||
| **預設值** | `false` |
|
||||
| **可選值** | `true` / `false` |
|
||||
|
||||
**使用情境**：
|
||||
|
||||
| 情境 | 建議設定 |
|
||||
|------|---------|
|
||||
| 直接存取容器 | `false` |
|
||||
| 透過 Nginx / Traefik / Caddy | `true` |
|
||||
| 情境 | 建議設定 |
|
||||
| ---------------------------- | -------- |
|
||||
| 直接存取容器 | `false` |
|
||||
| 透過 Nginx / Traefik / Caddy | `true` |
|
||||
|
||||
```yaml
|
||||
environment:
|
||||
- TRUST_PROXY=true # 使用反向代理時
|
||||
- TRUST_PROXY=true # 使用反向代理時
|
||||
```
|
||||
|
||||
### ACCOUNT_REGISTRATION
|
||||
|
||||
控制是否允許新使用者註冊。
|
||||
|
||||
| 項目 | 說明 |
|
||||
|------|------|
|
||||
| **類型** | 布林值 |
|
||||
| **預設值** | `true` |
|
||||
| 項目 | 說明 |
|
||||
| ---------- | ---------------- |
|
||||
| **類型** | 布林值 |
|
||||
| **預設值** | `true` |
|
||||
| **可選值** | `true` / `false` |
|
||||
|
||||
```yaml
|
||||
environment:
|
||||
- ACCOUNT_REGISTRATION=false # 關閉公開註冊
|
||||
- ACCOUNT_REGISTRATION=false # 關閉公開註冊
|
||||
```
|
||||
|
||||
### ALLOW_UNAUTHENTICATED
|
||||
|
||||
控制是否允許未登入的匿名使用者使用轉換功能。
|
||||
|
||||
| 項目 | 說明 |
|
||||
|------|------|
|
||||
| **類型** | 布林值 |
|
||||
| **預設值** | `false` |
|
||||
| 項目 | 說明 |
|
||||
| ---------- | ---------------- |
|
||||
| **類型** | 布林值 |
|
||||
| **預設值** | `false` |
|
||||
| **可選值** | `true` / `false` |
|
||||
|
||||
```yaml
|
||||
environment:
|
||||
- ALLOW_UNAUTHENTICATED=true # 允許匿名使用
|
||||
- ALLOW_UNAUTHENTICATED=true # 允許匿名使用
|
||||
```
|
||||
|
||||
---
|
||||
|
|
@ -179,20 +179,20 @@ environment:
|
|||
|
||||
設定系統時區，影響日誌時間顯示與自動清理排程。
|
||||
|
||||
| 項目 | 說明 |
|
||||
|------|------|
|
||||
| **類型** | 時區字串 |
|
||||
| **預設值** | `UTC` |
|
||||
| 項目 | 說明 |
|
||||
| ---------- | ------------------------------------------------------------------------ |
|
||||
| **類型** | 時區字串 |
|
||||
| **預設值** | `UTC` |
|
||||
| **可選值** | [時區列表](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) |
|
||||
|
||||
**常用時區**：
|
||||
|
||||
| 地區 | 時區值 |
|
||||
|------|--------|
|
||||
| 台灣 | `Asia/Taipei` |
|
||||
| 香港 | `Asia/Hong_Kong` |
|
||||
| 中國大陸 | `Asia/Shanghai` |
|
||||
| 日本 | `Asia/Tokyo` |
|
||||
| 地區 | 時區值 |
|
||||
| -------- | ------------------ |
|
||||
| 台灣 | `Asia/Taipei` |
|
||||
| 香港 | `Asia/Hong_Kong` |
|
||||
| 中國大陸 | `Asia/Shanghai` |
|
||||
| 日本 | `Asia/Tokyo` |
|
||||
| 美國東部 | `America/New_York` |
|
||||
|
||||
```yaml
|
||||
|
|
@ -204,10 +204,10 @@ environment:
|
|||
|
||||
設定介面預設語言。
|
||||
|
||||
| 項目 | 說明 |
|
||||
|------|------|
|
||||
| **類型** | 語言代碼 |
|
||||
| **預設值** | `auto`（自動偵測） |
|
||||
| 項目 | 說明 |
|
||||
| ---------- | ------------------------------------- |
|
||||
| **類型** | 語言代碼 |
|
||||
| **預設值** | `auto`（自動偵測） |
|
||||
| **可選值** | `zh-TW`, `zh-CN`, `en`, `ja` 等 65 種 |
|
||||
|
||||
```yaml
|
||||
|
|
@ -219,28 +219,28 @@ environment:
|
|||
|
||||
設定子路徑前綴，用於反向代理配置。
|
||||
|
||||
| 項目 | 說明 |
|
||||
|------|------|
|
||||
| **類型** | 路徑字串 |
|
||||
| 項目 | 說明 |
|
||||
| ---------- | ------------ |
|
||||
| **類型** | 路徑字串 |
|
||||
| **預設值** | 空（根路徑） |
|
||||
|
||||
```yaml
|
||||
environment:
|
||||
- WEBROOT=/convertx # 訪問路徑變為 http://example.com/convertx
|
||||
- WEBROOT=/convertx # 訪問路徑變為 http://example.com/convertx
|
||||
```
|
||||
|
||||
### HIDE_HISTORY
|
||||
|
||||
控制是否隱藏轉換歷史紀錄。
|
||||
|
||||
| 項目 | 說明 |
|
||||
|------|------|
|
||||
| **類型** | 布林值 |
|
||||
| 項目 | 說明 |
|
||||
| ---------- | ------- |
|
||||
| **類型** | 布林值 |
|
||||
| **預設值** | `false` |
|
||||
|
||||
```yaml
|
||||
environment:
|
||||
- HIDE_HISTORY=true # 隱藏歷史紀錄
|
||||
- HIDE_HISTORY=true # 隱藏歷史紀錄
|
||||
```
|
||||
|
||||
---
|
||||
|
|
@ -251,39 +251,39 @@ environment:
|
|||
|
||||
設定自動刪除轉換檔案的間隔時間（小時）。
|
||||
|
||||
| 項目 | 說明 |
|
||||
|------|------|
|
||||
| **類型** | 數字 |
|
||||
| **預設值** | `24` |
|
||||
| 項目 | 說明 |
|
||||
| ------------ | ----------- |
|
||||
| **類型** | 數字 |
|
||||
| **預設值** | `24` |
|
||||
| **建議範圍** | `1` - `168` |
|
||||
|
||||
```yaml
|
||||
environment:
|
||||
- AUTO_DELETE_EVERY_N_HOURS=12 # 每 12 小時清理一次
|
||||
- AUTO_DELETE_EVERY_N_HOURS=12 # 每 12 小時清理一次
|
||||
```
|
||||
|
||||
### MAX_CONVERT_PROCESS
|
||||
|
||||
設定最大同時轉換任務數量。
|
||||
|
||||
| 項目 | 說明 |
|
||||
|------|------|
|
||||
| **類型** | 數字 |
|
||||
| 項目 | 說明 |
|
||||
| ---------- | ------------- |
|
||||
| **類型** | 數字 |
|
||||
| **預設值** | `0`（無限制） |
|
||||
| **建議值** | CPU 核心數 |
|
||||
| **建議值** | CPU 核心數 |
|
||||
|
||||
```yaml
|
||||
environment:
|
||||
- MAX_CONVERT_PROCESS=4 # 最多同時 4 個轉換任務
|
||||
- MAX_CONVERT_PROCESS=4 # 最多同時 4 個轉換任務
|
||||
```
|
||||
|
||||
### FFMPEG_ARGS 與 FFMPEG_OUTPUT_ARGS
|
||||
|
||||
設定 FFmpeg 的全域參數。
|
||||
|
||||
| 變數 | 說明 |
|
||||
|------|------|
|
||||
| `FFMPEG_ARGS` | 輸入參數（套用於輸入檔案） |
|
||||
| 變數 | 說明 |
|
||||
| -------------------- | -------------------------- |
|
||||
| `FFMPEG_ARGS` | 輸入參數（套用於輸入檔案） |
|
||||
| `FFMPEG_OUTPUT_ARGS` | 輸出參數（套用於輸出檔案） |
|
||||
|
||||
**GPU 加速範例**：
|
||||
|
|
@ -303,10 +303,10 @@ environment:
|
|||
|
||||
設定 PDF 翻譯使用的服務。
|
||||
|
||||
| 項目 | 說明 |
|
||||
|------|------|
|
||||
| **類型** | 字串 |
|
||||
| **預設值** | `google` |
|
||||
| 項目 | 說明 |
|
||||
| ---------- | ----------------------------- |
|
||||
| **類型** | 字串 |
|
||||
| **預設值** | `google` |
|
||||
| **可選值** | `google`, `deepl`, `azure` 等 |
|
||||
|
||||
```yaml
|
||||
|
|
@ -318,9 +318,9 @@ environment:
|
|||
|
||||
設定 PDF 翻譯模型的存放路徑。
|
||||
|
||||
| 項目 | 說明 |
|
||||
|------|------|
|
||||
| **類型** | 路徑字串 |
|
||||
| 項目 | 說明 |
|
||||
| ---------- | --------- |
|
||||
| **類型** | 路徑字串 |
|
||||
| **預設值** | `/models` |
|
||||
|
||||
```yaml
|
||||
|
|
@ -361,16 +361,16 @@ services:
|
|||
- ./data:/app/data
|
||||
environment:
|
||||
- TZ=Asia/Taipei
|
||||
- JWT_SECRET=${JWT_SECRET} # 使用環境變數或 secrets
|
||||
- JWT_SECRET=${JWT_SECRET} # 使用環境變數或 secrets
|
||||
- HTTP_ALLOWED=false
|
||||
- TRUST_PROXY=true # 如果使用反向代理
|
||||
- ACCOUNT_REGISTRATION=false # 關閉公開註冊
|
||||
- TRUST_PROXY=true # 如果使用反向代理
|
||||
- ACCOUNT_REGISTRATION=false # 關閉公開註冊
|
||||
- AUTO_DELETE_EVERY_N_HOURS=12
|
||||
- MAX_CONVERT_PROCESS=4
|
||||
deploy:
|
||||
resources:
|
||||
limits:
|
||||
cpus: '4'
|
||||
cpus: "4"
|
||||
memory: 8G
|
||||
```
|
||||
|
||||
|
|
@ -390,8 +390,8 @@ services:
|
|||
- TRUST_PROXY=true
|
||||
- ALLOW_UNAUTHENTICATED=true
|
||||
- ACCOUNT_REGISTRATION=false
|
||||
- AUTO_DELETE_EVERY_N_HOURS=1 # 頻繁清理
|
||||
- MAX_CONVERT_PROCESS=2 # 限制資源使用
|
||||
- AUTO_DELETE_EVERY_N_HOURS=1 # 頻繁清理
|
||||
- MAX_CONVERT_PROCESS=2 # 限制資源使用
|
||||
```
|
||||
|
||||
---
|
||||
|
|
@ -406,11 +406,13 @@ services:
|
|||
- 不要使用範例中的值
|
||||
|
||||
2. **正式環境關閉 HTTP**
|
||||
|
||||
```yaml
|
||||
- HTTP_ALLOWED=false
|
||||
```
|
||||
|
||||
3. **使用反向代理處理 HTTPS**
|
||||
|
||||
```yaml
|
||||
- TRUST_PROXY=true
|
||||
```
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue