指南
Daemon
API
博客
版本
指南
Daemon
API
博客
简体中文

鉴权

aiod 只支持一个可选的启动期 key。

未设置 key 时，所有路由都会放行，aiod 处于完全开放状态。此时请将它绑定到 127.0.0.1，或放在自带鉴权的网关后面。

启动时设置 API key

命令行参数和环境变量设置的是同一个 key：

aiod start --api-key my-secret-key
# equivalently
AIO_API_KEY=my-secret-key aiod start

请求中携带 API key

三种等价形式：

curl "$BASE_URL/v1/sandbox" -H "Authorization: Bearer my-secret-key"
curl "$BASE_URL/v1/sandbox" -H "x-api-key: my-secret-key"
curl "$BASE_URL/v1/sandbox?api_key=my-secret-key"
通道什么时候用说明
Authorization: BearerHTTP 客户端的默认选择标准的 bearer token
x-api-key客户端原本使用的 header预构建镜像的网关同时接受 X-AIO-API-Key
?api_key=只在没法带 header 时用已废弃；比较前会先做 percent 解码

三种通道都用常数时间比较，所以 key 的长度和猜中了多少前缀都不会从响应耗时里泄漏出来。

URL 中的凭证可能出现在访问日志、浏览器历史和后续请求的 Referer 中。

因此，只有无法设置请求头时才使用 query 参数，例如浏览器原生 WebSocket 或 VNC 页面：

{ws_base_url}/v1/shell/ws?session_id=SESSION_ID&api_key=my-secret-key

WebSocket 会在升级前完成鉴权。没有有效 key 时，握手直接返回 401，不会先建立连接再断开。

除下文列出的公开路由外，其他请求没有有效 key 时都返回 401，响应体使用统一结构：

{
  "success": false,
  "message": "Unauthorized",
  "data": null,
  "hint": null
}

公开路由

以下路由跳过 key 校验：

  • /
  • /health
  • /v1/ping
  • /v1/openapi.json
  • /v2/openapi.json
  • /internal/auth

公开路径按前缀匹配。例如，/health 也会覆盖 /health/details；但 / 只覆盖自身，不会放行整个 API。

公开也不代表一定有响应内容：daemon 不提供 / 的内容，该路径通常留给网关放置首页。

设置 key 后其余路由都需要带 key，/metrics 也不例外——指标暴露的是路由名和流量形态，运维端点没有豁免。

放在网关后面

/internal/auth 是供 nginx auth_request 调用的子请求端点。它从 X-Original-URI 读取原始请求路径，并按同一套规则检查 key：

  • 请求已获授权、目标是公开路径，或未配置 key 时，返回 204。
  • 其他情况返回 401。
  • 该端点始终不返回响应体。

这样，网关只需配置一个 auth_request，就能保护前面的所有入口，包括不经过 aiod 中间件的 VNC 流。

直接调用 /internal/auth 时没有 X-Original-URI，此时会改为检查当前请求自己的凭证。

CORS

CORS 有意开放：aiod 自己不做 origin 校验，交由前面的网关处理。CDP 端口（默认 9222）不要暴露到不可信网络，它本身没有任何鉴权。

身份：执行身份与归属身份

请求里的 user 在不同接口上含义不同，AIO_DEFAULT_USER 提供同样的默认值：

在 commands、PTY 和 code 中，user 决定进程以哪个账户运行；在 files 中，它只决定新建对象归谁所有。

在 files 中，daemon 仍然以自己的权限读写文件，不会因为 user 改变执行权限。

这套语义只在 Linux 上生效。Windows 上显式传 user 返回 400，AIO_DEFAULT_USER 一旦生效就返回 503，详见 Windows。

相关页面