私有化安装
使用 Docker Compose、Helm 或离线包，在你运营的基础设施中安装 AISIX Cloud 控制面。本指南可帮助你选择安装方式、配置控制面端点，并验证持久化环境。
该安装方式提供与混合云相同的 AISIX Cloud 控制面工作流，包括资源管理、网关证书签发 、用量上报和预算执行。控制面服务及数据均保留在你的基础设施中，也支持完全隔离的内网环境。
如需在本地评估环境中继续创建网关资源并发送第一个 AI 请求，请改用 AISIX Cloud 快速入门。
在生产环境中使用 AISIX Cloud 控制面和控制台需要商业许可证。在生产环境中部署控制面前，请联系 API7，或发送邮件至 support@api7.ai。
规划安装
根据目标基础设施和网络访问条件选择安装方式：
| 安装方式 | 目标环境 | 要求 |
|---|---|---|
| Docker Compose | 可访问互联网的主机 | Docker 与 Docker Compose V2、cURL、tar、OpenSSL，以及 Docker Hub 访问权限 |
| Helm | 可访问互联网的 Kubernetes 集群 | 可用的集群、Helm、kubectl、OpenSSL，以及 Docker Hub 访问权限 |
| 离线部署包 | 隔离网络主机 | Docker 与 Docker Compose V2、tar、OpenSSL，以及一台可以 使用 cURL 下载部署包的独立机器 |
使用 Helm 安装前，请决定使用随包提供的 PostgreSQL 数据库，还是使用外部数据库。Docker Compose 和离线部署包只能使用随包数据库。还需确定公开控制台源站，以及网关要连接的数据面管理器端点。可以先使用本地端点，但在公开控制台或连接其他主机上的网关前，必须配置外部可访问的端点。
Docker Compose 安装默认使用主机端口 5432、8080 和 7944。请确保这些端口可用，或配置其他主机端口映射。有关各组件、流量方向和建议暴露方式，请参阅端口参考。
控制面组件
每种安装方式都包含以下组件：
| 服务 | 作用 |
|---|---|
cp-api | 管理组织、环境、资源和计费，处理控制台登录，并提供控制台 |
dp-manager | 签发 mTLS 证书，并向数据面下发配置 |
| PostgreSQL 数据库 | 共享数据存储。Docker Compose 部署包包含该数据库；Helm 可以部署随包数据库，也可以连接外部数据库。 |
控制台不是独立的服务：它的文件包含在 cp-api 镜像中，由 cp-api 在与 Admin API 相同的端口上提供。
在线和离线 Docker Compose 部署包必须使用随包提供的 PostgreSQL 16 服务。Helm Chart 可以部署随包 PostgreSQL 实例，也可以连接外 部数据库。
AISIX 网关会作为数据面单独运行。数据面通过 mTLS 主动连接到 dp-manager，因此控制面不需要能够入站访问网关主机。
生产资源建议基线
以下规格是部署容量规划的起点，不是 Helm Chart 的默认值、基准测试得出的容量保证，也不是适用于所有工作负载的固定下限。请根据请求速率、请求大小、已启用的流量控制策略、网关数量以及数据保留期进行压测和调整。
在主机上使用 Docker Compose 或离线部署包
在线和离线 Docker Compose 部署包提供单主机拓扑，为每个控制面服务启动一个实例，并启动随包提供的 PostgreSQL 数据库。它们不支持外部数据库，也不提供控制面高可用所需的多主机服务配置。
生产高可用拓扑请使用 Helm，并参考下表中的实例数量。使用部署包进行评估或非高可用部署时，可以根据 CPU、内存和存储列评估主机容量。
CPU、内存和主机存储均按单个组件实例计算。主机存储是为操作系统、容器镜像、平台管理的日志以及组件本地状态预留的主机容量，不等同于 Kubernetes 中应用持久卷的容量要求。
| 组件 | CPU | 内存 | 主机存储 | 起始实例数 | 规划说明 |
|---|---|---|---|---|---|
| AISIX 网关 | 4 核 | 8–16 GB | ≥100 GB | 每个网关部署至少 3 个，建议 4 个 | 随业务流量横向扩容。高并发或启用安全护栏时从 16 GB 起步；需要保留更长时间的本地日志时，请增加主机存储。 |
cp-api | 2 核 | 4 GB | ≥32 GB | 2 | 无状态服务；将实例分布到不同故障域。 |
dp-manager | 2–4 核 | 4–8 GB | ≥32 GB | 2 | 处理配置下发、网关心跳和用量遥测；将实例分布到不同故障域。 |
| PostgreSQL | 4–8 核 | 16 GB | ≥500 GB NVMe SSD | 3 | 关键有状态组件。生产高可用部署请使用 Helm 并连接外部 PostgreSQL，例如主节点、同步备用节点和异步备用节点；根据用量事件保留期调整存储。 |
| Prometheus（可选） | 4 核 | 8–16 GB | ≥200 GB | 1–2 | 用于存储监控指标。如果已有 Prometheus，可以复用现有部署；根据指标基数和保留期调整存储。 |
对于较小的部署，cp-api、dp-manager 和 Prometheus 可以共用服务器，但必须为各组件预留 CPU 和内存，并为容器镜像和日志提供充足的共享主机容量。请将冗余实例分布到不同故障域。
使用 Helm 部署到 Kubernetes
在 Kubernetes 中，应按副本规划计算资源，并根据性能与容量规划单独扩缩 AISIX 网关。下列规格是容量规划建议，而不是 Chart 的默认值：
| 组件 | 单个副本 CPU | 单个副本内存 | 起始副本数 | 规划说明 |
|---|---|---|---|---|
| AISIX 网关 | 4 核 | 8–16 GB | 每个网关部署至少 3 个，建议 4 个 | 随业务流量横向扩容。高并发或启用安全护栏时从 16 GB 起步。 |
cp-api | 2 核 | 4 GB | 2 | 无状态服务；将副本分布到不同故障域。 |
dp-manager | 2–4 核 | 4–8 GB | 2 | 将副本分布到不同故障域。 |
| PostgreSQL | 4–8 核 | 16 GB | 生产高可用部署使用 3 个 | 使用外部高可用部署，而不是随包提供的单实例数据库。 |
| Prometheus（可选） | 4 核 | 8–16 GB | 1–2 | 如果已有 Prometheus，可以复用现有部署。 |
默认控制面 Helm Chart 不会为 cp-api 或 dp-manager 分配应用持久卷。容器镜像和平台管理的日志应计入 Kubernetes Node 容量，而不是作为每个 Pod 的存储要求。如果在集群中自行运行 PostgreSQL 或 Prometheus，请单独配置持久存储，并根据用量事件或指标的保留期调整容量。建议起始容量为每个 PostgreSQL 实例至少 500 GB NVMe SSD、每个 Prometheus 实例至少 200 GB。
不要将 PostgreSQL 副本放在同一故障域或共享存储上。随附的 PostgreSQL Chart 默认不提供复制数据库，请参阅高可用和外部数据库。
这些规格只覆盖 AISIX 组件，不包含上游模型推理所需的计算资源。AISIX 本身不要求 GPU。
在线部署
当主机或 Kubernetes 集群可以从 Docker Hub 拉取容器镜像时，请使用在线部署。
Docker Compose
对于已安装 Docker 和 Docker Compose 的主机，可以使用 Docker Compose。快速开始 URL 会解析到当前版本。
curl -sL "https://run.api7.ai/aisix-self-hosted/quickstart" | bash
该脚本会将部署包下载到 ./aisix-self-hosted，生成包含新密钥的 .env 文件，从 Docker Hub 拉取镜像，并启动整个服务栈。
该部署包使用随包提供的 PostgreSQL 服务，不支持外部数据库。如需使用外部 PostgreSQL 数据库，请使用 Helm 安装。
启动完成后，脚本会打印控制台 URL；首次安装时还会打印首个管理员的邮箱地址和密码。默认 URL 为 http://localhost:8080。打开控制台后，以首个管理员身份登录。
在 ./aisix-self-hosted 中管理服务栈：
./aisix-self-hosted/run.sh logs # 查看日志
./aisix-self-hosted/run.sh stop # 停止容器
./aisix-self-hosted/run.sh down # 删除容器（保留数据卷）
使用 Helm 部署到 Kubernetes
在 Kubernetes 中，可以从 API7 Helm 仓库安装 chart：
helm repo add api7 https://charts.api7.ai
helm repo update
helm install aisix-cp api7/aisix-cp --version 1.6.0 \
--set secrets.masterKey="$(openssl rand -base64 32)" \
--set postgresql.auth.password="$(openssl rand -hex 24)" \
--set postgresql.auth.postgresPassword="$(openssl rand -hex 24)"
默认情况下，该 chart 会部署 cp-api（同时提供控制台）、数据面管理器和随包 PostgreSQL 实例。
配置外部访问前，可以通过端口转发访问 cp-api 服务：
kubectl port-forward svc/aisix-cp-api 8080:8080
端口转发运行期间，打开 http://localhost:8080，并以首个管理员身份登录。
如果需要使用已有数据库，请先准备外部数据库和角色。然后将 postgresql.builtin=false 禁用随包 PostgreSQL chart，并配置顶层 externalDatabase.* 值。
如需在本地查看默认 chart values，请运行：
helm show values api7/aisix-cp --version 1.6.0
Chart 源码和软件包发布在 aisix-cp-1.6.0 Helm Chart Release 中。
在 OpenShift 上安装
控制面 chart 可以在 OpenShift 默认的 restricted-v2 security context constraint 下安装。既不需要自定义 SCC，也不需要 anyuid，更不需要改动 ServiceAccount。
chart 不再固定 UID。cp-api 和 dp-manager——即 api、dpm 两个 values 键——的默认 Pod 安全上下文就是：
podSecurityContext:
runAsNonRoot: true
seccompProfile:
type: RuntimeDefault
restricted-v2 会从命名空间分配的区间中提供 runAsUser 和 fsGroup，Pod 接受它分配的任意值。容器镜像声明了数字用户 10001，并且每个进程读取的文件都对所有用户可读，因此以任意 UID 搭配 GID 0 运行都可以。运行期唯一被写入的路径是 emptyDir 卷。
容器级安全上下文未作改动，本身已满足 restricted-v2：丢弃全部 capability、只读根文件系统、禁止提权。
如果需要改为固定 UID——集群不分配 UID，或者需要匹配已有卷的属主——把这些 values 设置回去即可：
helm install aisix-cp api7/aisix-cp --version 1.6.0 \
--set api.podSecurityContext.runAsUser=10001 \
--set api.podSecurityContext.runAsGroup=101 \
--set api.podSecurityContext.fsGroup=101
在 OpenShift 上使用随包 PostgreSQL
随包 PostgreSQL chart 是控制面 chart 的依赖 chart，它仍然固定了自己的 UID，而依赖 chart 的 values 无法由父 chart 按条件控制。请在安装时关闭它的两个安全上下文，让 restricted-v2 分配 UID：
helm install aisix-cp api7/aisix-cp --version 1.6.0 \
--set postgresql.primary.podSecurityContext.enabled=false \
--set postgresql.primary.containerSecurityContext.enabled=false
除此之外不需要关闭其他项。特别是不要关闭 postgresql.shmVolume——那样 PostgreSQL 会退回到容器运行时提供的 64 MB /dev/shm，并行查询会以 could not resize shared memory segment 失败。
使用外部数据库可以完全回避这个问题，并且无论在哪个平台上都是推荐的生产选择。
离线内网部署
对于无法访问镜像仓库的主机，请使用离线部署包。离线包包含所有必要的容器镜像。
离线包按 CPU 架构分别发布，下面的 URL 已固定到本版本。请选择与离线主机匹配的那一个：
| 主机架构 | 下载 URL |
|---|---|
linux/amd64（x86-64） | https://run.api7.ai/aisix-self-hosted/aisix-self-hosted-offline-1.6.0-linux-amd64.tar.gz |
linux/arm64（AArch64） | https://run.api7.ai/aisix-self-hosted/aisix-self-hosted-offline-1.6.0-linux-arm64.tar.gz |
同一目录下还发布有 aisix-self-hosted-offline-<version>-linux-<arch>.tar.gz 形式的指定版本 URL。
在可以访问互联网的机器上，下载与目标主机架构匹配的部署包：
curl -fSL "https://run.api7.ai/aisix-self-hosted/aisix-self-hosted-offline-1.6.0-linux-amd64.tar.gz" \
-o aisix-self-hosted-offline-1.6.0-linux-amd64.tar.gz
不带架构后缀的 aisix-self-hosted-offline-1.6.0.tar.gz 仍然继续发布，内容就是 linux/amd64 包，因此已有自动化无需改动。linux/arm64 包只通过它自己的后缀提供。
将部署包传输到离线主机，然后启动服务栈：
tar -xzf aisix-self-hosted-offline-1.6.0-linux-amd64.tar.gz
cd aisix-self-hosted
./run.sh
每个部署包只内置一个架构的镜像。如果包与主机不匹配，run.sh 会在加载任何镜像之前停下并打印正确的下载 URL——而不是让 docker load 成功之后，每个容器再以 exec format error 退出。
启动脚本会执行以下操作：
- 加载内置容器镜像
- 生成包含新密钥的
.env文件 - 在无互联网访问的情况下启动服务栈
- 启动完成后打印控制台 URL； 首次安装时还会打印首个管理员的邮箱地址和密码
默认控制台 URL 为 http://localhost:8080。
随包提供的 cp-api 镜像包含模型价格快照，因此用量和预算计算可以在不访问 models.dev 的情况下初始化。启动时，控制面会从该快照加载模型价格目录。如需改用在线价格，请在 .env 中设置 AISIX_CLOUD_PRICESYNC_SNAPSHOT_PATH=，并重新创建 api 服务。价格目录相关设置请参见私有化部署配置。
以首个管理员身份登录
On-Premises 控制面不开放自行注册，也不允许任何人创建组织。取而代之的是，cp-api 在首次启动时创建首个管理员：当某次启动时数据库中还没有任何用户，它会创建组织 Default，并把该账号设为其所有者。之后由该管理员邀请其他所有人。On-Premises 控制面的其他差异参见部署模式。
首个管理员来自两项设置：邮箱地址和初始密码。
-
Docker Compose。
run.sh在首次启动生成.env时，会写入AISIX_CLOUD_BOOTSTRAP_ADMIN_EMAIL=admin@example.com和一个随机的AISIX_CLOUD_BOOTSTRAP_ADMIN_PASSWORD，并在整套服务启动后打印一次。它不会修改已存在的.env。如需用你自己的邮箱管理该部署，请从 该账号邀请你的邮箱，并授予owner角色。 -
Helm。
api.bootstrapAdmin.email默认为admin@example.com。除非设置了api.bootstrapAdmin.password或api.bootstrapAdmin.existingSecret，Chart 会生成一个随机密码，写入自己的 Secret 中的bootstrap-admin-password键，安装说明会打印读取该密码的命令：kubectl get secret <secret-name> -n <namespace> \-o jsonpath='{.data.bootstrap-admin-password}' | base64 -d; echohelm template以及自行渲染 Chart 的 GitOps 工具（例如 Argo CD）无法读回生成的 Secret，每次渲染都会生成新的密码。此类部署请显式设置api.bootstrapAdmin.password或api.bootstrapAdmin.existingSecret。
使用该邮箱地址和密码登录。首次登录时，控制台会先要求设置新密码，新密码必须与初始密码不同。在修改密码之前，该账号无法在控制台或 API 中执行任何其他操作。
首个管理员在一个数据库的生命周期内最多创建一次。之后修改这些设置、重启或增加副本都不会产生任何效果；已经有用户的数据库（例如升级而来的安装）永远不会创建首个管理员。两项设置都为空时，cp-api 可以启动，但会记录一条警告，且没有人能够登录。两项要么都设置，要么都不设置：只设置其中一项时，cp-api 会拒绝启动。相关设置参见首个管理员以及部署模式与首个管理员。
配置外部访问
在将控制面暴露到本地主机或集群之外之前，请配置公开控制台源站和数据面管理器端点。
对于 Docker Compose，请编辑 .env。对于 Kubernetes，请更新 Helm values：
| Docker Compose 设置 | Helm value | 作用 |
|---|---|---|
AISIX_CLOUD_PUBLIC_BASE_URL | api.publicBaseURL | 面向浏览器的源站，例如 https://aisix.example.com。登录始终信任该源站，邀请链接和密码重置链接也指向它。单点登录用它生成服务提供方 URL，因此它必须是浏览器实际使用的 URL。 |
AISIX_CLOUD_DPMGR_BASE_URL | api.dpmgrBaseURL | 数据面主机连接的 dp-manager mTLS 端点，需为 https:// URL，例如 https://dpm.example.com:7944，其主机可以是 DNS 名称或 IP 地址。 |
Helm Chart 默认将 cp-api 和 dp-manager 服务公开为 ClusterIP。请通过适合你集群的网络端点公开这两个服务，再将上述两个公开访问参数设置为相应端点。
dp-manager 同样会接收数据面管理器端点，并为该主机签发 TLS 服务器证书。数据面会根据实际连接的地址验证证书，因此该值必须与生成的网关安装命令中的端点一致，无论该端点是 DNS 名称还是 IP 地址。
更新这些设置后，请使用 docker compose up -d 重新创建相关服务，或使用 helm upgrade 应用变更。
可信登录源站
登录请求只接受来自可信浏览器源站的请求。公开 base URL 的源站会自动受信任，同时还会信任它的 loopback 对应源站。这个对应源站会在 localhost 与 127.0.0.1 之间替换主机名，并保持与 base URL 相同的 scheme 和端口。例如，base URL 为 http://localhost:8080 时，也会信任 http://127.0.0.1:8080，但不会信任不同端口或不同 scheme。这样，本地安装可以从两个地址访问。无需在其它位置再次列出 base URL。
只有当控制台会通过多个主机名访问时，才需要设置额外源站，例如第二个域名或反向代理地址：
| Docker Compose 设置 | Helm value | 作用 |
|---|---|---|
AISIX_TRUSTED_ORIGINS | api.trustedOrigins | 额外登录源站。Docker Compose 使用逗号分隔的列表，例如 https://console.example.com,https://admin.example.com；Helm 使用由同样源站组成的 YAML 列表。 |
来自不可信源站的登录尝试会失败，并提示该地址不允许访问。将该源站添加到这里即可解决。
反向代理
当 cp-api 位于 Ingress 控制器、负载均衡器或其他反向代理之后时，请列出代理的地址范围，使登录和密码重置的限流按用户生效，而不是所有用户共用：
| Docker Compose 设置 | Helm value | 作用 |
|---|---|---|
AISIX_TRUSTED_PROXIES | api.trustedProxies | 位于 cp-api 前方的代理，以 CIDR 表示，例如 10.0.0.0/8。Docker Compose 使用逗号分隔的列表；Helm 使用 YAML 列表。 |
参见反向代理后的限流。
邮件
如需发送邀请、密码重置和设置密码邮件，请将 cp-api 连接到 SMTP 中继。参见配置邮件（SMTP）。
更多 Docker Compose 环境变量和 Helm values 请参见私有化部署配置。
验证安装
通过配置的公开 base URL 打开控制台。对于新安装，请以首个管理员身份登录并修改初始密码。当前运行的控制面版本显示在控制台左侧导航底部，格式可能是以下两种之一：
v1.0.0：正式发布版本。查看发布说明或报告问题时，请提供该版本号。dev · 2f9c1ab：基于开发提交而非正式版本构建，并以缩写的提交 SHA 标识。
无需登录也可以获取相同的版本标识，便于在脚本和支持信息包中使用。如果控制面不是通过默认本地地址访问，请将下面的 base URL 替换为实际公开 base URL：
AISIX_CP_URL="http://localhost:8080"
curl -sS "${AISIX_CP_URL}/api/config/public" | jq '{cp_version, cp_commit}'
{
"cp_version": "1.0.0",
"cp_commit": "a22f131"
}
API 返回的正式版本号不包含控制台所显示的 v 前缀。如果构建并非来自正式版本，cp_version 为空；无论哪种情况，cp_commit 都会标识对应提交。
各网关实例的版本会单独显示在环境的 Data planes 视图中，因为控制面和网关分别升级。
下一步
创建或选择目标组织和环境，然后连接 AISIX 网关，签发网关证书并接入提供流量服务的运行时。
使用私有化部署配置参考查看 Docker Compose 环境变量和 Helm values。