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

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. 同步代码

# 从开发目录同步到安装目录
rsync -av --exclude='__pycache__' --exclude='.pytest_cache' \
  ~/.openclaw/sanguo_projects/sanguo_moziplus_v2/ \
  ~/.sanguo_projects/sanguo_moziplus_v2/

2. 安装依赖

cd ~/.sanguo_projects/sanguo_moziplus_v2
pip3 install -r requirements.txt

3. 配置

编辑 config/default.yaml，按需调整：

# 数据根目录（可选，不设则用 {安装目录}/data/）
data_root: "~/.sanguo_projects/sanguo_moziplus_v2/data"

daemon:
  tick_interval: 30
  max_global_agents: 5

4. 前端构建（如果从开发目录 rsync 了 dist/ 可跳过）

cd ~/.sanguo_projects/sanguo_moziplus_v2/src/frontend
npm install
npm run build
# 产物在 src/frontend/dist/

5. PM2 启动

cd ~/.sanguo_projects/sanguo_moziplus_v2
pm2 start ecosystem.config.cjs

6. 验证

# 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:

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）←─────────────┘

测试

单元测试

cd ~/.sanguo_projects/sanguo_moziplus_v2
python3 -m pytest tests/ -q

端到端测试（司马懿执行）

# 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