部署 aidy-server
用 Python、Go 或其他语言编写的宿主,通过 aidy-server serve 把 aidy 运行时作为独立服务运行。它来自 @aidy-dev/server 包,也有 Docker 镜像 ghcr.io/aidy-dev/aidy-server。反向代理把 aidy 的路径转发给它,aidy 再以用户身份回调你的 API。JavaScript 宿主也可以直接内嵌运行时,见 Hono 和 Express。
browser ──> reverse proxy (console.example.com) ├─ /aidy/v0/*, /mcp, /skill.md, /llms.txt, /.well-known/... ──> aidy-server ──> Postgres └─ everything else ─────────────────────────────────────────> your APIaidy-server ──(Authorization + Aidy-Assertion)──> your APIaidy-server serve 的全部配置都来自环境变量,没有配置文件。必填变量如下:
| 变量 | 含义 |
|---|---|
AIDY_URL |
aidy 实例的公开 URL,即断言的 iss。代理把 aidy 放在根路径时为 https://console.example.com。 |
AIDY_HOST_ORIGIN |
产品的源,即断言的 aud。 |
AIDY_SIGNING_KEY |
aidy 的 Ed25519 私钥 JWK(带 kid),JSON 格式(见签名密钥)。 |
AIDY_SECRET |
至少 32 字节,用于加密存储模型 API 密钥等设置。 |
AIDY_DATABASE_URL |
生产环境用 postgres://…,单实例可用 sqlite:<path>。aidy 会创建自己的 aidy_* 表,请给它单独的数据库或 schema。 |
可选变量:
| 变量 | 含义 |
|---|---|
AIDY_HOST_BASE_URL |
aidy 访问你的 API 的地址,与源不同时设置(例如集群内服务)。断言的 htu 仍然使用公开源。 |
AIDY_HOST_OPENAPI |
OpenAPI 3.1 文档的路径或 URL,用用户凭证获取。默认 /api/openapi.json。 |
AIDY_MODELS |
默认的模型链,JSON 数组,每项为 {id, provider, model, baseURL?, apiKey?, vision?, temperature?, maxOutputTokens?, cooldownSeconds?, providerOptions?};provider 取 openai-compatible、openai 或 anthropic,cooldownSeconds 为 {quota, rateLimit, error}。管理员可以在应用里修改。 |
AIDY_HOST_KEYS |
宿主用来签署 Aidy-Host-Assertion 的公钥 JWK,JSON 数组:用于延迟任务完成通知和宿主任务(POST /aidy/v0/generate)。 |
AIDY_PREVIOUS_SECRET |
轮换前的旧密钥:它仍能解密已保存的设置,这些设置在第一次读取时会改用 AIDY_SECRET 重新加密。之后删除该变量。见设置加密密钥。 |
AIDY_NAME |
助手名称,通过 GET /aidy/v0/info 提供给界面。默认 Aidy。 |
AIDY_INSTRUCTIONS |
系统指令,或用 @path 从文件读取。 |
AIDY_SKILL_GUIDE |
放在 /skill.md 最前面的手写指南,或 @path。 |
AIDY_SKILL_NAME |
/skill.md frontmatter 中的 name,一个 slug。默认取产品名的 slug(产品名不是 ASCII 时也能得到合法的 slug),否则取宿主主机名的第一段。 |
AIDY_CLI_COMMAND、AIDY_CLI_PACKAGE、AIDY_CLI_INSTALL |
/skill.md 和 /llms.txt 中提到的 CLI 及其安装方式:npm 包名,或一行自由格式的安装命令(优先于包名),例如 curl -fsSL https://tm.example.com/install.sh | sh。默认是 @aidy-dev/cli 的 aidy。 |
AIDY_KNOWLEDGE_DIR、AIDY_KNOWLEDGE_BASE_URL |
启动时建立索引、用于搜索和回答的 Markdown 文档目录,以及这些页面所在的 URL。见知识库。 |
AIDY_MCP_AUTHORIZATION_SERVERS |
向 MCP 客户端声明的 OAuth 签发方,逗号分隔。 |
AIDY_BASE_PATH |
aidy 挂在某个路径下时,所有路由的前缀。 |
AIDY_MAX_STEPS |
每次运行的模型步数。默认 16。 |
PORT |
监听端口。默认 8080。 |
变量缺失、不是合法 JSON 或超出范围时,服务会输出指明该变量的信息,并以退出码 2 退出。
AIDY_URL=https://console.example.com \AIDY_HOST_ORIGIN=https://console.example.com \AIDY_HOST_BASE_URL=http://console-api.default.svc:8000 \AIDY_HOST_OPENAPI=/openapi.json \AIDY_SIGNING_KEY="$(cat aidy-2026-11.private.jwk)" \AIDY_SECRET="$(openssl rand -base64 48)" \AIDY_DATABASE_URL=postgres://aidy:…@db/aidy \AIDY_MODELS='[{"id":"qwen","provider":"openai-compatible","model":"qwen3-max","baseURL":"https://dashscope.aliyuncs.com/compatible-mode/v1","apiKey":"…"}]' \npx @aidy-dev/server servenpm install -g @aidy-dev/server 会安装同一个命令 aidy-server。GET /healthz 返回 ok。收到 SIGTERM 或 SIGINT 时,服务停止接收请求,并等待进行中的运行结束。
aidy 启动时创建并升级自己的表(aidy_*)。多个副本可以共用一个 Postgres,见多实例。
内嵌 aidy 时,这些设置对应 createAidy 的选项:name、instructions、secret(字符串,或用于轮换的列表),以及 skill: { name?, guide?, cli?: { command, package?, install? } }。
aidy 用 Ed25519 密钥为每次调用 API 签名。以下两个命令都能生成:
aidy keys generate --kid aidy-2026-11 -o aidy-2026-11.private.jwk # @aidy-dev/clinpx @aidy-dev/server keys aidy-2026-11 # aidy-serveraidy keys generate 打印公钥 JWK,并把私钥 JWK 写入一个新的 0600 文件。两个命令写出的都是可移植的 JWK:{kty, crv, x, kid} 和 {kty, crv, x, d, kid},不含 alg、key_ops 或 ext,Node、Bun、Deno 和 workerd 都能导入。在代码中用 @aidy-dev/spec/delegation 的 importSigningKey 加载私钥:它也接受 Node 导出的带 alg: "Ed25519" 的 JWK(workerd 会拒绝直接导入这种 JWK),importPublicKeys 对公钥也是如此。aidy-server keys <kid> 把两者打印成一个 JSON 对象 {"signingKey": …, "publicKey": …}:signingKey 就是 AIDY_SIGNING_KEY 的值,所以要在输出不会被记录的地方运行。私钥是 aidy 的机密,只交给 aidy 服务。公钥 JWK 写进宿主配置(例如 Python 套件的 load_public_keys)。aidy 也在 /.well-known/aidy-keys.json 公开它以便查看;宿主要在配置中固定公钥,不能从请求中获取。
- 用新的
kid生成新密钥。 - 把新公钥 JWK 加到每个宿主的配置中(与旧公钥并存),然后部署。
- 把 aidy 的
AIDY_SIGNING_KEY切换为新私钥,然后部署。 - 一分钟后(断言有效期为 60 秒),从宿主中删除旧公钥。
设置加密密钥
Section titled “设置加密密钥”AIDY_SECRET 只生成一次(例如 openssl rand -base64 48)。管理员保存的模型设置用它加密。轮换步骤:
- 把新值设为
AIDY_SECRET,旧值设为AIDY_PREVIOUS_SECRET,然后部署。新密钥用于加密,两者都能解密;用旧密钥加密的设置在第一次读取时会改用新密钥重新加密。 - 设置被读取过之后(任意一次
GET /aidy/v0/settings或运行都会读取),删除AIDY_PREVIOUS_SECRET。
内嵌时传入列表:secret: [newSecret, oldSecret]。如果 aidy 手上没有加密设置时所用的任何一个密钥,设置路由会返回 503 settings_unreadable,运行也会失败,直到换回该密钥,或管理员调用 DELETE /aidy/v0/settings,之后重新使用配置中的模型链。
Docker
Section titled “Docker”docker run -d --name aidy -p 8080:8080 --env-file aidy.env ghcr.io/aidy-dev/aidy-server:v0.2.0镜像标签为发布版本(v0.2.0)和 latest。镜像以 node 用户在 8080 端口运行 aidy-server serve,并对 /healthz 做健康检查。aidy.env 存放上面的变量;使用 AIDY_KNOWLEDGE_DIR 或 @path 时,把文件挂载进容器,并让变量指向它们。
如果要基于自己的基础镜像构建(例如内部镜像仓库),给 packages/server 中的 Dockerfile 传入 --build-arg BASE_IMAGE=… --build-arg AIDY_VERSION=0.2.0。
Kubernetes
Section titled “Kubernetes”aidy 不提供 Helm chart。用 Deployment 运行镜像,从 Secret 读取变量,并探测 /healthz:
containers: - name: aidy image: ghcr.io/aidy-dev/aidy-server:v0.2.0 ports: [{ containerPort: 8080 }] envFrom: [{ secretRef: { name: aidy-env } }] readinessProbe: { httpGet: { path: /healthz, port: 8080 } }把 AIDY_SECRET、AIDY_PREVIOUS_SECRET、AIDY_DATABASE_URL、AIDY_SIGNING_KEY 和 AIDY_MODELS(其中含 API 密钥)放进 Secret。客户端断开时运行不会中断,停止的副本会让其租约自然过期。运行两个或更多副本时,要把 MCP 会话路由到同一个副本(见多实例)。
多个 aidy 实例可以共用一个数据库:审批和延迟任务只会被消费一次,运行持有租约,两个实例不会同时驱动同一个对话。有两样东西只存在于单个实例的内存中:
- MCP 会话及其待处理的 elicitation 留在打开它的实例上。要把带有同一个
Mcp-Session-Id的所有请求路由到同一个实例(粘性会话,或 Kubernetes Service 上的sessionAffinity: ClientIP),或者只运行一个实例。请求落到其他实例时返回404 session_not_found,客户端会重新打开会话。 - 模型休眠状态按实例保存,每个实例各自发现某个端点出错。
在 Cloudflare Workers 上
Section titled “在 Cloudflare Workers 上”运行只有在实例存活时才能比响应活得更久。在 Workers 上,运行通过 ctx.waitUntil 登记,而它受请求生命周期的限制,并且每个 isolate 都是一个独立实例。因此托管 aidy 的 Worker 应把每个用户(或每个对话)路由到一个持有 aidy 实例的 Durable Object:运行流式输出期间该对象一直存活,MCP 会话和休眠状态也都集中在一处。aidy 官网就是这样做的,每个访客一个 Durable Object。
import { DurableObject } from 'cloudflare:workers';import { createAidy, SqlStore, type Aidy } from '@aidy-dev/core';import { importSigningKey } from '@aidy-dev/spec/delegation';import { d1Driver } from '@aidy-dev/sql/d1';
export class AidyObject extends DurableObject<Env> { #aidy?: Promise<Aidy>;
fetch(request: Request) { this.#aidy ??= importSigningKey(JSON.parse(this.env.AIDY_SIGNING_KEY)).then((signingKey) => createAidy({ /* url, host, models … */ signingKey, secret: this.env.AIDY_SECRET, store: new SqlStore(d1Driver(this.env.DB)) }), ); return this.#aidy.then((aidy) => aidy.fetch(request, this.ctx)); }}
export default { async fetch(request: Request, env: Env) { const user = await userIdOf(request); // your session lookup return env.AIDY.get(env.AIDY.idFromName(user)).fetch(request); },};在 wrangler.jsonc 中把这个类绑定为 Durable Object(这里是 AIDY)。这样同一用户的请求都会到达同一个对象,该用户各个会话的 MCP 请求也一样。
把产品源上的以下路径原样转发给 aidy:
| 路径 | 用途 |
|---|---|
/aidy/v0/* |
HTTP API 和 AG-UI 事件流 |
/mcp |
基于 streamable HTTP 的 MCP |
/skill.md, /llms.txt |
生成的智能体文档 |
/.well-known/aidy-keys.json |
aidy 的公钥 |
/.well-known/oauth-protected-resource/mcp |
仅在设置了 AIDY_MCP_AUTHORIZATION_SERVERS 时 |
运行通过 Server-Sent Events 推送,因此要关闭响应缓冲并允许长时间读取。nginx 示例:
location ~ ^/(aidy/v0/|mcp$|skill\.md$|llms\.txt$|\.well-known/(aidy-keys\.json|oauth-protected-resource/mcp)$) { proxy_pass http://aidy:8080; proxy_http_version 1.1; proxy_set_header Host $host; proxy_set_header X-Forwarded-Proto $scheme; proxy_buffering off; proxy_read_timeout 1h;}Authorization 头和 cookie 要原样转发:aidy 用它们调用身份操作来认证每个请求。
如果要把 aidy 放在 /assistant 这样的前缀下,设置 AIDY_BASE_PATH=/assistant 和 AIDY_URL=https://console.example.com/assistant,并代理该前缀。客户端随后把这个前缀作为 baseUrl。
aidy check --openapi https://console.example.com/openapi.json通过。- 用某个用户的令牌请求
GET /aidy/v0/catalog,能列出该用户的操作。 - 通过侧边栏发起写操作时出现审批卡片,API 审计日志记录了
actor = aidy和审批 id。 /skill.md和/llms.txt能正常打开,claude mcp add能连上(见 MCP 客户端)。