auto-sync: 2026-05-17 00:05:04

2026-05-17 00:05:04 +08:00
parent 2a376ffbb0
commit 03123226ec
1 changed files with 84 additions and 1 deletions
@@ -385,7 +385,90 @@ Phase 5: Mail 逐步下线（远期目标，与黑板评论长期共存）

 ---

-## 12. 交付检查清单
+## 12. 依赖梳理
+
+### 12.1 运行时依赖
+
+| 依赖 | 版本要求 | 用途 | 安装方式 |
+|------|---------|------|----------|
+| Python | ≥ 3.9（推荐 3.11） | Daemon + FastAPI | macOS 系统自带 3.9.6 / venv 用 3.11 |
+| Node.js | ≥ 20 | 前端构建 | nvm 管理 |
+| PM2 | ≥ 5.0（当前 6.0.14） | 进程管理 | `npm i -g pm2` |
+| FastAPI | latest | HTTP API | `pip install fastapi` |
+| uvicorn | latest | ASGI server | `pip install uvicorn` |
+| PyYAML | latest | YAML 配置读写 | `pip install pyyaml` |
+| OpenClaw CLI | ≥ 2026.5.7 | Agent spawn / sessions_spawn | 已安装 |
+| Git | ≥ 2.x | 版本管理 | 系统自带 |
+
+### 12.2 构建时依赖
+
+| 依赖 | 用途 | 说明 |
+|------|------|------|
+| npm / pnpm | 前端构建 | React + Vite + TypeScript |
+| rsync | 开发→安装同步 | macOS 自带 |
+
+### 12.3 外部服务依赖
+
+| 服务 | 地址 | 用途 | 容错 |
+|------|------|------|------|
+| OpenClaw Gateway | 127.0.0.1:18789 | Agent spawn / sessions_spawn | v2 启动时检查，不可用则 Daemon 只运行 tick 不调度 Agent |
+| NAS SMB | 192.168.2.154 | 数据存储（跨项目桥接） | 挂载失败时 per-project 功能不受影响 |
+| Gitee | gitee.com | Git 远程 | 网络不可用时本地正常运行 |
+| Gitea | 192.168.2.154:3000 | Git 备份远程 | 网络不可用时本地正常运行 |
+
+---
+
+## 13. 运维场景手册
+
+### 13.1 日常运维
+
+| 场景 | 操作 | 频率 |
+|------|------|------|
+| 查看系统状态 | `curl http://127.0.0.1:8083/api/daemon/status` | 按需 |
+| 查看日志 | `pm2 logs sanguo-moziplus-v2 --lines 50` | 按需 |
+| 重启服务 | `pm2 restart sanguo-moziplus-v2` | 更新后 |
+| 查看活跃 Agent | `curl http://127.0.0.1:8083/api/daemon/sessions` | 按需 |
+
+### 13.2 数据备份
+
+| 数据 | 备份方式 | 频率 |
+|------|---------|------|
+| blackboard.db | Git commit（projects/ 目录） | 每次 tick 自动 git add？或手动 |
+| _registry.yaml | Git 管理 | CLI 操作时自动 commit |
+| skills/ 目录 | Git 管理 | Skill 变更时 commit |
+| 前端 dist/ | Git 管理 | 构建后 commit |
+| artifacts/ | 不备份（可重建） | — |
+
+**备份策略**：整个安装目录 `~/.sanguo_projects/sanguo_moziplus_v2/` 是 Git 仓库，推送到 gitee + gitea 双远程。
+
+### 13.3 磁盘满处理
+
+```bash
+# 1. 检查磁盘占用
+du -sh ~/.sanguo_projects/sanguo_moziplus_v2/projects/*/
+
+# 2. 归档不活跃项目
+python3 src/cli/admin.py project archive --id old_project
+
+# 3. 清理归档项目 artifacts
+rm -rf ~/.sanguo_projects/sanguo_moziplus_v2/projects/_archived/old_project/artifacts/
+
+# 4. 清理旧日志
+pm2 flush sanguo-moziplus-v2
+```
+
+### 13.4 告警升级
+
+| 级别 | 触发条件 | 处理方式 |
+|------|---------|----------|
+| 自动恢复 | 进程崩溃 | PM2 auto restart |
+| 应用告警 | 逻辑死循环 | observation 写黑板 + SSE 推送 |
+| 人工介入 | DB 损坏 / 逻辑异常 | Dashboard 告警 + 用户介入 |
+| 回滚 | v2 不可用 | `pm2 stop sanguo-moziplus-v2`，切回 v1(8082) |
+
+---
+
+## 14. 交付检查清单

 P1 部署前逐项验证：