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>
2026-03-17 15:06:08 +08:00
parent bbe6f339c7
commit 9b73c810e6
3 changed files with 367 additions and 1 deletions
--- a/README.md
+++ b/README.md
@@ -1 +1,172 @@
-https://github.com/hackmdio/codimd
+# 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)