# 完整安装手册 (installation.md)

> **本文档定位**: 给 CTO / SuperIntern 用,从零部署到生产可用的全流程。
>
> 与 `dev-quickstart.md` 区别:dev-quickstart 是"30 分钟本地跑起来";
> 本文档是"完整 prod 部署 + 监控 + 灰度上线"。
>
> 预估时间: 4-6 小时(首次) / 30 分钟(单机器重装)。
>
> **v3.1.1 (2026-05-27) 状态**:
> - ✅ V0 5 case 收官 (T11+T19+C3+C4+C5 panel 切换 5 类完整 · 6 维评委 5 案累计)
> - ✅ `/boss <议题>` 用户面 slash command (本地最小化 install: `bash scripts/install_tian_skill.sh`)
> - ✅ V0 7 项验收 6/7 预判达标
>
> **快速最小化 install (Claude Code 用户)**:
> ```bash
> git clone https://github.com/zhanglunet/boss-vault.git
> cd boss-vault
> bash scripts/install_tian_skill.sh          # symlink → ~/.claude/skills/boss/
> # 新 Claude Code session 输入 /boss list 即可
> ```
>
> 完整生产部署 (含 Hermes / 云 VM / laotian-adapter) 见以下章节.

---

> **🆕 v2.7 (2026-05-26) 部署形态修订**: PRD v3.1-r2 把"prod-01"从"本地 macOS / Linux 单机"
> 反向为**云端单租户 VM** (推荐: 腾讯云轻量 / 阿里云 ECS / Hetzner CX22 量级 ~80-200 元/月)。
> 本文档第 0 节架构图描述的 prod-01 等价于"云端单租户 VM",物理位置改云后流程不变。
>
> **本地 Mac 仅做开发 + git push, prod 跑云。**
>
> 新增同步链路 (v2.7):
> - laotian 原始备份仍跑本地 Mac (lark-cli 需 Mac 飞书 SSO),过滤后产物经
>   [`scripts/cloud_sync.sh`](../scripts/cloud_sync.sh) rsync 推到云 VM
> - 云 VM 上 cron 跑 [`scripts/git_sync_cron.sh`](../scripts/git_sync_cron.sh) 每 5 分钟
>   `git pull --ff-only` (T24 A 方案), skills/panels/schemas/config 变化触发 Hermes reload
> - 敏感配置 (filter_rules.yaml / .env) 经 1Password CLI + rsync 单独推, 不经 git
>   (`cloud_sync.sh --sensitive` 模式)
>
> 详见 [`prd-v3.1.md §4.1`](../docs/internal/prd-v3.1.md) (含"为什么不本地单机"解释段) 与
> [`prd-v3.1-design.html` Fig 01](../docs/internal/prd-v3.1-design.html)。

---

## 0. 部署架构总图

```
                        ┌──────────────────────────────┐
                        │  内网 (公司 VPN)             │
                        │                              │
   外部用户             │    ┌──────────────────────┐  │
   (锚点/项目主理)         │    │ prod-01 服务器       │  │
        │               │    │  Ubuntu 24 / 8C32G   │  │
        │ 飞书          │    │                      │  │
        ▼               │    │ ~/boss-vault/     │  │
   ┌────────┐           │    │ ~/.hermes/           │  │
   │ 飞书 API│ ─ webhook │    │ ~/laotian/           │  │
   └────────┘           │    │                      │  │
        │               │    │ systemd services:    │  │
        ▼               │    │ - hermes-agent       │  │
   ┌────────────┐       │    │ - sage-wiki-watch    │  │
   │ 飞书机器人 │ ─ HTTPS┼─── │ - hermes-scheduler   │  │
   │ webhook    │       │    │                      │  │
   └────────────┘       │    └──────────────────────┘  │
                        │              │               │
                        │     ┌────────┴────────┐      │
                        │     ▼                 ▼      │
                        │ 内部 GitLab        1Password │
                        │ (代码/PR)          (密钥)    │
                        └──────────────────────────────┘
                                       │
                                       │ outbound HTTPS
                                       ▼
                              Anthropic / 飞书 OpenAPI / marsdata
```

---

## 1. 前置准备 (1 小时)

### 1.1 硬件 / OS

| 项 | 要求 | 备注 |
|---|---|---|
| CPU | ≥ 4 核 (推荐 8 核) | V0 期 4 核够;500 docs 回填时 8 核更快 |
| RAM | ≥ 16 GB (推荐 32 GB) | sage-wiki 编译峰值 ~8 GB |
| 磁盘 | ≥ 200 GB SSD | 含飞书全量备份(zhanglu 飞书 5-50 GB) |
| OS | Ubuntu 24 LTS 或 22 LTS | macOS 仅适合开发, 不作生产 |
| 网络 | 公司内网 + 外网出口(HTTPS) | 需能访问 anthropic.com / open.feishu.cn / marsdata.ai |

### 1.2 账号 / 凭证 (CTO 提前准备)

| 账号 | 用途 | 谁拿 |
|---|---|---|
| 公司 GitLab 账号 + SSH key | 拉 vault repo | SuperIntern |
| 1Password 企业账号 | 密钥管理 | CTO + SuperIntern |
| Anthropic API key | Claude 调用 | CTO 申请,塞 1Password |
| 飞书企业自建 App | 机器人 + lark-cli | CTO 在飞书后台建 |
| marsdata.ai 订阅 key | attribution 验证数据 | CTO 申请 |
| 飞书账号(锚点授权) | laotian 用 user 身份抓 | zhanglu 操作 |

### 1.3 飞书 App scope 配置(飞书后台预先做)

进入飞书企业后台 → 应用开发 → 你的"boss 判断"App:

```
权限 (scope):
  通讯 / 联系人:
    contact:user.id:readonly        - 解析 @mentions
    contact:user.base:readonly      - 获取用户基本信息
  
  消息:
    im:message                       - 发卡片
    im:message:send_as_bot          - 机器人身份发送
    im:resource                      - 解析消息内文件
  
  文档(lark-cli 用):
    docs:document:readonly           - 读文档
    drive:file:download              - 下载附件
    minutes:minutes:readonly         - 妙记
    vc:note:read                     - 会议纪要
    wiki:node:read                   - 知识库
    sheets:spreadsheet:read          - 表格

事件订阅 (回调):
  Webhook URL: https://${HERMES_WEBHOOK_HOST}/feishu/webhook
  订阅事件:
    im.message.receive_v1              用户 @ 机器人
    application.bot.menu_v6            菜单点击
    card.action.trigger                卡片按钮(打分用)
```

---

## 2. 服务器准备 (30 min)

### 2.1 创建系统用户

```bash
# 在 prod-01 机器上, 以 root 登录
sudo adduser boss
sudo usermod -aG sudo boss
sudo su - boss

# 之后所有操作以 boss 身份做
```

### 2.2 安装系统依赖

```bash
sudo apt update
sudo apt install -y \
    python3.11 python3-pip python3-venv \
    git curl jq tree \
    ripgrep \
    fonts-noto-cjk \
    ca-certificates \
    pkg-config

# 验证
python3 --version    # ≥ 3.11
git --version
jq --version
rg --version
```

### 2.3 时区与 locale

```bash
sudo timedatectl set-timezone Asia/Shanghai
sudo locale-gen zh_CN.UTF-8
```

---

## 3. 拉代码 + 一键装 (15 min)

### 3.1 拉 vault repo

```bash
cd ~
git clone git@${GITLAB_HOST}:judgement/boss-vault.git
cd boss-vault
git log --oneline -3                    # 确认拿到 v0-prep tag
```

### 3.2 跑 install.sh(生产模式)

```bash
bash scripts/install.sh
```

脚本会自动:
1. ✅ 检查 OS / Python 版本
2. ✅ 装 Python 依赖 (`pip install -r requirements.txt`)
3. ✅ 创建必要目录(`_wiki/` `cases/` `reports/` `backups/feishu/` 等)
4. ✅ 链接 git pre-commit hook
5. ✅ 跑 smoke test
6. ⚠️ 提示装 Hermes Agent(下一节)
7. ⚠️ 提示装 sage-wiki(下一节)
8. ⚠️ 提示配 1Password(下一节)
9. ⚠️ 提示配 systemd(下一节)

如某步报错,看 `docs/troubleshooting.md`。

---

## 4. Hermes Agent 部署 (20 min)

### 4.1 安装

```bash
curl -sSL https://hermes-agent.io/install.sh | bash

# 验证
hermes --version
which hermes                            # /usr/local/bin/hermes
```

### 4.2 初始化

```bash
hermes init --workdir ~/.hermes

# 链接 vault 的 skills/ 和 .mcp.json
ln -sfn ~/boss-vault/skills ~/.hermes/skills
ln -sfn ~/boss-vault/.mcp.json ~/.hermes/.mcp.json
ln -sfn ~/boss-vault/.hermes/scheduler.yaml ~/.hermes/scheduler.yaml
```

### 4.3 验证 Skills 被识别

```bash
hermes skills list

# 应输出 11 个 Skill:
# - tian-judgement-orchestrator
# - tian-perspective
# - industry-trend-perspective
# - strategic-vision-perspective
# - customer-strategy-perspective
# - product-strategy-perspective
# - org-strategy-perspective
# - financial-strategy-perspective
# - meta/attribution-checker
# - meta/failure-card-classifier
# - laotian-adapter
```

---

## 5. sage-wiki 部署 (15 min)

### 5.1 安装

```bash
# 从内部 mirror 下载 (CTO 提供 ${INTERNAL_MIRROR_HOST})
curl -sSL https://${INTERNAL_MIRROR_HOST}/sage-wiki/v0.4-linux-amd64 -o /tmp/sage-wiki
sudo install /tmp/sage-wiki /usr/local/bin/sage-wiki
sage-wiki --version
```

### 5.2 首次编译

```bash
cd ~/boss-vault
sage-wiki recompile --all

# 预期: 当前 vault 是空的, 仅会编译 SKILL.md 等代码注释, 1-2 分钟完成
sage-wiki doctor
```

---

## 6. 1Password 密钥配置 (15 min)

### 6.1 装 op CLI

```bash
curl -sSL https://app-updates.agilebits.com/cli/v2/op_install.sh | bash
op --version
op signin
```

### 6.2 创建 vault + 添加 4 个密钥

```bash
op vault create boss-vault-prod

# 然后在 1Password GUI(或 op item create)添加 4 个 item:
```

| Item 名 | 字段 | 值来源 |
|---|---|---|
| `anthropic` | `credential` | console.anthropic.com 生成 |
| `lark` | `app_id`, `app_secret` | 飞书 App 后台 → 凭证与基础信息 |
| `marsdata` | `credential` | marsdata.ai 后台 → API key |
| `gitlab-ci` | `token` | GitLab → Settings → CI/CD 生成 read_repository token |

### 6.3 创建 op.env (生产用)

```bash
cat > ~/boss-vault/op.env <<'EOF'
ANTHROPIC_API_KEY=op://boss-vault-prod/anthropic/credential
LARK_APP_ID=op://boss-vault-prod/lark/app_id
LARK_APP_SECRET=op://boss-vault-prod/lark/app_secret
MARSDATA_API_KEY=op://boss-vault-prod/marsdata/credential

# 内部基础设施 host
GITLAB_HOST=gitlab.your-company.internal
HERMES_WEBHOOK_HOST=hermes.your-company.internal
INTERNAL_MIRROR_HOST=mirror.your-company.internal

# 路径
BOSS_VAULT_ROOT=/home/boss/boss-vault
LAOTIAN_ROOT=/home/boss/laotian
HERMES_WORKDIR=/home/boss/.hermes

TZ=Asia/Shanghai
ZHIFANG_VERSION=v0.1
ZHIFANG_ENV=production
EOF

chmod 600 ~/boss-vault/op.env       # 严格权限
```

### 6.4 验证

```bash
op run --env-file=$HOME/boss-vault/op.env -- env | grep -E "ANTHROPIC|LARK" | sed 's/=.*$/=<masked>/'

# 应输出 (值被 mask):
# ANTHROPIC_API_KEY=<masked>
# LARK_APP_ID=<masked>
# LARK_APP_SECRET=<masked>
```

---

## 7. laotian 部署 (zhanglu 操作, 30 min)

### 7.1 拉 laotian repo

```bash
cd ~
git clone https://github.com/zhanglunet/laotian.git
cd laotian
```

### 7.2 装 lark-cli

```bash
# macOS
brew install lark-cli

# 或从二进制装(Linux):
curl -sSL https://lark-cli.example.com/install | bash
lark-cli --version
```

### 7.3 OAuth 登录 (用户身份)

```bash
lark-cli auth login

# 浏览器跳转 → 飞书授权 → 完成
# 验证:
lark-cli auth status
# 应显示 identity: user (不是 tenant)

lark-cli auth check --scope "docs:document:readonly drive:file:download minutes:minutes:readonly vc:note:read wiki:node:read sheets:spreadsheet:read"
```

### 7.4 软链 backups 到 vault

```bash
# vault 一侧的 backups/feishu/ 应链接到 laotian 输出位置
mkdir -p ~/laotian/backups
ln -sfn ~/laotian/backups/feishu ~/boss-vault/backups/feishu

ls -la ~/boss-vault/backups/
# 应显示 feishu -> /home/boss/laotian/backups/feishu
```

### 7.5 试抓 1 篇 (W2 D1 验证, 不是 install 步骤)

```bash
cd ~/laotian
python3 tools/feishu_backup/backup.py auth-check       # 应 PASS

# 用 zhanglu 自己飞书的某个 docx URL 试拉
python3 tools/feishu_backup/backup.py backup-url "https://your-feishu.cn/docx/xxx"

# 验证落盘
ls -la ~/boss-vault/backups/feishu/docs/
```

---

## 8. systemd 服务 (20 min)

### 8.1 创建 3 个 systemd unit

```bash
# 8.1.1 Hermes Agent
sudo tee /etc/systemd/system/hermes-agent.service > /dev/null <<'UNIT'
[Unit]
Description=本项目 Hermes Agent
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=boss
WorkingDirectory=/home/boss/boss-vault
ExecStart=/usr/bin/op run --env-file=/home/boss/boss-vault/op.env -- /usr/local/bin/hermes start
Restart=on-failure
RestartSec=10
StandardOutput=journal
StandardError=journal

[Install]
WantedBy=multi-user.target
UNIT

# 8.1.2 sage-wiki watch
sudo tee /etc/systemd/system/sage-wiki-watch.service > /dev/null <<'UNIT'
[Unit]
Description=本项目 sage-wiki watch
After=network.target

[Service]
Type=simple
User=boss
WorkingDirectory=/home/boss/boss-vault
ExecStart=/usr/local/bin/sage-wiki watch --project /home/boss/boss-vault
Restart=on-failure
RestartSec=10

[Install]
WantedBy=multi-user.target
UNIT

# 8.1.3 Hermes scheduler
sudo tee /etc/systemd/system/hermes-scheduler.service > /dev/null <<'UNIT'
[Unit]
Description=本项目 Hermes Scheduler (cron jobs)
After=hermes-agent.service
Requires=hermes-agent.service

[Service]
Type=simple
User=boss
WorkingDirectory=/home/boss/boss-vault
ExecStart=/usr/bin/op run --env-file=/home/boss/boss-vault/op.env -- /usr/local/bin/hermes scheduler --config /home/boss/.hermes/scheduler.yaml
Restart=on-failure
RestartSec=30

[Install]
WantedBy=multi-user.target
UNIT
```

### 8.2 启动 + 启用开机自启

```bash
sudo systemctl daemon-reload

sudo systemctl enable --now hermes-agent
sudo systemctl enable --now sage-wiki-watch
sudo systemctl enable --now hermes-scheduler

# 验证
sudo systemctl status hermes-agent sage-wiki-watch hermes-scheduler
# 3 个都应该 active (running)
```

### 8.3 journal 日志查看

```bash
# 实时
journalctl -u hermes-agent -f
journalctl -u sage-wiki-watch -f

# 历史
journalctl -u hermes-agent --since "1 hour ago"
```

---

## 9. 飞书 webhook 反向代理 (15 min)

飞书 OpenAPI 要求 webhook 是 HTTPS,公网可访问。**生产部署**有两种方式:

### 方式 A · 公司域名 + 反向代理(推荐)

```bash
# 假设公司有 nginx, 加这个 server block:
sudo tee /etc/nginx/sites-available/boss-hermes <<'NGINX'
server {
    listen 443 ssl http2;
    server_name hermes.your-company.com;        # ← 已在 DNS 配置
    
    ssl_certificate /etc/letsencrypt/live/hermes.your-company.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/hermes.your-company.com/privkey.pem;
    
    location /feishu/webhook {
        proxy_pass http://127.0.0.1:8080/feishu/webhook;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
    
    location / {
        return 403;        # 其他路径拒绝
    }
}
NGINX

sudo ln -sfn /etc/nginx/sites-available/boss-hermes /etc/nginx/sites-enabled/
sudo nginx -t && sudo systemctl reload nginx
```

### 方式 B · ngrok / Cloudflare Tunnel(开发期 / 测试用)

```bash
# 临时方案:
brew install ngrok    # 或 cloudflared

# 启动隧道指向 Hermes 内部端口
ngrok http 8080

# 把 ngrok 给的 URL 填进飞书 App webhook 配置
# (但要注意: ngrok 免费版 URL 每次重启会变)
```

### 9.3 验证 webhook 可达

```bash
# 从 prod-01 之外的网络 curl:
curl -X POST https://hermes.your-company.com/feishu/webhook \
    -H "Content-Type: application/json" \
    -d '{"type":"url_verification","challenge":"test123"}'

# 应返回: {"challenge":"test123"}
```

---

## 10. 灰度上线 (按 v3.1 实施手册 §4.6)

### 阶段 1 · alpha 内部 (W1)
- 仅 项目主理 + SuperIntern + CTO 用
- 仅 CLI 触发, 不开飞书入口
- 验证 Phase 0-5 跑通

### 阶段 2 · beta 锚点 (W3-W4)
- 飞书入口开放给锚点
- 走 Gate 1-3 验收

### 阶段 3 · V0.1 投委试用 (V0+30d ~ +60d)
- 飞书机器人对投委开放只读
- 投委可发"本周判断", 不可起新议题

### 阶段 4 · V0.2 项目全员 (+60d ~ +90d)
- 核心团队 5 人可起议题
- 月活目标 ≥ 5 人

### 阶段 5 · V1.0 生产 (+90d 起)
- 所有相关方
- SLA: 月度可用性 ≥ 99%, 平均判断时长 < 30 分钟

---

## 11. 监控配置

### 11.1 关键指标(Hermes 自动采集)

| 类型 | 指标 | 阈值 | 渠道 |
|---|---|---|---|
| 系统 | hermes-agent 进程 | down ≥ 5min | PagerDuty |
| 系统 | sage-wiki ingest 错误率 | > 5% | 飞书 group |
| 系统 | Anthropic API 错误率 | > 10% | 飞书 group |
| 系统 | 磁盘使用 | > 80% | 飞书 group |
| 业务 | 今日判断数 | 工作日 < 1 | 项目主理 飞书 |
| 业务 | attribution 30d 命中率 | 周环比降 > 20% | 项目主理 飞书 |
| 安全 | redact_check 阻断 | 日 > 0 | CTO + 项目主理 |
| 安全 | 1P 密钥即将过期 | < 14 天 | CTO 飞书 |
| 安全 | laotian quarantine | > 5 份 | 项目主理 + zhanglu |

### 11.2 健康检查脚本(每日 09:00 cron 跑)

scheduler.yaml 中已配 `attribution-checker` job, 自动跑。

要看实时健康:
```bash
# 一键看所有状态
make smoke && make filter-status && hermes status && sage-wiki doctor
```

---

## 12. 备份策略

### 12.1 备份层级

| 层 | 内容 | 频率 | 保留 | 位置 |
|---|---|---|---|---|
| 热备 | `git push` | 每次 commit | 永久 | 内部 GitLab |
| 温备 | `_wiki/` + `raw/` + `cases/` + `reports/` rsync | 每天 03:00 | 30 天 | 公司备份机 |
| 冷备 | 整个 vault tarball + 加密 | 每周日 04:00 | 180 天 | 离线存储 |
| 密钥 | 1Password 自动备份 | 实时 | 永久 | 1Password Cloud |

### 12.2 rsync 备份脚本(运维加 cron)

```bash
# /etc/cron.d/boss-backup
0 3 * * * boss /usr/bin/rsync -avz --delete \
    --exclude='.git' --exclude='__pycache__' --exclude='_wiki/.sage-state' \
    /home/boss/boss-vault/ \
    backup-server:/backup/boss/$(date +\%Y\%m\%d)/
```

### 12.3 灾备 RTO/RPO

| 场景 | RTO | RPO |
|---|---|---|
| prod-01 硬盘坏 | ≤ 4h | ≤ 24h |
| GitLab 内部宕机 | ≤ 2h | 0(本地 git 即副本) |
| 1Password 不可用 | ≤ 8h | 0(本地缓存 + 密钥轮换) |

---

## 13. 故障排查与回滚

### 13.1 常见故障

详见 `docs/troubleshooting.md` (10 类症状, 32 个故障 + 修复)。

### 13.2 回滚 SOP(发现新版本有问题)

```bash
# 1. 评估当前状态
git tag -l | tail -5
git log --oneline --since="3 days ago"

# 2. 群通知用户
# 飞书: "因 X 问题, 系统回滚到 v0.1.2, 预计恢复 30 分钟"

# 3. 备份当前状态后再回滚
git tag rollback-$(date +%Y%m%d-%H%M%S)-from-broken
git push origin --tags

# 4. 回滚
git checkout v0.1.2
git reset --hard v0.1.2

# 5. 重启服务
sudo systemctl restart hermes-agent sage-wiki-watch hermes-scheduler

# 6. 验证
make smoke
hermes status

# 7. 在 _wiki/log.md 追加 (在 vault 不被覆盖的话)
echo "## [$(date +%F)] rollback | to v0.1.2 due to ..." >> _wiki/log.md
```

---

## 14. 安全合规

### 14.1 push 前必跑

```bash
make pre-public-push
```

详见 `docs/security-and-deidentification.md`。

### 14.2 月度安全审计

```bash
# 项目主理 每月 15 号
make monthly-review-current
make pre-public-push        # 复用做月度扫描
op item list --vault boss-vault-prod    # 检查密钥过期
```

---

## 15. 安装就绪 checklist

部署完毕后,CTO 跑完这个,标记为可上线:

- [ ] `make smoke` 全 PASS
- [ ] `make pre-public-push` 6 项全 PASS
- [ ] `hermes status` = active
- [ ] `systemctl status hermes-agent sage-wiki-watch hermes-scheduler` 都 active (running)
- [ ] `sage-wiki doctor` 无 error
- [ ] `lark-cli auth status` = active
- [ ] `op vault list` 含 boss-vault-prod
- [ ] 飞书 webhook curl 测通 (§9.3)
- [ ] 飞书 @本项目 发"help"有响应
- [ ] `tests/` 跑 pytest 全 PASS
- [ ] git pre-commit hook 链接生效 (故意 commit 含真名 fixture 应被阻断)
- [ ] `~/boss-vault/op.env` 权限 = 600
- [ ] backups/feishu 软链到 ~/laotian/backups/feishu
- [ ] `config/laotian_filter_rules.yaml` 填好锚点 user_id 且 .gitignore 排除
- [ ] 备份脚本已配 cron
- [ ] 飞书机器人加锚点 + 项目主理 + CTO + SuperIntern 为好友

15 项全 ✅ 后,**git tag v0.1 + push**, V0 期生产正式开始。

---

> 本文档与 `dev-quickstart.md`(开发引导) / `user-manual.md`(用户使用) /
> `troubleshooting.md`(故障排查) / `security-and-deidentification.md`(安全 SOP) 互补。
> 修订需 CTO 双人 review。