Files
streamline/.claude/skills/streamline-deploy/SKILL.md
T
2026-11-16 17:26:44 -08:00

21 KiB
Raw Blame History

name, description
name description
streamline-deploy 把 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 .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>,跑着那个 版本的节点直接跳过。只跳过「字节相同」的那一版:落后更多版本的节点照推不误。

单独用:

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 回填,而回填是对线上记录的写操作,必须先征得用户同意,且它依赖卫星已经发布到位。