21 KiB
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)。
七个反直觉的点(都是踩过的)
手写这套命令基本一定会错在这几处,脚本已经处理,但改脚本前先读:
-
路径不是
~/…。 是/data00/home/jiaopengwen/streamline。写~/home/jiaopengwen/streamline会展开成/home/<你>/home/jiaopengwen/streamline,不存在。 -
必须以
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)。 -
bun不在jiaopengwen的非交互 PATH 里。 只有npm/git能找到。bun 在/home/jiaopengwen/.bun/bin/bun,必须显式加进 PATH(systemd unit 里也是这么硬写的)。bun run build内部会 shell out 到bun,所以npm run build也救不了。 -
没有
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 不存在。 -
SSH 要
-6+ 裸 IPv6,不能加方括号。ssh jingyuan.yi@[fdbd:…]会把整串当 hostname 解析失败;ssh -6 jingyuan.yi@fdbd:…才对。 -
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 过期的组合。 -
卫星 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 直接把字节推给节点。
两个陷阱脚本已经处理:
- 控制面刚重启的那十几秒里,它还没从心跳重新学到各节点的
supportsQueuedDeploy, 此时推送会把每台忙节点都判成「不支持空档部署」。所以脚本会先等到每个节点都有一次 重启之后的心跳(默认最多 45 秒)再动手。 - 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 回填,而回填是对线上记录的写操作,必须先征得用户同意,且它依赖卫星已经发布到位。