docs: add troubleshooting guide and update environment examples

- Add TROUBLESHOOTING.md with comprehensive issue resolution guide - Update .env.example with additional configuration options - Include solutions for Mixed Content, CSP, and database issues - Add network, performance, and upgrade troubleshooting sections Co-Authored-By: Claude Sonnet 4 <noreply@anthropic.com>
2026-03-17 15:40:42 +08:00
parent 6126f74fb8
commit cbe76b1f96
2 changed files with 340 additions and 1 deletions
--- a/.env.example
+++ b/.env.example
@@ -8,12 +8,25 @@ CMD_DB_URL=postgres://codimd:CHANGE_THIS_TO_A_STRONG_PASSWORD@database/codimd

 # CodiMD Domain Configuration
 # For local development, use localhost
-# For production, set your actual domain (e.g., hackmd.example.com)
+# For production with HTTPS, set your actual domain (e.g., md.automodules.com)
 CMD_DOMAIN=localhost

 # URL Configuration
+# Set CMD_PROTOCOL_USESSL=true when using HTTPS (with reverse proxy)
+# Set CMD_URL_ADDPORT=false when using standard ports (80/443)
 CMD_URL_ADDPORT=false
 CMD_PROTOCOL_USESSL=false

 # CodiMD Session Secret (generate a random string)
 CMD_SESSION_SECRET=CHANGE_THIS_TO_A_RANDOM_SECRET_STRING
+
+# Optional: Allow iframe embedding (if needed)
+# CMD_ALLOW iframeorigin=https://example.com
+
+# Optional: Session lifetime in milliseconds (default: 1209600000 = 14 days)
+# CMD_SESSION_LIFETIME=1209600000
+
+# Optional: Maximum upload size in bytes (default: 50MB)
+# CMD_IMAGE_UPLOAD_TYPE=filesystem
+# CMD_MAX_UPLOAD_SIZE=52428800
+
--- a/TROUBLESHOOTING.md
+++ b/TROUBLESHOOTING.md
@@ -0,0 +1,326 @@
+# CodiMD 故障排除指南
+
+常見問題及解決方案。
+
+## HTTPS 設置相關問題
+
+### Mixed Content 錯誤
+
+**錯誤訊息：**
+```
+Mixed Content: The page was loaded over HTTPS, but requested an insecure resource
+```
+
+**原因：**
+CodiMD 環境變數中的域名設定不正確，仍在使用 `localhost`。
+
+**解決方案：**
+
+1. 編輯 `.env` 文件：
+```bash
+nano .env
+```
+
+2. 更新以下變數：
+```env
+# 改為你的實際域名
+CMD_DOMAIN=md.automodules.com
+
+# 啟用 HTTPS
+CMD_PROTOCOL_USESSL=true
+
+# 使用反向代理時設為 false
+CMD_URL_ADDPORT=false
+```
+
+3. 重啟 CodiMD：
+```bash
+docker-compose restart codimd
+```
+
+4. 清除瀏覽器快取並重新載入頁面。
+
+### CSP (Content Security Policy) 錯誤
+
+**錯誤訊息：**
+```
+Loading the stylesheet violates the following Content Security Policy directive
+```
+
+**原因：**
+環境變數設定不正確，導致資源路徑錯誤。
+
+**解決方案：**
+參考上述 Mixed Content 的解決方案，確保：
+- `CMD_DOMAIN` 設為正確的域名
+- `CMD_PROTOCOL_USESSL=true`（使用 HTTPS 時）
+
+### 資源載入失敗
+
+**錯誤訊息：**
+```
+Loading the script 'http://localhost/config' violates CSP directive
+```
+
+**原因：**
+CodiMD 仍在產生 `localhost` 的 URL。
+
+**解決方案：**
+1. 確認 `.env` 中的 `CMD_DOMAIN` 設定正確
+2. 重啟 CodiMD 服務
+3. 清除瀏覽器快取（Ctrl+Shift+Delete 或 Cmd+Shift+Delete）
+
+## 資料庫連線問題
+
+### 無法連接資料庫
+
+**檢查步驟：**
+
+1. 確認資料庫服務是否運行：
+```bash
+docker-compose ps
+```
+
+2. 查看資料庫日誌：
+```bash
+docker-compose logs database
+```
+
+3. 測試資料庫連線：
+```bash
+docker-compose exec database psql -U codimd -d codimd -c "SELECT 1;"
+```
+
+**常見原因：**
+- 資料庫尚未完全啟動（等待 30 秒後重試）
+- 密碼設定錯誤（檢查 `.env` 中的 `POSTGRES_PASSWORD` 和 `CMD_DB_URL`）
+
+### 資料庫遺失
+
+**症狀：**
+重新啟動後所有資料都不見了。
+
+**解決方案：**
+1. 確認 `pgdata` 目錄存在：
+```bash
+ls -la pgdata/
+```
+
+2. 如果目錄不存在，停止服務並從備份還原：
+```bash
+docker-compose down
+# 從備份還原
+docker-compose up -d
+```
+
+## 網路連線問題
+
+### 無法從外部存取
+
+**檢查步驟：**
+
+1. 確認 port 綁定：
+```bash
+docker-compose ps | grep 0.0.0.0
+```
+
+應該看到 `0.0.0.0:3000->3000/tcp` 而不是 `127.0.0.1:3000->3000/tcp`
+
+2. 檢查防火牆：
+```bash
+# Ubuntu/Debian
+sudo ufw status
+
+# CentOS/RHEL
+sudo firewall-cmd --list-all
+```
+
+3. 測試本地連線：
+```bash
+curl http://localhost:3000
+```
+
+4. 測試外部連線（從另一台機器）：
+```bash
+curl http://your-server-ip:3000
+```
+
+### WebSocket 連線失敗
+
+**症狀：**
+多人協作功能無法使用，編輯器無法即時同步。
+
+**解決方案：**
+
+1. 確認 Nginx 配置包含 WebSocket 支援：
+```nginx
+proxy_set_header Upgrade $http_upgrade;
+proxy_set_header Connection "upgrade";
+proxy_http_version 1.1;
+```
+
+2. 確認沒有使用 HTTP/2 不當配置：
+```nginx
+# 移除可能干擾 WebSocket 的配置
+# proxy_buffering off;
+# proxy_request_buffering off;
+```
+
+3. 重啟 Nginx：
+```bash
+sudo systemctl reload nginx
+```
+
+## 效能問題
+
+### 頁面載入緩慢
+
+**檢查步驟：**
+
+1. 查看容器資源使用：
+```bash
+docker stats
+```
+
+2. 查看日誌中的錯誤：
+```bash
+docker-compose logs --tail=100 codimd
+```
+
+**解決方案：**
+- 增加 Docker 資源限制（如果使用 Docker Desktop）
+- 升級伺服器規格
+- 啟用 CDN（設定 `CMD_USECDN=true`）
+
+### 資料庫效能問題
+
+**解決方案：**
+
+1. 定期清理舊的修訂版本：
+```bash
+docker-compose exec database psql -U codimd -d codimd -c "DELETE FROM revisions WHERE \"createdAt\" < NOW() - INTERVAL '30 days';"
+```
+
+2. 資料庫維護：
+```bash
+docker-compose exec database psql -U codimd -d codimd -c "VACUUM ANALYZE;"
+```
+
+## 檔案上傳問題
+
+### 圖片上傳失敗
+
+**檢查步驟：**
+
+1. 確認上傳目錄權限：
+```bash
+ls -la upload-data/
+```
+
+2. 查看容器日誌：
+```bash
+docker-compose logs codimd | grep upload
+```
+
+**解決方案：**
+- 確認 `upload-data` 目錄存在且可寫入
+- 檢查磁碟空間：`df -h`
+
+### 檔案大小限制
+
+**症狀：**
+上傳大檔案時失敗。
+
+**解決方案：**
+
+1. 在 `.env` 中增加上傳限制：
+```env
+CMD_MAX_UPLOAD_SIZE=104857600
+```
+
+2. 在 Nginx 配置中增加限制：
+```nginx
+client_max_body_size 100M;
+```
+
+## 重置服務
+
+### 完全重置（會遺失所有資料）
+
+```bash
+# 停止並移除所有容器
+docker-compose down
+
+# 移除資料庫和上傳檔案
+rm -rf pgdata upload-data
+
+# 重新啟動
+docker-compose up -d
+```
+
+### 重置資料庫（保留上傳檔案）
+
+```bash
+# 停止服務
+docker-compose down
+
+# 移除資料庫
+rm -rf pgdata
+
+# 重新啟動
+docker-compose up -d
+```
+
+## 日誌除錯
+
+### 查看即時日誌
+
+```bash
+# 所有服務
+docker-compose logs -f
+
+# 僅 CodiMD
+docker-compose logs -f codimd
+
+# 僅資料庫
+docker-compose logs -f database
+```
+
+### 查看最近錯誤
+
+```bash
+docker-compose logs --tail=50 codimd | grep -i error
+docker-compose logs --tail=50 codimd | grep -i warn
+```
+
+## 升級問題
+
+### 升級後無法啟動
+
+**解決方案：**
+
+1. 備份資料：
+```bash
+# 備份資料庫
+docker-compose exec database pg_dump -U codimd codimd > backup.sql
+
+# 備份上傳檔案
+cp -r upload-data upload-data.backup
+```
+
+2. 恢復舊版本：
+```bash
+# 編輯 docker-compose.yml，改回舊版本
+# 然後重新啟動
+docker-compose down
+docker-compose up -d
+```
+
+3. 查看升級說明：
+- 檢查：https://github.com/hackmdio/codimd/releases
+
+## 需要更多幫助？
+
+- [CodiMD GitHub Issues](https://github.com/hackmdio/codimd/issues)
+- [CodiMD 官方文件](https://hackmd.io/)
+- [Docker 文件](https://docs.docker.com/)