262 lines
5.9 KiB
Markdown
262 lines
5.9 KiB
Markdown
# Momentry Core 版本管理規範
|
||
|
||
| 項目 | 內容 |
|
||
|------|------|
|
||
| 建立者 | Warren |
|
||
| 建立時間 | 2026-03-23 |
|
||
| 文件版本 | V1.0 |
|
||
|
||
---
|
||
|
||
## 版本歷史
|
||
|
||
| 版本 | 日期 | 目的 | 操作人 | 工具/模型 |
|
||
|------|------|------|--------|-----------|
|
||
| V1.0 | 2026-03-23 | 創建版本管理規範 | Warren | OpenCode |
|
||
|
||
---
|
||
|
||
## 1. 版本與通訊埠對照表
|
||
|
||
| 版本 | Binary | Port | Redis Prefix | 用途 |
|
||
|------|--------|------|--------------|------|
|
||
| **Production** | `momentry` | **3002** | `momentry:` | 正式環境 |
|
||
| **Development** | `momentry_playground` | **3003** | `momentry_dev:` | 開發測試 |
|
||
|
||
### 通訊埠嚴禁事項
|
||
- ❌ 開發版嚴禁使用 3002
|
||
- ❌ 任何 `cargo run` 直接啟動的 server 嚴禁綁定 3002
|
||
- ❌ Debug build 嚴禁部署到 3002
|
||
|
||
---
|
||
|
||
## 2. 開發環境隔離原則
|
||
|
||
### 2.1 開發流程
|
||
```bash
|
||
# 永遠在 3003 開發測試
|
||
cd /Users/accusys/momentry_core_0.1
|
||
|
||
# 開發版啟動 (3003)
|
||
cargo run --bin momentry_playground -- server
|
||
# 或
|
||
cargo run --bin momentry -- server --port 3003
|
||
```
|
||
|
||
### 2.2 測試完成後
|
||
1. 確認所有功能在 3003 正常運作
|
||
2. 進行 `cargo clippy --lib` 檢查
|
||
3. 進行 `cargo test --lib` 測試
|
||
4. 確認後才能進行 release
|
||
|
||
### 2.3 環境變數隔離
|
||
```bash
|
||
# Development
|
||
export MOMENTRY_SERVER_PORT=3003
|
||
export MOMENTRY_REDIS_PREFIX=momentry_dev:
|
||
|
||
# Production (launchd 管理，勿手動設定)
|
||
# MOMENTRY_SERVER_PORT=3002
|
||
# MOMENTRY_REDIS_PREFIX=momentry:
|
||
```
|
||
|
||
---
|
||
|
||
## 3. Release 版本管理
|
||
|
||
### 3.1 Release 前檢查清單
|
||
|
||
```
|
||
□ 開發版 (3003) 功能測試完成
|
||
□ cargo clippy --lib 通過
|
||
□ cargo test --lib 通過
|
||
□ cargo fmt -- --check 通過
|
||
□ 所有修改已 commit 到 Gitea
|
||
```
|
||
|
||
### 3.2 Release 流程
|
||
|
||
```bash
|
||
# 1. 確保目前是乾淨的工作目錄
|
||
git status
|
||
|
||
# 2. 備份當前 production binary
|
||
BACKUP_DIR="/Users/accusys/momentry/backup/bin"
|
||
TIMESTAMP=$(date +%Y%m%d_%H%M%S)
|
||
cp /Users/accusys/momentry/bin/momentry "${BACKUP_DIR}/momentry_${TIMESTAMP}"
|
||
|
||
# 3. 停止 production server
|
||
sudo launchctl unload /Library/LaunchDaemons/com.momentry.api.plist
|
||
# 或
|
||
pkill -f "target/release/momentry server"
|
||
|
||
# 4. 編譯 release 版本
|
||
cargo build --release --bin momentry
|
||
|
||
# 5. 部署到正式位置
|
||
cp target/release/momentry /Users/accusys/momentry/bin/momentry
|
||
|
||
# 6. 啟動 production server
|
||
sudo launchctl load /Library/LaunchDaemons/com.momentry.api.plist
|
||
|
||
# 7. 驗證
|
||
curl http://localhost:3002/health
|
||
```
|
||
|
||
### 3.3 Backup 存放位置
|
||
```
|
||
/Users/accusys/momentry/backup/bin/
|
||
├── momentry_20260325_143000 (backup)
|
||
├── momentry_20260324_100000
|
||
├── momentry_20260323_090000
|
||
└── ...
|
||
```
|
||
|
||
---
|
||
|
||
## 4. Gitea 版本控制
|
||
|
||
### 4.1 Commit 規範
|
||
```
|
||
feat: 新功能
|
||
fix: 錯誤修復
|
||
refactor: 重構
|
||
docs: 文件更新
|
||
chore: 杂项
|
||
test: 测试
|
||
```
|
||
|
||
### 4.2 Release Tag 規範
|
||
```bash
|
||
# 建立 release tag
|
||
git tag -a v0.1.1 -m "Release v0.1.1 - API Key Authentication"
|
||
git push origin v0.1.1
|
||
```
|
||
|
||
### 4.3 版本號命名
|
||
```
|
||
v{major}.{minor}.{patch}
|
||
│ │ └── Patch version (bug fix)
|
||
│ └───────── Minor version (新功能)
|
||
└──────────────── Major version (破壞性變更)
|
||
```
|
||
|
||
### 4.4 Gitea Release 建立
|
||
1. 在 Gitea Repo > Releases > New Release
|
||
2. 選擇對應的 Tag
|
||
3. 填寫 Release Notes
|
||
4. 上傳 compiled binary（如需要）
|
||
|
||
---
|
||
|
||
## 5. 服務管理
|
||
|
||
### 5.1 Production Service (launchd)
|
||
```bash
|
||
# Plist 位置
|
||
/Library/LaunchDaemons/com.momentry.api.plist
|
||
|
||
# 管理指令
|
||
sudo launchctl load /Library/LaunchDaemons/com.momentry.api.plist # 啟動
|
||
sudo launchctl unload /Library/LaunchDaemons/com.momentry.api.plist # 停止
|
||
sudo launchctl list | grep momentry # 狀態
|
||
```
|
||
|
||
### 5.2 緊急回滾
|
||
```bash
|
||
# 1. 停止當前服務
|
||
sudo launchctl unload /Library/LaunchDaemons/com.momentry.api.plist
|
||
|
||
# 2. 恢復上一個 backup
|
||
BACKUP_FILE=$(ls -t /Users/accusys/momentry/backup/bin/ | head -1)
|
||
cp "/Users/accusys/momentry/backup/bin/${BACKUP_FILE}" /Users/accusys/momentry/bin/momentry
|
||
|
||
# 3. 重啟服務
|
||
sudo launchctl load /Library/LaunchDaemons/com.momentry.api.plist
|
||
|
||
# 4. 驗證
|
||
curl http://localhost:3002/health
|
||
```
|
||
|
||
---
|
||
|
||
## 6. 快速參考卡片
|
||
|
||
### Development
|
||
```bash
|
||
# 啟動開發版
|
||
cd /Users/accusys/momentry_core_0.1
|
||
cargo run --bin momentry_playground -- server
|
||
|
||
# 或手動指定 port
|
||
cargo run --bin momentry -- server --port 3003
|
||
|
||
# 測試端點
|
||
curl -H "X-API-Key: muser_68600856036340bcafc01930eb4bd839_1774418104_97221b69" \
|
||
http://localhost:3003/api/v1/jobs
|
||
```
|
||
|
||
### Production
|
||
```bash
|
||
# 查看狀態
|
||
sudo launchctl list | grep momentry
|
||
|
||
# 重啟服務
|
||
sudo launchctl unload /Library/LaunchDaemons/com.momentry.api.plist
|
||
sudo launchctl load /Library/LaunchDaemons/com.momentry.api.plist
|
||
|
||
# 查看日誌
|
||
tail -f /Users/accusys/momentry/log/momentry_release.log
|
||
```
|
||
|
||
### 常用指令
|
||
```bash
|
||
# 檢查 port 使用
|
||
lsof -i :3002 # Production
|
||
lsof -i :3003 # Development
|
||
|
||
# 檢查 process
|
||
ps aux | grep momentry | grep server
|
||
|
||
# 停止所有 momentry server
|
||
pkill -9 -f "momentry.*server"
|
||
```
|
||
|
||
---
|
||
|
||
## 7. 禁止事項
|
||
|
||
| 項目 | 說明 |
|
||
|------|------|
|
||
| ❌ 禁止在 3002 測試 | 3002 是 Production，嚴禁用於測試 |
|
||
| ❌ 禁止覆蓋 production binary | 使用 backup + deploy 流程 |
|
||
| ❌ 禁止跳過測試直接 release | 必須完成檢查清單 |
|
||
| ❌ 禁止在未備份的情況下部署 | 每次部署前必須備份 |
|
||
|
||
---
|
||
|
||
## 8. 疑難排解
|
||
|
||
### Q: 3002 無法綁定怎麼辦？
|
||
```bash
|
||
# 檢查誰在使用
|
||
lsof -i :3002
|
||
|
||
# 停止舊的 server
|
||
pkill -9 -f "momentry.*server"
|
||
```
|
||
|
||
### Q: 如何確認使用的是哪個版本？
|
||
```bash
|
||
# 檢查 binary 位置和版本
|
||
file $(which momentry)
|
||
./target/release/momentry --version 2>/dev/null || echo "No version flag"
|
||
```
|
||
|
||
### Q: 如何確認有沒有 API Key 驗證？
|
||
```bash
|
||
# 沒有 API Key 應該返回 401
|
||
curl -s http://localhost:3002/api/v1/jobs
|
||
# HTTP/1.1 401 Unauthorized
|
||
```
|