Timmy
cbe76b1f96
- 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>
327 lines
5.7 KiB
Markdown
327 lines
5.7 KiB
Markdown
# 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/)
|