Files
2026-11-16 17:26:44 -08:00

292 lines
21 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
---
name: streamline-deploy
description: "把 Streamline 部署到生产:拉代码、构建前端、重启控制面、验证生效,重建卫星 bundle,并自动推到 3 台卫星节点(忙节点走空档部署,不打断任务)。Use when the user asks 部署 / 上线 / deploy / 发布一下 / 把改动发到生产 / restart streamline / 重启服务, or after merging a change that needs to go live. Also use when the satellite bundle / 卫星热部署面板 shows an older SHA than HEAD (--satellite-only)."
---
# 部署 Streamline
一条命令,从 devbox 一路到卫星节点:
```bash
bash .claude/skills/streamline-deploy/deploy.sh # 控制面 + 重建 bundle + 推 3 台卫星
bash .claude/skills/streamline-deploy/deploy.sh --check # 只做预检,不写任何东西
bash .claude/skills/streamline-deploy/deploy.sh --satellite-only # 只重建 bundle 并推送,不碰控制面
bash .claude/skills/streamline-deploy/deploy.sh --skip-satellite # 只发控制面,bundle 和节点都不动
bash .claude/skills/streamline-deploy/deploy.sh --no-push # 重建 bundle 但不推节点(留给人点)
bash .claude/skills/streamline-deploy/deploy.sh --force-push # 立即换装,会中断节点上正在跑的任务
```
默认那条走完**三个产物**:控制面(pull → install → build → restart → verify)、
`satellite/dist/satellite.js`(卫星 bundle)、以及把 bundle 推到各执行节点。
推送对**忙节点默认用「空档部署」**——不打断任何在跑的任务,见下面「卫星」。
## 先确认,再执行
**部署是生产写操作。** 按 CLAUDE.md 的规矩,除非用户这一轮明确要求部署/上线,否则不要自己跑——"顺手帮你发一下"不算授权。用户说了就直接做,不用二次确认。
不确定要不要部署时,先跑 `--check`:它只读,会把 HEAD、分支、工作区是否干净都报出来。
## 目标环境
| | |
|---|---|
| host | `fdbd:dc01:ff:31a:6973:d9b4:988a:23c0`(IPv6,公司内网) |
| 仓库 | `/data00/home/jiaopengwen/streamline` |
| 服务 | `streamline-server.service`(`User=jiaopengwen`) |
| 端口 | `:5173` — API + WS + **前端静态资源**,同一个进程 |
| 对外 | 前端 `https://streamline.bytedance.net`:Caddy `file_server` **直接读 `control-web/dist`**,不经过 :5173;API `https://streamline-internal-api.bytedance.net`:Caddy → :5173(只放 `/api`、`/ws`)。配置在 devbox `/etc/caddy/Caddyfile`,前端的缓存头 / `/assets` 404 规则要和 `control-server/src/index.ts` 保持一致 |
覆盖用环境变量:`STREAMLINE_DEPLOY_HOST` / `_USER` / `_OWNER` / `_REPO` / `_UNIT` / `_BUN_BIN` / `_BRANCH` / `_PRINCIPAL`(默认 `<_USER>@BYTEDANCE.COM`)/ `_ENV_FILE`(默认仓库根 `.env`)。
## 七个反直觉的点(都是踩过的)
手写这套命令基本一定会错在这几处,脚本已经处理,但改脚本前先读:
1. **路径不是 `~/…`。** 是 `/data00/home/jiaopengwen/streamline`。写 `~/home/jiaopengwen/streamline` 会展开成 `/home/<你>/home/jiaopengwen/streamline`,不存在。
2. **必须以 `jiaopengwen` 身份跑,不能用自己的账号。** 仓库属于 `jiaopengwen`,你是别人 → git 直接拒绝:`fatal: detected dubious ownership`。
**不要**用 `git config --global --add safe.directory` 绕过——那样 `git pull` 和 `bun run build` 会以你的身份写文件,`dist/` 和 `.git/` 里混进你拥有的文件,之后以 `jiaopengwen` 运行的服务就管不动它们了。正确做法是 `sudo -n -u jiaopengwen`(该机已配免密 sudo)。
3. **`bun` 不在 `jiaopengwen` 的非交互 PATH 里。** 只有 `npm`/`git` 能找到。bun 在 `/home/jiaopengwen/.bun/bin/bun`,必须显式加进 PATH(systemd unit 里也是这么硬写的)。`bun run build` 内部会 shell out 到 `bun`,所以 `npm run build` 也救不了。
4. **没有 `streamline-web` 这个服务,也不需要。** 系统里只有 `streamline-server` 一个 unit。前端**不是**独立进程:`control-server/src/index.ts:45` 解析 `WEB_DIST` 并由 control-server 自己把 `control-web/dist` 静态托管在 :5173(但对外前端域名由 Caddy 直接读 dist,不走这里,见上表;`:8080` 上没有任何监听,README 里"Vite 常驻"那段对这台机器已经过时)。
→ `bun run build` + 重启 `streamline-server` 就是完整部署。`systemctl restart streamline-web` 会直接报 unit 不存在。
5. **SSH 要 `-6` + 裸 IPv6,不能加方括号。** `ssh jingyuan.yi@[fdbd:…]` 会把整串当 hostname 解析失败;`ssh -6 jingyuan.yi@fdbd:…` 才对。
6. **devbox 只认 Kerberos,ticket 每天过期。** sshd 只开 `gssapi-keyex` / `gssapi-with-mic`,不收公钥;
ticket 约 10 小时,隔夜必失效,症状是 `Permission denied (gssapi-…)`,长得像公钥 / 网络问题。
预检第一步因此先 `klist -s`:没有有效 ticket 就从本机仓库根 `.env` 读 `KINIT_PASSWORD`,
经 stdin 喂给 `kinit --password-file=STDIN`(不进 argv、不落临时文件、不回显;只用 sed 取这一行,
不 `source` 整个 `.env`)。没配这个键就停下并提示手动 `kinit`;kinit 失败多半是 SSO 密码轮换了、
`.env` 里的旧了。它只写本机凭据缓存,所以 `--check` 也会做。
**在 git worktree 里部署**(如 `~/orca/workspaces/streamline/*`):`.env` 被 gitignore、不跟着 worktree 走,
脚本找不到仓库根 `.env` 时会自动退到主检出(worktree 共用的 `.git` 所在仓库,如
`/Users/bytedance/Documents/streamline/.env`)读。要用别的文件就显式设 `STREAMLINE_DEPLOY_ENV_FILE`。
`git push` 到 code.byted.org 不受影响——「代码推得上去、部署连不上」正是 ticket 过期的组合。
7. **卫星 bundle 是另一个产物,`bun run build` 不产它。** 面板顶部那个 SHA 读的是
`satellite/dist/VERSION`,由 `bun run build:satellite` 写;控制面部署完全不碰它。
历史上这导致:控制面已经在新 commit 上,面板还提供几小时前的 bundle,而已经推过的
节点显示「最新」—— 一个**相对旧 bundle** 的最新。现在脚本每次部署都重建它,`--check`
也会把 `bundle SHA vs HEAD` 的漂移报出来。
## 顺序为什么是 pull → install → schema check → build → restart
### install:锁文件变了不等于生产依赖已经变了
`git pull` 只更新 `package.json` 和 `bun.lock`,不会刷新已经存在的 `node_modules`。
部署脚本因此在每次 pull 后运行 `bun install --frozen-lockfile`;锁文件未变化时 Bun 会快速
走完无操作路径,新增运行时依赖时则会在重启前补齐。安装失败会立即停止部署,此时旧进程
仍在运行,避免出现代码已经更新、服务也重启了,但首次执行新路径才报 module not found。
### schema check:谁部署,谁替所有人的未落库迁移买单
这个仓库**没有迁移执行器**——`deploy.sh` 从不碰 schema,迁移靠人手工跑
`scripts/apply-migration.ts`。于是有一个不写下来就一定会再犯的坑:你这次改动不需要
迁移,但 `git pull` 会把别人**已经合进 main、迁移却还没跑**的提交一起带上生产,
重启之后相关查询全线 500。
2026-08-22 就这么炸过:一次知识库改动的部署顺带把 `tasks.method_coverage` 的代码拉了
上去,那一列从没建过,`/api/tasks` 全线 500,面板打不开约四分钟。验证步骤拦住了,
但那时服务已经重启完——**拦得太晚**。
所以 `bun scripts/check-migrations.ts` 卡在 **pull 之后、restart 之前**:此刻新代码在
盘上、老进程还在跑,缺列只是一个可以从容处理的告警。它查表、索引、**以及列**
(真正炸掉的那次就是 `ADD COLUMN`,而原来的复核只看表和索引)。
红了怎么办:按它打印的两行提示,先预演再 `--commit` 跑那份迁移,然后重跑部署。
脚本**不会**替你执行 DDL——那是对生产的写操作,按 CLAUDE.md 归人决定。
故意不落库的对象(例如 `spec_delta_events`,设计已被 `run_conditions` 取代、全仓库无
引用)写在 `check-migrations.ts` 的 `ACKNOWLEDGED` 里,每条都要写明理由:一个天天变红
的检查等于没有检查,人会学会忽略它,然后连真的那次也一起忽略。
### build 为什么在 restart 之前
`vite build` 会先清空 `dist/`。所以构建失败时前端是**空的**。脚本把 build 放在 restart 之前并在失败时立刻退出——宁可服务还跑着旧代码(前端已经没了但 API 正常),也不要把服务重启到一棵半更新的树上。构建失败时按提示修好再重跑,别先重启。
预检还会在**工作区有未提交的 tracked 改动**时拒绝执行:那说明有人直接在生产上改过代码,`git pull` 要么失败要么把他的改动冲掉,得让人先处理。
## 验证(脚本自动做)
- 重启后**轮询到接口真的应答**才继续(`is-active` + `curl :5173/api/tasks`,最多 30 秒),
否则打 journal 最后 30 行。等的是「能服务」而不是「进程起来了」:unit 已经 active、
但还没绑上 :5173 的那个窗口里,紧接着的验证会撞上连接被拒。
这里以前是无条件 `sleep 6` —— 快的时候白等,慢的时候(机器忙 / DB 连接慢)不够,
于是把一次正常启动误判成失败,而假阴性会让人去动一个其实好好的服务。
- `curl :5173/` 里的 asset hash **必须**等于刚构建出来的那两个文件名——不等就说明在服务旧 index.html。
- `GET /api/tasks` → 200。
- 对外域名的 hash 与内部一致(不一致会警告,通常是 Caddy 缓存)。
### 为什么脚本里有一坨 ControlMaster 选项
到 devbox 的一次 SSH **冷握手实测 3.8 秒**,复用后 0.6 秒;而一次完整部署要发 ~30 次
远程命令。没有连接复用时,脚本 80% 的墙钟时间花在握手上而不是干活上——`--check`
(11 次调用)实测 44 秒,加上复用之后 6–10 秒。
所以 `CM_OPTS` 不是可有可无的调优,删掉它等于把部署时间乘以四。`ControlPath` 用 `%C`
(连接元组的哈希)而不是 `%h`:host 是 39 字符的 IPv6 字面量,macOS 的 unix socket
路径上限约 104 字节,把地址拼进路径正是它在别人机器上失效的方式。
一个好用的额外信号:**构建是可复现的**。本地 `bun run build` 和 devbox 上的 asset hash 应该一模一样。不一样就说明两边源码/依赖不同,值得先查清楚。
## 卫星:脚本构建 + 自动推送(忙节点走空档部署)
`shared/` 和 `satellite/` 会被**打进卫星的自包含构建**,卫星是**另外的机器**(`fei-android-01`、`fei-ios-01`、`fei-ios-02`;这台 devbox 上没有卫星,`:5180` 无监听)。
机制是控制面把 bundle 的字节 POST 给节点 `/sat/admin/deploy` → 节点校验 sha256 → 原子替换 →
进程退出 → `scripts/run-satellite.sh` 守护脚本用新代码重启 → 节点带新 VERSION 重新注册,
面板上变成「最新」。不需要 SSH 到卫星,也不需要在节点上放 git 凭据。
### bundle 装了什么,没装什么
热部署只替换 `satellite/dist/satellite.js`(和它旁边的 `VERSION`)。**进 bundle 的**除了
`shared/` + `satellite/`,还有三个 wrapper——`bin/record-evidence.ts`、`bin/conditions.ts`、
`bin/claude-pty.ts`——`satellite/src/entry.ts` 用子命令分发把它们折了进来,正是为了消灭
下面这类漂移。
**没进 bundle 的**只剩两个:`bin/claude-cursor.ts`(生产不跑 cursor 引擎)和
`scripts/run-satellite.sh`(守护循环本身,没法把自己装进自己)。
脚本对节点侧那一半是**减法推导**的(扫 `bin/` 再滤掉 `entry.ts` 折进 bundle 的那几个,
见 `deploy.sh` 的 `BUNDLED_BIN`),不是写死清单——这样往 `bin/` 里新加一个 wrapper 会
**默认触发告警**,而不是被静默漏掉;漏掉正是这一节存在的原因。
#### 为什么这一节存在(`claude-pty` 的教训)
`bin/claude-pty.ts` 是 pty 引擎,生产上**每一次执行**都从它拉起。它曾经只存在于
`<repo>/bin/`,由 `claude_launch.ts` 从**节点自己的检出**里解析——而热部署一次都不碰
那份检出。失败是静默的:节点上报的 `version` 只来自 `dist/VERSION`,对 `bin/` 的状态
一个字都不报,于是面板显示「最新」,而 agent 引擎可能落后好几周。
旧判据(只看 `shared/ satellite/`)会以两种方式漏掉它,**后一种更常见也更误导**:
- **区间里只有 `bin/` 改动** → `SAT_DIFF` 为空 → 打印「No satellite-side changes」。
可构造:`git diff --stat 313a802^..b55ea2a -- shared/ satellite/` 为空,而那两个提交
改的正是 `bin/claude-pty.ts`(104 行)。
- **区间里混着 `shared/`/`satellite/` 改动** → `SAT_DIFF` 非空 → 打印
「Satellite code CHANGED — **that is what the push above was for**」。这是**肯定式的错误保证**:
推送确实发生了,但它装不下 `bin/`。实测部署 `c863538..c80bbea`:`SAT_DIFF` = 105 个文件
(于是打印上面那句),而同区间里 `bin/claude-pty.ts` + `scripts/run-satellite.sh`
一共改了 131 行,**一行都没随 bundle 走**。
实测后果:2026-08-21 探过三台节点最近一次执行的会话日志,终态 `result` 帧里都没有
`reason` 字段(那是 `343f322` 加的)——三台的检出当时都落后于它。
所以 `NODE_FILES` 是**无条件**计算的——它必须在这两种情况下都触发。
`bin/claude-pty.ts` 已于 2026-08-21 折进 bundle(`CLAUDE_PTY_SUBCOMMAND`)。**这意味着
历史上积累的 pty 引擎漂移不需要人工补**:任何节点只要收到一次这之后构建的 bundle,
引擎就跟着一起换了。
#### 剩下那两个还得人工
⚠️ **告警是边沿触发的**:它报的是「**这一次**部署的区间里动了这些文件」。
忽略一次之后,后续区间不再碰这些文件的部署就什么都不打印,漂移的节点会一直漂着、
而且看起来是干净的。**安静的部署不等于节点已同步。**
要把它变成可持续观测的状态量,得让节点上报自己的检出版本(尚未做)。
同步节点检出仍是人工动作,**具体怎么做取决于这台节点是怎么装起来的**:
- 有 git 历史的检出:在各卫星进程自己的目录里 fast-forward 到 `${STREAMLINE_DEPLOY_BRANCH:-main}`
(一台机器可能跑多个卫星,检出也是多份)。`satellite/dist/` 和 `.env` 都在 `.gitignore` 里,
所以不会和热部署产物冲突。
- 用 `scripts/executor-snapshot.sh` 恢复出来的节点:它默认带 `--exclude=.git`(第 121 行),
**没有 `.git`,fast-forward 和 `git rev-parse` 都跑不了**,只能把文件拷进去。
不变量只有一个:**每个节点的这些文件必须处在本次部署的 SHA 上**。
`scripts/run-satellite.sh` 是守护循环本身,**必须杀掉重启守护进程**才生效;
`bin/claude-cursor.ts` 只在 `AGENT_MODE=cursor` 下才被读到,生产不跑它。
**推送以前是面板上的人工点击,现在脚本自己做**(`scripts/push-satellites.ts`)。
改变前提的是「空档部署」:以前唯一的推送方式会立刻让进程退出、打断在跑的任务,所以必须
有人看着哪台空闲;空档部署让节点先把 bundle 存下来、停止接新活、跑完当前任务再在空档里
换装——**没有任务会被打断,也就没有需要人来做的判断了**。所以:
| 节点状态 | 脚本的动作 |
|---|---|
| 空闲 | 立即换装重启 |
| 忙 | **空档部署**:存盘 + 停止接单,当前任务结束后自己换装重启 |
| 已是该版本 / 已排队该版本 | 跳过(版本比对,脚本可重复跑) |
| 离线 | 跳过并明确报出来(回来后**不会**自动补装,需重跑) |
| 忙且卫星太老不认 `x-bundle-mode` | 报错并说明选项,**绝不**擅自强制 |
只有 `--force-push` 会走 强制部署(立刻中断任务),它是显式 opt-in。
**推送范围默认只有 `#default` 池**——也就是 `fei-android-01` / `fei-ios-01` / `fei-ios-02`
这三台。fleet 里还挂着别的团队的池子(`#im-sg` 的 `messaging-sg`、`messaging-sg-ios`,
`#pns` 的 `pns-android-01`),它们按自己的节奏跑、落后好几十个 commit,被一次日常部署
顺手拉到 HEAD 是个比这次发布本身大得多的变更,没人要求过。真要全推:
`bun scripts/push-satellites.ts --all-clusters`(或 `--cluster <tag>`)。
脚本每次都会把「谁不在范围内」打出来,免得局部发布被读成全量。
脚本为什么走 HTTP 而不是调 `/api/deploy`:那条路由是 SSO + admin 门禁(浏览器凭据),
脚本没有;为了让脚本进去而放宽门禁,比多写这个文件糟得多。节点的 `pendingDeploy` 与
`supportsQueuedDeploy` 又只活在控制面**进程内存**里(心跳学来的,见 `cluster.ts`),所以
它从只读的 `GET /api/nodes` 读状态,再用 cluster secret 直接把字节推给节点。
**两个陷阱脚本已经处理**:
1. 控制面刚重启的那十几秒里,它还没从心跳重新学到各节点的 `supportsQueuedDeploy`,
此时推送会把每台忙节点都判成「不支持空档部署」。所以脚本会先等到每个节点都有一次
**重启之后**的心跳(默认最多 45 秒)再动手。
2. **bundle 的 VERSION 是 git SHA,不是内容哈希。** 只改了控制面/前端/脚本的部署,
产出的 bundle 与上一版**逐字节相同**、只是版本号变了——照直推,三台节点就会为了
一个字符串停止接单、排空队列、重启一轮,每次部署都来一遍。所以 `deploy.sh` 会比对
新旧 bundle 的 sha256,相同时给推送脚本传 `--equivalent-version <旧SHA>`,跑着那个
版本的节点直接跳过。**只跳过「字节相同」的那一版**:落后更多版本的节点照推不误。
单独用:
```bash
bun scripts/push-satellites.ts --dry-run # 打印计划,不动任何东西
bun scripts/push-satellites.ts --node fei-ios-01.shiro0.icu
```
(必须在控制面那台机器上跑:要 `.env` 里的 `CLUSTER_SECRET`、要能连到节点。)
面板 **管理 → 卫星热部署** 仍在,用于手动补推、取消排队、看状态。
### 空档部署是怎么实现的
(脚本默认就用它,这里是它凭什么可靠。)
空档部署的实现在 `satellite/src/pending_deploy.ts`:bundle 落盘成 `satellite.js.pending` +
`pending-deploy.json`(**持久化**,中途因别的原因重启也不会丢,新进程会在下一个空档补上),
两个 claim 循环(`evaluator.ts` / `runner.ts`)看到有排队就**不再领新活**——这个「排空闸门」是
它能收敛的关键,否则队列一满,节点上一个任务刚结束下一个就claim走了,永远没有空档。
换装前会**重新校验一次 sha256**(字节在盘上躺了一段时间,截断的 bundle 会让节点重启后起不来)。
排队中的节点在面板上显示「已排队」(不是「待更新」——它不需要你再做什么),可以「取消排队」
让它保持当前版本并立刻恢复接单。
**注意一个过渡期陷阱**:旧卫星不认 `x-bundle-mode` 头,收到就会立刻换装——正好是空档部署要避免的
后果。所以卫星在心跳里用 `queuedDeploy: true` 声明能力,控制面对**没声明**的节点拒绝排队,并提示
「等它空闲,或强制部署」。这意味着本功能自身上线时,还在跑旧 bundle 的节点只能用老办法推一次。
面板上「最新 / 待更新」比的是**节点 VERSION vs bundle VERSION**,不是 vs 控制面 HEAD。
所以 bundle 不重建时,所有节点都可能显示「最新」而其实都在跑旧代码——这就是第 6 点。
**本次部署改没改卫星侧**:脚本会算 `git diff --stat <bundle 的 SHA>..HEAD -- <进 bundle 的路径>`
并在结尾报出「Bundled satellite code CHANGED」。**注意它只涵盖进 bundle 的那部分**,
`bin/` 里没进 bundle 的文件另有一条 `NODE-CHECKOUT files changed` 告警,见上方
「但 bundle 不是全部」。现在这只是**信息**,不再是待办——推送已经做过了。典型场景是改了 prompt
(`shared/src/readable_prompt.ts`、`satellite/src/runner.ts`、`feature_runner.ts`)。
用 `--no-push` / 节点离线 / 节点排队中时的行为:控制面会正常发新字段,**老卫星忽略未知字段**,
退化成改动前的行为——不会崩,但新能力不生效。**排队中的节点也属于这一档**:它要等当前任务
结束才换装,在那之前仍跑旧代码。汇报"已上线"时这点要说清楚。
回滚:上一份 bundle 会留成 `satellite/dist/satellite.js.bak-<sha>`(保留最近 3 份)。
需要回退时把它拷回 `satellite.js`(连带 `VERSION.bak-<sha>` → `VERSION`)再重推
(`bun scripts/push-satellites.ts` 或面板)。
要 SSH 上卫星排查时注意 `fei-ios-01` 的用户名是 `fei`,不是 `bytedance`。
## 部署完不等于生效
改 prompt / 报告生成逻辑时,**已有数据不会被追溯重写**——历史任务仍带着旧的报告 HTML,要用
`scripts/backfill_readable_reports.ts --batch --force` 回填,而**回填是对线上记录的写操作,必须先征得用户同意**,且它依赖卫星已经发布到位。