使用 Podman 部署

API7 网关的单主机部署包支持在 Podman 上运行，无需 Docker Engine。本指南介绍如何在 Red Hat Enterprise Linux（RHEL）上准备 Podman，启动控制面和网关，验证 API 请求，并确认主机重启后服务能够恢复。

API7 网关从 3.10.10 起支持此部署方式，可使用 rootless 或 rootful 模式。3.10.9 及更早版本不支持此部署方式。部署时通过 podman-docker 兼容层使用 Docker Compose，不能用 podman-compose 替代 Docker Compose。

本指南适用于可访问互联网、控制面和网关运行在同一台主机上的部署。如果需要原生重新调度、滚动更新或自动扩缩容，请使用 Kubernetes。

前置条件

安装 API7 网关之前，请准备以下条件：

• 一台已注册并可使用提供 Podman 的软件仓库的 RHEL 9.8 主机，以及安装 RPM 软件包和管理所需 systemd 服务的权限。
• cURL、jq、tar 和 OpenSSL。
• 能够访问 run.api7.ai、Docker Hub 和即将配置的上游服务。
• 主机端口 4321、7080、7443、7900、7943、9080 和 9443，以及回环端口 16686 均可用。
• 能够访问主机 7443 端口的浏览器。
• 有效的 API7 企业版许可证。获取试用许可证。

选择一种 Podman 模式，安装和运维时均使用该模式。Rootless 和 rootful 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 socket，使用户服务在退出登录后继续运行，并让容器在主机重启后恢复：

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 版本、socket 处于活动状态、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 socket 和容器恢复服务：

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 版本、socket 处于活动状态，以及重启服务已启用。Rootful 模式无需启用用户 lingering。

安装 API7 网关

在尚无 api7-ee 子目录的目录下运行快速安装脚本：

mkdir -p ~/api7
cd ~/api7

curl -fsSL "https://run.api7.ai/api7/quickstart" -o api7-quickstart.sh &&
  bash api7-quickstart.sh

请保留生成的目录名 api7-ee。Compose 项目名称以及网关接入控制面网络时均使用该名称。

快速安装脚本会下载当前的部署包，启动控制面服务，并在 default 网关组中创建一个网关实例。网关会自动加入部署包的 Compose 网络，并通过 https://dp-manager:7943 连接 DP Manager，无需为 Podman 单独覆盖 Compose 配置。

进入安装目录，检查服务状态和网关的重启策略：

cd ~/api7/api7-ee

docker compose ps
docker ps --filter "name=api7-ee-gateway-1"
docker inspect api7-ee-gateway-1 \
  --format '{{.HostConfig.RestartPolicy.Name}}'

Compose 服务和 api7-ee-gateway-1 应处于运行状态，网关的重启策略应为 always。

检查控制台和网关的端点：

curl -k -I "https://127.0.0.1:7443/"
curl -i "http://127.0.0.1:9080/"

控制台应返回成功的 HTTP 响应。创建路由前，网关应返回 404 Not Found。

如果快速安装失败，脚本会以非零状态码退出，并输出服务状态和近期日志。请先解决报告的问题。启动失败的服务可能仍在反复重启。如果已创建 api7-ee 目录，请先停止整个服务栈，再重试：

cd ~/api7/api7-ee
bash run.sh down

激活 API7 网关并验证流量

打开 https://<host-address>:7443/，使用 admin / admin 登录，立即修改默认密码，然后上传 API7 企业版许可证。

接着创建服务和路由，然后验证代理。快速安装脚本已创建 default 网关组及其网关实例。请从许可证激活和 API 配置开始，跳过快速入门中的 Docker 安装步骤。

通过 http://127.0.0.1:9080 发送请求，确认获得预期的上游响应后再继续。

验证主机重启后的恢复情况

首次请求成功后，重启主机。在 rootless 模式下运行：

sudo systemctl reboot

在 rootful 模式下，从 root shell 运行 systemctl reboot。主机恢复后，以负责管理此部署的用户登录。对于 rootful 部署，请重新进入 root shell。此时请勿手动启动任何容器。

等待在快速入门中创建的路由恢复处理流量：

cd ~/api7/api7-ee

curl -fsS --max-time 3 --retry 30 --retry-delay 2 --retry-all-errors \
  -o /dev/null "http://127.0.0.1:9080/anything/hello" &&
  echo "API request recovered"

如果重试后请求仍然失败，请在手动启动任何容器前检查 docker ps -a、docker compose logs --tail=100 和 docker logs --tail=100 api7-ee-gateway-1。

确认容器已恢复，且重启策略仍然有效：

docker ps --format '{{.Names}} | {{.Status}}'
docker inspect api7-ee-gateway-1 \
  --format '{{.HostConfig.RestartPolicy.Name}}'

打开控制台，确认 default 网关组有一个健康的网关实例。再次发送请求，确认重启前上传的许可证、创建的服务和路由仍可用。

主机重启后，Podman 启动容器时不按 Compose 的依赖顺序启动。控制台或网关可能在 PostgreSQL 或 DP Manager 就绪期间重启，并通过 always 重启策略恢复。若网关一直未达到健康状态或流量未恢复，请排查问题。

管理部署

在 api7-ee 目录中运行控制面命令。持续查看 Compose 服务日志：

docker compose logs -f

网关在 Compose 项目之外运行，请单独查看网关日志：

docker logs -f api7-ee-gateway-1

先停止网关，再停止 Compose 服务：

docker stop api7-ee-gateway-1
docker compose stop

重新启动 Compose 服务，等待 DP Manager 就绪后，再启动网关：

docker compose start
curl -fsS --max-time 3 --retry 30 --retry-delay 2 --retry-all-errors \
  "http://127.0.0.1:7900/version" > /dev/null &&
  docker start api7-ee-gateway-1

如果重试后 DP Manager 仍未就绪，请检查 Compose 服务状态和日志，待 DP Manager 就绪后再启动网关。

如果修改默认 admin 密码后删除了网关，run.sh 将无法使用 admin:admin 创建替代实例。请在控制台选择 新增网关实例，将 DP Manager 地址设为 https://dp-manager:7943，并在生成的 Docker 命令中添加 --network=api7-ee_api7。

容器停止后，PostgreSQL 和 Prometheus 数据仍保留在 api7-ee 目录下。如果还需要这些部署数据，请保留该目录。

移除部署

警告

以下命令会永久删除 api7-ee 下保存的 API7 网关配置、PostgreSQL 数据、Prometheus 数据和网关身份信息。

对于 rootless 部署，先移除容器和卷，再通过 Podman 用户命名空间删除安装目录：

cd ~/api7/api7-ee &&
docker rm -f -t 5 api7-ee-gateway-1 &&
docker compose --profile portal down -v &&
cd .. &&
podman unshare rm -rf ./api7-ee

对于 rootful 部署，在 root shell 中执行对应的清理命令：

cd ~/api7/api7-ee &&
docker rm -f -t 5 api7-ee-gateway-1 &&
docker compose --profile portal down -v &&
cd .. &&
rm -rf ./api7-ee

如果移除网关或清理 Compose 部署失败，后续命令不会执行，安装目录也不会被删除。

兼容性

API7 网关从 3.10.10 起支持此部署方式。下表列出已验证可用的组合。安装命令使用软件仓库中当前可用的软件包，实际安装的版本可能与表中不同。

组件	已验证兼容的版本或设置
API7 网关	3.10.10
操作系统	linux/amd64 架构的 RHEL 9.8
Podman 和 podman-docker	5.8.2-8.el9_8
Docker Compose	5.7.0（docker-compose-plugin-5.7.0-1.el9）
Podman 模式	Rootless 和 rootful
SELinux	Enforcing

部署适用范围

• 本指南涵盖在同一台 RHEL 主机上使用在线快速安装脚本部署控制面和网关。离线安装包、手动 Compose 部署、网关与控制面分开部署、远程客户端、firewalld 规则和网关 9443 端口上的 HTTPS 流量均不在适用范围内。
• 在两种 Podman 模式下，默认 Compose 网络上来自同一台主机的请求，其来源地址可能会被记录为 Podman 网桥或容器地址，而非原始客户端地址。远程客户端场景未经测试。请在实际使用的网络拓扑中验证依赖客户端 IP 的功能。
• 如果 rootless RHEL 主机没有向用户委派 CPU 控制权限，则无法使用 Podman 的 --cpus 选项。本指南不配置 CPU 限制。

后续步骤

使用单主机部署承载生产流量前，请查看生产部署检查清单。

使用 Podman 部署的 API7 网关遵循与 Docker Compose 部署相同的升级流程。请保留安装目录和数据库备份，再按适用的升级指南操作。