CodiMD Docker Deployment

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

關於 CodiMD

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

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

功能特色

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

快速開始

1. 複製環境設定

cp .env.example .env

2. 啟動服務

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/     # 使用者上傳的圖片和檔案

維護指令

查看日誌

docker-compose logs -f

停止服務

docker-compose down

重新啟動

docker-compose restart

更新 CodiMD

docker-compose pull
docker-compose up -d

備份資料庫

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

還原資料庫

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)

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;
    }
}

故障排除

無法訪問

確認服務是否正常運行：

docker-compose ps

查看錯誤日誌

docker-compose logs codimd
docker-compose logs database

重置資料庫

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

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

授權

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

相關連結

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