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

6.8 KiB Raw Blame History Unescape Escape