版本：3.10.x

从 Docker 脚本接入 RPM 数据面

当你已经通过 RPM 安装了 api7-gateway，并需要将它接入控制面时，可以使用本文流程。控制台（Dashboard）的 Add Instance 当前会生成 Docker、Docker Compose 和 Helm 脚本，但尚未生成原生 RPM 脚本。

本文会从生成的 Docker 脚本中提取连接参数，并将等价配置写入 RPM 数据面的 config.yaml。RPM 安装流程请参考使用离线 RPM 包部署。

从控制台（Dashboard）获取 Docker 脚本

在控制台（Dashboard）中进入目标网关组，点击 Add Instance，选择 Docker，复制生成的 docker run 命令。该命令会通过环境变量携带所有连接参数：

docker run -d \
  -e API7_DP_MANAGER_ENDPOINTS='["https://<CP_HOST>:7943"]' \
  -e API7_GATEWAY_GROUP_SHORT_ID=default \
  -e API7_DP_MANAGER_CERT="-----BEGIN CERTIFICATE-----
  ...client certificate...
  -----END CERTIFICATE-----" \
  -e API7_DP_MANAGER_KEY="-----BEGIN PRIVATE KEY-----
  ...client private key...
  -----END PRIVATE KEY-----" \
  -e API7_CONTROL_PLANE_CA="-----BEGIN CERTIFICATE-----
  ...CA certificate...
  -----END CERTIFICATE-----" \
  -p 9080:9080 -p 9443:9443 \
  api7/api7-ee-3-gateway:<version>

你只需要其中 5 个 API7_* 环境变量的值。

环境变量与 RPM 配置映射

Docker 环境变量	RPM `config.yaml` 中的位置	说明
`API7_DP_MANAGER_ENDPOINTS`	`deployment.etcd.host`	JSON 数组 -> YAML 列表
`API7_DP_MANAGER_CERT`	写入 `conf/cert/api7ee.crt`，并在 `deployment.etcd.tls.cert` 中配置路径	客户端证书
`API7_DP_MANAGER_KEY`	写入 `conf/cert/api7ee.key`，并在 `deployment.etcd.tls.key` 中配置路径	客户端私钥
`API7_CONTROL_PLANE_CA`	写入 `conf/cert/api7ee_ca.crt`，并在 `apisix.ssl.ssl_trusted_certificate` 中配置路径	用于校验 dp-manager 服务端证书
`API7_DP_MANAGER_SNI`（可选）	`deployment.etcd.tls.sni`	如果 Docker 脚本未设置可省略；当 endpoint 是服务端证书 SAN 中包含的 IP 时也可省略
`API7_GATEWAY_GROUP_SHORT_ID`	不需要写入 `config.yaml`	网关组身份由客户端证书承载

写入证书文件

将三个 PEM 内容写入网关证书目录。注意去掉 Docker 命令中可能附带的行首缩进：

sudo install -d -m 0755 /usr/local/apisix/conf/cert

sudo tee /usr/local/apisix/conf/cert/api7ee.crt > /dev/null <<'EOF'
-----BEGIN CERTIFICATE-----
...API7_DP_MANAGER_CERT content...
-----END CERTIFICATE-----
EOF

sudo tee /usr/local/apisix/conf/cert/api7ee.key > /dev/null <<'EOF'
-----BEGIN PRIVATE KEY-----
...API7_DP_MANAGER_KEY content...
-----END PRIVATE KEY-----
EOF

sudo tee /usr/local/apisix/conf/cert/api7ee_ca.crt > /dev/null <<'EOF'
-----BEGIN CERTIFICATE-----
...API7_CONTROL_PLANE_CA content...
-----END CERTIFICATE-----
EOF

编辑网关配置

编辑网关配置文件 /usr/local/apisix/conf/config.yaml，写入 Docker 命令中的连接参数：

deployment:
  role: traditional
  role_traditional:
    config_provider: etcd
  etcd:
    host:
      - https://<CP_HOST>:7943
    tls:
      cert: /usr/local/apisix/conf/cert/api7ee.crt
      key: /usr/local/apisix/conf/cert/api7ee.key
      # sni: <API7_DP_MANAGER_SNI>
apisix:
  ssl:
    ssl_trusted_certificate: /usr/local/apisix/conf/cert/api7ee_ca.crt

如果 Docker 脚本中包含 API7_DP_MANAGER_SNI，请取消 sni 的注释并填入该值。

启动并验证网关

启动网关服务，并确认服务为 active：

sudo systemctl enable --now api7-gateway
systemctl is-active api7-gateway

确认数据面端口已经监听：

ss -ltn | grep -E ':9080|:9443'

回到控制台（Dashboard），打开网关组的 Instances 列表。实例稍后应出现并变为 Healthy。

故障排查

如果实例一直不出现，并且日志提示 requires a sufficient license，说明控制面尚未上传许可证（Dashboard -> Settings -> License）。这是控制面的前置条件，不是数据面配置问题。

控制台（Dashboard）指标依赖 Prometheus，RPM 包不包含该服务。请安装 Prometheus 并在 dp-manager 中配置它，见离线 RPM 指南中的安装 Prometheus。在此之前，已接入的网关可能记录 agent.lua:544: upload metrics block failed, status: 500；这是缺少 Prometheus 时的预期现象，实例仍可保持 Healthy，流量转发不受影响。

排查 mTLS 问题时，请查看 /usr/local/apisix/logs/error.log。certificate verify failed 或 handshake failed 通常表示 CA 或 SNI 不匹配。如果 endpoint 使用主机名，请确认该主机名出现在 dp-manager 服务端证书的 SAN 中，或设置 API7_DP_MANAGER_SNI 对应的 sni。

从控制台（Dashboard）获取 Docker 脚本​

环境变量与 RPM 配置映射​

写入证书文件​

编辑网关配置​

启动并验证网关​

故障排查​