# 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/)