From 9b73c810e6fa20bca6d66b0387585fa66698c6c8 Mon Sep 17 00:00:00 2001 From: Timmy Date: Tue, 17 Mar 2026 15:06:08 +0800 Subject: [PATCH] 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 --- QUICKSTART.md | 95 +++++++++++++++++++++++++++ README.md | 173 +++++++++++++++++++++++++++++++++++++++++++++++++- SUMMARY.md | 100 +++++++++++++++++++++++++++++ 3 files changed, 367 insertions(+), 1 deletion(-) create mode 100644 QUICKSTART.md create mode 100644 SUMMARY.md diff --git a/QUICKSTART.md b/QUICKSTART.md new file mode 100644 index 0000000..7c7a38e --- /dev/null +++ b/QUICKSTART.md @@ -0,0 +1,95 @@ +# CodiMD 快速開始指南 + +5 分鐘內啟動你的 CodiMD 服務！ + +## 前置需求 + +- Docker +- Docker Compose + +## 三步驟啟動 + +### 步驟 1：複製環境設定 + +```bash +cp .env.example .env +``` + +### 步驟 2：啟動服務 + +```bash +docker-compose up -d +``` + +等待大約 30 秒讓服務完全啟動。 + +### 步驟 3：開始使用 + +打開瀏覽器訪問：**http://localhost:3000** + +## 驗證服務狀態 + +```bash +# 查看所有服務 +docker-compose ps + +# 查看日誌 +docker-compose logs -f +``` + +正常輸出應該顯示兩個服務都在運行： + +``` +NAME STATUS PORTS +codimd-postgres Up (healthy) +codimd-app Up (healthy) 127.0.0.1:3000->3000/tcp +``` + +## 第一次使用 + +1. 點擊「Sign in」登入 +2. 預設使用「臨時筆記」或註冊新帳號 +3. 開始創作你的第一個 Markdown 文件！ + +## 常用指令 + +| 操作 | 指令 | +|------|------| +| 查看日誌 | `docker-compose logs -f` | +| 停止服務 | `docker-compose down` | +| 重新啟動 | `docker-compose restart` | +| 更新映像 | `docker-compose pull && docker-compose up -d` | + +## 資料存放在哪裡？ + +``` +. +├── pgdata/ # 資料庫資料 +└── upload-data/ # 上傳的圖片和檔案 +``` + +## 需要更多說明？ + +查看完整文件：[README.md](README.md) + +## 遇到問題？ + +```bash +# 查看錯誤日誌 +docker-compose logs codimd +docker-compose logs database +``` + +常見問題： + +| 問題 | 解決方案 | +|------|----------| +| 無法訪問 3000 port | 等待 30 秒後重新整理 | +| 資料庫連線失敗 | 確認 `docker-compose ps` 顯示兩個服務都在運行 | +| 忘記密碼 | 編輯 `.env` 中的 `POSTGRES_PASSWORD`，然後 `docker-compose restart` | + +## 下一步 + +- **生產部署**：參考 [README.md](README.md) 的安全建議 +- **自訂設定**：編輯 `.env` 檔案 +- **設定網域**：使用 Nginx 或 Caddy 作為反向代理 diff --git a/README.md b/README.md index 5874e3e..17f8994 100644 --- 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) diff --git a/SUMMARY.md b/SUMMARY.md new file mode 100644 index 0000000..fa711f1 --- /dev/null +++ b/SUMMARY.md @@ -0,0 +1,100 @@ +# CodiMD Docker 部署 - 專案摘要 + +## 專案概述 + +本專案提供一個安全、易於部署的 CodiMD（HackMD）Docker 配置，適合個人使用或團隊協作。 + +## 專案結構 + +``` +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