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:
95
QUICKSTART.md
Normal file
95
QUICKSTART.md
Normal file
@@ -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 作為反向代理
|
||||||
173
README.md
173
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)
|
||||||
|
|||||||
100
SUMMARY.md
Normal file
100
SUMMARY.md
Normal file
@@ -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
|
||||||
Reference in New Issue
Block a user