On-Premises 配置
On-Premises 部署可通过 Docker Compose .env 文件或 Helm 配置值进行配置，具体取决于控制面的安装方式。
需要查看或自定义生成的部署配置时，请结合 On-Premises 安装 阅读本参考。
请将这些设置与匹配的数据库备份一起保留 。完整恢复集和恢复顺序请参阅备份与恢复。
这些设置用于配置私有化控制面部署包，与 AISIX 网关运行时环境变量不同。网关运行时变量请参见环境变量。
部署模式
cp-api 以两种部署模式之一运行。该模式在 cp-api 配置文件中为 deployment.mode，对应环境变量 AISIX_CLOUD_DEPLOYMENT_MODE 和 Helm 配置值 api.deploymentMode。默认值为 on-premises，这也是自托管部署唯一支持的模式。另一个取值 saas 是 API7 托管服务使用的模式，不支持在你自己托管的部署中使用。设置为其他任何值时，cp-api 会拒绝启动。
在 on-premises 模式下，cp-api 会强制执行以下规则，控制台也会隐藏不适用的内容：
- 任何人都不能自行注册。账号只能通过邀请创建：受邀者通过邀请中的链接注册。参见邀请成员。没有有效邀请的注册请求会被拒绝，返回
403 SIGN_UP_DISABLED或403 INVITATION_INVALID。 - 任何人都不能创建组织。第一个组织随首个管理员一同创建。创建其他组织的请求会被拒绝，返回
403 ORG_CREATION_DISABLED。从 1.5.x 或更早版本升级、仍包含多个组织的控制面，会以403 ORG_CONSOLIDATION_REQUIRED拒绝控制台请求，直到某个 Owner 保留其中一个组织并删除其余组织。参见将多个组织合并为一个。 - 没有计费页面和套餐。
- 注册时不要求受邀者接受托管服务条款。
cp-api自身的出站调用可以访问私有地址，除非你禁止。参见私有网络访问。
Docker Compose 部署包不会把该变量传给 cp-api，因此部署包安装始终以 on-premises 模式运行。
saas 模式有其自身的要求和配置项，它们不适用于 on-premises 控制面：
- 它要求配置 SMTP 中继，因为每个新账号都必须验证邮箱地址。
saas模式下smtp.host（AISIX_CLOUD_SMTP_HOST）为空时，cp-api拒绝启动；api.smtp.host为空时，Helm Chart 拒绝渲染。 domain_verification.dns_server（AISIX_CLOUD_DOMAIN_VERIFICATION_DNS_SERVER，Helm 配置值api.domainVerification.dnsServer）是组织域名验证发送 TXT 查询所用的 DNS 服务器，格式为host:port。该项可选，默认为空，表示使用系统解析器。on-premises控制面没有组织域名，会忽略该项；但如果设置了该值且不是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}，即同一版本的网关。 |
单独设置的镜像覆盖项会在部署包升级后继续生效。
数据库
| 变量 | 作用 |
|---|---|
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://*<后缀> 模式。公共基础 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 文件。
私有网络访问
默认情况下，on-premises 控制面的以下出站连接可以访问私有、内部和回环地址，因此位于内网的模型、Webhook 接收器和文档无需额外配置即可使用。每个变量为一类连接覆盖该默认值。当控制面的操作者不应能借助它访问你 的内网时，将其设置为 false 以拒绝私有目标，作为服务端请求伪造（SSRF）防护。
| 变量 | 作用 |
|---|---|
AISIX_PLAYGROUND_ALLOW_PRIVATE_IPS | 控制台 Playground 是否可以访问位于私有地址上的服务提供方密钥的 api_base。参见 Playground。 |
AISIX_CLOUD_NOTIFY_ALLOW_PRIVATE_URLS | 预算通知是否可以访问私有 Webhook 接收器或 Slack 代理。 |
AISIX_CLOUD_MCP_SPEC_ALLOW_PRIVATE_URLS | 控制面是否可以从私有 spec_url 获取 MCP 服务器的 OpenAPI 文档。不允许时，请改为提供 spec_content。 |
AISIX_GUARDRAIL_TEST_CONNECTION_ALLOW_INSECURE | 护栏连接测试是否可以访问明文 HTTP 端点、私有地址以及 Azure 以外的主机，例如内部端点或 Private Link 端点。 |
每个变量接受 true、false、1、0、yes、no、on 或 off，不区分大小写。值为空或未设置时跟随部署模式，其他任何值都会使 cp-api 在启动时报错退出。
在 .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.6.0
Chart 源码和软件包发布在 aisix-cp-1.6.0 Helm Chart Release 中。
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。
控制台不再是独立的工作负载，因此 ui.extraEnvVars 本身不配置任何内容。保留它是为了兼容从 1.5.0 版 Chart 升级的 release，1.5.0 的安装说明曾把额外的登录源站放在这里：其中的 AISIX_TRUSTED_ORIGINS 条目仍会传给 cp-api，除非 api.extraEnvVars 设置了同名变量。请把这类条目迁移到 api.trustedOrigins。
通过 api.extraEnvVars 或 dpm.extraEnvVars 覆盖 Chart 自己在容器上设置的变量，只是为现有部署保留的兼容途径，且 extraEnvVars 中的值仍然优先。对于 1.5.0 版 Chart 已渲染的变量名，Chart 会把自己的条目保留在你的条目之前，因此容器中会出现两个同名条目，而 Helm 4 的 server-side apply 会拒绝这种情况。新安装请改为在 values.yaml 中设置该值。从现有 release 中删除这类覆盖需要运行两次 helm upgrade，参见将应用设置迁移到 Chart values。
镜像和服务
| 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 设置。 |
ui.service.type, ui.service.port, ui.service.nodePort | 为从 1.5.0 版 Chart 升级的 release 保留的 <release>-ui Service，现在转发到 cp-api。直接通过 NodePort 连接时使用明文 HTTP。 |
只有对应 Service 类型为 NodePort 时，Chart 才会渲染已配置的 nodePort。将该值留空可让 Kubernetes 动态分配端口。对于其他 Service 类型，Chart 会忽略该值。
cp-api 在同一端口上提供控制台和 Admin API，因此 cp-api Service 是两者的入口。1.5.0 版 Chart 将控制台作为独立工作负载运行在 <release>-ui Service 之后。该 Service 保留其名称、类型、端口和 nodePort，但现在选择 cp-api 的 Pod，因此仍指向它的反向代理等组件无需修改即可继续工作。新安装请使用 cp-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>。 |
api.corsAllowedOrigins | 允许跨域调用 cp-api /api/* 路由（包括 /api/auth/*）的浏览器源站列表。默认为空，此时完全不写出 CORS 响应头。可接受的取值参见跨域浏览器访问。 |
api.trustedOrigins | 额外允许登录的浏览器源站列表，取值为裸源站（例如 https://console.example.com）或 https://*<后缀> 模式。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 自带一份快照。默认留空，表示在线同步；价格目录仍为空时同步失败，会加载这份自带快照。 |
私有网络目标
这些配置值对应私有网络访问中的变量。每项默认不设置（null），在 on-premises 模式下允许私有、内部和回环目标。设置为 false 表示拒绝，设置为 true 表示显式允许。
| Helm 配置项 | 作用 |
|---|---|
api.playgroundAllowPrivateIPs | 控制台 Playground 是否可以访问私有地址上的 LLM 端点。 |
api.notifyAllowPrivateURLs | cp-api 是否可以向私有地址发送预算通知。 |
api.mcpSpecAllowPrivateURLs | 控制面是否可以从解析 到私有地址的 spec_url 获取 MCP 服务器的 OpenAPI 文档。无论是否允许，都可以直接提供 spec_content。 |
api.guardrailTestConnectionAllowInsecure | 护栏连接测试是否可以访问明文 HTTP 端点、私有地址以及 Azure 以外的主机。 |
使用 helm upgrade --reuse-values 从 Chart 1.5.0 升级的 Release，仍会把该 Chart 中 api.playgroundAllowPrivateIPs 和 api.notifyAllowPrivateURLs 的默认值 false 作为显式值保留，因此在清除这两项之前，它们仍会拒绝私有目标。参见从 1.5.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 会拒绝占位密钥值。
请保留并备份所有已退役的主密钥。AISIX Cloud 目前没有检查全部已存储加密数据或将其全部迁移至当前主密钥的命令。如果某项数据仍依赖已退役的密钥，删除该密钥会导致该数据无法读取。不要仅凭密钥退役时长或新写入数据的数量决定删除密钥。
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 数据库的顶层配置值。 |
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，因此密码可以包含 +、/、= 等字符。
控制台语言
| Helm 配置项 | 作用 |
|---|---|
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 接受的取值就是控制面能够启动的取值。