docs: add comprehensive documentation

- 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>
This commit is contained in:
2026-03-17 15:06:08 +08:00
parent bbe6f339c7
commit 9b73c810e6
3 changed files with 367 additions and 1 deletions

100
SUMMARY.md Normal file
View File

@@ -0,0 +1,100 @@
# CodiMD Docker 部署 - 專案摘要
## 專案概述
本專案提供一個安全、易於部署的 CodiMDHackMDDocker 配置,適合個人使用或團隊協作。
## 專案結構
```
codimd/
├── .env # 環境變數(不提交到版本控制)
├── .env.example # 環境變數範本
├── .gitignore # Git 忽略規則
├── docker-compose.yml # Docker 服務配置
├── CLAUDE.md # Claude Code 開發指南
├── README.md # 完整說明文件
├── QUICKSTART.md # 快速開始指南
└── SUMMARY.md # 本文件
```
## 服務架構
| 服務 | 映像 | Port | 說明 |
|------|------|------|------|
| PostgreSQL | postgres:16-alpine | - | 資料庫服務 |
| CodiMD | hackmdio/hackmd:2.6.1 | 3000 | 應用程式服務 |
## 資料持久化
| 路徑 | 用途 |
|------|------|
| `./pgdata/` | PostgreSQL 資料庫檔案 |
| `./upload-data/` | 使用者上傳的圖片和檔案 |
## 安全措施
- ✅ 環境變數保護敏感資訊
- ✅ 資料庫容器唯讀設定
- ✅ 服務隔離在 Docker 內部網路
- ✅ CodiMD 僅綁定 127.0.0.1
- ✅ 隨機產生的 session secret
- ✅ 健康檢查確保服務正常
## 快速指令
```bash
# 啟動服務
docker-compose up -d
# 查看狀態
docker-compose ps
# 查看日誌
docker-compose logs -f
# 停止服務
docker-compose down
# 備份資料庫
docker-compose exec database pg_dump -U codimd codimd > backup.sql
```
## 環境變數
| 變數 | 用途 |
|------|------|
| `POSTGRES_USER` | 資料庫使用者名稱 |
| `POSTGRES_PASSWORD` | 資料庫密碼 |
| `POSTGRES_DB` | 資料庫名稱 |
| `CMD_DB_URL` | CodiMD 資料庫連線 |
| `CMD_SESSION_SECRET` | Session 加密金鑰 |
## 版本資訊
| 組件 | 版本 |
|------|------|
| PostgreSQL | 16 Alpine |
| CodiMD | 2.6.1 |
| Docker Compose | 3.x |
## 相關文件
- **README.md** - 完整部署文件
- **QUICKSTART.md** - 5 分鐘快速開始
- **CLAUDE.md** - Claude Code 開發指南
## 外部資源
- [CodiMD 官方文件](https://hackmd.io/)
- [CodiMD GitHub](https://github.com/hackmdio/codimd)
- [Docker Hub - hackmdio/hackmd](https://hub.docker.com/r/hackmdio/hackmd)
## 授權
本配置檔案使用 MIT 授權。
CodiMD 專案使用 AGPL-3.0 授權。
---
**最後更新**2026-03-17