版本：1.2.0

CLI 参考

aisix 二进制文件用于运行 AISIX 网关，并提供处理开源 AISIX 网关配置的命令。使用 validate 检查声明式 resources.yaml 文件，使用 export 将现有 etcd 存储中的资源转换为该格式。这两个命令都不会启动网关监听器。

Usage: aisix --config <CONFIG>
       aisix <COMMAND>

命令	用途
`aisix --config <CONFIG>`	使用指定的启动配置文件启动网关。请参阅启动配置参考。
`aisix validate --resources <FILE>`	在不启动网关的情况下检查资源文件。
`aisix export --etcd <ENDPOINT> [-o <FILE>]`	将开源 AISIX 网关 etcd 存储中的资源导出为可加载的资源文件。

运行官方容器镜像时，请直接调用二进制文件：

docker run --rm --entrypoint /usr/local/bin/aisix ghcr.io/api7/aisix:1.2.0 --help

验证资源文件

aisix validate 会运行网关加载资源文件时使用的相同流水线——读取、${VAR} 插值、名称引用解析、规范 Schema 验证和交叉引用检查——但不会启动任何监听器。可以在启动或重新加载前将其用作预检查，也可以将其用作配置变更的 CI 门禁。

aisix validate --resources resources.yaml

选项	必填	说明
`--resources <FILE>`	是	要验证的资源文件路径。

文件中的 ${VAR} 引用会根据 validate 进程自身的环境进行解析。请使用网关将收到的相同变量运行该命令，否则验证会因无法解析引用而失败。

文件加载通过之后，validate 会报告两类仅凭「加载成功」看不出来的安全护栏问题。

第一类是没有任何 Attachment 的安全护栏。它会被加载、会计入资源总数，但不检查任何流量，因为安全护栏的作用范围完全由 Attachment 决定。这是合法状态而非错误——它原本挂靠的模型或路由可能已从文件中移除——因此 validate 会在标准错误中列出这些条目，退出码仍为 0。

第二类是无法运行的行。validate 会构建每一条已启用的安全护栏，并报出其中构建不出来的行。配置能解析但构建不出来的安全护栏——非法正则、未知的检测器、语法有误的 custom 脚本——会在网关启动时被丢弃，网关随后在没有这项检查的情况下继续提供服务。由于加载本身是成功的，其他地方都不会报告问题：这项检查正是这类行唯一会暴露的地方。

退出码

退出码	含义
`0`	文件加载成功，且每一条已启用的安全护栏都能运行，并将摘要打印到标准输出；如果有已启用但没有任何 Attachment 的安全护栏，还会在标准错误中列出它们。
非零	文件加载失败，或某条安全护栏能加载但无法运行，并将报告打印到标准错误。

成功时：

OK: resources.yaml loaded 3 resource(s)

没有任何 Attachment 的安全护栏会被报告出来，但不影响退出码：

resources file resources.yaml: 1 enabled guardrail(s) have no attachment and inspect no traffic:
  - guardrails ("no-secrets"): add a guardrail_attachments entry to put it in force
OK: resources.yaml loaded 4 resource(s)

失败时，会统一报告整个文件中的所有问题，并指出资源类型、条目和字段：

resources file resources.yaml: 3 error(s):
  - provider_keys[0]: field `api_key`: environment variable `OPENAI_API_KEY` is unset or empty
  - models[0] ("gpt-4o-mini"): `provider_key` references unknown provider key "openai-main" (no provider_keys are defined in this file)
  - api_keys[0] ("quickstart-caller"): `key_env` environment variable `CALLER_API_KEY` is unset or empty

能加载但无法运行的安全护栏也以同样方式报告，并给出该行会被丢弃的原因。custom 脚本的错误会带上引擎自己给出的行号和列号：

resources file resources.yaml: 1 guardrail(s) load but cannot run:
  - guardrails ("screen-with-my-service"): custom guardrail script does not compile: Error: unsupported keyword: export
    at guardrail.js:12:3

使用容器镜像进行验证

如果本地没有二进制文件，请通过 Docker 运行相同检查。挂载文件并传入该文件引用的环境变量：

docker run --rm \
  -v "$(pwd)/resources.yaml:/etc/aisix/resources.yaml:ro" \
  -e OPENAI_API_KEY \
  -e CALLER_API_KEY \
  --entrypoint /usr/local/bin/aisix \
  ghcr.io/api7/aisix:1.2.0 \
  validate --resources /etc/aisix/resources.yaml

从 etcd 导出资源

aisix export 读取开源 AISIX 网关 etcd 前缀下的资源，并将其写入声明式资源文件。可以使用该命令将以 etcd 为后端的网关迁移到资源文件，包括资源由早期版本的网关 Admin API 创建的网关。该命令还可以为网关能够加载的资源创建便于审查的备份。

aisix export \
  --etcd "http://127.0.0.1:2379" \
  --output resources.yaml

选项	必填	说明
`--etcd <ENDPOINT>`	是	要读取的 etcd 端点。多个端点可以重复提供该选项，或使用逗号分隔的列表。
`--prefix <PREFIX>`	否	包含资源的 Key 前缀。默认为 `/aisix`，即网关默认的 `etcd.prefix`。
`-o`、`--output <FILE>`	否	将 YAML 文档写入文件，而不是标准输出。在 Unix 上，AISIX 会以 `0600` 模式创建或重置该文件。
`--reveal-secrets`	否	内联写出存储的凭证，不使用环境变量占位符替换。生成的输出包含有效机密。

导出使用与运行中网关相同的 etcd 解码路径。它会把资源引用转换回显示名称，并省略生成的 ID，使输出文档符合资源文件格式。

默认情况下，存储的凭证会替换为 ${VAR} 占位符。AISIX 会将占位符名称及其来源字段打印到标准错误。加载导出的文件之前，请在网关环境中设置这些变量。

警告

只有在受控迁移确实需要把明文凭证保留在文件中时才使用 --reveal-secrets。请勿提交、发布该输出，也不要将其复制到不安全的位置。

该命令会报告无法解码的 etcd 条目和资源关系警告，并仍然写出结果供检查。如果命名冲突或悬空引用导致文件无法加载，它会以非零状态退出。切换网关使用该文件之前，请验证完成后的文件：

aisix validate --resources resources.yaml

验证资源文件​

退出码​

使用容器镜像进行验证​

从 etcd 导出资源​

验证资源文件

退出码

使用容器镜像进行验证

从 etcd 导出资源