cfdaily
213 lines
6.8 KiB
Markdown
213 lines
6.8 KiB
Markdown
# v2.6 部署方案设计
|
||
|
||
**版本**: v2.6.1-deploy (含评审修正 + 独立部署)
|
||
**基于**: technical-design-v2.6.md
|
||
**作者**: 庞统（副军师）
|
||
**日期**: 2026-05-15
|
||
|
||
---
|
||
|
||
## 1. 部署环境
|
||
|
||
| 项目 | 当前状态 |
|
||
|------|---------|
|
||
| 主机 | 楚锋的 Mac mini (ARM64, macOS) |
|
||
| Python | 3.9.6（系统）+ 3.11（moziplus venv）|
|
||
| Node.js | v22.22.1 |
|
||
| PM2 | 6.0.14（管理 10 个进程）|
|
||
| 运行目录 | `~/.sanguo_projects/sanguo_moziplus_v2/` |
|
||
| 开发目录 | `~/.openclaw/sanguo_projects/sanguo_moziplus_v2/` |
|
||
| Git 远程 | gitee (origin) + gitea (内网 NAS) |
|
||
| 前端 | port 8083（v2 独立端口） |
|
||
| Gateway | 127.0.0.1:18789 |
|
||
|
||
---
|
||
|
||
## 2. 部署架构
|
||
|
||
```
|
||
PM2 (进程管理器)
|
||
├── sanguo-moziplus-v2 (port 8083) ← 🆕 v2 独立进程
|
||
├── sanguo-moziplus (port 8082) ← v1 保留（v2 验证后下线）
|
||
├── sanguo-git-sync ← 不变
|
||
├── sanguo-mail-* (8 个) ← 不变（v2 验证后下线）
|
||
└── sanguo-mozi ← 不变
|
||
|
||
新增文件：
|
||
~/.sanguo_projects/sanguo_moziplus_v2/
|
||
├── blackboard.db ← 🆕 黑板数据库（自动创建）
|
||
├── artifacts/ ← 🆕 产出物目录（自动创建）
|
||
├── src/blackboard/ ← 🆕 黑板模块
|
||
├── src/daemon/ ← 🆕 Daemon 模块
|
||
├── src/api/ ← 🆕 API
|
||
├── src/cli/ ← 🆕 CLI
|
||
└── ecosystem.config.cjs ← 🆕 PM2 配置
|
||
```
|
||
|
||
**关键：不新增 PM2 进程。** Daemon ticker 作为 asyncio background task 运行在 moziplus 进程内。
|
||
|
||
---
|
||
|
||
## 3. 部署流程
|
||
|
||
### 3.1 开发→安装同步
|
||
|
||
按照 AGENTS.md 的"代码变更标准流程"，但简化（非代码变更，是文档确认后的首次实现）：
|
||
|
||
```
|
||
步骤 1: 创建项目
|
||
mkdir -p ~/.openclaw/sanguo_projects/sanguo_moziplus_v2
|
||
cd ~/.openclaw/sanguo_projects/sanguo_moziplus_v2
|
||
git init
|
||
git remote add origin git@gitee.com:cfdaily:sanguo_moziplus_v2.git
|
||
git remote add gitea http://192.168.2.154:3000/cfdaily/sanguo_moziplus_v2.git
|
||
|
||
步骤 2: 开发编码
|
||
~/.openclaw/sanguo_projects/sanguo_moziplus_v2/src/blackboard/
|
||
~/.openclaw/sanguo_projects/sanguo_moziplus_v2/src/daemon/
|
||
~/.openclaw/sanguo_projects/sanguo_moziplus_v2/src/api/
|
||
~/.openclaw/sanguo_projects/sanguo_moziplus_v2/src/cli/
|
||
|
||
步骤 3: 单元测试通过
|
||
cd ~/.openclaw/sanguo_projects/sanguo_moziplus_v2
|
||
python3 -m pytest tests/unit/test_blackboard.py -v
|
||
python3 -m pytest tests/unit/test_daemon_tick.py -v
|
||
|
||
步骤 4: 发司马懿评审（代码级）
|
||
|
||
步骤 5: 评审通过后，同步到安装目录
|
||
rsync -av --exclude='.venv' --exclude='node_modules' \
|
||
~/.openclaw/sanguo_projects/sanguo_moziplus_v2/ ~/.sanguo_projects/sanguo_moziplus_v2/
|
||
|
||
步骤 6: PM2 启动 v2
|
||
cd ~/.sanguo_projects/sanguo_moziplus_v2
|
||
pm2 start ecosystem.config.cjs
|
||
|
||
步骤 7: 验证
|
||
curl http://127.0.0.1:8083/api/daemon/status
|
||
python3 ~/.sanguo_projects/sanguo_moziplus_v2/src/cli/blackboard.py create --title "test" --creator test
|
||
```
|
||
pm2 restart sanguo-moziplus
|
||
|
||
步骤 6: 验证
|
||
curl http://127.0.0.1:8082/api/daemon/status
|
||
python3 ~/.sanguo_projects/sanguo_moziplus_v2/src/cli/blackboard.py create --title "test" --creator test
|
||
```
|
||
|
||
### 3.2 数据库初始化
|
||
|
||
blackboard.db 在 moziplus 启动时自动创建和初始化（`init_blackboard_db()`）。不需要手动建表。
|
||
|
||
首次部署时 `blackboard.db` 文件不存在，启动后自动创建。后续启动检测到已存在则跳过 schema 初始化（`CREATE TABLE IF NOT EXISTS` 天然幂等）。
|
||
|
||
---
|
||
|
||
## 4. 回滚方案
|
||
|
||
| 场景 | 回滚方式 |
|
||
|------|---------|
|
||
| v2 启动失败 | `pm2 stop sanguo-moziplus-v2` → v1 不受影响 |
|
||
| Daemon tick 异常 | API 调用 `POST /api/daemon/stop` 停 ticker 不停服务 |
|
||
| SQLite 损坏 | 删除 `blackboard.db` 重启自动重建 |
|
||
| v2 整体不可用 | v1 仍在 8082 运行，切换回 v1 即可 |
|
||
|
||
**关键：v1 和 v2 完全独立，互不影响。** v2 出问题直接停掉，v1 继续服务。
|
||
|
||
---
|
||
|
||
## 5. 监控
|
||
|
||
### 5.1 日志
|
||
|
||
所有黑板操作和 daemon tick 通过 Python logging 输出到 PM2 日志：
|
||
|
||
```bash
|
||
# 查看 daemon tick 日志
|
||
pm2 logs sanguo-moziplus --lines 100 | grep "Daemon\|Blackboard\|Tick"
|
||
|
||
# 查看 spawn 日志
|
||
pm2 logs sanguo-moziplus --lines 100 | grep "Spawning\|Cleaned up"
|
||
```
|
||
|
||
### 5.2 健康端点
|
||
|
||
```
|
||
GET /api/daemon/status
|
||
返回：
|
||
{
|
||
"ticker_running": true,
|
||
"last_tick": "2026-05-15T01:30:00",
|
||
"tick_interval_seconds": 60,
|
||
"active_sessions": 2,
|
||
"blackboard_db_size_bytes": 45056,
|
||
"tasks_summary": {
|
||
"pending": 3,
|
||
"claimed": 1,
|
||
"working": 2,
|
||
"review": 0,
|
||
"done": 15,
|
||
"failed": 1,
|
||
"blocked": 0
|
||
}
|
||
}
|
||
```
|
||
|
||
### 5.3 PM2 告警
|
||
|
||
复用现有 PM2 配置，sanguo-moziplus 如果异常退出会自动重启（已配置 `max_restarts: 10`）。
|
||
|
||
---
|
||
|
||
## 6. 安全考虑
|
||
|
||
| 项目 | 措施 |
|
||
|------|------|
|
||
| SQLite 文件权限 | `blackboard.db` 只有 owner 可读写（0600）|
|
||
| API 认证 | 复用 moziplus 现有认证（如有）|
|
||
| CLI 路径 | blackboard.py 只能本地 exec 调用，不暴露网络 |
|
||
| Session 清理锁 | fcntl 文件锁防止并发编辑 sessions.json |
|
||
| Agent 权限 | SOUL.md 约束 + blackboard.py claim 时的 assignee 检查 |
|
||
|
||
---
|
||
|
||
## 7. 性能预估
|
||
|
||
| 指标 | 预估值 | 理由 |
|
||
|------|--------|------|
|
||
| Tick 循环耗时 | <100ms | 6 张表、几十条记录的 SQLite 查询 |
|
||
| Agent spawn 延迟 | 2-5s | openclaw agent 冷启动时间 |
|
||
| 并发 Agent 数 | ≤6 | 6 个将军，通常不会同时活跃 |
|
||
| SQLite 并发写入 | WAL 模式支持读写并发 | 已验证 |
|
||
| blackboard.db 大小 | 初期 <1MB | 每个任务几 KB，100 个任务 < 1MB |
|
||
|
||
---
|
||
|
||
## 8. 交付检查清单
|
||
|
||
Phase 1 部署前逐项验证：
|
||
|
||
- [ ] 项目创建、git init、远程配置完成
|
||
- [ ] `blackboard.db` 自动创建且 schema 正确
|
||
- [ ] CLI `blackboard.py read/claim/output/comment/decide/observe/create` 全部可用
|
||
- [ ] Daemon tick 60s 循环正常运行
|
||
- [ ] Agent spawn 成功创建隔离 session
|
||
- [ ] Session 完成后自动存档 + sessions.json 清理
|
||
- [ ] API `/api/blackboard/tasks` 可创建/查询任务
|
||
- [ ] API `/api/daemon/status` 返回正确状态
|
||
- [ ] API `/api/daemon/tick` 可手动触发
|
||
- [ ] PM2 启动后 daemon ticker 自动恢复
|
||
- [ ] `pm2 logs` 中能看到 tick 和 spawn 日志
|
||
- [ ] v1 (8082) 不受 v2 (8083) 影响
|
||
|
||
---
|
||
|
||
## 9. 后续 Phase 规划
|
||
|
||
| Phase | 内容 | 依赖 |
|
||
|-------|------|------|
|
||
| **Phase 1** | 黑板 + Daemon + CLI + API（本方案） | 无 |
|
||
| Phase 2 | 前端黑板视图 + Agent 黑板 Skill | Phase 1 |
|
||
| Phase 3 | 依赖自动推进 + 产出验证门禁 | Phase 2 |
|
||
| Phase 4 | 庞统 AI 规划 + Agent 自主领活 | Phase 3 |
|
||
| Phase 5 | 经验沉淀 + Mail 完全移除 | Phase 4 |
|