codimd/TROUBLESHOOTING.md

CodiMD 故障排除指南

常見問題及解決方案。

HTTPS 設置相關問題

Mixed Content 錯誤

錯誤訊息：

Mixed Content: The page was loaded over HTTPS, but requested an insecure resource

原因： CodiMD 環境變數中的域名設定不正確，仍在使用 localhost。

解決方案：

1. 編輯 .env 文件：

nano .env

2. 更新以下變數：

# 改為你的實際域名
CMD_DOMAIN=md.automodules.com

# 啟用 HTTPS
CMD_PROTOCOL_USESSL=true

# 使用反向代理時設為 false
CMD_URL_ADDPORT=false

3. 重啟 CodiMD：

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. 確認資料庫服務是否運行：

docker-compose ps

2. 查看資料庫日誌：

docker-compose logs database

3. 測試資料庫連線：

docker-compose exec database psql -U codimd -d codimd -c "SELECT 1;"

常見原因：

• 資料庫尚未完全啟動（等待 30 秒後重試）
• 密碼設定錯誤（檢查 .env 中的 POSTGRES_PASSWORD 和 CMD_DB_URL）

資料庫遺失

症狀： 重新啟動後所有資料都不見了。

解決方案：

1. 確認 pgdata 目錄存在：

ls -la pgdata/

2. 如果目錄不存在，停止服務並從備份還原：

docker-compose down
# 從備份還原
docker-compose up -d

網路連線問題

無法從外部存取

檢查步驟：

1. 確認 port 綁定：

docker-compose ps | grep 0.0.0.0

應該看到 0.0.0.0:3000->3000/tcp 而不是 127.0.0.1:3000->3000/tcp

2. 檢查防火牆：

# Ubuntu/Debian
sudo ufw status

# CentOS/RHEL
sudo firewall-cmd --list-all

3. 測試本地連線：

curl http://localhost:3000

4. 測試外部連線（從另一台機器）：

curl http://your-server-ip:3000

WebSocket 連線失敗

症狀： 多人協作功能無法使用，編輯器無法即時同步。

解決方案：

1. 確認 Nginx 配置包含 WebSocket 支援：

proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_http_version 1.1;

2. 確認沒有使用 HTTP/2 不當配置：

# 移除可能干擾 WebSocket 的配置
# proxy_buffering off;
# proxy_request_buffering off;

3. 重啟 Nginx：

sudo systemctl reload nginx

效能問題

頁面載入緩慢

檢查步驟：

1. 查看容器資源使用：

docker stats

2. 查看日誌中的錯誤：

docker-compose logs --tail=100 codimd

解決方案：

• 增加 Docker 資源限制（如果使用 Docker Desktop）
• 升級伺服器規格
• 啟用 CDN（設定 CMD_USECDN=true）

資料庫效能問題

解決方案：

1. 定期清理舊的修訂版本：

docker-compose exec database psql -U codimd -d codimd -c "DELETE FROM revisions WHERE \"createdAt\" < NOW() - INTERVAL '30 days';"

2. 資料庫維護：

docker-compose exec database psql -U codimd -d codimd -c "VACUUM ANALYZE;"

檔案上傳問題

圖片上傳失敗

檢查步驟：

1. 確認上傳目錄權限：

ls -la upload-data/

2. 查看容器日誌：

docker-compose logs codimd | grep upload

解決方案：

• 確認 upload-data 目錄存在且可寫入
• 檢查磁碟空間：df -h

檔案大小限制

症狀： 上傳大檔案時失敗。

解決方案：

1. 在 .env 中增加上傳限制：

CMD_MAX_UPLOAD_SIZE=104857600

2. 在 Nginx 配置中增加限制：

client_max_body_size 100M;

重置服務

完全重置（會遺失所有資料）

# 停止並移除所有容器
docker-compose down

# 移除資料庫和上傳檔案
rm -rf pgdata upload-data

# 重新啟動
docker-compose up -d

重置資料庫（保留上傳檔案）

# 停止服務
docker-compose down

# 移除資料庫
rm -rf pgdata

# 重新啟動
docker-compose up -d

日誌除錯

查看即時日誌

# 所有服務
docker-compose logs -f

# 僅 CodiMD
docker-compose logs -f codimd

# 僅資料庫
docker-compose logs -f database

查看最近錯誤

docker-compose logs --tail=50 codimd | grep -i error
docker-compose logs --tail=50 codimd | grep -i warn

升級問題

升級後無法啟動

解決方案：

1. 備份資料：

# 備份資料庫
docker-compose exec database pg_dump -U codimd codimd > backup.sql

# 備份上傳檔案
cp -r upload-data upload-data.backup

2. 恢復舊版本：

# 編輯 docker-compose.yml，改回舊版本
# 然後重新啟動
docker-compose down
docker-compose up -d

3. 查看升級說明：

• 檢查：https://github.com/hackmdio/codimd/releases

需要更多幫助？

• CodiMD GitHub Issues
• CodiMD 官方文件
• Docker 文件