From 03123226ecadf3f715f839cfe3e108a5495ea8cb Mon Sep 17 00:00:00 2001 From: cfdaily Date: Sun, 17 May 2026 00:05:04 +0800 Subject: [PATCH] auto-sync: 2026-05-17 00:05:04 --- docs/design/deployment-v2.6.md | 85 +++++++++++++++++++++++++++++++++- 1 file changed, 84 insertions(+), 1 deletion(-) diff --git a/docs/design/deployment-v2.6.md b/docs/design/deployment-v2.6.md index e951173..abf2fd8 100644 --- a/docs/design/deployment-v2.6.md +++ b/docs/design/deployment-v2.6.md @@ -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 部署前逐项验证：