auto-sync: 2026-05-17 07:28:29

docs/design/deployment-v2.6-guide.md

@@ -0,0 +1,171 @@
+# v2.6 部署指南
+
+**版本**: 2.6.0
+**作者**: 庞统（副军师）🐦
+**日期**: 2026-05-17
+
+---
+
+## 架构概览
+
+```
+安装目录: ~/.sanguo_projects/sanguo_moziplus_v2/
+├── config/default.yaml          # 全局配置
+├── data/                        # 运行时数据（项目黑板DB）
+├── src/                         # Python 源码
+│   ├── main.py                  # FastAPI 入口
+│   ├── frontend/dist/           # 前端构建产物
+│   ├── api/                     # API 路由
+│   ├── blackboard/              # 黑板核心
+│   └── daemon/                  # Daemon 模块
+├── tests/                       # 单元测试
+├── pyproject.toml               # Python 项目配置
+├── ecosystem.config.cjs         # PM2 配置
+└── requirements.txt             # Python 依赖
+
+开发目录: ~/.openclaw/sanguo_projects/sanguo_moziplus_v2/
+└── （同结构，git 仓库）
+```
+
+## 路径解析策略
+
+所有路径通过以下优先级解析：
+
+1. **环境变量** `BLACKBOARD_ROOT` → 项目数据根目录（最高优先级）
+2. **配置文件** `config/default.yaml` 的 `data_root` → 项目数据根目录
+3. **相对路径默认** → `{安装目录}/data/`（`main.py` 用 `__file__` 相对定位）
+
+### 关键路径
+
+| 用途 | 解析方式 | 默认值 |
+|------|---------|--------|
+| 项目数据 | `BLACKBOARD_ROOT` 环境变量 或 `config.data_root` | `{src/../data/}` |
+| 配置文件 | `__file__` 相对定位 | `{src/../config/default.yaml}` |
+| 前端静态文件 | `__file__` 相对定位 | `{src/frontend/dist/}` |
+| Inbox JSONL | 相对于项目数据目录 | `{项目}/inbox/daemon.jsonl` |
+| 日志 | PM2 管理 | stdout |
+
+## 部署步骤
+
+### 1. 同步代码
+
+```bash
+# 从开发目录同步到安装目录
+rsync -av --exclude='__pycache__' --exclude='.pytest_cache' \
+  ~/.openclaw/sanguo_projects/sanguo_moziplus_v2/ \
+  ~/.sanguo_projects/sanguo_moziplus_v2/
+```
+
+### 2. 安装依赖
+
+```bash
+cd ~/.sanguo_projects/sanguo_moziplus_v2
+pip3 install -r requirements.txt
+```
+
+### 3. 配置
+
+编辑 `config/default.yaml`，按需调整：
+
+```yaml
+# 数据根目录（可选，不设则用 {安装目录}/data/）
+data_root: "~/.sanguo_projects/sanguo_moziplus_v2/data"
+
+daemon:
+  tick_interval: 30
+  max_global_agents: 5
+```
+
+### 4. 前端构建（如果从开发目录 rsync 了 dist/ 可跳过）
+
+```bash
+cd ~/.sanguo_projects/sanguo_moziplus_v2/src/frontend
+npm install
+npm run build
+# 产物在 src/frontend/dist/
+```
+
+### 5. PM2 启动
+
+```bash
+cd ~/.sanguo_projects/sanguo_moziplus_v2
+pm2 start ecosystem.config.cjs
+```
+
+### 6. 验证
+
+```bash
+# API
+curl http://localhost:8080/api/daemon/status
+
+# Swagger 文档
+open http://localhost:8080/docs
+
+# 前端 Dashboard
+open http://localhost:8083
+# 或（如果 FastAPI 托管静态文件）
+open http://localhost:8080/
+```
+
+## PM2 配置
+
+`ecosystem.config.cjs`:
+
+```javascript
+module.exports = {
+  apps: [{
+    name: "sanguo-moziplus-v2",
+    script: "src/main.py",
+    interpreter: "python3",
+    cwd: "/Users/chufeng/.sanguo_projects/sanguo_moziplus_v2",
+    env: {
+      BLACKBOARD_ROOT: "/Users/chufeng/.sanguo_projects/sanguo_moziplus_v2/data",
+    },
+    max_memory_restart: "500M",
+    log_date_format: "YYYY-MM-DD HH:mm:ss",
+  }]
+};
+```
+
+## NAS/Docker 部署（姜维负责）
+
+- 数据目录挂载到 NAS `/Volumes/stock/moziplus-v2/`
+- Docker 容器运行 FastAPI + 前端
+- 定时 `sqlite3 backup` 黑板 DB 到 NAS
+
+## 开发 → 部署 同步流程
+
+```
+开发目录修改 → git commit → rsync 到安装目录 → pm2 restart → 验证
+                ↑                                              ↓
+                └────────────── 回滚（git revert）←─────────────┘
+```
+
+## 测试
+
+### 单元测试
+
+```bash
+cd ~/.sanguo_projects/sanguo_moziplus_v2
+python3 -m pytest tests/ -q
+```
+
+### 端到端测试（司马懿执行）
+
+```bash
+# 1. 创建项目
+python3 src/cli/admin.py create demo "Demo Project" --agents agent1,agent2
+
+# 2. 创建任务
+python3 src/cli/blackboard.py create demo --title "Test Task" --type coding
+
+# 3. 查看任务
+python3 src/cli/blackboard.py read demo
+
+# 4. API 测试
+curl http://localhost:8080/api/projects
+curl http://localhost:8080/api/daemon/status
+
+# 5. 前端访问
+open http://localhost:8083
+```