AirlockDocumentation
文档中心
GitHub ↗

从零开始：15 分钟跑通第一条路由

本教程带你完成：安装 Airlock → 启动桌面端 → 创建并验证第一条 HTTP 路由 → 再创建 SSH 与 LLM 路由 → 最后轮换和撤销凭据。完成后你就掌握了日常使用 Airlock 的完整闭环。

01

前置条件

  • macOS 12+（Apple Silicon 或 Intel）、Windows 10+（x64/x86/arm64）或 Linux x64/arm64。
  • Node.js 20+（仅安装器需要；安装完成后可卸载）。
  • 一个你拥有凭据的上游目标：例如一个需要 Authorization 的下载 URL、一台 SSH 服务器、或一个 OpenAI/Anthropic 兼容 API。
  • 建议先阅读安全模型一章，理解 Airlock 的边界。
02

安装 Airlock

所有平台使用同一条命令安装。安装器会下载当前平台的固定校验和产物，SHA-256 校验失败时拒绝执行。

安装（首次安装请去掉 --open）
npm install -g airlock-relay
airlock-installer install --open

安装后建议立即校验一次安装器契约：

查看平台状态
airlock-installer status --json
airlock-installer doctor
关于签名

macOS 包为 ad-hoc 签名且未经 Apple 公证，首次打开需要 Gatekeeper 确认；Windows/Linux 为未签名预览产物。请始终从官方 Release 下载并核对 SHA-256。

03

启动并了解界面

首次启动 Airlock Desktop 后，本地核心 airlockd 会自动运行：HTTP 入口默认监听 127.0.0.1:4768，SSH 入口监听 127.0.0.1:4770。关闭窗口不会停止转发服务；控制通道是当前用户专属的 Unix 套接字（Windows 为命名管道）。

左侧导航：概览（核心状态与端口）、路由（创建与管理入口）、活动（脱敏请求记录）、设置（网络范围、Secret 存储、代理与主题）。

04

创建第一条 HTTP 路由

在"路由"页点击新增路由，类型选择 HTTP / Wget，填写：名称（如 release）、别名（releases）、上游基址（如 https://example.com/releases/）、允许的方法与查询参数。上游 Authorization 在 Airlock 窗口内录入，只发送到本机核心，不会进入日志。

服务端（无桌面）环境使用规格文件：

/etc/airlock/releases.json
{
  "name": "Release mirror",
  "alias": "releases",
  "base_url": "https://example.com/releases/",
  "authorization": "Bearer upstream-secret",
  "methods": ["GET", "HEAD"],
  "egress": "Auto"
}
创建并启用（CLI）
airlock --data-dir /var/lib/airlock --token-file /etc/airlock/control.token \
  routes create http --file /etc/airlock/releases.json
airlock --data-dir /var/lib/airlock --token-file /etc/airlock/control.token \
  routes enable releases
创建输出只出现一次

创建成功后终端会打印一次本地 capability。请立即把它交给调用方；它不会再次显示，也不要用命令行参数传递上游 Secret。

05

验证 HTTP 路由

调用方使用本地入口 127.0.0.1:4768/r/releases/... 和本地凭据，真实上游地址与 Authorization 不会出现在调用方一侧。

成功场景
curl -H "Authorization: Bearer <local-token>" \
  http://127.0.0.1:4768/r/releases/latest.zip -o latest.zip
预期失败场景
curl -H "Authorization: Bearer wrong" http://127.0.0.1:4768/r/releases/latest.zip
# HTTP 401 invalid_api_key；不会泄露上游地址或真实凭据

在"活动"页应看到两条记录：一条 allowed、一条 blocked，均不包含 URL 与 Secret。

06

创建 SSH 路由

SSH 路由需要先探测上游 Host Key。桌面向导会引导完成：上游地址/账号/密码或私钥 → 本地用户名与本地密码 → Host Key 确认。CLI 路径如下：

探测 Host Key
airlock --data-dir /var/lib/airlock --token-file /etc/airlock/control.token \
  ssh probe --address build.example:22 --egress Auto
# 输出 host_key，写入 0600 规格文件后创建
build.json
{
  "name": "Build server",
  "alias": "build",
  "local_username": "build",
  "upstream": "build.example:22",
  "username": "deploy",
  "password": "upstream-password",
  "host_key": "ssh-ed25519 AAAA...",
  "allowed_command": "deploy --release",
  "egress": "Auto"
}
创建、健康检查并启用
airlock ... routes create ssh --file /etc/airlock/build.json
airlock ... routes health build
airlock ... routes enable build

调用方连接：ssh build@127.0.0.1 -p 4770（输入本地密码）。默认只允许精确命令 deploy --release；需要交互式 Shell 时，在路由设置中开启"允许交互式 Shell"（同时要求开放所有命令，属高风险操作）。

07

创建 LLM 路由

coding.json
{
  "name": "Coding",
  "alias": "coding",
  "base_url": "https://api.example.com/v1",
  "authorization": "upstream-key",
  "provider": "openai",
  "models": ["model-a", "model-b"],
  "max_output_tokens": 4096,
  "requests_per_minute": 60,
  "max_concurrent": 4,
  "track_usage": true
}

创建成功后，CLI 会打印一次本地二次 API Key。调用方这样使用：

客户端配置
export OPENAI_BASE_URL=http://127.0.0.1:4768/r/coding
export OPENAI_API_KEY=<local-api-key>

模型白名单之外的请求返回 403 model_not_allowed；输出超过限额返回 400。用法统计只保留数字，不保存提示词或响应正文。

08

轮换与撤销凭据

  • 轮换本地凭据：桌面端"编辑路由 → 轮换"；CLI 使用 routes rotate-credential。轮换后旧凭据立即失效。
  • 撤销访问：routes disable <alias> 停用路由但保留配置；routes delete <alias> 删除路由与相关 Secret。
  • 紧急全停：routes stop-all --yes 禁用所有路由，配置保留待审查。
建议

把轮换纳入例行操作：怀疑凭据泄露、人员变动或季度例行时执行。

09

下一步

已复制