部署指南 · 三种形态

v0.3.0 起 boss-vault 支持三种部署形态与多 LLM provider。任选其一, 不互斥。三种判断质量一致 (同一 boss-skills + 5 镜头 + adversarial_view + anchor_delta + 30/90/365 attribution)。
见 ADR-003 · Deployment as optional 的决策背景。

部署形态对比

形态	别名	适合	always-on	30/90/365 attribution	飞书 push	infra 成本	装机时间
D1	Local Agent CLI	个人 / 小团队 / V0 期	❌ 终端在线时	launchd cron 本地	❌ CLI 调用	$0	5 min
D2	Self-host Hermes	内部团队 / always-on 需求	✅	Hermes scheduler 自动	✅ 飞书 webhook	$10-30/月	1-2 小时
D3	GitHub Actions	开源用户 / 无本地 / 无云	⚠️ schedule 触发	GitHub cron (5 min granularity)	❌	$0 (公开 repo)	15 min

D1 · Local Agent CLI (推荐 default)

最轻量。装完 5 分钟可用。

安装

bash

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

# 2. 装依赖 (Python 3.10+)
pip install -r requirements.txt

# 3. 装 /boss skill (symlink 到 ~/.claude/skills/)
bash scripts/install_tian_skill.sh

# 4. 配 .env (按 provider 选择)
cp .env.example .env
# 可填 ANTHROPIC_API_KEY / OPENAI_API_KEY / compatible base_url

使用

在 Claude Code 内:

/boss list                          # 验证安装
/boss "评估某战略议题" --quick     # 跑一次判断 (~ 18 分钟)
/boss panels                        # 列出可用 panel

或直接用 Python CLI + Codex 子进程 provider:

bash

python3 scripts/run_pipeline_local.py "评估某战略议题" \
  --brand demo-strategy \
  --llm-provider codex-cli \
  --export-full

30/90/365 attribution (本地 launchd, macOS)

attribution-checker 每天 09:00 扫所有 case, 把到期 checkpoint 拉数据更新。本地用 launchd plist:

bash

# 1. 复制模板 (推迟到 v0.3.0 提供)
cp templates/com.boss-vault.attribution.plist.example ~/Library/LaunchAgents/com.boss-vault.attribution.plist

# 2. 编辑路径
sed -i '' "s|VAULT_ROOT|$HOME/boss-vault|g" ~/Library/LaunchAgents/com.boss-vault.attribution.plist

# 3. 加载
launchctl load ~/Library/LaunchAgents/com.boss-vault.attribution.plist

# 4. 验证
launchctl list | grep boss-vault

已知限制: 本地终端 sleep / 关机时 cron 漏触发, 重启后下次 09:00 才补跑。如果痛点严重, 升级到 D2 或 D3。

Linux 替代 (crontab)

bash

# crontab -e 加入:
0 9 * * * cd $HOME/boss-vault && python3 scripts/attribution_check.py >> $HOME/.boss-vault-attribution.log 2>&1

D2 · Self-host Hermes (云 VM, 内部团队)

适合内部团队 always-on 用法。需要云 VM + 简单运维。

适用信号 (来自 ADR-003 §2.3)

锚点明确表示需要从飞书 always-on 触发 (非 ad-hoc CLI 调用)
D1 launchd 大量漏 cron (本地终端常 sleep)
团队 ≥ 3 人跨位置协作

项	推荐
云厂商	腾讯云轻量 / 阿里云 ECS / Hetzner CX22
规格	4C8G · 80GB SSD
OS	Ubuntu 22.04 LTS
月费	~80-200 元/月 (腾讯云轻量 CN-1) / €5-15 (Hetzner)

部署步骤

bash

# 1. SSH 到云 VM, 装基础环境
ssh boss@&lt;vm-ip&gt;
sudo apt update && sudo apt install -y python3-pip git nginx

# 2. clone vault
git clone https://github.com/zhanglunet/boss-vault.git ~/boss-vault
cd ~/boss-vault
pip install -r requirements.txt

# 3. 装 Hermes (always-on Agent runtime)
# 详见 Hermes 自己的 install 文档
# 简化: 它会读 .hermes/scheduler.yaml 里的 cron 调度

# 4. 配 systemd service
sudo cp templates/boss-hermes.service.example /etc/systemd/system/boss-hermes.service
sudo systemctl daemon-reload
sudo systemctl enable boss-hermes
sudo systemctl start boss-hermes

# 5. (可选) nginx + 飞书 webhook
sudo cp templates/nginx-boss-hermes.conf.example /etc/nginx/sites-available/boss-hermes
sudo ln -sfn /etc/nginx/sites-available/boss-hermes /etc/nginx/sites-enabled/
sudo nginx -t && sudo systemctl reload nginx

详见 docs/installation.md (CTO 完整部署指南)。

boss_server API 认证 (v0.6 起必配)

v0.6 起 scripts/boss_server.py 走 Bearer token 认证, fail-close:

必须设置环境变量 BOSS_API_TOKEN (生成: openssl rand -hex 32); 未设置时除 /v1/healthz 外所有 endpoint 返回 503 (拒绝服务而非裸奔)
客户端带 Authorization: Bearer <token> 头; 缺失/错误 → 401
/v1/healthz 永远豁免 (探活)

bash

# .env 加一行 (systemd EnvironmentFile 自动加载)
BOSS_API_TOKEN=<openssl rand -hex 32 的输出>

# 验证
curl -s localhost:8421/v1/healthz                       # 200, 无需 token
curl -s localhost:8421/v1/panels                        # 401
curl -s -H "Authorization: Bearer $BOSS_API_TOKEN" localhost:8421/v1/panels   # 200

token 用 op run --env-file=op.env 注入, 不要写进任何 git 文件。 nginx 反代零额外配置 (校验在应用层)。

飞书 webhook (D2 独有)

飞书 @ 机器人触发 /boss → Hermes 接收 webhook → 派发 Phase 0-5 → 完成后推送飞书卡片回群。需要:

飞书应用 (lark.feishu.cn) 配置 webhook URL → https://<vm-domain>/feishu/event
nginx 转发 → Hermes
.env 填 LARK_APP_ID / LARK_APP_SECRET

D3 · GitHub Actions (开源用户, 零 infra)

把 attribution-checker 跑在 GitHub Actions 上。适合:

没有本地 always-on 机器
没有云 VM 预算
公开使用 boss-vault, 数据非 confidential

workflow 示例

.github/workflows/attribution.yml (v0.3.0 待添加, 设计如下):

yaml

name: boss attribution checker

on:
  schedule:
    - cron: '0 9 * * *'        # UTC 09:00 每天 (CN 17:00)
  workflow_dispatch:           # 手动触发

jobs:
  attribution:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with: { python-version: '3.11' }
      - run: pip install -r requirements.txt
      - env:
          BOSS_LLM_PROVIDER: anthropic
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
          WEBSEARCH_API_KEY: ${{ secrets.WEBSEARCH_API_KEY }}
        run: python3 scripts/attribution_check.py --commit-results
      - name: Commit updated attribution
        run: |
          git config user.name "boss-attribution-bot"
          git config user.email "noreply@boss-vault"
          git add reports/ cases/ failure_cards/
          git diff --staged --quiet || git commit -m "chore: attribution checkpoint $(date -I)"
          git push

适用场景

attribution_check 不需要 confidential 数据 (用 metric URL + WebSearch)
公开 repo 的 GitHub Actions 是 unlimited free
私有 repo 也免费 2000 min/月

局限

GitHub Actions 调度精度: 至少 5 min 间隔, 高峰期有延迟
不能跑超过 6 小时单次 job
触发飞书 push 需要 webhook secret (用 secrets.LARK_*)

D4 · Cloudflare Containers (提案中 · ADR-010, 待双签)

⚠️ 状态: proposed — 本节是 ADR-010 的评估结论摘要, 双签通过前不提供部署脚本。静态层 (www/ + /handbook/) 已在 Cloudflare Pages, 与本节无关。

把 boss_server 容器跑在 Cloudflare Containers 上, 作为 D2 (腾讯云 VM) 的替代:

维度	结论
可行性	✅ 现有 Dockerfile 即用 (docker-build CI 已验证); wrangler 配 instance type + `BOSS_API_TOKEN` secret
成本	scale-to-zero, 按活跃 10ms 计费 (含在 Workers Paid $5/月); 低频调用显著低于常开 VM
约束	容器 ephemeral: 启动时 git clone vault 快照 (有滞后); `POST /v1/attribution/check` 写盘随实例回收丢失 → D4 下该 endpoint 默认 dry-run
不适用	完整判断流水线 / Hermes always-on — 145MB raw 不在 git, 判断产物需 push-back, 常开与 scale-to-zero 相悖 → 维持 D2 VM
Workers (非 Containers)	❌ boss_server 依赖 subprocess + vault 文件系统, Python Workers (Pyodide) 不支持

分层原则 (ADR-010 §6): 静态层吃尽 CF 红利 (已做) · API 层可选迁移 (本提案) · 数据与流水线层留有持久盘的地方。

跨形态可移植性

anchors/<slug>/ + panels/*.yaml + cases/<case-id>/ + reports/<brand>/ 在三种形态下结构完全一致, 可任意迁移:

bash

# D1 ↔ D2 迁移 (例)
# 在 D1 (本地 Mac) 跑了几个判断 → 想换到 D2 (云 VM)
rsync -av ~/boss-vault/{cases,reports,anchors}/  boss@vm:~/boss-vault/

# 反向 (从 D2 拉回本地)
rsync -av boss@vm:~/boss-vault/{cases,reports,anchors}/  ~/boss-vault/

versions/v{n}_*.md 永久不可变, 跨形态读出来内容 identical。

安全 / 脱敏 (跨三种形态相同)

所有 deployment 形态前 → 都过 scripts/redact_check.py fail-close 出站闸 (CLAUDE.md §9)
D3 (GitHub Actions) 提交回 repo 前自动 redact_check, fail → 阻断 commit
D2 (Hermes) 推飞书卡片前 redact_check, fail → 写 failure_cards/blocked-publish.log
D1 (Local) pre-commit hook 自动 redact_check

confidential 数据 (anchors/<slug>/raw/, cases/, reports/) 默认 gitignored, 三种形态下都不入 git。

你的场景	推荐起步	何时升级
个人首次试用	D1	痛点出现再升
内部团队 V0 期	D1	锚点要求飞书 push 时升 D2
开源外部使用	D1 (+ D3 自动 attribution)	永远不必升 D2
多个锚点 (multi-anchor)	D1	anchors/<slug>/ 数据多到本地 SSD 紧张时升 D2

部署指南 · 三种形态

部署形态对比

D1 · Local Agent CLI (推荐 default)

安装

使用

30/90/365 attribution (本地 launchd, macOS)

Linux 替代 (crontab)

D2 · Self-host Hermes (云 VM, 内部团队)

适用信号 (来自 ADR-003 §2.3)

推荐云配置

部署步骤

boss_server API 认证 (v0.6 起必配)

飞书 webhook (D2 独有)

D3 · GitHub Actions (开源用户, 零 infra)

workflow 示例

适用场景

局限

D4 · Cloudflare Containers (提案中 · ADR-010, 待双签)

跨形态可移植性

安全 / 脱敏 (跨三种形态相同)

推荐路径

相关文档

部署指南 · 三种形态 ​

部署形态对比 ​

D1 · Local Agent CLI (推荐 default) ​

安装 ​

使用 ​

30/90/365 attribution (本地 launchd, macOS) ​

Linux 替代 (crontab) ​

D2 · Self-host Hermes (云 VM, 内部团队) ​

适用信号 (来自 ADR-003 §2.3) ​

推荐云配置 ​

部署步骤 ​

boss_server API 认证 (v0.6 起必配) ​

飞书 webhook (D2 独有) ​

D3 · GitHub Actions (开源用户, 零 infra) ​

workflow 示例 ​

适用场景 ​

局限 ​

D4 · Cloudflare Containers (提案中 · ADR-010, 待双签) ​

跨形态可移植性 ​

安全 / 脱敏 (跨三种形态相同) ​

推荐路径 ​

相关文档 ​

部署指南 · 三种形态

部署形态对比

D1 · Local Agent CLI (推荐 default)

安装

使用

30/90/365 attribution (本地 launchd, macOS)

Linux 替代 (crontab)

D2 · Self-host Hermes (云 VM, 内部团队)

适用信号 (来自 ADR-003 §2.3)

推荐云配置

部署步骤

boss_server API 认证 (v0.6 起必配)

飞书 webhook (D2 独有)

D3 · GitHub Actions (开源用户, 零 infra)

workflow 示例

适用场景

局限

D4 · Cloudflare Containers (提案中 · ADR-010, 待双签)

跨形态可移植性

安全 / 脱敏 (跨三种形态相同)

推荐路径

相关文档