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