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:latest --help
验证资源文件
aisix validate 会运行网关加载资源文件时使用的相同流水线——读取、${VAR} 插值、名称引用解析、规范 Schema 验证和交叉引用检查——但不会启动任何监听器。可以在启动或重新加载前将其用作预检查，也可以将其用作配置变更的 CI 门禁。
aisix validate --resources resources.yaml
| 选项 | 必填 | 说明 |
|---|---|---|
--resources <FILE> | 是 | 要验证的资源文件路径。 |
文件中的 ${VAR} 引用会根据 validate 进程自身的环境进行解析。请使用网关将收到的相同变量运行该命令，否则验证会因无法解析引用而失败。
退出码
| 退出码 | 含义 |
|---|---|
0 | 文件加载成功，并将摘要打印到标准输出。 |
| 非零 | 文件加载失败，并将完整的聚合错误报告打印到标准错误。 |
成功时：
OK: resources.yaml loaded 3 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
使用容器镜像进行验证
如果本地没有二进制文件，请通过 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:latest \
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