Airlock MCP
by XneoZero
README.md
# Airlock
[](https://github.com/XneoZero/airlock/actions/workflows/ci.yml)
[](https://github.com/XneoZero/airlock/releases)
[](LICENSE)
[](package.json)
**A capability airlock for agents.** Narrow, auditable SSH channels to a server —
only registered operations pass, and every pass is logged.
给 agent 的「能力气闸」:通往服务器的窄通道。模型只能执行登记过的操作,拿不到任意 shell。
两个通道,方向相反:
| 通道 | 方向 | 用途 |
|---|---|---|
| `remote-dev` | 读写服务器上的工作区 | 让 agent 看代码、改文件、跑预注册的检查 |
| `deploy` | 本地构建产物 → 服务器 | 发版、切版本、失败自动回滚 |
---
## 它是什么
两台机器之间只跑一条 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 + 版本号 + 归档」:启停命令、健康检查、目录结构全部来自服务器本地配置,
本机传不了命令进服务器。
## 它不是什么
- 不是 SSH 的替代品,不是 Ansible,不是通用运维通道。
- 不执行任意命令、不提供交互式 PTY、不管理数据库、不 `tail -f` 日志。
- 不托管凭据:私钥在本机 ssh agent 或受保护文件里,profile 只存路径。
- 不负责构建:`deploy` 推的是**已经构建好的目录**,构建是调用方的事。
## 架构
```
agent / MCP client 本地
│ stdio (MCP) │
▼ │ npm run build(你自己)
bin/airlock-mcp.mjs ──┐ │
bin/airlock.mjs ──────┤ ssh -T -o BatchMode=yes
bin/airlock-deploy.mjs┘ │
│ │
▼ │
sshd (restrict + ForceCommand) │
│ stdin/stdout │
▼ │
bin/airlock-broker.mjs 或 │
bin/airlock-deployer.mjs │
├─ JSON Lines 协议(版本不符直接拒) │
├─ 路径白名单 + realpath 校验 │
├─ 版本目录 + current 链接 │
└─ 状态、日志、数据快照 │
```
## 快速开始
需要 **Node.js ≥ 24**:直接运行 TypeScript,靠内置类型剥离,没有构建步骤。
```bash
git clone https://github.com/XneoZero/airlock.git && cd airlock
npm install
npm test # 78 个测试,不连服务器、不读 config/
npm run typecheck
```
不想 clone:下 [Releases](https://github.com/XneoZero/airlock/releases) 里的 `airlock-0.1.0.tgz`,
`npm i -g ./airlock-0.1.0.tgz` 直接装。
想先看界面:双击 `airlock-ui.cmd`(或 `./airlock-ui.sh`),见 [控制台](#控制台)。
还没有档案时它不会空转退出,而是打开「接入第一台服务器」的引导页——顺序是
**先由人 RDP 进目标机把 SSH 打开**(agent 进不去没有 SSH 的机器),再把页面上那段提示词交给 agent。
### 通道一:`remote-dev`(改服务器上的文件)
服务器侧配置 `broker.json`:
```json
{
"profileId": "prod",
"serverId": "srv-prod01",
"workspaceId": "ws-app",
"root": "/opt/airlock/workspace",
"stateDir": "/opt/airlock/state",
"releaseInbox": "/opt/airlock/inbox",
"writable": true,
"tasks": {
"test": { "command": "npm", "args": ["test"], "timeoutMs": 600000 },
"build": { "command": "npm", "args": ["run", "build"], "timeoutMs": 600000 }
}
}
```
`root` 是唯一可读写的工作区;`stateDir` 与 `releaseInbox` 必须在工作区之外。
`tasks` 里没登记的名字,`check` 一律拒绝。完整示例见 `examples/broker.example.json`。
本机 profile:
```json
{
"default": "dev",
"profiles": {
"dev": {
"serverId": "srv-dev01",
"host": "ssh.example.com",
"user": "airlock-dev",
"identityFile": "~/.ssh/airlock-dev",
"brokerCommand": "node /opt/airlock/bin/airlock-broker.mjs --config /opt/airlock/config/broker.json",
"hostKeyChecking": "yes"
}
}
}
```
profile 只放连接信息,不放私钥内容。完整示例见 `examples/remote-profiles.example.json`。
```bash
node bin/airlock.mjs status
node bin/airlock.mjs list --path src
node bin/airlock.mjs read --path package.json
node bin/airlock.mjs apply --path src/a.ts --expected-hash <hash|none> --operation-id op-0001 --content-file a.ts
node bin/airlock.mjs check --task test
```
MCP(暴露 10 个 `remote_*` 工具):
```bash
node bin/airlock.mjs mcp
```
### 通道二:`deploy`(本地构建产物 → 服务器)
```bash
npm run build # 先自己验证
airlock-deploy release --app web --source ./dist # 打包 → 上传 → 切版本 → 重启 → 探活
airlock-deploy rollback --app web # 切回上一版,起不来会自己退回来
airlock-deploy status --app web --probe # 现在跑的是哪版、健康不健康
airlock-deploy status --app web --server staging # 同一份代码,换台机器查
```
服务器侧目录:
```
/srv/apps/web/
├── releases/<版本>/ 每次发布一个目录,解压后原样保存
├── current -> releases/… 正在跑的版本(Linux 符号链接 / Windows junction)
├── backups/<版本>.tar.gz 发布前数据快照(配置了 backupPaths 才有)
├── state.json 当前版本 + 历史
└── deploy.log 每次切版本、启停都记一行
```
三条纪律:请求侧只提交「应用 id + 版本号 + 归档」;包解压后在服务器重算摘要,对不上整包作废;
切换前后都落 `state.json` 与日志,失败如实写 `failed` 并自动回退到上一版。
配置、回滚语义、数据备份细节见 [docs/DEPLOY.md](docs/DEPLOY.md);
从零接入一台新服务器见 [docs/ONBOARDING.md](docs/ONBOARDING.md)(Windows)或
[docs/ONBOARDING-LINUX.md](docs/ONBOARDING-LINUX.md)(Linux)。
## 控制台
不想敲命令时,直接用仓库根目录的启动入口:
| 平台 | 入口 |
|---|---|
| Windows | 双击 `airlock-ui.cmd`(参数可直接跟在后面,如 `airlock-ui.cmd --app web`) |
| macOS / Linux | `./airlock-ui.sh`(首次可能需要 `chmod +x airlock-ui.sh`) |
也可以用命令:
```bash
airlock-deploy ui --app web # 全局安装后
node bin/airlock-deploy-ui.mjs # 或直接跑仓库里的入口
```
> 控制台是本地服务端渲染的单页,**没有 `index.html` 可以双击打开**:
> 页面由 `src/deploy/ui/page.ts` 在请求时生成,一次性 token 也在那时下发。
> 上面的两个脚本就是入口。
纯本地服务(只绑 `127.0.0.1`,一次性 token 进 URL),一个页面做四件事:
- **切项目 / 切服务器**:同一份代码可以推到测试机和正式机,不用配两份档案。
下拉只列真实存在的服务器;选择会记在浏览器本地,下次打开回到上次的项目与服务器。
切换项目时服务器跟着该项目的默认目标机走。
- **看**:本地 git 提交、服务器上的版本历史、`deploy.log`
- **发**:选本地构建产物目录(自动探测 `dist` / `build` / `out` 等)→ 发布
- **退**:点某个版本回退,或改服务器上的发布落点
落点(`root`)可以直接在控制台改:点「落点」后面的「改」,走服务器端目录浏览器,
默认停在管理员桌面。改完下一次请求就生效,旧目录里的版本不会自动搬过去。
**Windows 上的默认落点就是管理员桌面**:`C:\Users\Administrator\Desktop\<应用id>`。
`scripts\provision-windows.ps1` 在 `deployer.json` 缺省时按这个位置生成配置,
并顺手把 ACL 授给部署组——部署账号读不到别人的 profile 目录,不授权第一次发布就会失败。
新机器生成的配置用 `"layout": "mirror"`:**服务器落点就是本地发布目录的副本**,内容与目录结构
和本地一致,不掺 `releases/`、`current`、`state.json`。版本信息留在本地 git,回退就是
`git checkout <旧版本>` 再发一版。
想换回「root 是链接 → 当前版本」的老结构,把 `layout` 改成 `flat`(root 是链接)或删掉
(`nested`,root 下带 `releases/current`)。
mirror 下默认会「按本地对齐」——源里没有的文件会被删掉。上传目录、数据库这类运行时数据
必须显式保护:`sharedPaths`(换成链接,数据挪到 `.airlock/<应用id>/shared/`)或
`preservePaths`(只跳过,目录结构不变)。两者分工见 [docs/DEPLOY.md](docs/DEPLOY.md#preservepaths只保护不改目录结构)。
### 多项目与多服务器
档案分三层:
```json
{
"default": "web-prod",
"servers": {
"prod": { "host": "ssh.example.com", "user": "airlock-deploy", "identityFile": "~/.ssh/k1",
"serverId": "srv-prod01", "deployerCommand": "node /opt/airlock/bin/airlock-deployer.mjs --config /etc/airlock/deployer.json" },
"staging": { "host": "10.0.0.12", "user": "deploy", "identityFile": "~/.ssh/k2",
"serverId": "srv-stage01", "deployerCommand": "..." }
},
"profiles": {
"web-prod": { "server": "prod", "app": "web", "workspace": "~/work/my-web" },
"api-prod": { "server": "prod", "app": "api", "workspace": "~/work/my-api" },
"web-staging": { "server": "staging", "app": "web", "workspace": "~/work/my-web" }
}
}
```
`servers` 是机器清单,`profiles` 是项目。控制台右上角的服务器下拉就是 `servers` 的键;
命令行用 `--server <名字>`,和控制台是同一套解析:**只换机器,app 与本地目录跟着项目走**。
名字写错会直接报错,不会退回默认那台。
档案**每个请求前都会重读**,所以运行中改了档案,回控制台刷新就能看到新服务器,不用重启。
档案查找顺序:`--profiles` > `AIRLOCK_DEPLOY_PROFILES_FILE` > `AIRLOCK_DEPLOY_PROFILES`(内联 JSON)
> `~/.airlock/deploy-profiles.json` 与 `./config/deploy-profiles.json` **合并**(同名以项目内为准)。
前三项是「只读这一份」,会**关掉合并**——项目内配的项目会看不见,所以一般不要设。
老格式(把 `host` 直接内联在 profile 里)仍然可用。
### 接入新机器
**Windows 上一条命令**(在目标机的管理员 PowerShell 里跑,源码先按
[docs/TRANSFER.md](docs/TRANSFER.md) 弄上去):
```powershell
.\scripts\bootstrap-windows.ps1 -PublicKey 'ssh-ed25519 AAAA... ag-ssh-deploy' -AppId demo
```
它依次做:下载源码(GitHub 被 reset 就自动换国内镜像)→ 装 Node 24(npmmirror)→
解到 `C:\airlock` 并 `npm ci --omit=dev` → 建部署账号 + 密钥 + sshd 门禁 →
**在管理员桌面生成默认落点配置与启停脚本并授权**。加 `-DryRun` 可以先看它要做什么。
不想用脚本、或目标是 Linux,按 [docs/ONBOARDING.md](docs/ONBOARDING.md)(Windows)/
[docs/ONBOARDING-LINUX.md](docs/ONBOARDING-LINUX.md)(Linux)一步步来。
国内云主机拿不到 GitHub、或 agent 只剩发布通道时怎么办,见 [docs/TRANSFER.md](docs/TRANSFER.md)。
控制台顶部「+ 服务器」会把这一整套写成一段提示词,复制给 agent 就行——里面带了本机实际路径、
每步的验证要求和几个已知的坑(Windows 防火墙规则、`AllowGroups` 白名单、profile 目录带机器后缀、ACL 别一刀切)。
平台相关的路径和措辞按运行控制台的操作系统生成,Windows / macOS / Linux 各按各的写。
## 配合 agent 使用
仓库带一份 DSH 技能:[`skills/airlock-deploy/SKILL.md`](skills/airlock-deploy/SKILL.md)。
装到本机技能目录后,agent 遇到「发版 / 回滚 / 接新服务器」会自动加载它——里面是完整的
操作流程、配置要点、失败模式对照表(13 类报错 → 原因 → 处理)和交付前自检清单。
```bash
mkdir -p ~/.dsh/skills/airlock-deploy
cp skills/airlock-deploy/SKILL.md ~/.dsh/skills/airlock-deploy/
```
**在每个使用 airlock 的项目里也要落一份**,否则那个项目的 agent 读不到规范——
技能文件躺在 `node_modules/airlock/skills/` 下,不在 agent 的扫描路径里:
```bash
airlock-deploy skill install --profile web-prod # 写 <项目>/.dsh/skills/airlock-deploy/SKILL.md
```
生成的文件 = 通用规范 + 自动填好的「本项目」小节(profile、服务器、app、落点、布局、
`sharedPaths` / `preservePaths`)。首行带 `<!-- airlock:generated -->` 标记,重复执行会刷新;
遇到手写的同名文件不覆盖,除非加 `--force`。`release` 发现项目还没落规范时会提示一行。
技能里刻意不写死任何路径和 IP,改用「先查再答」:`status` 返回的 `root`、`where airlock-deploy`、
档案的实际来源。这样换机器、换账号都不用改技能。
## 安全模型
1. **路径**:先过语法白名单(拒绝绝对路径、`..`、NUL),再 `resolve` + 带分隔符的前缀比较,
最后对落点 `realpath`——挡住指向工作区外的符号链接。
2. **并发**:`apply` 必须持有效租约;`expectedHash` 不匹配就 `HASH_MISMATCH`,不会覆盖别人的修改。
3. **幂等**:`operationId` 落在 `stateDir`,重启后同一次重试不会产生第二次写入。
4. **执行**:`check` 只认预注册任务名,`shell:false`,参数数组固定,输出有上限。
5. **失败**:只回错误码,不回堆栈;未预期异常一律 `INTERNAL`。
6. **发布落点**:只认服务器配置里的 `root`,客户端不能在请求里临时指定;改落点要走 `set-root`
并拒绝盘根与系统目录。
7. **控制台**:只绑 `127.0.0.1`,所有 API 都要 URL 里的 token,防其它网页撞进来发版。
## 与 ssh-mcp 类项目的关系
社区主流是「把 shell 交给模型」,再用正则白名单或审批做补救。Airlock 反过来:
**默认没有 shell**,能力面由 op 决定,策略在服务器侧强制执行,不在模型侧拦截。
代价是表达力——没预注册的排障要等人扩任务。这是有意的取舍。
## 目录结构
```
src/contracts/ 协议契约(zod schema、错误码)
src/transports/remote-dev/ Broker / client / 协议 / 工作区 / 任务 / MCP
src/transports/host-runtime/ systemd / Windows service 的预注册动作
src/deploy/ 发布通道:归档校验、版本状态、启停探活、落点管理
src/deploy/ui/ 本地控制台(node:http + 单页 HTML,无前端构建)
bin/ CLI、MCP 入口、服务器侧 Broker 与 deployer
docs/ 发布通道与接入流程
examples/ 各类配置示例,含 Minecraft 服务端模板
test/ 隔离测试(临时目录 + 本机 node 进程)
```
## 开发与测试
```bash
npm install
npm test # node --test,全部隔离
npm run typecheck # tsc --noEmit
```
测试不连服务器、不读 `config/`、不发消息。改代码时约定:
- 注释和提交信息用中文,代码标识符用英文。
- 报错信息写「为什么错 + 怎么办」,不要只回一个错误码。
- 不猜默认值:任何会影响服务器上真实文件的参数要么必填,要么有明确回退理由。
## 状态
已用隔离测试覆盖:协议编解码、Broker 路径 / CAS / 租约 / 任务白名单、客户端超时与错误码、
工作区写入原子性、宿主动作白名单、打包与摘要一致性、路径穿越、协议行与二进制混读、
`install` / `activate` / `rollback`、激活失败自动回退、数据备份恢复、落点校验与写回。
已用真实服务器端到端跑通:Windows + OpenSSH `ForceCommand` 的部署通道、版本切换与自动回滚、
多服务器切换、有状态服务(Minecraft Fabric 服务端:世界数据放在 `releases/` 之外,用 junction 持久化)。
未验证:Linux 服务器上的完整链路、多客户端并发、慢链路下的大包传输稳定性、
带数据库迁移的回滚、macOS 作为控制台宿主。
## 许可
MIT
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessNo recent community issues