Timmy
9b73c810e6
- Add QUICKSTART.md for 5-minute setup guide - Add SUMMARY.md as project overview - Update README.md with full deployment guide - Update .env.example with better descriptions Co-Authored-By: Claude Sonnet 4 <noreply@anthropic.com>
173 lines
3.4 KiB
Markdown
173 lines
3.4 KiB
Markdown
# 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)
|