Repository navigation
Releases
v0.6.3:skill install——把规范落到项目里
新增
airlock-deploy skill install:在每个使用 airlock 的项目里落一份 agent 能直接读到的规范。
此前存在一个断层:skills/airlock-deploy/SKILL.md 随 npm 包分发,装在 node_modules/airlock/ 下,而 agent 的 skill 扫描路径是 <项目>/.dsh/skills/——文件在,但读不到。于是"规范随包分发"实际等于"看不见",别的项目也不会自动生成任何规范文件。
- 生成
<项目>/.dsh/skills/airlock-deploy/SKILL.md:通用规范 + 自动填好的「本项目」小节(profile / 服务器 / app / 本地工作区 / 服务器落点 / 布局 /sharedPaths/preservePaths) - 能连上部署器时从
status取真实值;连不上就把原因写进文件,标出哪几行待补 - 首行
<!-- airlock:generated -->标记:重复执行刷新通用部分;同名文件若没有标记(用户手写)拒绝覆盖,--force才动 release成功后检测项目是否已落规范,没有就在 stderr 打一行提示
用法
airlock-deploy skill install --profile web-prod # 缺省写当前目录
airlock-deploy skill install --dir ./my-site --force # 覆盖非生成文件验证
npm run typecheck通过,node --test test/*.test.mjs119 条全绿(新增deploy-skill.test.mjs4 条:渲染、连不上服务器、重复执行、拒绝覆盖手写文件)- 真机实测:在青芒项目执行后生成的文件里 profile / 服务器 / app / 落点 /
preservePaths三项数据保护路径全部正确
安装:npm i -g ./airlock-0.6.3.tgz
v0.6.2:preservePaths 与发布通道自更新
新增
preservePaths:mirror 布局下「只保护、不改目录结构」的白名单。sharedPaths会把目录换成链接、数据搬进.airlock/<应用>/shared/;preservePaths发版时整棵跳过,线上目录保持普通目录。仅 mirror 生效。- 发布通道自更新(
scripts/build-updater.mjs):生成更新器经沙盒应用发布,覆盖服务器上的 airlock 安装目录后起服务让健康检查通过。--preserve 应用:路径1,路径2顺带改配置(先确认代码覆盖成功才动配置,改前备份deployer.json);--publish 应用@服务器一条命令完成生成与发布。 status返回新增layout/sharedPaths/preservePaths,确认保护了什么不用再猜目录。
修正
- 文档澄清:mirror / flat 下
shared/在<root 父目录>/.airlock/<应用>/shared/,不在 root 里——此前用「root/shared 不存在」判断未配sharedPaths是错的。 .gitignore从 GBK 转 UTF-8,并忽略updater/产物。
升级注意
- 先升级服务器上的 deployer,再加
preservePaths。deployerConfigSchema是严格的,旧版遇到未知字段会拒绝整份配置,那台机器的发布全断。 - 更新服务器用发布通道自更新;前提是沙盒应用的
start真的执行版本目录里的 node 入口(固定的start-<app>.ps1不会执行更新器)。踩坑记录见docs/TRANSFER.md4.2。 - 完整验证:
npm run typecheck通过,node --test test/*.test.mjs115 条全绿(含新增deploy-preserve.test.mjs4 条)。
安装:npm i -g ./airlock-0.6.2.tgz 或用下面的资产。
v0.5.2:剥 BOM + mirror 切换前的三个坑
修掉两个会让部署通道「哑掉」的坑
1. 配置文件带 BOM 时 deployer 直接起不来
bin/airlock-deployer.mjs 与 bin/airlock-broker.mjs 在解析配置前先剥掉 UTF-8 BOM。
之前用 PowerShell 5.1 的 Set-Content -Encoding utf8 改过 deployer.json,BOM 会让 JSON.parse 抛错,
而这一步发生在握手之前——客户端只看到「部署器没有返回响应」,完全看不出是编码问题。
2. 切 mirror 的三个前置条件写进文档
docs/DEPLOY.md 新增「从 nested 切到 mirror 之前,先处理三条」:
install/start钩子不能再往版本目录里造 junction:镜像同步遇到 junction 会把它当文件复制而失败,
而 mirror 布局没有回退,失败时网站停在半路;- Windows 计划任务的运行主体必须是 SYSTEM:
Register-ScheduledTask不指定-Principal时默认
「只使用交互式」,从 ssh / deployer 这类非交互会话里会静默不执行(任务显示「上次运行时间: N/A」); - 配置文件要纯 UTF-8、别带 BOM。
已在生产上实测:qingmang 从 nested 切到 mirror 后,落点目录就是发布源的副本
(117 个文件,不再有 releases/、current、state.json、shared/),
状态与日志移到 <落点父目录>/.airlock/<应用id>/,整条 stop → 同步 → start → 健康检查链路跑通。
v0.5.1:新机器默认 mirror 布局
新机器默认 mirror 布局
scripts/provision-windows.ps1 的 -Layout 默认值从 flat 改为 mirror:从仓库下载源码、
一条命令接入后,服务器落点就是本地发布目录的副本——内容和目录结构与本地一致,不掺
releases/、current、state.json。
版本信息留在本地 git,回退流程:
git checkout <旧版本标签或提交>
node bin/airlock-deploy.mjs release --app <应用id> --source .\dist --version $(git rev-parse --short HEAD)变更
provision-windows.ps1:-Layout默认mirror,补.PARAMETER Layout说明;
mirror 下不再往配置里写没有意义的keepReleases。- README、
docs/DEPLOY.md、技能说明同步:默认布局、回退靠 git、rollback在 mirror 下会被拒绝。 provision-windows.ps1在仓库里统一成 LF 存储(checkout 到 Windows 时由.gitattributes
转回 CRLF),之前 API 推送留下的 CRLF blob 造成的整文件 diff 噪音消失。
需要旧行为时显式传 -Layout nested 或 -Layout flat;老配置不写 layout 仍按 nested 解析。
v0.4.0
桌面上的应用夹,打开就是网站
新增 layout: "flat":
root本身就是指向当前版本的链接,版本与状态挪到<root 父目录>/.airlock/<应用id>/;- 桌面打开应用夹直接看到
index.html,不再混着releases/、current、state.json; - 回滚只是换链接目标,能力不变;
- 首次从旧结构切过来,root 原有内容整体挪进
releases/legacy-<时间戳>/保留; provision-windows.ps1给新机器生成的配置默认就是 flat。
不写 layout 的老配置行为完全不变(nested)。测试 106(+4)。
v0.3.0
有状态应用的数据能跨版本活下来了
- 新增
sharedPaths:deployer.json 里配一行,版本目录里的data/、assets/img/uploads在激活时换成指向<root>/shared/...的链接(Windows junction / Linux symlink)。activate与rollback都生效。- 首版自带的数据会整体迁进 shared,不丢;
- shared 已有内容时以 shared 为准,版本包里那份丢弃并记日志;
- 嵌套路径自动补父目录;只认相对路径。
- 连不上服务器时,报错不再只贴 ssh stderr,而是分类:端口没监听 / 安全组没放行 / 认证被拒(点名 AllowGroups)/ 主机键变了(给
ssh-keygen -R)。 - 文档:
docs/DEPLOY.md增 sharedPaths 一节;docs/TRANSFER.md增「打包 node_modules 比在服务器 npm ci 更快」。 - 测试 102 个(+5 sharedPaths、+5 ssh 错误归类)。
v0.2.0
这次的重点:从下载到发布只要一条命令
- scripts/bootstrap-windows.ps1:目标机上一条命令完成下载源码(GitHub 被 reset 自动换国内镜像)、装 Node 24、npm ci、建账号+密钥+sshd 门禁、在管理员桌面生成落点配置与启停脚本并授权。
- 默认落点就是管理员桌面 C:\Users\Administrator\Desktop<应用id>,-AppId / -HealthPort / -EntryFile 可配。
- STOP_FAILED:stop 之后确认端口真的释放,避免旧进程的 200 骗过健康检查造成"假成功";失败时 current 不动,服务不中断。
- 零配置打开控制台进入「接入第一台服务器」引导页,不再一闪而过。
- 档案读取兼容 PowerShell 5.1 写出的 UTF-8 BOM,并把"读不到"和"不是合法 JSON"分开报。
- 中文 Windows 的 AllowGroups 本地化坑、profile 自动创建,都已写进脚本与文档。
详见 docs/TRANSFER.md(网络受限时的传输办法)与 docs/ONBOARDING.md。
v0.1.0 — 首个可用版本
首个可用版本:两条通道、版本回滚、本地控制台。
安装
需要 Node.js ≥ 24——直接运行 TypeScript,靠内置类型剥离,没有构建步骤。
git clone https://github.com/l1217974476/airlock.git
cd airlock && npm install不想 clone 就用下面的附件:
npm i -g ./airlock-0.1.0.tgz两条通道
两台机器之间只跑一条 SSH 连接,stdin/stdout 接一个 JSON Lines 协议。请求侧说得越少,能被滥用的面就越小。
remote-dev —— 读写服务器上的工作区。12 个固定 op:读(status / list / read / git-status / git-diff)、
写(lease-acquire / lease-release / apply)、执行(check / job-status / job-cancel)、
交接(release-request)。另有 host-runtime 端口:4 个服务槽位 + 3 个动作(restart / reload / status),
请求侧只能给槽位 id,不能给命令或单元名。
deploy —— 本地构建产物到服务器。只认「应用 id + 版本号 + 归档」:
启停命令、健康检查、目录结构全部来自服务器本地配置,本机传不了命令进服务器。
发布通道的形态
<root>/releases/<version>/ 每个版本一个目录
<root>/current 指向当前版本
<root>/backups/<version>.tar.gz
<root>/state.json installed / deployed / failed / rolled_back
<root>/deploy.log
- 健康检查不过就自动退回上一版,状态记
rolled_back - 落点可改;Windows 默认管理员桌面,其他平台默认
~/Desktop/<app> - 默认只回滚代码。要连数据一起保,就在归档配置里声明
backupPaths,
并把状态目录放在releases/之外(Minecraft 的世界数据就是这么做的) install/activate/rollback全在服务器侧执行,本机只发请求
本地控制台
双击 airlock-ui.cmd(或跑 ./airlock-ui.sh)。绑 127.0.0.1,带一次性 token 的 URL。
能看每个项目的发布记录、每个服务器的版本列表,手动发布与回退,改发布落点,
加项目(原生文件夹对话框,自动探测构建产物目录)、加服务器,
以及连不上服务器时给出一段可以直接交给 agent 的接入提示词。
服务器侧
scripts/provision-windows.ps1:建专用部署账号(默认 ag-ssh)、把公钥写进真实的 profile 目录、
配 sshd 的 ForceCommand 门禁。完整接入流程见 docs/ONBOARDING.md,踩坑记录见 docs/DEPLOY.md。
已验证
- 隔离测试 78 个全绿:协议编解码、路径白名单与穿越、CAS 与租约、归档摘要一致性、
宿主服务动作白名单、激活失败自动回退、数据备份恢复、落点校验与写回。 - 真实服务器端到端跑通:Windows + OpenSSH
ForceCommand、版本切换与自动回滚、多服务器切换、
有状态服务(Minecraft Fabric 服务端,世界数据靠 junction 留在releases/之外)。
未验证
Linux 服务器上的完整链路、多客户端并发、慢链路下的大包传输稳定性、
带数据库迁移的回滚、macOS 作为控制台宿主。
已知的取舍
- 不执行任意命令、不给交互式 PTY、不管理数据库、不
tail -f日志。 - 不托管凭据:私钥在本机 ssh agent 或受保护文件里,profile 只存路径。
- 不负责构建:
deploy推的是已经构建好的目录,构建是调用方的事。 - 历史说明:本 tag 之前曾有一次性接入脚本误入版本库(含真实公钥与 IP),
推送前已用filter-branch从全部历史清除,因此旧 commit hash 与常见教程里的不同属正常。
附件
airlock-0.1.0.tgz —— npm pack 产物,58 个文件,127.9 KB,可直接 npm i -g。
SHA-256 AA0C8A2D7C40AB74495CA939C8D2F4B7F8ADCB02CC7A836EC774117D206F7373
许可:MIT。