On-Premises 配置

On-Premises 部署可通过 Docker Compose .env 文件或 Helm values 进行配置，具体取决于控制面的安装方式。

需要查看或自定义生成的部署配置时，请结合 On-Premises 安装阅读本参考。

这些设置用于配置私有化控制面部署包，与 AISIX 网关运行时环境变量不同。网关运行时变量请参见环境变量。

Docker Compose 环境变量

Docker Compose 部署包会从 ./aisix-self-hosted/.env 读取环境变量。快速开始脚本和离线包会在首次启动时生成该文件，并在后续部署包刷新时保留它。

镜像和发布版本

变量	作用
`AISIX_VERSION`	控制面镜像使用的发布版本标签。
`AISIX_API_IMAGE`	`cp-api` 的可选镜像覆盖项。
`AISIX_DPM_IMAGE`	`dp-manager` 的可选镜像覆盖项。
`AISIX_UI_IMAGE`	控制台的可选镜像覆盖项。
`AISIX_CLOUD_DP_IMAGE`	生成 AISIX Cloud 网关安装片段时展示的 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。如果修改时没有保留旧密钥，已加密数据可能无法读取。

运行时 URL

变量	作用
`AISIX_CLOUD_PUBLIC_BASE_URL`	面向浏览器的控制面源站，例如 `https://aisix.example.com`。登录时会根据该值校验会话签发方。
`AISIX_CLOUD_DPMGR_BASE_URL`	AISIX 网关主机可访问的 `dp-manager` mTLS 端点，可以是 DNS 名称或 IP 地址。
`AISIX_CLOUD_DASHBOARD_URL`	`cp-api` 使用的内部控制台 URL。Compose 默认指向 dashboard 服务。
`AISIX_TRUSTED_ORIGINS`	允许登录的其他浏览器源站，以逗号分隔。公共基础 URL 及其回环对应地址会自动受信任。

在将部署暴露到本地主机或容器网络之外前，请设置 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 即可初始化模型价格。

以下是 docker-compose.yaml 中的服务级设置，不会直接暴露在生成的 .env 文件中：

`api` 服务设置	作用
`AISIX_CLOUD_PRICESYNC_SNAPSHOT_PATH`	从镜像内快照初始化模型价格，并禁用在线同步。
`AISIX_CLOUD_PRICESYNC_URL`	在在线定价模式下覆盖 `models.dev` 目录 URL。

如需使用在线定价，请从 api 服务中移除 AISIX_CLOUD_PRICESYNC_SNAPSHOT_PATH。可以选择添加 AISIX_CLOUD_PRICESYNC_URL 指向内部镜像，然后重新创建该服务。

Playground

变量	作用
`AISIX_PLAYGROUND_ALLOW_PRIVATE_IPS`	设置为 `1` 时，允许控制台 Playground 访问私有、内部或回环地址上的 LLM 端点。该项默认关闭，用作 SSRF 防护；仅在自托管模型位于内网时启用。参见 Playground。

通知目标

AISIX_CLOUD_NOTIFY_ALLOW_PRIVATE_URLS 允许 cp-api 向私有、内部或回环地址发送预算通知。该设置默认禁用，以防范 SSRF。随包提供的 Compose 文件不会在生成的 .env 文件中暴露该设置，默认也不会把它传给 cp-api。

要启用私有通知目标，请在 docker-compose.yaml 的 services.api.environment 下添加该设置，然后重新创建 api 服务：

services:
  api:
    environment:
      AISIX_CLOUD_NOTIFY_ALLOW_PRIVATE_URLS: "true"

只有当受信任的 Webhook 接收器或 Slack 代理位于内部网络时才应启用。

控制台和端口

变量	作用
`AISIX_DASHBOARD_LOCALE`	部署使用的控制台语言。支持值为 `en` 和 `zh`。
`POSTGRES_HOST_PORT`	随包 PostgreSQL 的宿主机端口绑定。
`API_HOST_PORT`	`cp-api` 和控制台反向代理的宿主机端口绑定。
`DPM_HOST_PORT`	`dp-manager` 的宿主机端口绑定。

如果某个服务只应绑定到回环地址，请在宿主机端口前添加 127.0.0.1:。

Helm Values

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

Chart 源码和配置值发布在 api7/api7-helm-chart 仓库中。

镜像和服务

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`	`cp-api` 的 Kubernetes Service 设置。
`dpm.service.type`, `dpm.service.port`	`dp-manager` 的 Kubernetes Service 设置。
`ui.service.type`, `ui.service.port`	位于 `cp-api` 后方的控制台服务设置。

控制面 URL

Helm 配置项	作用
`api.publicBaseURL`	面向浏览器的控制面源站。
`api.dpmgrBaseURL`	AISIX 网关主机可访问的 `dp-manager` mTLS 端点，可以是 DNS 名称或 IP 地址。Chart 也会把该值传递给 `dp-manager` Deployment，后者会为该主机签发 TLS 服务器证书。
`api.dpImage`	生成 AISIX Cloud 网关安装片段时展示的 AISIX 网关镜像。

Playground

Helm 配置项	作用
`api.playgroundAllowPrivateIPs`	允许控制台 Playground 访问私有、内部或回环地址上的 LLM 端点。默认值为 `false`，用作 SSRF 防护。
`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 数据库的顶层 values。

请使用 URL 安全的 PostgreSQL 密码，例如 openssl rand -hex 24 生成的值，因为 Chart 会根据配置的凭证构造 postgres:// 连接 URL。

控制台语言

Helm 配置项	作用
`ui.defaultLocale`	部署使用的控制台语言。支持值为 `en` 和 `zh`。

Docker Compose 环境变量​

镜像和发布版本​

数据库​

密钥​

运行时 URL​

价格目录​

Playground​

通知目标​

控制台和端口​

Helm Values​

镜像和服务​

控制面 URL​

Playground​

密钥​

PostgreSQL​

控制台语言​

Docker Compose 环境变量

镜像和发布版本

数据库

密钥

运行时 URL

价格目录

Playground

通知目标

控制台和端口

Helm Values

镜像和服务

控制面 URL

Playground

密钥

PostgreSQL

控制台语言