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。