版本：Dev

使用 Podman 部署 AISIX Enterprise

AISIX Enterprise 可以在不使用 Docker Engine 的情况下运行于 Podman，让 RHEL 运维人员使用 Podman 部署控制面和同一主机上的 AISIX 网关。Docker Compose 通过 podman-docker 兼容层编排服务。

AISIX Enterprise 1.10.0 及更高版本支持以 rootless 和 rootful 模式运行 Podman。请使用 Docker Compose 作为 Compose 提供程序，不支持 podman-compose。

将控制面和网关一起运行在一台可访问互联网的 RHEL 主机上，可简化评估和非高可用部署。流程从主机准备开始，经过安装和 AI 请求验证，最后检查重启后的自动恢复。如需控制面高可用或外部 PostgreSQL 数据库，请使用 Helm。

准备工作

安装 AISIX Enterprise 之前，请准备：

一台 RHEL 9.8 主机，已注册提供 Podman 的软件仓库，以及安装 RPM 软件包和管理所需 systemd 服务的权限。
cURL、jq、tar 和 OpenSSL。
能够访问 run.api7.ai、download.docker.com、Docker Hub 和将要配置的模型服务提供方。
主机端口 5432、8080、7944 和 3000 可用。
能够访问主机 8080 端口的浏览器。
模型服务提供方的 API Key。验证步骤使用 OpenAI。

选择一种 Podman 模式，并在安装和运维过程中始终使用该模式。Rootless 模式将容器和卷存储在所选用户的账户下，rootful 模式将它们存储在 root 的 Podman 存储中。两种模式不共享容器、镜像或卷。

准备 Rootless Podman

对于 rootless Podman，请以拥有和运维该部署的普通用户登录。使用 SSH 或控制台登录，使 systemd 创建真正的用户会话。通过 su 或 sudo -i 切换到该用户不会创建 systemctl --user 所需的会话。

安装 Podman、其 Docker 兼容层和 Docker Compose：

sudo dnf install -y dnf-plugins-core podman podman-docker
sudo dnf config-manager --add-repo https://download.docker.com/linux/rhel/docker-ce.repo
sudo dnf install -y --setopt=install_weak_deps=False docker-compose-plugin

启用 rootless Podman API 套接字，设置用户服务在注销后继续运行，并配置主机重启后自动恢复容器：

systemctl --user enable --now podman.socket
sudo loginctl enable-linger "$USER"
systemctl --user enable podman-restart.service

验证 Docker Compose 和恢复设置：

docker compose version
systemctl --user is-active podman.socket
loginctl show-user "$USER" -p Linger
systemctl --user is-enabled podman-restart.service

命令应输出 Docker Compose 版本、处于活动状态的套接字、Linger=yes 和已启用的重启服务。

准备 Rootful Podman

对于 rootful 模式，请打开 root shell，并在该 shell 中执行后续所有安装和生命周期管理命令：

sudo -i

安装 Podman、其 Docker 兼容层和 Docker Compose：

dnf install -y dnf-plugins-core podman podman-docker
dnf config-manager --add-repo https://download.docker.com/linux/rhel/docker-ce.repo
dnf install -y --setopt=install_weak_deps=False docker-compose-plugin

启用系统 Podman API 套接字和容器恢复服务：

systemctl enable --now podman.socket
systemctl enable podman-restart.service

验证 Docker Compose 和恢复服务：

docker compose version
systemctl is-active podman.socket
systemctl is-enabled podman-restart.service

命令应输出 Docker Compose 版本、处于活动状态的套接字和已启用的重启服务。Rootful 模式不需要启用用户 linger。

部署控制面

按照在主机上使用 Docker Compose 完成在线安装。准备好上面的 podman-docker、Docker Compose 和 Podman 套接字后，严格按快速入门中的说明运行。成功后，返回本指南并进入安装目录：

cd aisix-self-hosted

为将加入同一 Compose 网络的网关配置数据面管理器地址。

安装包默认使用 http://localhost:8080 访问控制台。如果浏览器通过其他源站访问控制台，请先将 .env 中的 AISIX_CLOUD_PUBLIC_BASE_URL 设置为该源站的确切地址。有关可信源站、反向代理和可从外部访问的端点，请参阅配置外部访问。

以下命令使用配置的控制台源站重新创建 api，并使用数据面管理器地址重新创建 dpm：

sed -i \
  's|^AISIX_CLOUD_DPMGR_BASE_URL=.*|AISIX_CLOUD_DPMGR_BASE_URL=https://dpm:7944|' \
  .env

docker compose up -d api dpm

检查控制面健康检查端点：

curl -fsS --retry 30 --retry-delay 2 --retry-all-errors \
  "http://127.0.0.1:8080/healthz"

该端点应返回 {"status":"ok"}。如果重试后仍未恢复健康，请检查服务状态：

docker compose ps
docker compose logs --tail=100 api dpm postgres

请将 .env 与数据库一起备份。该文件包含解读存储数据所需的 PostgreSQL 密码和主密钥，后续的安装包归档不包含该文件。请参阅备份与恢复。

配置网关资源

打开配置的控制台 URL，使用首个管理员凭据登录。出现提示时，请修改初始密码。

完成创建 Admin Token 和创建网关资源。在同一终端中保留导出的 AISIX_CP、AISIX_TOKEN、ENV_ID 和 AISIX_API_KEY，供下方验证步骤使用。

连接网关

将网关连接到控制面服务所在的网络：

在控制台中打开创建的环境，选择 数据面。
选择 签发证书，然后打开 Docker 选项卡。
复制生成的命令，在 docker run 行之后立即添加 --network aisix-self-hosted_aisix。该命令包含网关证书和私钥，请将该命令视为机密信息，不要提交或分享。
在 Podman 主机上运行修改后的命令。

生成的命令会启动名为 aisix-dp 的容器，设置重启策略和 45 秒的停止超时。命令等待 http://127.0.0.1:3000/readyz，并在网关收到首个配置后返回。配置的 https://dpm:7944 端点通过共享的 Compose 网络解析。

如果就绪检查一直等待，请在另一个终端中查看网关日志：

docker logs aisix-dp

返回 数据面，刷新页面并确认网关上报了近期心跳。

发送并验证请求

导出本地网关地址并检查其监听端点：

export AISIX_PROXY="http://127.0.0.1:3000"

curl -fsS "$AISIX_PROXY/livez"
curl -fsS "$AISIX_PROXY/v1/models" \
  -H "Authorization: Bearer ${AISIX_API_KEY}"

第一个命令应返回 ok。第二个响应的 data 数组应包含配置的模型。配置更改可能需要几秒钟才能到达网关，如果模型尚未列出，请重试。

通过网关发送请求：

curl -sS -X POST "$AISIX_PROXY/v1/chat/completions" \
  -H "Authorization: Bearer ${AISIX_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [
      {"role": "user", "content": "Say hello from AISIX Enterprise on Podman."}
    ]
  }'

网关应返回与 OpenAI 兼容的响应，其中 choices[0].message 包含助手消息。在控制台中，使用环境中的日志查看请求，并通过组织导航中的用量确认用量数据已到达。

验证主机重启后的恢复

首次请求成功后，重启主机：

sudo systemctl reboot

对于 rootless 模式，请以拥有该部署的用户重新登录。对于 rootful 模式，请重新打开 root shell。不要手动启动容器。

确认控制面和网关已恢复：

docker ps --format '{{.Names}} | {{.Status}}'
curl -fsS --retry 30 --retry-delay 1 --retry-all-errors \
  "http://127.0.0.1:8080/healthz"
curl -fsS --retry 30 --retry-delay 1 --retry-all-errors \
  "http://127.0.0.1:3000/readyz"

容器应处于运行状态，控制面端点应返回 {"status":"ok"}，网关端点应返回 ok。再次发送请求，并确认此前创建的环境、模型、API Key、证书和管理员密码仍然可用。

重启后，数据面 可能会暂时同时显示健康的恢复实例和状态为 warning 或 offline 的旧网关实例。旧条目会保留约一小时，这不表示恢复失败。请确认当前实例有近期心跳。

重启后，cp-api 可能会短暂记录 the database system is starting up (SQLSTATE 57P03)，因为 Podman 启动容器时不会应用 Compose 的依赖顺序。其重启策略应使服务自动恢复。只有健康检查端点未恢复时才需要排查。

管理部署

在 aisix-self-hosted 目录中运行控制面生命周期管理命令：

./run.sh logs
./run.sh stop

关闭 Compose 项目之前，请停止并移除单独管理的网关。随后 ./run.sh down 会移除控制面容器，但保留 PostgreSQL 卷：

docker rm -f aisix-dp
./run.sh down

停止网关时，处理完活动请求可能需要约 30 秒。生成的命令为优雅关闭预留 45 秒，超过该超时时间的请求可能被终止。

兼容性

AISIX Enterprise 从 1.10.0 开始支持 Podman。快速入门安装当前 AISIX Enterprise 版本。RHEL、Podman 和 Docker Compose 来自主机的软件包仓库，因此确切版本可能不同。RHEL 部署可参考以下配置。

组件	参考版本或设置
AISIX Enterprise	1.10.0
操作系统	`linux/amd64` 上的 RHEL 9.8
Podman 和 `podman-docker`	5.8.2-8.el9_8
Docker Compose	`docker-compose-plugin-5.7.0-1.el9` 提供的 5.7.0
Podman 模式	Rootless 和 rootful
SELinux	Enforcing

部署注意事项

上述部署使用在线安装包，将控制面和网关一起运行在一台 RHEL 主机上。如需离线安装或使用 Helm 部署控制面，请从部署 AISIX Enterprise 控制面开始。网关或客户端运行在其他主机上时，请针对目标网络规划外部可访问的端点、防火墙规则和客户端地址行为。

如果 rootless 网关未连接到共享的 Compose 网络，请使用 127.0.0.1:3000 而非 localhost:3000。由于网关监听 IPv4，将 localhost 解析为 IPv6 环回地址可能导致连接重置。
在未将 CPU 控制权委派给用户的 rootless RHEL 主机上，Podman 的 --cpus 选项不可用。上述命令没有设置 CPU 限制。
来自同一主机的请求可能记录转换后的 Podman 网络地址，而非原始客户端地址。请在实际运行的网络拓扑中使用客户端验证基于 IP 的访问控制。
在启用 SELinux 的主机上，为运维人员添加的绑定挂载添加 :Z 卷选项。如果不调整标签，即使容器以 root 身份运行，也可能收到 Permission denied。
在未启用持久化 journal 的主机上使用 journald 日志时，容器日志不会在主机重启后保留。如果需要在重启后保留日志，请单独规划日志保留方案。

下一步

规划生产环境时，请参阅部署 AISIX Enterprise 控制面，了解资源规模、外部访问、高可用和数据库选项。

升级前，请将相互匹配的数据库、.env、部署文件和软件版本作为一个恢复集保存。AISIX Enterprise Podman 部署与 Docker Compose 部署使用相同的 AISIX Enterprise 升级流程。

准备工作​

准备 Rootless Podman​

准备 Rootful Podman​

部署控制面​

配置网关资源​

连接网关​

发送并验证请求​

验证主机重启后的恢复​

管理部署​

兼容性​

部署注意事项​

下一步​