AISIX Enterprise 配置
根据控制面安装方式，通过 Docker Compose .env 文件或 Helm values 配置 AISIX Enterprise。
需要查看或自定义生成的部署配置时，请结合安装 AISIX Enterprise使用本参考。
请将这些设置与匹配的数据库备份一起保留。完整恢复集和恢复顺序请参阅备份与恢复。
这些设置用于配置 AISIX Enterprise，与 AISIX 网关运行时环境变量不同。网关运行时变量请参阅环境变量。
部署模式
AISIX Enterprise 和 AISIX Cloud 使用相同的 cp-api 实现，但内部部署模式不同。模式在 cp-api 配置文件中为 deployment.mode，环境变量为 AISIX_CLOUD_DEPLOYMENT_MODE，Helm Chart 中为 api.deploymentMode。字面值 on-premises 运行 AISIX Enterprise，是客户自行托管安装唯一支持的模式。字面值 saas 运行由 API7 运维的 AISIX Cloud。其他任何值都会使 cp-api 拒绝启动。
cp-api 启动时会检查部署模式与依赖它的设置是否匹配。Helm Chart 会渲染任何组合，因此被拒绝的组合会让 cp-api 无法启动，原因写在它的 Pod 日志中：
| 被拒绝的配置 | 配置文件 key（环境变量） | Helm value |
|---|---|---|
部署模式既不是 on-premises 也不是 saas | deployment.mode（AISIX_CLOUD_DEPLOYMENT_MODE） | api.deploymentMode |
saas 模式下没有第二个数据库 URL | database.admin_url（AISIX_CLOUD_ADMIN_DATABASE_URL） | twoDSN.enabled |
on-premises 模式下设置了第二个数据库 URL | database.admin_url（AISIX_CLOUD_ADMIN_DATABASE_URL） | twoDSN.enabled |
saas 模式下没有 SMTP 中继 | smtp.host（AISIX_CLOUD_SMTP_HOST） | api.smtp.host |
on-premises 模式下开启用量推送 | billing.usage_push（AISIX_CLOUD_USAGE_PUSH） | api.billing.usagePush |
on-premises 模式下设置了 mock 以外的计费服务提供方 | billing.provider（AISIX_BILLING_PROVIDER） | api.billing.provider |
日志中给出的是配置文件 key，并说明每个值来自环境变量、配置文件还是默认值。使用 Helm 时，配置文件由 Chart 渲染，因此请修改对应的 Helm value。twoDSN.enabled 为 true 时 Chart 会写入 database.admin_url，因此第二个数据库 URL 相关的错误要通过 twoDSN.enabled 修复。
在 AISIX Enterprise 中，cp-api 强制实施以下行为，控制台会隐藏不适用的内容：
- 任何人都不能自行注册。账户通过邀请创建：受邀者使用邀请链接注册，参见邀请成员。没有有效邀请的注册请求会被拒绝，返回
403 SIGN_UP_DISABLED或403 INVITATION_INVALID。 - 任何人都不能创建组织。首个组织与首位管理员一起创建。创建其他组织的请求会被拒绝，返回
403 ORG_CREATION_DISABLED。从 1.5.x 或更早版本升级、仍包含多个组织的控制面，会以403 ORG_CONSOLIDATION_REQUIRED拒绝控制台请求，直到所有者保留一个组织并删除其他组织。参见将多个组织合并为一个。 - 没有计费页面或套餐。
- 注册时不会要求受邀者接受托管服务条款。
cp-api自身的出站调用可以访问私有地址，除非开启服务端请求伪造（SSRF）防护。参见私有网络访问。cp-api只通过database.url（AISIX_CLOUD_DATABASE_URL）连接 PostgreSQL，对数据库角色的要求只有拥有该数据库，且不使用 PostgreSQL 行级安全（Row-Level Security）。如果同时设置了database.admin_url（AISIX_CLOUD_ADMIN_DATABASE_URL），cp-api会拒绝启动。twoDSN.enabled为true时，Helm 首先要求设置twoDSN.existingSecret，或设置非空且不以CHANGE_ME开头的twoDSN.servingPassword；通过该检查后，Chart 会渲染第二个数据库 URL，cp-api会在启动时拒绝它。参见外部数据库。
Docker Compose 部署包不会把该变量传给 cp-api，因此部署包安装始终以 on-premises 模式运行。
内部 saas 模式有一些仅适用于 AISIX Cloud、不适用于 AISIX Enterprise 的要求：
- 必须配置 SMTP 中继，因为每个新账户都需要验证邮箱。当
smtp.host（AISIX_CLOUD_SMTP_HOST，Helm Chart 中为api.smtp.host）为空时，cp-api会拒绝以saas模式启动。Helm 仍会渲染该发布，因此失败原因出现在cp-api启动时的 Pod 日志中。 domain_verification.dns_server（环境变量AISIX_CLOUD_DOMAIN_VERIFICATION_DNS_SERVER，Helm Chart 中为api.domainVerification.dnsServer）指定组织域名验证执行 TXT 查询时使用的 DNS 服务器，格式为host:port。该设置可选，默认空值使用系统解析器。AISIX Enterprise 没有组织域名功能，会忽略此设置；但若设置的值不是host:port格式，cp-api仍会拒绝启动。
Docker Compose 环境变量
Docker Compose 部署包会从 ./aisix-self-hosted/.env 读取环境变量。快速开始脚本和离线包会在首次启动时生成该文件。请将它与数据库一同备份：其中包含数据库密码和主密钥，后续发布的部署包归档中不会包含该文件。
在常规的原地升级中，run.sh 会更新 AISIX_VERSION，使其与解压后的部署包一致。.env 中的其他设置和密钥会保留。
请在 ./aisix-self-hosted 目录中运行本页的 Docker Compose 命令。
镜像和发布版本
| 变量 | 作用 |
|---|---|
AISIX_VERSION | 部署包拥有的镜像发布版本标签；除非设置了单独的镜像覆盖项，否则各镜像使用此标签。run.sh 会在升级时更新该值。 |
AISIX_API_IMAGE | cp-api 的可选镜像覆盖项。cp-api 镜像同时包含控制台。 |
AISIX_DPM_IMAGE | dp-manager 的可选镜像覆盖项。 |
AISIX_CLOUD_DP_IMAGE | 生成网关安装片段时使用的可选 AISIX 网关镜像覆盖项。未设置时，部署包会下发 docker.io/api7/aisix:${AISIX_VERSION}，即同一版本的网关。Helm 片段只使用其中的镜像仓库，镜像标签跟随所安装的 api7/aisix Chart 版本。 |
单独设置的镜像覆盖项会在部署包升级后继续生效。
数据库
| 变量 | 作用 |
|---|---|
POSTGRES_USER | 随包 PostgreSQL 使用的用户名。 |
POSTGRES_PASSWORD | 随包 PostgreSQL 使用的密码。请使用强且 URL 安全的值，因为它会嵌入 postgres:// URL。 |
POSTGRES_DB | PostgreSQL 数据库名称。 |
这些变量仅配置随包提供的 PostgreSQL 服务。部署包不会在 .env 中提供外部数据库 URL 覆盖项。控制面必须连接外部 PostgreSQL 数据库时，请使用 Helm 安装。
密钥
| 变量 | 作用 |
|---|---|
AISIX_CLOUD_MASTER_KEY | Base64 编码的 32 字节 AES 密钥，用于信封加密。dp-manager 也会使用同一个值。 |
AISIX_CLOUD_MASTER_KEY_ID | 与加密数据一起存储的标识，用于让控制面识别包装密钥。 |
AISIX_CLOUD_SMTP_PASSWORD | 可选的 SMTP 中继密码。参见邮件。 |
除非正在执行主密钥轮换流程，否则不要修改已有部署中的 AISIX_CLOUD_MASTER_KEY。如果修改时没有保留旧密钥，已加密数据可能无法读取。
首个管理员
| 变量 | 作用 |
|---|---|
AISIX_CLOUD_BOOTSTRAP_ADMIN_EMAIL | 首个管理员的邮箱地址。run.sh 生成 .env 时写入 admin@example.com。 |
AISIX_CLOUD_BOOTSTRAP_ADMIN_PASSWORD | 首个管理员的初始密码，长度为 12 到 128 个字符。run.sh 生成 .env 时写入一个随机密码。 |
run.sh 在首次启动生成 .env 时写入这两项，并在整套服务启动后打印一次。它不会修改已存在的 .env。当某次启动时数据库中还没有任何用户，cp-api 会创建组织 Default，并把该账号设为其所有者；该账号首次登录时必须修改密码。这在一个数据库的生命周期内最多发生一次：之后再修改任一值都不会产生任何效果。两项要么都设置，要么都不设置：只设置其中一项时，cp-api 会拒绝启动。两项都为空时，cp-api 可以启动，但会记录一条警告，且没有人能够登录。参见以首个管理员身份登录。
恢复缺失的 CA 根证书
仅当 cp-api 或 dp-manager 因 ca_root row missing but dp_certificates has rows 错误而拒绝启动，并且已经确认控制面连接的是预期数据库时，才使用此恢复覆盖项。生成新的根 CA 会使所有现有网关 mTLS 链失效，无法恢复丢失的根证书。
如果无法从完整数据库备份中恢复缺失的根证书，并且确定要替换它，请将以下设置添加到 .env：
AISIX_CLOUD_ALLOW_FRESH_BOOTSTRAP=1
重新创建两个服务，使任一进程都能引导生成替代 CA：
docker compose up -d --wait api dpm
两个服务都健康后，从 .env 中删除 AISIX_CLOUD_ALLOW_FRESH_BOOTSTRAP，再运行同一命令，以不带覆盖项的方式重新创建服务。两个服务再次恢复健康后，请重新注册每个 AISIX 网关；由缺失根证书签发的证书将无法再通过身份验证。
运行时 URL
| 变量 | 作用 |
|---|---|
AISIX_CLOUD_PUBLIC_BASE_URL | 面向浏览器的控制面源站，例如 https://aisix.example.com。登录始终信任该源站，邀请链接和密码重置链接也指向它。单点登录用它生成服务提供方 URL，因此它必须是浏览器实际使用的 URL。 |
AISIX_CLOUD_DPMGR_BASE_URL | AISIX 网关主机可访问的 dp-manager mTLS 端点，需为 https:// URL，例如 https://dpm.example.com:7944，其主机可以是 DNS 名称或 IP 地 址。 |
AISIX_TRUSTED_ORIGINS | 允许登录的其他浏览器源站，以逗号分隔，取值为裸源站或 https://*<suffix> 模式。公共基础 URL 及其回环对应地址会自动受信任。cp-api 无法识别为源站的条目会被记录到日志并忽略。 |
AISIX_TRUSTED_PROXIES | 位于 cp-api 前方的反向代理，以逗号分隔的 CIDR 表示。cp-api 按客户端对登录和密码重置限流时，会信任这些代理传入的 X-Forwarded-For 请求头。默认为空。参见反向代理后的限流。 |
AISIX_CLOUD_CORS_ALLOWED_ORIGINS | 允许跨域调用 cp-api /api/* 路由（包括 /api/auth/*）的浏览器源站，以逗号分隔。默认为空，此时完全不写出 CORS 响应头。跨域登录还需将源站添加到 AISIX_TRUSTED_ORIGINS。可接受的取值参见跨域浏览器访问。 |
在将部署暴露到本地主机或容器网络之外前，请设置 AISIX_CLOUD_PUBLIC_BASE_URL 和 AISIX_CLOUD_DPMGR_BASE_URL。
Compose 还会把 AISIX_CLOUD_DPMGR_BASE_URL 传递给 dpm 服务，因为 dp-manager 会为该主机签发 TLS 服务器证书。修改后请重新创建 api 和 dpm。
价格目录
打包的 Docker Compose 文件默认以离线定价模式运行 cp-api。它在 api 服务上把 AISIX_CLOUD_PRICESYNC_SNAPSHOT_PATH 设置 为 cp-api 镜像内置的快照，使控制面无需访问 models.dev 即可初始化模型价格。
在在线模式下，如果价格目录仍为空时同步失败（例如主机无法访问 models.dev），cp-api 会改为加载这份镜像内置快照。它不会用快照替换已有的价格目录，并且会继续每 24 小时尝试一次在线同步。
部署包通过 .env 暴露定价模式，Compose 会将这些变量传给 api 服务：
| 变量 | 作用 |
|---|---|
AISIX_CLOUD_PRICESYNC_SNAPSHOT_PATH | 值为快照路径时选择离线模式。未设置该变量时，Compose 使用镜像内置快照；显式设置为空值时选择在线模式。 |
AISIX_CLOUD_PRICESYNC_URL | 在在线模式下覆盖 models.dev 目录 URL，例如改用内部镜像。值为空时，在线模式使用 https://models.dev/api.json。 |
如需使用在线定价，请在部署目录的 .env 中添加空的快照路径赋值。只有需要改用其他目录端点时才添加 URL：
AISIX_CLOUD_PRICESYNC_SNAPSHOT_PATH=
修改任一设置后，重新创建 cp-api：
docker compose up -d api
请将这些覆盖项保留在 .env 中，而不是写入 docker-compose.yaml，因为解压后续部署包时会替换 Compose 文件。
私有网络访问
cp-api 会向运维人员和组织成员提供的 URL 发起出站调用：
- 控制台 Playground 对服务提供方密钥
api_base的调用，包括语义路由测试和语义护栏试运行中的 Embedding 调用。参见 Playground。 - 通知渠道的投递和测试发送，例如发往 Webhook 接收器或 Slack 代理的预算告警。参见预算告警。
- 从
spec_url一次性获取 MCP 服务器的 OpenAPI 文档。 - Azure AI Content Safety 护栏的连接测试。
它们统一由一个服务端请求伪造（SSRF）防护设置控制。on-premises 控制面默认关闭该防护，因此位于内网的模型、Webhook 接收器和文档无需额外配置即可使用。当控制面的操作者不应能借助它访问你的内网时，请开启该防护。
| 变量 | 作用 |
|---|---|
AISIX_CLOUD_SSRF_PROTECTION_ENABLED | 是否开启 SSRF 防护。值为空或未设置时跟随部署模式：on-premises 关闭，saas 开启。接受 true、false、1、0、yes、no、on 或 off，不区分大小写；其他任何值都会使 cp-api 在启动时报错退出。 |
AISIX_CLOUD_SSRF_PROTECTION_ALLOWED_HOSTS | 不受该防护约束的主机，以逗号分隔，每项写作 host（匹配任意端口）、host:port 或 [v6addr]:port。无法解析的条目会使 cp-api 在启动时报错退出。 |
开启防护后：
- 解析到私有、内部、回环、链路本地或其他非公网地址的目标会被拒绝；主机名解析出的每个地址都会检查，连接只发往检查过的地址。Playground 会失败并返回
UPSTREAM_PRIVATE_IP_BLOCKED，通知投递会失败，MCPspec_url获取会被拒绝，此时请改为通过spec_content粘贴文档。 - 护栏连接测试还要求端点使用
https，且位于 Azure AI Content Safety 官方域名下。
列入 AISIX_CLOUD_SSRF_PROTECTION_ALLOWED_HOSTS 的主机不受上述任何检查约束，包括连接测试的 https 和 Azure 域名要求。关闭防护时，这些检查都不生效。
这些调用会经过 cp-api 环境中的 HTTPS_PROXY 或 HTTP_PROXY，除非 NO_PROXY 覆盖该主机。防护开启时，cp-api 会先自行解析并检查主机，再把请求交给代理，因此 cp-api 本地无法解析的主机会被拒绝；这种情况下请把它列入允许的主机。
在 cp-api 配置文件中，对应设置为 outbound.ssrf_protection.enabled 和 outbound.ssrf_protection.allowed_hosts。它们取代了按连接类型划分的变量 AISIX_PLAYGROUND_ALLOW_PRIVATE_IPS、AISIX_CLOUD_NOTIFY_ALLOW_PRIVATE_URLS、AISIX_CLOUD_MCP_SPEC_ALLOW_PRIVATE_URLS 和 AISIX_GUARDRAIL_TEST_CONNECTION_ALLOW_INSECURE；cp-api 现在会忽略这些旧变量，并在启动时打印警告。参见从 1.6.x 或更早版本升级。
在 .env 中设置所需变量，然后重新创建 cp-api：
docker compose up -d api
邮件
cp-api 通过 SMTP 中继发送邀请邮件、密码重置邮件和设置密码链接。在设置 AISIX_CLOUD_SMTP_HOST 之前，邮件功能处于关闭状态。各项设置的行为参见配置邮件（SMTP）。
| 变量 | 作用 |
|---|---|
AISIX_CLOUD_SMTP_HOST | 中继主机名。留空表示关闭邮件功能。 |
AISIX_CLOUD_SMTP_TLS | starttls（默认）、smtps 或 none。 |
AISIX_CLOUD_SMTP_PORT | 中继端口。默认按 TLS 模式取 587、465 或 25。 |
AISIX_CLOUD_SMTP_FROM | 发件人地址。设置了主机时必填。 |
AISIX_CLOUD_SMTP_USERNAME、AISIX_CLOUD_SMTP_PASSWORD | 中继凭据。两者都设置表示进行身份认证，都不设置表示不认证直接发送。 |
AISIX_CLOUD_SMTP_INVITATION_LIMIT_PER_HOUR | 单个账号每个滚动小时最多可发送的邀请邮件数。默认为 50。 |
修改后重建 cp-api：
docker compose up -d api
审计日志保留
cp-api 每天删除超过保留期限的审计事件。控制台和 Admin API 的审计日志只显示保留的数据。保留期限在整个部署层面设置，不能在控制台或 Admin API 中设置。
| 变量 | 作用 |
|---|---|
AISIX_CLOUD_AUDIT_RETENTION_DAYS | 审计事件被删除前保留的天数。默认为 730。0 表示永久保留审计事件。必须是大于或等于 0 的整数；取其他值时 cp-api 无法启动。 |
首次删除会在 cp-api 以支持该设置的版本启动时执行。如需保留超过 730 天的审计事件，请在升级前设置更大的值或 0。修改后重建 cp-api：
docker compose up -d api
控制台和端口
| 变量 | 作用 |
|---|---|
AISIX_DASHBOARD_LOCALE | 控制台以及 cp-api 所发邮件的默认语言，在语言选择器、组织语言和浏览器语言都未指定语言时使用。支持值为 en 和 zh。 |
AISIX_CLOUD_DEFAULT_LOCALE | 可选。设置后，控制台和邮件改用该值，而不是 AISIX_DASHBOARD_LOCALE。 |
POSTGRES_HOST_PORT | 随包 PostgreSQL 的宿主机端口绑定。 |
API_HOST_PORT | cp-api 的宿主机端口绑定，cp-api 同时提供 Admin API 和控制台。 |
DPM_HOST_PORT | dp-manager 的宿主机端口绑定。 |
如果某个服务只应绑定到回环地址，请在宿主机端口前添加 127.0.0.1:。
Helm 配置值
api7/aisix-cp Chart 使用 Helm 配置值，而不是 Compose .env 文件。查看或安装 Chart 前，请先添加 API7 Helm 仓库：
helm repo add api7 https://charts.api7.ai
helm repo update
查看所有 Chart 配置值：
helm show values api7/aisix-cp --version 1.8.0
Chart 源码和发布包见 aisix-cp-1.8.0 Helm Chart 发布版本。
cp-api 和 dp-manager 的每项应用设置都是显式的 Helm 配置值。控制台由 cp-api 提供，因此控制台的设置也是 cp-api 的设置。Chart 会把每个组件的配置值渲染成该组件自己的配置文件，存放在 ConfigMap 中并以只读方式挂载；修改其中任一项后，helm upgrade 会滚动更新对应组件的 Pod。密钥永远不会写入 ConfigMap：数据库密码、主密钥、SMTP 密码和首个管理员的密码都通过 Kubernetes Secret 传入 Pod。
每个组件仍会读取它一直以来为每项设置读取的环境变量，且环境变量会覆盖配置文件。因此，此前通过 api.extraEnvVars 或 dpm.extraEnvVars 提供的设置在升级后依然有效，并且会覆盖现在用于配置该设置的 value。cp-api 和 dp-manager 会在启动时为每个被环境变量覆盖的设置记录一条警告。请把这类设置迁移到下文对应的配置值，并删除该环境变量。extraEnvVars 仅用于系统级变量，例如 TZ。
控制台不再是独立的工作负载，Chart 也没有 ui.extraEnvVars 配置值。对于从 1.5.0 版 Chart 升级的 release（1.5.0 的安装说明曾把额外的登录源站放在这里），1.6.x 和 1.7.x 版 Chart 会把其中的 AISIX_TRUSTED_ORIGINS 或 AISIX_AUTH_BEARER_SESSIONS 条目传给 cp-api。当前 Chart 不再这样做，请改为设置 api.trustedOrigins 或 api.bearerSessions，参见最初以 1.5.0 版 Chart 安装的 Helm Release。
通过 api.extraEnvVars 或 dpm.extraEnvVars 覆盖 Chart 自己在容器上设置的变量，只是为现有部署保留的兼容途径，且 extraEnvVars 中的值仍然优先。覆盖了 Chart 也会渲染的变量名时，Chart 会省略自己的同名条目，因此容器中每个变量名只出现一次。1.6.x 和 1.7.x 版 Chart 则会把 1.5.0 版 Chart 渲染的条目保留在这类覆盖之前，因此从它们升级的第一次 helm upgrade 会删除该变量。升级现有 release 之前，请参见将应用设置迁移到 Chart values。新安装请改为在 values.yaml 中设置该值。
镜像和服务
| Helm 配置项 | 作用 |
|---|---|
api.image.repository, api.image.tag | cp-api 镜像。 |
dpm.image.repository, dpm.image.tag | dp-manager 镜像。 |
api.replicaCount, dpm.replicaCount | 每个控制面组件的副本数。 |
api.affinity, dpm.affinity | 用于将副本分散到不同节点或故障域的 Kubernetes 调度规则。 |
api.nodeSelector, dpm.nodeSelector | 每个控制面组件的节点标签约束。 |
api.tolerations, dpm.tolerations | 每个控制面组件的 Kubernetes 污点容忍配置。 |
api.service.type, api.service.port, api.service.nodePort | cp-api 的 Kubernetes Service 设置，cp-api 同时提供 Admin API 和控制台。直接通过 NodePort 连接时使用明文 HTTP。 |
dpm.service.type, dpm.service.port, dpm.service.nodePort | dp-manager mTLS 端点的 Kubernetes Service 设置。 |
只有对应 Service 类型为 NodePort 时，Chart 才会渲染已配置的 nodePort。将该值留空可让 Kubernetes 动态分配端口。对于其他 Service 类型，Chart 会忽略该值。
cp-api 在同一端口上提供控制台和 Admin API，因此 <release>-api Service 是两者在所有路径上的入口。1.5.0 版 Chart 将控制台作为独立工作负载运行在 <release>-ui Service 之后，1.6.x 和 1.7.x 版 Chart 保留了该 Service 并将其指向 cp-api 的 Pod。当前 Chart 删除了它，因此升级前请把仍在使用它的 NodePort、Ingress 或反向代理改为指向 <release>-api Service。除非仅在可信私有网络中运行，否则请在该 Service 前终止 TLS。
控制面指标
cp-api 会通过独立的、仅集群内可达的监听器公开关于控制面写入路径的 Prometheus 指标。承载 Admin API 和控制台的 API 端口不提供这些指标，控制台也不会读取它们。指标名称使用 aisix_cp_ 前缀，以便在同一个 Prometheus 部署中与网关指标区分。
| 值 | 用途 |
|---|---|
api.metrics.enabled | 是否由 cp-api 提供 Prometheus 指标。默认 true，与网关 Chart 保持一致。 |
api.metrics.port | 指标监听器在容器内绑定的端口。默认 9090。 |
api.metrics.service.port | 暴露指标端点的独立 ClusterIP Service 的端口，抓取流量不会走 API Service。默认 9090。 |
api.metrics.service.annotations | 指标 Service 的额外注解，例如按注解发现目标的 Prometheus 所需的抓取提示。 |
api.metrics.serviceMonitor.enabled | 是否为指标 Service 创建 Prometheus Operator 的 ServiceMonitor。默认 false。 |
api.metrics.serviceMonitor.namespace | 创建 ServiceMonitor 的命名空间。留空则使用 Release 所在命名空间。 |
api.metrics.serviceMonitor.interval、api.metrics.serviceMonitor.scrapeTimeout | 抓取间隔（默认 30s）与超时。超时留空表示沿用 Prometheus 默认值。 |
api.metrics.serviceMonitor.labels | 额外标签，例如 Prometheus 用于筛选的 release 标签。 |
api.metrics.serviceMonitor.relabelings、api.metrics.serviceMonitor.metricRelabelings | 抓取时和指标级的 relabel 规则。 |
当 api.metrics.enabled 为 true 时，cp-api 会在 api.metrics.port 上通过 /metrics 提供 Prometheus 文本。设为 false 时，指标端口在 Pod 内不被绑定，而不只是移除相应的 Service。
api.metrics.port 必须与 cp-api 提供 Admin API 和控制台的端口 8080 不同；两个监听器使用相同地址时，cp-api 会拒绝启动。
目前导出两个指标，都用于反映一次控制面写入向数据面投影了多少内容：
| 指标 | 类型 | 标签 | 含义 |
|---|---|---|---|
aisix_cp_outbox_rows_per_transaction | Histogram | operation、declared | 一次控制面写入事务入队的资源 outbox 行数。operation 是已声明的扇出名称，未声明扇出时为 none。 |
aisix_cp_outbox_undeclared_fanout_total | Counter | — | 入队行数超过守卫阈值但未声明扇出的写入事务数。 |
控制面 URL
| Helm 配置项 | 作用 |
|---|---|
api.publicBaseURL | 面向浏览器的控制面源站。登录始终信任该源站，邀请链接和密码重置链接也指向它。单点登录用它生成服务提供方 URL，因此它必须是浏览器实际使用的 URL。当 cp-api 使用 NodePort 时，请将其设为该端口上外部可访问的源站，或前置 TLS 反向代理的源站。 |
api.dpmgrBaseURL | AISIX 网关主机可访问的 dp-manager mTLS 端点，需为 https:// URL，例如 https://dpm.example.com:7944，其主机可以是 DNS 名称或 IP 地址。当 dp-manager 使用 NodePort 时，请将其设为外部可访问的 HTTPS 端点。Chart 也会把该值传递给 dp-manager Deployment，后者会为该主机签发 TLS 服务器证书。 |
api.dpImage | 生成 AISIX Cloud 网关安装片段时展示的 AISIX 网关镜像。默认留空，表示下发与 cp-api 同一版本的网关 docker.io/api7/aisix:<version>。Docker 和 Compose 片段使用完整的镜像引用；Helm 片段只把其中的镜像仓库设置为 image.repository，镜像标签跟随所安装的 api7/aisix Chart 版本。 |
api.corsAllowedOrigins | 允许跨域调用 cp-api /api/* 路由（包括 /api/auth/*）的浏览器源站列表。默认为空，此时完全不写出 CORS 响应头。可接受的取值参见跨域浏览器访问。 |
api.trustedOrigins | 额外允许登录的浏览器源站列表，取值为裸源站（例如 https://console.example.com）或 https://*<suffix> 模式。api.publicBaseURL 的源站及其 loopback 对应源站会自动受信任。cp-api 无法识别为源站的条目会被记录到日志并忽略。 |
api.trustedProxies | 位于 cp-api 前方的反向代理，为 CIDR 列表，例如 10.0.0.0/8。cp-api 按客户端对登录和密码重置限流时，会信任这些代理传入的 X-Forwarded-For 请求头。默认为空，此时把建立连接的地址视为客户端，因此在 Ingress 之后所有用户共用一个限流额度。参见反向代理后的限流。 |
部署模式与首个管理员
| Helm 配置项 | 作用 |
|---|---|
api.deploymentMode | 默认为 on-premises。取值 saas 由 API7 托管服务使用，不支持用于自托管部署。参见部署模式。 |
api.domainVerification.dnsServer | 组织域名验证使用的 DNS 服务器，格式为 host:port。仅适用于 saas 模式。默认为空，表示使用 cp-api Pod 所配置的解析器。参见部署模式。 |
api.bootstrapAdmin.email | 首个管理员的邮箱地址，默认为 admin@example.com。设置为空字符串表示不创建管理员。 |
api.bootstrapAdmin.password | 首个管理员的初始密码，长度为 12 到 128 个字符，存放在 Chart 自己的 Secret 中。设置了 api.bootstrapAdmin.existingSecret 时忽略该值。默认留空，表示自动生成。 |
api.bootstrapAdmin.existingSecret、api.bootstrapAdmin.existingSecretKey | 保存初始密码的已有 Secret 及其中的键（默认为 bootstrap-admin-password）。 |
既未设置 password 也未设置 existingSecret 时，Chart 会生成一个随机密码，写入自己的 Secret 中的 bootstrap-admin-password 键，并在 helm upgrade 时读回该 Secret 以保持密码不变。安装说明会打印读取该密码的 kubectl 命令。
helm template 以及自行渲染 Chart 的 GitOps 工具（例如 Argo CD）无法读回已有的 Secret，因此每次渲染都会生成新的密码。此类部署请设置 api.bootstrapAdmin.password 或 api.bootstrapAdmin.existingSecret。
管理员只会在数据库中还没有任何用户的那次启动时创建一次，并且首次登录时必须修改密码。之后修改这些值不会产生任何效果。参见以首个管理员身份登录。
升级
| Helm 配置项 | 作用 |
|---|---|
api.allowUnsupportedUpgrade | 允许 cp-api 迁移上一次由低于本版本升级下限的版本运行过的数据库。默认值为 false。请仅在读过启动时的拒绝信息并备份数据库后再设置，升级完成后改回。参见升级下限闸门。 |
价格目录来源
| Helm 配置项 | 作用 |
|---|---|
api.pricesyncURL | cp-api 同步模型价格目录的 URL，格式为 models.dev 的 api.json。留空时使用 https://models.dev/api.json。当 cp-api 无法访问互联网时，可指向内部镜像。设置了 api.pricesyncSnapshotPath 时忽略该值。 |
api.pricesyncSnapshotPath | 在启动时从该快照文件加载一次价格目录，之后不再拉取。cp-api 镜像在 /etc/aisix/models-dev-snapshot.json.gz 自带一份快照。默认留空，表示在线同步；价格目录仍为空时同步失败，会加载这份自带快照。 |
私有网络目标
这些配置值对应私有网络访问中的变量。
| Helm 配置项 | 作用 |
|---|---|
api.outbound.ssrfProtection.enabled | 是否为 cp-api 的出站调用开启 SSRF 防护。默认不设置（null），跟随部署模式：on-premises 关闭，saas 开启。设置为 true 表示拒绝私有、内部和回环目标。 |
api.outbound.ssrfProtection.allowedHosts | 不受该防护约束的主机，每项写作 host、host:port 或 [v6addr]:port。默认为空。 |
它们取代了 api.playgroundAllowPrivateIPs、api.notifyAllowPrivateURLs、api.mcpSpecAllowPrivateURLs 和 api.guardrailTestConnectionAllowInsecure。仍设置了旧配置项的 Release（例如使用 helm upgrade --reuse-values 从 Chart 1.5.0 升级、带着该 Chart 中前两项默认值 false 的 Release）可以正常安装，但 cp-api 会忽略这些值并打印警告。因此，这类 Release 会允许访问私有目标，直到你设置 api.outbound.ssrfProtection.enabled=true。参见从 1.6.x 或更早版本升级。
邮件
cp-api 通过 SMTP 中继发送邀请邮件、密码重置邮件和设置密码链接。在设置 api.smtp.host 之前，邮件功能处于关闭状态。示例和各项设置的行为参见配置邮件（SMTP）。
| Helm 配置项 | 作用 |
|---|---|
api.smtp.host | 中继主机名。默认留空，表示关闭邮件功能。 |
api.smtp.tls | starttls（默认）、smtps 或 none。 |
api.smtp.port | 中继端口。默认值 0 表示按 TLS 模式取 587、465 或 25。 |
api.smtp.from | 发件人地址。设置了主机时必填。 |
api.smtp.username | SMTP 身份认证的用户名。需与密码同时设置；两者都留空表示不认证直接发送。 |
api.smtp.password | SMTP 密码，存放在 Chart 自己的 Secret 中。设置了 api.smtp.existingSecret 时忽略该值。 |
api.smtp.existingSecret、api.smtp.existingSecretKey | 保存 SMTP 密码的已有 Secret 及其中的键（默认为 smtp-password）。 |
api.smtp.invitationLimitPerHour | 单个账号在所有组织中每个滚动小时最多可发送的邀请邮件数。默认为 50，最小为 1。 |
审计日志保留
cp-api 每天删除超过保留期限的审计事件。此设置不在控制台或 Admin API 中提供。
| Helm 配置项 | 作用 |
|---|---|
api.audit.retentionDays | 审计事件被删除前保留的天数。默认为 730。0 表示永久保留审计事件。必须是大于或等于 0 的整数；取其他值时 cp-api 无法启动。 |
首次删除会在 cp-api 以支持该设置的版本启动时执行。如需保留超过 730 天的审计事件，请在同一次 helm upgrade 中设置更大的值或 0。
密钥
| Helm 配置项 | 作用 |
|---|---|
secrets.masterKey | Base64 编码的 32 字节 AES 密钥，用于信封加密。 |
secrets.masterKeyID | 与加密数据一起存储的标识，用于让控制面识别包装密钥。 |
secrets.retiredMasterKeys | 主密钥轮换期间保留的仅用于解密的主密钥，为从密钥记录时所用的密钥 ID 到 Base64 编码密钥的映射。ID 由小写字母、数字、: 和 - 组成。轮换时，将原主密钥及其 ID 移入该映射，再设置新的主密钥及 ID。新写入的值使用当前主密钥；轮换前加密的值在被重写前仍可能依赖已退役密钥。 |
安装前请替换 Chart 中的占位 主密钥。Chart 会拒绝占位密钥值。
请保留并备份每个已退役的主密钥。控制面目前不提供检查所有存储加密值或将其全部迁移至活动密钥的命令。如果某个存储值仍依赖退役密钥，移除该密钥会使该值无法读取。不要仅根据退役时间或已写入的新值数量决定移除密钥。
PostgreSQL
| Helm 配置项 | 作用 |
|---|---|
postgresql.builtin | 设置为 true 时部署随包 PostgreSQL Chart。 |
postgresql.auth.password | 随包 Chart 所配置 PostgreSQL 用户的密码。即使应用使用 postgres 用户连接，Chart 也要求提供非占位值。 |
postgresql.auth.postgresPassword | PostgreSQL 超级用户密码。Chart 默认使用该密码建立控制面连接。 |
postgresql.auth.usePostgresUserForAppConnections | 控制面连接使用 postgres 用户，默认值为 true。 |
postgresql.auth.existingSecret | 用于随包 PostgreSQL 凭证的已有 Kubernetes Secret。 |
externalDatabase.* | 当 postgresql.builtin=false 时，用于已有 PostgreSQL 数据库的顶层配置值。 |
twoDSN.enabled | 保持默认值 false。该值为 true 时，Helm 首先要求设置 twoDSN.existingSecret，或设置非空且不以 CHANGE_ME 开头的 twoDSN.servingPassword。通过该检查后，Chart 会以 database.admin_url 提供第二个数据库 URL。在 on-premises 模式下，cp-api 会因该 URL 拒绝启动，原因写在它的 Pod 日志中。 |
externalDatabase.sslmode | 外部数据库连接的 libpq sslmode，例如 require 或 verify-full。默认值为 disable。 |
externalDatabase.sslRootCert.existingSecret | 已有 Secret 的名称，其中存放签发数据库服务器证书的 PEM CA 证书包。cp-api 和 dp-manager 用它校验服务器。默认值为空，即由镜像的系统信任库完成校验。参见信任私有数据库 CA。 |
externalDatabase.sslRootCert.key | 该 Secret 中存放 CA 证书包的 key。默认值为 ca.crt。 |
Chart 构造的每个 postgres:// 连接 URL 都不包含密码。每个组件会从 Kubernetes Secret 读取密码，并在启动时对其进行百分号编码后拼入 URL，因此密码可以包含 +、/、= 等字符。
控制台语言
| 值 | 用途 |
|---|---|
ui.defaultLocale | 控制台和 cp-api 邮件的默认语言。支持 en 和 zh，默认为 en。当语言选择器、组织语言和浏览器语言均未指定英语或中文时，使用该回退值。参见控制台语言。 |
跨域浏览器访问
AISIX_CLOUD_CORS_ALLOWED_ORIGINS 和 api.corsAllowedOrigins 接受相同的取值。常规安装两者都不需要：cp-api 同时提供 API 和控制台，浏览器只有一个源站，不会产生跨域。只有当页面由其他 Origin 提供、需要直接调用 /api/* 时，才需要配置它；允许列表同时覆盖 Admin API 和 /api/auth/* 下的登录路由。
如果用户从该 Origin 登录，还需将 Origin 添加到受信任的登录源站：Docker Compose 使用 AISIX_TRUSTED_ORIGINS，Helm 使用 api.trustedOrigins。CORS 允许浏览器访问路由，受信任 Origin 设置则允许 cp-api 接受来自该 Origin 的登录及其他基于会话的变更请求。
使用 Helm 时，将控制台 Origin 同时加入两个设置：
api:
corsAllowedOrigins:
- https://dashboard.example.com
# 用户从此 Origin 登录时必需。
trustedOrigins:
- https://dashboard.example.com
每个条目为以下两种形式之一：
- 裸源站
https://host或https://host:port，按浏览器在Origin请求头中序列化的写法书写。scheme 和主机为小写，不带路径、查询、片段、结尾斜杠和结尾点；省略该 scheme 的默认端口，端口不带前导零。国际化域名需写成 punycode 形式，IPv6 地址需写成浏览器发送的方括号形式，最后一段为数字的主机必须本身就是点分十进制 IPv4 地址。只接受https，但localhost、127.0.0.1和::1也接受http。 - 后缀模式
https://*加一个主机后缀，用于主机名随部署变化的控制台。后缀以.或-开头，至少包含三段标签，且不带端口、路径、查询、片段和结尾点。它按字节后缀匹配，而不是按 DNS 边界匹配，因此它能约束书写失误，但不能保证共享托管域名上没有其他人申请到匹配的名称。
裸 * 会被拒绝，任何不可能等于浏览器 Origin 的取值同样会被拒绝。cp-api 会在取值不符合该语法时拒绝启动，并指出该条目的位置和它违反的规则。允许的 Origin 的响应不会携带 Access-Control-Allow-Credentials，因此其他 Origin 上的页面无法随请求发送已登录用户的会话 Cookie。
Chart 在渲染时应用与 cp-api 启动时相同的语法校验，因此 Chart 接受的取值就是控制面能够启动的取值。