momentry_core/docs/VERSION_MANAGEMENT.md

Momentry Core 版本管理規範

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 開發流程

# 永遠在 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 環境變數隔離

# 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 流程

# 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 規範

# 建立 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)

# 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 緊急回滾

# 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

# 啟動開發版
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

# 查看狀態
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

常用指令

# 檢查 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 無法綁定怎麼辦？

# 檢查誰在使用
lsof -i :3002

# 停止舊的 server
pkill -9 -f "momentry.*server"

Q: 如何確認使用的是哪個版本？

# 檢查 binary 位置和版本
file $(which momentry)
./target/release/momentry --version 2>/dev/null || echo "No version flag"

Q: 如何確認有沒有 API Key 驗證？

# 沒有 API Key 應該返回 401
curl -s http://localhost:3002/api/v1/jobs
# HTTP/1.1 401 Unauthorized