convertor/docs/configuration/security.md

安全性設定

本文件說明 ConvertX-CN 的安全性設定與最佳實踐。

---

Cookie 與登入安全

HTTP_ALLOWED

控制是否允許非 HTTPS 連線。

- 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。

- 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

- ACCOUNT_REGISTRATION=true # 開放註冊
- ACCOUNT_REGISTRATION=false # 關閉註冊

建議流程

1. 首次部署設為 true（或不設定）
2. 註冊管理員帳號
3. 改為 false
4. 重啟容器

JWT_SECRET

- JWT_SECRET=your-secret-key-at-least-32-chars

重要性

• 用於簽署登入 Token
• 不設定：每次重啟產生新密鑰，所有人被登出
• 設定固定值：登入狀態跨重啟保留

產生方式

# Linux / macOS
openssl rand -hex 32

# 輸出範例：a1b2c3d4e5f6789...（64 字元）

---

公開服務安全

ALLOW_UNAUTHENTICATED

- ALLOW_UNAUTHENTICATED=true # 允許未登入使用
- ALLOW_UNAUTHENTICATED=false # 必須登入（預設）

風險

設為 true 時：

• 任何人可使用轉換功能
• 消耗伺服器 CPU / 記憶體 / 磁碟
• 可能被惡意利用

緩解措施

若需要公開服務，建議：

environment:
  - ALLOW_UNAUTHENTICATED=true
  - AUTO_DELETE_EVERY_N_HOURS=1 # 頻繁清理
  - HIDE_HISTORY=true # 隱藏歷史
  - MAX_CONVERT_PROCESS=2 # 限制同時轉換數

---

網路安全

防火牆

只開放必要的埠：

# UFW (Ubuntu)
sudo ufw allow 3000/tcp

# 或只允許特定 IP
sudo ufw allow from 192.168.1.0/24 to any port 3000

只允許本機存取

ports:
  - "127.0.0.1:3000:3000" # 只有本機可存取

搭配反向代理提供對外服務。

限制上傳大小

在反向代理層限制：

# Nginx
client_max_body_size 100M;

---

資料安全

定期清理

- AUTO_DELETE_EVERY_N_HOURS=24 # 每 24 小時清理

備份

# 定期備份資料
0 2 * * * tar -czvf /backup/convertx-$(date +\%Y\%m\%d).tar.gz /path/to/data

權限設定

# 限制資料夾權限
chmod 700 ./data

---

安全檢查清單

部署前

• 設定固定的 JWT_SECRET
• 關閉 ACCOUNT_REGISTRATION（如果不需要公開註冊）
• 設定 TRUST_PROXY=true（如果使用反向代理）
• 設定 HTTP_ALLOWED=false（如果有 HTTPS）

部署後

• 確認只有必要的埠對外開放
• 確認反向代理有正確設定
• 確認 HTTPS 憑證有效
• 設定定期備份
• 設定定期清理

---

相關文件

• 環境變數設定
• 反向代理設定
• Docker 部署