Initial import of streamline

This commit is contained in:
2026-11-16 17:26:44 -08:00
commit 8e4aec1855
1221 changed files with 274256 additions and 0 deletions
+291
View File
@@ -0,0 +1,291 @@
---
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` 回填,而**回填是对线上记录的写操作,必须先征得用户同意**,且它依赖卫星已经发布到位。