Skip to content

Releases

v0.6.3:skill install——把规范落到项目里

Choose a tag to compare

@XneoZero XneoZero released this 12 Nov 09:51

新增

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.mjs 119 条全绿(新增 deploy-skill.test.mjs 4 条:渲染、连不上服务器、重复执行、拒绝覆盖手写文件)
  • 真机实测:在青芒项目执行后生成的文件里 profile / 服务器 / app / 落点 / preservePaths 三项数据保护路径全部正确

安装:npm i -g ./airlock-0.6.3.tgz

v0.6.2:preservePaths 与发布通道自更新

Choose a tag to compare

@XneoZero XneoZero released this 12 Nov 09:42

新增

  • 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/ 产物。

升级注意

  1. 先升级服务器上的 deployer,再加 preservePaths。deployerConfigSchema 是严格的,旧版遇到未知字段会拒绝整份配置,那台机器的发布全断。
  2. 更新服务器用发布通道自更新;前提是沙盒应用的 start 真的执行版本目录里的 node 入口(固定的 start-<app>.ps1 不会执行更新器)。踩坑记录见 docs/TRANSFER.md 4.2。
  3. 完整验证:npm run typecheck 通过,node --test test/*.test.mjs 115 条全绿(含新增 deploy-preserve.test.mjs 4 条)。

安装:npm i -g ./airlock-0.6.2.tgz 或用下面的资产。

v0.5.2:剥 BOM + mirror 切换前的三个坑

Choose a tag to compare

@XneoZero XneoZero released this 12 Nov 07:52

修掉两个会让部署通道「哑掉」的坑

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 布局

Choose a tag to compare

@XneoZero XneoZero released this 12 Nov 07:18

新机器默认 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

Choose a tag to compare

@XneoZero XneoZero released this 12 Nov 07:01

桌面上的应用夹,打开就是网站

新增 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

Choose a tag to compare

@XneoZero XneoZero released this 12 Nov 06:39

有状态应用的数据能跨版本活下来了

  • 新增 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

Choose a tag to compare

@XneoZero XneoZero released this 11 Nov 14:26

这次的重点:从下载到发布只要一条命令

  • 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 — 首个可用版本

Choose a tag to compare

@XneoZero XneoZero released this 11 Nov 10:30

首个可用版本:两条通道、版本回滚、本地控制台。

安装

需要 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。