版本：3.10.x

使用离线 RPM 包部署

本文介绍如何在 Red Hat 系 Linux 系统（RHEL、Rocky Linux、AlmaLinux、CentOS 8/9）中，使用离线 RPM 包部署 API7 网关。下载安装包后，安装过程不再依赖外网，只需要 tar、systemctl、文本编辑器和浏览器即可完成部署。

架构

API7 网关由控制面（CP）和数据面（DP）组成：

层级	职责	说明
控制面	管理与控制	配置网关、签发数据面证书、下发配置、汇聚可观测性数据，并将配置、用户和审计日志等持久化到 PostgreSQL
数据面	流量处理	运行 APISIX/OpenResty，执行路由和插件；数据面本身无状态，配置由控制面同步

评估环境可以将控制面和数据面部署在同一台主机上；生产环境建议将二者部署在不同主机上。本文用“CP 主机”表示控制面主机，用“DP 主机”表示数据面主机；在单机部署中二者指同一台机器。

控制台必需组件

要构建功能完整的控制面，控制台管理界面和 API 需要下列组件。前三项是离线 RPM 包提供的 systemd 服务，其余为需要自行准备的依赖项。

组件	来源	是否必需	用途
`api7ee-dashboard`	`api7ee-dashboard` RPM，内置 Node.js	是	控制面后端，通过 `7443` 提供 UI/API
`api7ee-console`	同一个 `api7ee-dashboard` RPM，通过内置 Node.js 运行	是	Web 控制台 UI，由 `api7ee-dashboard` 服务反向代理（`3000` → `7443`）
`api7ee-dp-manager`	`api7ee-dp-manager` RPM	是	向网关下发配置、签发数据面 mTLS 证书、处理心跳（`7943`）
PostgreSQL	外部依赖；单机 RPM 快速试用会安装本地 PostgreSQL，生产环境建议自行提供	是	持久化配置、用户、审计日志等数据
Prometheus	外部依赖，不包含在安装包中	指标场景必需	接收 dp-manager remote-write 的网关指标，用于控制台分析视图，见安装 Prometheus
Jaeger	外部依赖，不包含在安装包中	链路追踪场景必需	保存请求 Trace，用于控制台在线调试和追踪视图（dp-manager → OTLP Collector `4318`；控制台 → 查询界面 `16686`）
`api7-gateway`	`api7-gateway` RPM	数据面必需	处理 API 流量；控制台本身不依赖它启动，但需要它才能管理实际流量，见接入数据面网关

系统要求

项目	要求
操作系统	RHEL / Rocky / AlmaLinux / CentOS 8 或 9，x86_64
初始化系统	systemd，所有组件都以 systemd 服务运行。容器化评估时也必须让 systemd 作为 PID 1 运行，见方法 A
权限	`root` 或 `sudo`
PostgreSQL	13+，推荐 15；可部署在本机、独立主机或云托管数据库中
控制面端口	`7443`（控制台/API，对外访问）、`7943`（数据面 mTLS 接入，需对 DP 主机开放）、`7900/7901/7080/7081`（本地/内部）
数据面端口	`9080`/`9443`，用于业务流量入口
网络	可完全离线；如控制面和数据面分离，DP 主机必须能访问 CP 主机的 `7943`，控制面必须能访问 PostgreSQL 的 `5432`

获取安装包

先确认目标主机的 CPU 架构和 Red Hat 系发行版主版本：

uname -m              # CPU 架构 → <arch>，例如 x86_64
cat /etc/os-release   # 查看 PLATFORM_ID，例如 "platform:el9" → <dist>，例如 el9

安装包文件名格式为 api7-ee-rpm-<version>-<dist>.<arch>.tar.gz，例如 api7-ee-rpm-3.10.1-el9.x86_64.tar.gz。

字段	来源	示例
`<version>`	要安装的 API7 网关版本	`3.10.1`
`<dist>`	`/etc/os-release` 中 `PLATFORM_ID` 对应的 Red Hat 系主版本	`el8`、`el9`
`<arch>`	`uname -m` 输出的 CPU 架构，目前安装包为 x86_64	`x86_64`

替换以下变量后下载匹配的安装包：

export API7EE_VERSION="3.10.1"   # 要安装的版本
export API7EE_DIST="el9"         # 来自 /etc/os-release 的 PLATFORM_ID
export API7EE_ARCH="x86_64"      # 来自 uname -m
curl -fSLO "https://run.api7.ai/api7-ee/api7-ee-rpm-${API7EE_VERSION}-${API7EE_DIST}.${API7EE_ARCH}.tar.gz"

如果目标主机处于隔离网络，请在可访问互联网的机器上下载 .tar.gz，再复制到目标主机。只有下载步骤需要联网，解压和安装可以完全离线完成。

安装包内容

文件	类别	内容
`api7ee-dp-manager-*.rpm`	控制面	数据面管理、配置下发和证书签发服务
`api7ee-dashboard-*.rpm`	控制面	控制面后端和 Web 控制台，默认 TLS `7443`，内置 Node.js；一个包提供 `api7ee-dashboard` 和 `api7ee-console` 两个 systemd 服务
`api7-gateway-*.rpm`	数据面	网关运行时，包含 APISIX 和内置 OpenResty
`which-.rpm`、`libxslt-.rpm` 等	系统依赖	网关运行所需的少量系统库，已随包提供
`install.sh`	安装脚本	一次性离线安装上述 RPM
`quickstart.sh`	评估辅助脚本	单机评估一键启动脚本，见方法 A

每个软件包都自带运行时（Node.js / OpenResty），不依赖主机预装的 nodejs 或 openresty，因此离线安装不会影响主机上已有软件。

安装包不包含以下外部依赖和部署制品：

PostgreSQL：控制面的唯一外部依赖，详情参阅系统要求和准备 PostgreSQL。
许可证：安装完成后在控制台中上传。
数据面证书：由控制台按网关组自动签发，详情参阅接入数据面网关。

部署流程概览

标准部署路径按以下顺序执行：

准备 PostgreSQL。
安装 RPM 包。
配置并启动控制面。
初始化控制台：修改默认密码并上传许可证。
接入数据面网关：使用控制台签发的证书和连接参数配置 DP 主机上的网关。
在控制台确认实例状态为 Healthy。

根据场景选择一种部署路径：

路径	适用场景	特点
方法 A：单机 RPM 快速试用	单机评估 / 概念验证（PoC）	一条命令完成安装，自动安装并初始化本地 PostgreSQL，几分钟内可用
方法 B：标准生产部署	生产环境	手动逐步配置，支持外部/高可用数据库、CP/DP 分离和安全加固

方法 A：快速评估

在单机评估或概念验证（PoC）场景中，安装包内置的 quickstart.sh 可以在几分钟内拉起控制面。它会安装 RPM，安装并初始化本地 PostgreSQL，配置并启动控制面，然后打印访问地址。

完整流程请参考单机 RPM 快速试用，其中也包含容器化评估方式。

方法 B：生产标准部署

准备 PostgreSQL

控制面需要 PostgreSQL 13+，推荐使用 15。控制面启动时会自动迁移数据库模式，无需手动建表。如果你已经有可用数据库，请直接跳到创建数据库和角色。

安装

联网主机：

sudo dnf -y module enable postgresql:15   # RHEL/Rocky 8 必需，9 可选
sudo dnf -y install postgresql-server

离线主机：在同版本联网机器上下载 RPM，复制到目标主机后安装：

# 联网机器
sudo dnf -y module enable postgresql:15    # RHEL/Rocky 8 必需，否则默认 PG 10（低于 13）
sudo dnf install -y --downloadonly --downloaddir=./pg-rpms postgresql-server
# 目标机器（复制 pg-rpms/ 后）
sudo dnf -y localinstall ./pg-rpms/*.rpm --disablerepo='*'

初始化并启动 PostgreSQL

sudo /usr/bin/postgresql-setup --initdb
sudo systemctl enable --now postgresql

创建数据库和角色

sudo -u postgres psql <<'SQL'
CREATE USER api7ee WITH PASSWORD 'YourStrongPassword';
CREATE DATABASE api7ee OWNER api7ee;
SQL

启用密码认证

控制面会通过“用户名 + 密码 + TCP”连接 PostgreSQL，而 RHEL 默认本地 TCP 可能使用 ident，会导致连接失败。编辑 /var/lib/pgsql/data/pg_hba.conf，在通用规则之前加入：

host    api7ee    api7ee    127.0.0.1/32    scram-sha-256
host    api7ee    api7ee    ::1/128         scram-sha-256

如果数据库和控制面不在同一台主机，还需要在 postgresql.conf 中设置 listen_addresses = '*'，在 pg_hba.conf 中加入控制面网段，例如 host api7ee api7ee 10.0.0.0/24 scram-sha-256，并开放防火墙 5432 端口。

修改后重载 PostgreSQL：

sudo systemctl reload postgresql

验证并记录连接串

PGPASSWORD='YourStrongPassword' psql -h 127.0.0.1 -U api7ee -d api7ee -c '\conninfo'

下一步会用到连接串：postgres://api7ee:YourStrongPassword@<PG_HOST>:5432/api7ee。如果密码包含 @、冒号（:）、斜杠（/）或问号（?）等特殊字符，请做 URL 编码，例如 @ 编码为 %40。

安装软件包

在 CP 主机和 DP 主机各执行一次：

tar -xzf api7-ee-rpm-<version>-<dist>.<arch>.tar.gz
cd api7-ee-rpm-<version>-<dist>.<arch>/
sudo ./install.sh         # 等价于 dnf -y localinstall ./*.rpm --disablerepo='*'

如果控制面和数据面分离，CP 主机只需要两个控制面包（api7ee-dp-manager、api7ee-dashboard），DP 主机只需要 api7-gateway。安装完整包也受支持，但不要启动不需要的服务。

配置控制面

在 /usr/local/api7/dp-manager/conf/dp-manager.yaml 和 /usr/local/api7/dashboard/conf/dashboard.yaml 中写入相同的数据库连接串，其余配置可先保持默认：

database:
  dsn: "postgres://api7ee:YourStrongPassword@<PG_HOST>:5432/api7ee"

控制台默认通过 7443 以 TLS 方式监听。如需使用自有证书，请在 dashboard.yaml 中设置 server.tls.cert_file 和 server.tls.key_file；留空则使用内置自签名证书。

通常不需要修改 console.env。请保持 PORT=3000，因为 api7ee-dashboard 服务会反向代理到 127.0.0.1:3000；修改该端口会导致 502。

启动控制面

sudo systemctl enable --now api7ee-dp-manager
sudo systemctl enable --now api7ee-dashboard     # 同时拉起 api7ee-console
systemctl is-active api7ee-dp-manager api7ee-dashboard api7ee-console   # 预期均为 active

开放浏览器访问端口 7443，以及分离部署时 DP → CP 需要访问的 7943：

sudo firewall-cmd --add-port=7443/tcp --add-port=7943/tcp --permanent && sudo firewall-cmd --reload

如果 SELinux 为 Enforcing 且服务异常，可先查看 sudo ausearch -m avc -ts recent。必要时可临时执行 sudo setenforce 0 验证是否与策略相关，再补充正确策略；不建议无理由全局禁用 SELinux。

初始化控制台

在浏览器打开 https://<CP_HOST>:7443，接受自签名证书。
首次使用 admin / admin 登录，并按提示修改密码。
进入 Settings → License，上传包含 BEGIN CERTIFICATE 和 BEGIN LICENSE 两个区段的许可证，并确认状态正常。

接入数据面网关

控制台会统一签发数据面的连接参数和 mTLS 证书，不要手动拼接或复制不同环境的参数。

如果 Add Instance 弹窗要求填写 DP Manager（控制面）端点，请填写 https://<CP_HOST>:7943。<CP_HOST> 是 DP 主机可访问的控制面 IP 或域名，7943 是数据面 mTLS 端口。

在控制台进入 Gateway Groups，选择或创建网关组，点击 Add Instance。
控制台会生成包含网关组证书和控制面地址的部署脚本。

当前 Add Instance 会生成 Docker、Docker Compose 和 Helm 脚本，还不会直接生成原生 RPM 脚本。对于通过 RPM 安装的网关，请参考从 Docker 脚本接入 RPM 数据面，将相同连接参数写入 /usr/local/apisix/conf/config.yaml，然后重启网关服务：

systemctl restart api7-gateway

验证部署

# DP 主机
systemctl is-active api7-gateway                                   # active
curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:9080/   # 404 = 已提供服务（尚无路由）

在控制台打开网关组的 Instances 页面。实例状态变为 Healthy（心跳和配置同步均成功）后，部署完成。此后在控制台发布服务和路由，数据面会自动同步配置。

安装 Prometheus

控制台的指标和分析数据不存储在 dp-manager 中。网关会将指标块推送到 dp-manager，再由 dp-manager remote-write 到 Prometheus。Prometheus 是外部服务，不包含在 RPM 包中；需要安装并配置后，控制台才能展示流量指标。

在 CP 主机或可达主机上安装 Prometheus，并启用 remote-write receiver：

prometheus --web.enable-remote-write-receiver   # Prometheus v2.54+
# 较旧版本：--enable-feature=remote-write-receiver

配置 dp-manager 指向 Prometheus：

prometheus:
  addr: "http://127.0.0.1:9090"   # Prometheus 地址
  remote_write_path: "/api/v1/write"

保存后重启 dp-manager：

systemctl restart api7ee-dp-manager

在 Prometheus 安装和配置完成前，控制台不会显示流量指标，网关日志可能出现 agent.lua:544: upload metrics block failed, status: 500。这是未配置 Prometheus 时的预期现象，不影响代理流量和实例健康状态。

运维参考

安装后的文件布局

/usr/local/api7/              # 控制面
├── dp-manager/               # 二进制文件和配置
└── dashboard/                # 控制台、Console、配置和 Node.js 运行时

/usr/local/apisix/            # 数据面网关
├── conf/                     # config.yaml 和接入证书/参数
└── logs/                     # 网关日志

/usr/local/openresty/         # 内置 OpenResty 运行时
/usr/bin/apisix               # 网关 CLI
/usr/lib/systemd/system/      # systemd 服务单元文件
/var/log/api7/                # 控制面日志
/var/lib/api7/                # 控制面运行时数据

常用文件：

用途	路径
dp-manager 配置	`/usr/local/api7/dp-manager/conf/dp-manager.yaml`
控制台配置	`/usr/local/api7/dashboard/conf/dashboard.yaml`
Console 配置	`/usr/local/api7/dashboard/conf/console.env`
网关配置	`/usr/local/apisix/conf/config.yaml`
控制面日志	`/var/log/api7/*.log`
网关日志	`/usr/local/apisix/logs/error.log`

服务和端口

层级	systemd 服务	默认端口	主配置文件
控制面	`api7ee-dp-manager`	7900 / 7943 (mTLS) / 7901	`/usr/local/api7/dp-manager/conf/dp-manager.yaml`
控制面	`api7ee-dashboard`	7443 (UI/API) / 7080 / 7081	`/usr/local/api7/dashboard/conf/dashboard.yaml`
控制面	`api7ee-console`	3000 internal，由 `api7ee-dashboard` 服务反向代理	`/usr/local/api7/dashboard/conf/console.env`
数据面	`api7-gateway`	9080 / 9443	`/usr/local/apisix/conf/config.yaml`

api7-gateway 兼容 apisix.service 别名，因此 systemctl ... apisix 也可使用。

软件包行为

dnf upgrade 会安装新的 RPM；%config(noreplace) 会保留现有配置，新默认配置会保存为 *.rpmnew。升级后请重启受影响服务。服务运行在安装时自动创建的专用账号下：控制面为 api7，数据面为 apisix。

故障排查

现象	排查方向
Console UI 502	`console.env` 中的 `PORT` 必须为 3000；修正后执行 `systemctl restart api7ee-console`
控制面启动失败	通常是数据库不可达：检查数据库连接串、PostgreSQL 可达性、`api7ee` 数据库和角色是否存在，以及 `pg_hba.conf` 是否启用密码认证
数据面实例 `OutOfSync` 或无法连接控制面	通常是 DP → CP 的 `7943` 不可达，或证书与连接参数来自不同环境；重新运行控制台生成的接入脚本
离线安装提示 `nothing provides which/libxslt`	使用的是缺少依赖的精简包；请使用官方完整包
`System has not been booted with systemd as init system`	主机或容器未以 systemd 作为 PID 1 运行；API7 网关以 systemd 服务运行，见系统要求和方法 A

卸载

停止服务并移除 RPM：

sudo systemctl disable --now api7-gateway api7ee-console api7ee-dashboard api7ee-dp-manager
# Console 由控制台包安装，没有独立 RPM，因此下方不单独列出
sudo dnf -y remove api7-gateway api7ee-dashboard api7ee-dp-manager
# 配置和数据仍保留在 /usr/local/api7、/usr/local/apisix、/var/log/api7、/var/lib/api7；如需清理请手动删除

架构​

控制台必需组件​

系统要求​

获取安装包​

安装包内容​

部署流程概览​

方法 A：快速评估​

方法 B：生产标准部署​

准备 PostgreSQL​

安装​

初始化并启动 PostgreSQL​

创建数据库和角色​

启用密码认证​

验证并记录连接串​

安装软件包​

配置控制面​

启动控制面​

初始化控制台​

接入数据面网关​

验证部署​

安装 Prometheus​

运维参考​

安装后的文件布局​

服务和端口​

软件包行为​

故障排查​

卸载​

架构