版本：3.10.x

使用离线 RPM 包部署

本文介绍如何在 Red Hat 系 Linux 系统（RHEL、Rocky Linux、AlmaLinux、CentOS 8/9）中，使用离线 RPM 包部署 API7 网关。准备好 API7 安装包及所需的操作系统和数据库软件包后，即可在没有互联网连接的情况下安装。

主流程适用于 API7 网关 3.10.7 及更高版本的 RPM 包布局，其控制台二进制内嵌 Web UI。较早的 3.10.x 安装包请参阅下文的旧版包说明。

架构

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

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

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

控制台必需组件

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

组件	来源	是否必需	用途
`api7ee-dashboard`	`api7ee-dashboard` RPM	是	内嵌 Web UI 的控制面后端，通过 `7443` 提供 UI/API
`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 或 aarch64
初始化系统	systemd，所有组件都以 systemd 服务运行。容器化评估时也必须让 systemd 作为 PID 1 运行，见方法 A
权限	`root` 或 `sudo`
PostgreSQL	13+，推荐 15；可部署在本机、独立主机或云托管数据库中
控制面端口	`7443`（控制台/API，对外访问）、`7943`（数据面 mTLS 接入，需对 DP 主机开放）、`7900`/`7901`/`7081`（本地/内部）。控制台默认配置禁用明文 HTTP `7080`
数据面端口	`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.9-el9.x86_64.tar.gz。请替换为许可证随附安装包的版本。

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

将许可证随附的 .tar.gz 复制到目标主机。对于隔离网络主机，请在断网前同时准备部署所需的操作系统和数据库软件包。

安装包内容

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

网关包自带 OpenResty 运行时，控制面包提供静态 Go 二进制文件，不需要主机的 nodejs 或 openresty 包，因此安装可离线进行，也不会影响主机上已有软件。

旧版独立 Console 安装包

API7 网关 3.10.2 至 3.10.6 使用较早的控制台包，还会安装 Node.js、Console 目录、console.env，以及监听内部端口 3000 的独立 api7ee-console systemd 服务。其服务和文件布局请按该安装包随附的说明操作。下文流程适用于 3.10.7 及更高版本的内嵌控制台安装包。

API7 网关 3.10.1 提供 el8 和 el9 的 x86_64 包，请按该包内的说明和 systemd 单元文件操作。

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

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

部署流程概览

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

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

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

路径	适用场景	特点
方法 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 --no-same-owner
cd api7-ee-rpm-<version>-<dist>.<arch>/
sudo ./install.sh         # 等价于 dnf -y localinstall ./*.rpm --disablerepo='*'

--no-same-owner 选项让解压出的文件归执行解压的用户所有。v3.10.10 之前发布的安装包中，文件属主记录为构建机上的用户，以 root 身份运行 tar 时会保留这个属主。

如果控制面和数据面分离，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"

控制台默认通过 TLS 7443 提供内嵌 UI 和 API，禁用明文 HTTP 7080，7081 为本地状态端口。如需使用自有证书，请在 dashboard.yaml 中设置 server.tls.cert_file 和 server.tls.key_file；两者都为空时，控制台会生成自签名证书。

启动控制面

启动两个控制面服务，并确认二者都为 active：

sudo systemctl enable --now api7ee-dp-manager
sudo systemctl enable --now api7ee-dashboard
systemctl is-active api7ee-dp-manager api7ee-dashboard   # 预期二者均为 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 登录，并按提示修改密码。
从组织菜单进入 许可证，上传包含 BEGIN CERTIFICATE 和 BEGIN LICENSE 两个区段的许可证，并确认状态正常。

接入数据面网关

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

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

在控制台进入 网关组，选择或创建网关组，点击 新增网关实例。
选择 RPM，选择证书有效期，然后生成脚本。
在 DP 主机上安装 api7-gateway RPM 后，运行生成的脚本。脚本会写入该网关组的证书文件，用该组的控制面连接设置替换网关 config.yaml，然后重启网关服务。选择非默认网关组时，脚本会生成该组的材料；不要复用其他组的脚本。

API7 网关 3.10.2 及更高版本提供 RPM 选项。较早版本或不显示该选项的定制控制台，请使用从 Docker 脚本手动接入 RPM 数据面这一备用流程。

验证部署

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

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

安装 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/                # Dashboard 二进制文件和配置

/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`
网关配置	`/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）/ 7081；明文 HTTP 7080 已禁用	`/usr/local/api7/dashboard/conf/dashboard.yaml`
数据面	`api7-gateway`	9080 / 9443	`/usr/local/apisix/conf/config.yaml`

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

软件包行为

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

故障排查

现象	排查方向
控制台 UI 不可用	检查 `systemctl status api7ee-dashboard` 和 `/var/log/api7/`，确认 `7443` 端口开放、控制台 TLS 配置有效
控制面启动失败	通常是数据库不可达：检查数据库连接串、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-dashboard api7ee-dp-manager
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​

运维参考​

安装后的文件布局​

服务和端口​

软件包行为​

故障排查​

卸载​

架构