# CodiMD Docker Deployment

安全的 CodiMD（HackMD）Docker 部署配置，使用 PostgreSQL 資料庫。

## 關於 CodiMD

CodiMD 是一個開源的協作 Markdown 編輯器，讓多個使用者可以同時編輯文件。

- 專案首頁：https://github.com/hackmdio/codimd
- 官方文件：https://hackmd.io/

## 功能特色

- 即時協作編輯
- Markdown 支援
- 多種匯出格式（PDF、HTML、Markdown）
- 圖檔上傳支援
- 標籤和分類管理
- 權限控制（公開/僅限連結/私人）

## 快速開始

### 1. 複製環境設定

```bash
cp .env.example .env
```

### 2. 啟動服務

```bash
docker-compose up -d
```

### 3. 訪問應用

打開瀏覽器訪問：http://localhost:3000

## 設定說明

### 環境變數 (.env)

| 變數 | 說明 | 預設值 |
|------|------|--------|
| `POSTGRES_USER` | 資料庫使用者名稱 | `codimd` |
| `POSTGRES_PASSWORD` | 資料庫密碼 | 需要修改 |
| `POSTGRES_DB` | 資料庫名稱 | `codimd` |
| `CMD_DB_URL` | CodiMD 資料庫連線字串 | 自動產生 |
| `CMD_SESSION_SECRET` | Session 加密金鑰 | 自動產生 |

### 資料持久化

所有資料都存儲在當前目錄：

```
.
├── pgdata/          # PostgreSQL 資料庫檔案
└── upload-data/     # 使用者上傳的圖片和檔案
```

## 維護指令

### 查看日誌

```bash
docker-compose logs -f
```

### 停止服務

```bash
docker-compose down
```

### 重新啟動

```bash
docker-compose restart
```

### 更新 CodiMD

```bash
docker-compose pull
docker-compose up -d
```

### 備份資料庫

```bash
docker-compose exec database pg_dump -U codimd codimd > backup.sql
```

### 還原資料庫

```bash
docker-compose exec -T database psql -U codimd codimd < backup.sql
```

## 安全特性

- **環境變數保護**：敏感資訊存放在 `.env`（已加入 `.gitignore`）
- **網路隔離**：資料庫不對外開放，僅服務內部存取
- **唯讀容器**：資料庫容器設為唯讀，提升安全性
- **本地綁定**：CodiMD 僅綁定 127.0.0.1，不直接對外暴露
- **健康檢查**：自動監控服務狀態
- **隨機金鑰**：自動產生強密的 session secret

## 生產部署建議

在正式環境部署前，請務必：

1. **修改密碼**：編輯 `.env`，更換強密碼
2. **設定反向代理**：使用 Nginx 或 Caddy 提供 HTTPS
3. **定期備份**：設定自動備份資料庫和上傳檔案
4. **監控資源**：監控磁碟空間和容器狀態
5. **更新映像**：定期更新 Docker 映像以獲得安全修補

## 反向代理範例 (Nginx)

```nginx
server {
    listen 80;
    server_name your-domain.com;

    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}
```

## 故障排除

### 無法訪問

確認服務是否正常運行：

```bash
docker-compose ps
```

### 查看錯誤日誌

```bash
docker-compose logs codimd
docker-compose logs database
```

### 重置資料庫

⚠️ **警告**：這會刪除所有資料！

```bash
docker-compose down
rm -rf pgdata
docker-compose up -d
```

## 授權

本部署配置基於 MIT 授權條款。
CodiMD 專案使用 AGPL-3.0 授權。

## 相關連結

- [CodiMD 官方文件](https://hackmd.io/)
- [CodiMD GitHub](https://github.com/hackmdio/codimd)
- [Docker Hub](https://hub.docker.com/r/hackmdio/hackmd)