On-Premises 配置
On-Premises 部署可通过 Docker Compose .env 文件或 Helm 配置值进行配置，具体取决于控制面的安装方式。
需要查看或自定义生成的部署配置时，请结合 On-Premises 安装 阅读本参考。
请将这些设置与匹配的数据库备份一起保留。完整恢复集和恢复顺序请参阅备份与恢复。
这些设置用于配置私有化控制面部署包，与 AISIX 网关运行时环境变量不同。网关运行时变量请参见环境变量。
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 的可选镜像覆盖项。 |
AISIX_DPM_IMAGE | dp-manager 的可选镜像覆盖项。 |
AISIX_UI_IMAGE | 控制台的可选镜像覆盖项。 |
AISIX_CLOUD_DP_IMAGE | 生成网关安装片段时使用的可选 AISIX 网关镜像覆盖项。 |
单独设置的镜像覆盖项会在部署包升级后继续生效。
数据库
| 变量 | 作用 |
|---|---|
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 | 与加密数据一起存储的标识，用于让控制面识别包装密钥。 |
BETTER_AUTH_SECRET | 控制台身份认证的会话签名密钥。 |
除非正在执行主密钥轮换流程，否则不要修改已有部署中的 AISIX_CLOUD_MASTER_KEY。如果修改时没有保留旧密钥，已加密数据可能无法读取。
恢复缺失的 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。登录时会根据该值校验会话签发方。 |
AISIX_CLOUD_DPMGR_BASE_URL | AISIX 网关主机可访问的 dp-manager mTLS 端点，需为 https:// URL，例如 https://dpm.example.com:7944，其主机可以是 DNS 名称或 IP 地址。 |
AISIX_CLOUD_DASHBOARD_URL | cp-api 使用的内部控制台 URL。Compose 默认指向 dashboard 服务。 |
AISIX_TRUSTED_ORIGINS | 允许登录的其他浏览器源站，以逗号分隔。公共基础 URL 及其回环对应地址会自动受信任。 |
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 即可初始化模型价格。
部署包通过 .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 会拒绝以下出站连接。仅为受信任且 cp-api 可以访问的网络中的服务启用必要权限。
| 变量 | 作用 |
|---|---|
AISIX_PLAYGROUND_ALLOW_PRIVATE_IPS | 设置为 1 时，允许控制台 Playground 访问私有、内部或回环地址上的 LLM 端点。该项默认关闭，用作 SSRF 防护；仅在自托管模型位于内网时启用。参见 Playground。 |
AISIX_CLOUD_NOTIFY_ALLOW_PRIVATE_URLS | 设置为 true 时，允许预算通知访问私有 Webhook 接收器或 Slack 代理。 |
AISIX_CLOUD_MCP_SPEC_ALLOW_PRIVATE_URLS | 设置为 true 时，允许控制面从私有 spec_url 获取 MCP 服务器的 OpenAPI 文档。如果文档位于私有 URL 且此设置保持关闭，请改为提供 spec_content。 |
在 .env 中设置所需变量，然后重新创建 cp-api：
docker compose up -d api
控制台和端口
| 变量 | 作用 |
|---|---|
AISIX_DASHBOARD_LOCALE | 部署使用的控制台语言。支持值为 en 和 zh。 |
POSTGRES_HOST_PORT | 随包 PostgreSQL 的宿主机端口绑定。 |
API_HOST_PORT | cp-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.4.0
Chart 源码和软件包发布在 aisix-cp-1.4.0 Helm Chart Release 中。
镜像和服务
| Helm 配置项 | 作用 |
|---|---|
api.image.repository, api.image.tag | cp-api 镜像。 |
dpm.image.repository, dpm.image.tag | dp-manager 镜像。 |
ui.image.repository, ui.image.tag | 控制台镜像。 |
api.replicaCount, dpm.replicaCount, ui.replicaCount | 每个控制面组件的副本数。 |
api.affinity, dpm.affinity, ui.affinity | 用于将副本分散到不同节点或故障域的 Kubernetes 调度规则。 |
api.nodeSelector, dpm.nodeSelector, ui.nodeSelector | 每个控制面组件的节点标签约束。 |
api.tolerations, dpm.tolerations, ui.tolerations | 每个控制面组件的 Kubernetes 污点容忍配置。 |
api.service.type, api.service.port, api.service.nodePort | cp-api 的 Kubernetes Service 设置。直接通过 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 | 位于 cp-api 后方的控制台服务设置。直接通过 NodePort 连接时使用明文 HTTP。 |
只有对应 Service 类型为 NodePort 时，Chart 才会渲染已配置的 nodePort。将该值留空可让 Kubernetes 动态分配端口。对于其他 Service 类型，Chart 会忽略该值。
运维人员通常通过 cp-api 访问控制台，由 cp-api 将控制台流量代理到 UI Service。不要把 UI NodePort 用作独立的控制台入口。如果外部同源代理将其用作上游，请将控制台页面路由到 UI Service，并将 /api/* 请求路由到 cp-api。除非该代理仅在可信私有网络中运行，否则请在代理上终止 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 时，Chart 会在 cp-api Deployment 上设置 AISIX_CLOUD_METRICS_LISTEN，并通过 /metrics 提供 Prometheus 文本。设为 false 时则不设置该环境变量，使指标端口在 Pod 内不被绑定，而不只是移除相应的 Service。
指标地址必须与 AISIX_CLOUD_LISTEN 不同；两个监听器使用相同地址时，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 | 面向浏览器的控制面源站。当 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 网关镜像。 |
api.corsAllowedOrigins | 允许跨域调用 cp-api /api/* 路由（包括 /api/auth/*）的浏览器源站列表。默认为空，此时完全不写出 CORS 响应头。跨域登录还需将源站添加到 AISIX_TRUSTED_ORIGINS。可接受的取值参见跨域浏览器访问。 |
Playground
| Helm 配置项 | 作用 |
|---|---|
api.playgroundAllowPrivateIPs | 允许控制台 Playground 访问私有、内部或回环地址上的 LLM 端点。默认值为 false，用作 SSRF 防护。 |
通知目标
| Helm 配置项 | 作用 |
|---|---|
api.notifyAllowPrivateURLs | 允许 cp-api 向私有、内部或回环地址发送预算通知。默认值为 false，用作 SSRF 防护。 |
密钥
| Helm 配置项 | 作用 |
|---|---|
secrets.masterKey | Base64 编码的 32 字节 AES 密钥，用于信封加密。 |
secrets.masterKeyID | 与加密数据一起存储的标识，用于让控制面识别包装密钥。 |
secrets.betterAuthSecret | 控制台身份认证的会话签名密钥。 |
安装前请替换 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 数据库的顶层配置值。 |
请使用 URL 安全的 PostgreSQL 密码，例如 openssl rand -hex 24 生成的值，因为 Chart 会根据配置的凭证构造 postgres:// 连接 URL。
控制台的私有 PostgreSQL CA
从 aisix-cp chart 1.2.1（应用版本 1.2.0）开始，可通过 ui.extraVolumes 和 ui.extraVolumeMounts 为控制台挂载私有数据库 CA。两者默认为空列表，配置的内容会追加到内置 Next.js 缓存卷和挂载之后。
如果外部 PostgreSQL 使用私有 CA，控制台的 Node.js 客户端必须信任该 CA。否则，即使控制台页面能够加载，注册和登录仍可能因 SELF_SIGNED_CERT_IN_CHAIN 而失败。
在控制台所在命名空间创建 ConfigMap，存放 PEM 格式的公开 CA 证书。以下示例的 release 和命名空间均为 aisix-cp，请替换为实际部署名称：
kubectl create configmap aisix-postgres-ca \
--namespace aisix-cp --from-file=ca.crt=./ca.crt
将以下设置合并到现有 Helm values 文件中，保留数据库配置及三个 ui 列表中已有的条目：
ui:
extraEnvVars:
- name: NODE_EXTRA_CA_CERTS
value: /etc/aisix/postgres-ca/ca.crt
extraVolumes:
- name: postgres-ca
configMap:
name: aisix-postgres-ca
items:
- key: ca.crt
path: ca.crt
extraVolumeMounts:
- name: postgres-ca
mountPath: /etc/aisix/postgres-ca
readOnly: true
使用 Secret 时，将 configMap 块替换为：
secret:
secretName: aisix-postgres-ca
items:
- key: ca.crt
path: ca.crt
该 Secret 也必须位于同一命名空间。这里只需要公开 CA 证书，CA 私钥应保留在证书签发方。卷名和挂载路径必须唯一，内置缓存使用的 next-cache 和 /app/.next/cache 应予以保留。这些设置仅影响控制台；其他控制面组件的数据库 TLS 配置需按实际情况单独设置。
使用支持这些字段的 chart 版本应用 values，并保持 PostgreSQL TLS 证书验证开启。将证书资源和 values 纳入部署配置源，确保后续 GitOps 同步保留挂载。
更新或轮换 CA 后，需要重启控制台，让 Node.js 重新加载 NODE_EXTRA_CA_CERTS。外部 ConfigMap 或 Secret 变化时，chart 不会自动重启 Pod：
kubectl rollout restart deployment/aisix-cp-ui --namespace aisix-cp
kubectl rollout status deployment/aisix-cp-ui --namespace aisix-cp
控制台语言
| Helm 配置项 | 作用 |
|---|---|
ui.defaultLocale | 部署使用的控制台语言。支持值为 en 和 zh。 |
跨域浏览器访问
AISIX_CLOUD_CORS_ALLOWED_ORIGINS 和 api.corsAllowedOrigins 接受相同的取值。常规安装两者都不需要：cp-api 提供 API 并代理控制台，浏览器只有一个源站，不会产生跨域。只 有当控制台由其他 Origin 提供、需要直接调用 /api/* 时，才需要配置它；允许列表同时覆盖 Admin API 和 /api/auth/* 下的 Better Auth 路由。
如果用户从该控制台 Origin 登录，还需将 Origin 添加到 AISIX_TRUSTED_ORIGINS。CORS 允许浏览器访问路由，受信任 Origin 设置则允许 Better Auth 接受登录 Origin。
使用 Helm 时，将控制台 Origin 同时加入两个设置：
api:
corsAllowedOrigins:
- https://dashboard.example.com
ui:
extraEnvVars:
# 用户从此 Origin 登录时必需。
- name: AISIX_TRUSTED_ORIGINS
value: 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；控制台通过请求头附加 API 和会话凭据。
Chart 在渲染时应用与 cp-api 启动时相同的语法校验，因此 Chart 接受的取值就是控制面能够启动的取值。