VM 多场景部署 · 多飞书机器人联调

本页描述如何在 D2 云 VM 上启动多场景评委体系 — 每个 Scene 对应一个独立飞书机器人，共用同一套 boss 判断引擎、wiki 知识库与锚点心智模型。
前置阅读: 多场景评委体系 · 部署指南

0. 架构总览

飞书 (N 个机器人)
  │  机器人 A: review 场景        机器人 B: competition 场景
  │  收到文档                      收到方案
  ▼                                ▼
feishu_ws_client (单进程，N 条长连接，按 scene 路由)
  │
  ├─ scene A → job {scene_slug: "review-scene-a"}
  └─ scene B → job {scene_slug: "competition-scene-b"}
  ▼
review_worker (从 job.scene_slug 选对应 panel)
  │
  ├─ review-scene-a  → scenes/review-scene-a/panel.yaml  (100分, anchor judge)
  └─ competition-scene-b → scenes/competition-scene-b/panel.yaml (10分, 无 anchor)
  ▼
boss_server (HTTP API, port 8421)
  └─ GET /v1/scenes → 检查各场景 env 就绪状态

三个服务:

服务	进程	职责
`boss-hermes`	`uvicorn scripts.boss_server:app`	HTTP API + 健康检查 + `/v1/scenes`
`boss-review-worker`	`python scripts/review_worker.py`	从 job 队列消费，调 LLM 跑评审流水线
`boss-feishu-ws`	`python scripts/feishu_ws_client.py`	飞书长连接，按 scene 路由事件

1. VM 准备

1.1 推荐规格

项	推荐	说明
CPU	4C	2C 可跑，但 worker 并发时慢
RAM	8G	4G 最低
OS	Ubuntu 22.04 LTS	系统依赖最完整
公网 IP	是	飞书长连接是 outbound，无需开放入站

飞书长连接是 VM 主动连飞书，不需要 VM 开放任何入站端口给飞书。

1.2 安装依赖

bash

sudo apt update && sudo apt install -y python3.11 python3.11-venv git curl

# 建专用用户
sudo useradd -r -m -d /home/boss -s /bin/bash boss
sudo -u boss bash

# clone vault
cd ~ && git clone https://github.com/zhanglunet/boss-vault.git
cd boss-vault

# 建 venv + 安装依赖
python3.11 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
pip install lark-oapi>=1.3.0   # 飞书长连接 SDK

# 验证
python3 -c "import fastapi, lark_oapi; print('deps OK')"

2. 配置 .env

2.1 复制模板

bash

cp .env.example .env
chmod 600 .env

2.2 必填字段

bash

# LLM (review worker 调用)
ANTHROPIC_API_KEY=<your-key>

# boss_server 认证 token (必须，无此字段 server 返回 503)
BOSS_API_TOKEN=$(openssl rand -hex 32)

# 飞书事件验证 token
FEISHU_VERIFICATION_TOKEN=<from-feishu-console>

# 每个 scene 各配一对 (从 scene.yaml feishu 块的 app_id_env / app_secret_env 取名)
LARK_APP_ID_<SCENE_A>=<app-id-from-feishu>
LARK_APP_SECRET_<SCENE_A>=<app-secret-from-feishu>

LARK_APP_ID_<SCENE_B>=<app-id-from-feishu>
LARK_APP_SECRET_<SCENE_B>=<app-secret-from-feishu>

# VM 只读标志 (避免 VM 写 _wiki/log.md 破坏 ff-only pull)
BOSS_VM_READER=1

查看每个 scene 需要哪些 env 变量名:

bash

python3 scripts/scene_loader.py list
# 输出示例:
# review-scene-a    type=review       bot_env=LARK_APP_ID_REVIEW_SCENE_A
# competition-scene-b  type=competition  bot_env=LARK_APP_ID_COMPETITION_SCENE_B

3. 飞书后台配置

3.1 为每个 scene 创建独立飞书自建应用

在飞书开放平台为每个 scene 各创建一个自建应用:

新建应用 → 自建应用 → 填写名称（建议与 scene 的 bot_name 一致）

权限管理 → 申请以下权限:

im:message           # 接收消息
im:message:send_as_bot  # 发送消息 (回推评审报告)
im:resource          # 读取图片/文件

凭证与基础信息 → 复制 App ID / App Secret → 填入对应 env var

3.2 事件订阅 — 长连接模式（推荐）

飞书后台 → 事件订阅 → 选择「使用长连接接收事件」
添加事件: im.message.receive_v1

⚠️ 长连接与 webhook URL 二选一。用了长连接就不填 webhook URL，否则事件重复投递。

长连接优势: 无需公网入站端口、无需 HTTPS 证书、无需 URL 验证环节。

4. 部署 systemd 服务

按顺序启动（boss-hermes 先起，review-worker 次之，feishu-ws 最后）:

4.1 boss-hermes (HTTP API)

bash

VAULT_ROOT=/home/boss/boss-vault

sudo cp templates/boss-hermes.service.example /etc/systemd/system/boss-hermes.service
sudo sed -i "s|__VAULT_ROOT__|$VAULT_ROOT|g; s|__USER__|boss|g" \
    /etc/systemd/system/boss-hermes.service

sudo systemctl daemon-reload
sudo systemctl enable --now boss-hermes

# 验证
curl http://localhost:8421/v1/healthz
# → {"status": "ok", "timestamp": "..."}

4.2 boss-review-worker

bash

sudo cp templates/boss-review-worker.service.example /etc/systemd/system/boss-review-worker.service
sudo sed -i "s|__VAULT_ROOT__|$VAULT_ROOT|g; s|__USER__|boss|g" \
    /etc/systemd/system/boss-review-worker.service

sudo systemctl daemon-reload
sudo systemctl enable --now boss-review-worker

sudo systemctl status boss-review-worker

4.3 boss-feishu-ws (多 bot 长连接)

bash

sudo cp templates/boss-feishu-ws.service.example /etc/systemd/system/boss-feishu-ws.service
sudo sed -i "s|__VAULT_ROOT__|$VAULT_ROOT|g; s|__USER__|boss|g" \
    /etc/systemd/system/boss-feishu-ws.service

sudo systemctl daemon-reload
sudo systemctl enable --now boss-feishu-ws

# 验证多 bot 连接
sudo journalctl -u boss-feishu-ws -n 30 --no-pager
# 期望每个 env 已配置的 scene 各出现一行 "WS connected"

5. 验证检查清单

5.1 静态链路校验（不调 LLM）

bash

cd ~/boss-vault && source .venv/bin/activate

# 各场景全链路静态检查
for scene in <scene-a-slug> <scene-b-slug>; do
  make smoke-scene SCENE=$scene && echo "✅ $scene"
done

# boss_server 场景状态（检查 env 是否就绪）
TOKEN=$(grep BOSS_API_TOKEN .env | cut -d= -f2)
curl -s -H "Authorization: Bearer $TOKEN" \
     http://localhost:8421/v1/scenes | python3 -m json.tool
# 期望: 每个 scene 的 feishu.env_ready = true

5.2 飞书端到端验证（需真实机器人）

不同场景按类型用不同评委编排（见多场景评委体系 · 场景决定评委类型）： review 场景用「锚点 + 多维度评委」，competition 场景用单一虚拟评价助手。

向 review 场景机器人 发送测试文档，验证:

[ ] 机器人回复评审报告
[ ] 报告含 6 段 (§1 总分 → §6 一页汇总表)
[ ] 总分制与 panel 的 total_max_score 一致 (通常 100)
[ ] 评委包含该 scene 配置的 anchor judge + 多个维度评委
[ ] 角色化维度评委的点评含标准免责声明（评委是判断框架，非真实人物本人）
[ ] 无其他 scene 的评委出现

向 competition 场景机器人 发送测试方案，验证:

[ ] 机器人回复评审报告
[ ] 总分为自定义分制 (如 10 分)
[ ] 用单一虚拟评价助手，无 anchor judge 信息
[ ] 评分维度与 panel scoring_lenses 一致

⚠️ 出站脱敏：评审报告含角色化评委的点评，群投递 / 外发前由 redact_review / 出站闸把关（评委 doctrine 源属内部资料，不随报告外泄）。

5.3 路由隔离验证

bash

# 确认 feishu_ws 多 bot 路由日志
sudo journalctl -u boss-feishu-ws -f

# 发送文档到 scene A 机器人时，期望日志:
# [feishu_ws:scene-a] handled: {status: "queued", ...}
# 不应出现 [feishu_ws:scene-b] 的日志

# 确认 review_worker 使用了正确 panel
sudo journalctl -u boss-review-worker -f
# 期望: panel=scenes/<scene-a-slug>/panel.yaml

6. 常见问题

长连接未建立 / scene 被跳过

bash

sudo journalctl -u boss-feishu-ws -n 50
# 如果见到 "skip scene xxx: env LARK_APP_ID_xxx unset"
# → .env 里对应 env 变量未填

source .env && printenv | grep LARK_APP_ID

报告用了错误场景的评委

bash

# 确认多 bot 路由是否生效
journalctl -u boss-feishu-ws | grep "starting scene bots"
# 期望: "[feishu_ws] starting scene bots: scene-a, scene-b, ..."

# 如果只见到单 bot 模式:
# "[feishu_ws] using fallback single-bot mode (LARK_APP_ID)"
# → 检查 scene.yaml 的 feishu 块是否配置，以及对应 env var 是否设置

boss_server 返回 503

bash

# 原因: BOSS_API_TOKEN 未配置
grep BOSS_API_TOKEN .env

# healthz 永远 200，其余 endpoint 需要 token
curl http://localhost:8421/v1/healthz       # 200
curl http://localhost:8421/v1/scenes        # 401 (缺 token) 或 503 (未配置)

7. 服务日志位置汇总

bash

# 三个服务的实时日志
sudo journalctl -u boss-hermes       -f   # HTTP API
sudo journalctl -u boss-review-worker -f  # LLM 评审 job
sudo journalctl -u boss-feishu-ws    -f   # 多 bot 长连接路由

# 查看所有三个服务的状态
sudo systemctl status boss-hermes boss-review-worker boss-feishu-ws

VM 多场景部署 · 多飞书机器人联调 ​

0. 架构总览 ​

1. VM 准备 ​

1.1 推荐规格 ​

1.2 安装依赖 ​

2. 配置 .env ​

2.1 复制模板 ​

2.2 必填字段 ​

3. 飞书后台配置 ​

3.1 为每个 scene 创建独立飞书自建应用 ​

3.2 事件订阅 — 长连接模式（推荐） ​

4. 部署 systemd 服务 ​

4.1 boss-hermes (HTTP API) ​

4.2 boss-review-worker ​

4.3 boss-feishu-ws (多 bot 长连接) ​

5. 验证检查清单 ​

5.1 静态链路校验（不调 LLM） ​

5.2 飞书端到端验证（需真实机器人） ​

5.3 路由隔离验证 ​

6. 常见问题 ​

长连接未建立 / scene 被跳过 ​

报告用了错误场景的评委 ​

boss_server 返回 503 ​

7. 服务日志位置汇总 ​

VM 多场景部署 · 多飞书机器人联调

0. 架构总览

1. VM 准备

1.1 推荐规格

1.2 安装依赖

2. 配置 .env

2.1 复制模板

2.2 必填字段

3. 飞书后台配置

3.1 为每个 scene 创建独立飞书自建应用

3.2 事件订阅 — 长连接模式（推荐）

4. 部署 systemd 服务

4.1 boss-hermes (HTTP API)

4.2 boss-review-worker

4.3 boss-feishu-ws (多 bot 长连接)

5. 验证检查清单

5.1 静态链路校验（不调 LLM）

5.2 飞书端到端验证（需真实机器人）

5.3 路由隔离验证

6. 常见问题

长连接未建立 / scene 被跳过

报告用了错误场景的评委

boss_server 返回 503

7. 服务日志位置汇总