版本：3.10.x

在 OpenShift 上部署

API7 网关在 Red Hat OpenShift 和标准 Kubernetes 部署上使用相同的 Helm Chart，但需要额外配置安全上下文约束（SCC）和服务账号。本页中的值与已发布的 Chart 匹配，但此流程并未在每一种受支持的 OpenShift 配置上完成端到端安装验证。请先在非生产项目中测试，并在发布前根据集群的 SCC 和存储策略审查渲染后的清单。

架构概览

API7 网关在 OpenShift 上使用与其他 Kubernetes 集群相同的双组件架构：

控制面（CP）：控制台、DP Manager 和 PostgreSQL 数据库。
数据面（DP）：处理 API 流量的 API7 网关实例。

OpenShift 的主要区别是 Pod 必须符合安全上下文约束（SCC），它限制 Pod 可以执行的操作。

前置条件

开始前，请确保具备：

受支持的 OpenShift 4 集群，以及向服务账号授予 SCC 的权限。
与集群兼容的 oc CLI 版本。请参阅安装 OpenShift CLI。
Helm 3。请参阅安装 Helm。
API7 网关许可证。请参阅获取试用许可证。

登录 OpenShift 集群

使用 oc CLI 登录。可以在 OpenShift Web 控制台的用户菜单中找到登录命令：

oc login \
  --token=sha256~YOUR_TOKEN \
  --server=https://api.YOUR_CLUSTER.openshiftapps.com:6443

验证当前身份是否可以使用本指南稍后引用的 nonroot-v2 SCC：

oc auth can-i use scc/nonroot-v2

此命令仅检查当前身份。将 SCC 使用权委托给网关服务账号，还需要在目标项目中创建 Role 和 RoleBinding 的权限。如果当前身份无法创建或绑定它们，请让集群管理员执行这些步骤。

第 1 步：创建项目

为 API7 创建专用 OpenShift 项目（命名空间）：

oc new-project api7

也可以通过 OpenShift Web 控制台创建项目。

第 2 步：安装控制面

添加 API7 Helm 仓库

helm repo add api7 https://charts.api7.ai
helm repo update

配置内置组件的安全上下文

内置 PostgreSQL、Prometheus 和 Jaeger Pod 带有明确的 securityContext 设置，与 OpenShift SCC 系统冲突。PostgreSQL 和 Prometheus 需要可写文件系统，Jaeger 则使用固定 UID。在 OpenShift 上应清除这些设置，使 SCC 系统可以从项目允许的范围中分配 UID：

cp-values.yaml
postgresql:
  primary:
    podSecurityContext:
      enabled: false
    containerSecurityContext:
      enabled: false

prometheus:
  server:
    podSecurityContext:
      enabled: false
    containerSecurityContext:
      enabled: false

jaeger:
  jaeger:
    podSecurityContext:
      runAsUser: null
      runAsGroup: null
      fsGroup: null

备注

从 API7 网关 3.9.5 开始，Jaeger 成为支持分布式追踪的内置控制面组件。与 PostgreSQL 和 Prometheus 不同，内置 Jaeger Chart 的安全上下文没有 enabled 开关，并将 runAsUser、runAsGroup 和 fsGroup 设置为 10001，会被 OpenShift SCC 拒绝。由于 Helm 会合并配置值，podSecurityContext: {} 无法清除这些键，必须逐一设置为 null。Jaeger 使用内存存储，因此不需要固定 fsGroup。

生产环境建议

生产部署应使用外部 PostgreSQL 数据库（例如 Amazon RDS、Azure Database for PostgreSQL 或专用 PostgreSQL 实例），而不是内置数据库。外部数据库配置请参阅在 Kubernetes 上部署 API7 企业版。

安装控制面 Helm Chart

helm install api7ee3 api7/api7ee3 \
  --version 3.10.14 \
  -f cp-values.yaml \
  -n api7

控制面 Chart 3.10.14 打包的是 API7 Enterprise 3.10.10，Chart 版本与应用版本相互独立。参见已发布的 Chart.yaml 和 values.yaml。

验证控制面 Service

oc get svc -n api7 -l app.kubernetes.io/name=api7ee3 -o wide

预期输出：

NAME                       TYPE        CLUSTER-IP       EXTERNAL-IP   PORT(S)             AGE
api7ee3-dashboard          ClusterIP   172.30.39.137    <none>        7080/TCP,7443/TCP   2m
api7ee3-developer-portal   ClusterIP   172.30.114.132   <none>        4321/TCP            2m
api7ee3-dp-manager         ClusterIP   172.30.232.75    <none>        7900/TCP,7943/TCP   2m

第 3 步：激活许可证

对控制台 Service 执行端口转发：

oc port-forward svc/api7ee3-dashboard -n api7 7443:7443

在浏览器中打开 https://localhost:7443，使用默认凭证（admin / admin）登录，然后上传许可证。

第 4 步：配置控制面地址

在 API7 控制台中进入 网关设置，将 DP Manager 地址 设置为：

https://api7ee3-dp-manager.api7.svc.cluster.local:7943

数据面实例将使用此地址通过 mTLS 连接控制面。

第 5 步：安装数据面

为 API7 网关配置 SCC

API7 网关运行时需要写入本地文件，例如 nginx.conf、日志和缓存文件。nonroot-v2 SCC 提供所需权限。

为网关创建服务账号：

oc create serviceaccount api7-gateway -n api7

创建授予 nonroot-v2 SCC 使用权限的角色：

oc create role api7-gateway-scc \
  --verb=use \
  --resource=scc \
  --resource-name=nonroot-v2 \
  -n api7

将角色绑定到服务账号：

oc create rolebinding api7-gateway-scc \
  --role=api7-gateway-scc \
  --serviceaccount=api7:api7-gateway \
  -n api7

生成部署脚本

在 API7 控制台中选择网关组（例如 default），进入 网关实例 并点击 新增网关实例。切换到 Kubernetes 标签页并点击生成，生成包含 mTLS 证书的部署脚本。

生成的脚本包括：

用于控制面与数据面双向认证的 TLS 证书。
包含所有必需参数的 Helm 安装命令。

添加 OpenShift 专用 Helm 配置

在生成的 Helm 命令中，将以下参数插入最后的镜像设置之前。保持生成脚本中的证书 Secret 创建命令和所有控制面连接值不变：

--set "serviceAccount.name=api7-gateway" \
--set "apisix.securityContext.runAsNonRoot=true" \
--set "apisix.securityContext.runAsUser=636" \
--version 3.10.19 \

服务账号值用于选择已获授 nonroot-v2 SCC 的账号。安全上下文值使容器保持以非 root 用户运行，并使用已发布网关镜像中内置 apisix 用户的 UID 636。此处显示的 Chart 版本是应用版本为 3.10.10 的已发布网关 Chart；生成的命令还应从网关组配置中选择 3.10.10 网关镜像。

第 6 步：验证安装

检查网关 Pod

oc get pods -n api7 -l app.kubernetes.io/name=gateway

预期输出：

NAME                                       READY   STATUS    RESTARTS   AGE
api7-ee-3-gateway-xxxxx-yyyyy              1/1     Running   0          1m

在控制台中检查网关实例

在 API7 控制台中进入网关组，网关实例应显示为健康。

发送测试请求

对网关 Service 执行端口转发并发送测试请求：

oc port-forward svc/api7-ee-3-gateway-gateway -n api7 9080:80

curl -i "http://127.0.0.1:9080/"

如果尚未配置路由，应收到 API7 网关返回的 404 响应，表明网关正在运行并接收流量。

暴露网关

使用 OpenShift Route

创建 OpenShift Route，将网关暴露到集群外：

oc expose svc/api7-ee-3-gateway-gateway -n api7 --port=apisix-gateway

要使用边缘终止 HTTPS：

oc create route edge api7-gateway \
  --service=api7-ee-3-gateway-gateway \
  --port=apisix-gateway \
  -n api7

获取 Route URL：

oc get route api7-gateway -n api7 -o jsonpath='{.spec.host}'

使用 LoadBalancer Service

如果 OpenShift 集群支持云负载均衡器：

oc patch svc api7-ee-3-gateway-gateway -n api7 \
  -p '{"spec": {"type": "LoadBalancer"}}'

故障排查

Pod 因违反 SCC 而启动失败

现象：Pod 启动失败，错误中出现 SecurityContextConstraint 或 forbidden。

解决方法：验证服务账号是否拥有正确的 SCC 绑定：

oc get rolebinding api7-gateway-scc -n api7 -o yaml

验证 SCC 是否已应用到 Pod：

oc describe pod <gateway-pod-name> -n api7 | grep -i scc

PostgreSQL、Prometheus 或 Jaeger Pod 启动失败

现象：内置 PostgreSQL、Prometheus 或 Jaeger Pod 因文件系统权限错误，或 SCC 拒绝固定 UID（Jaeger 为 runAsUser: 10001）而启动失败。

解决方法：确保按第 2 步所示，在 Helm 配置中覆盖三个组件的 securityContext。对于 Jaeger，请确认 runAsUser、runAsGroup 和 fsGroup 均设为 null，空 {} 无法清除这些值。

数据面无法连接控制面

有关 mTLS 连接问题，请参阅在 Kubernetes 上部署 API7 企业版。

常见问题

应使用哪个 SCC？

已发布的网关镜像以非 root 的 apisix 用户运行，其 UID 和 GID 均为 636，可写的运行时目录由该用户拥有。请首先尝试 nonroot-v2 和本指南中的配置值。如果集群应用了额外策略，请先检查准入错误和渲染后的 Pod 安全上下文，再授予范围更广的 SCC。不要只为绕过未解释的部署失败而授予 privileged 或 anyuid。

能否将控制面和数据面部署到不同项目？

可以。控制面与数据面通信使用 Kubernetes Service DNS（https://{service-name}.{namespace}.svc.cluster.local:7943），支持跨命名空间。请确保 OpenShift 集群网络策略允许项目之间的流量。

如何连接外部 PostgreSQL？

在 Helm 配置文件中配置数据库 DSN：

postgresql:
  builtin: false

dashboard_configuration:
  database:
    dsn: "postgres://api7ee:YOUR_DB_PASSWORD@YOUR_PG_HOST:5432/api7ee"

dp_manager_configuration:
  database:
    dsn: "postgres://api7ee:YOUR_DB_PASSWORD@YOUR_PG_HOST:5432/api7ee"

developer_portal_configuration:
  database:
    dsn: "postgres://api7ee:YOUR_DB_PASSWORD@YOUR_PG_HOST:5432/api7ee"

不要将生产数据库密码提交到 values 文件中。请使用适合集群的密钥管理工作流存储该密码。

后续步骤

部署高可用环境：配置多副本部署。
API7 网关控制面配置参考：调整控制面设置。
扩缩容数据面：添加更多网关实例。

架构概览​

前置条件​

登录 OpenShift 集群​

第 1 步：创建项目​

第 2 步：安装控制面​

添加 API7 Helm 仓库​

配置内置组件的安全上下文​

安装控制面 Helm Chart​

验证控制面 Service​

第 3 步：激活许可证​

第 4 步：配置控制面地址​

第 5 步：安装数据面​

为 API7 网关配置 SCC​

生成部署脚本​

添加 OpenShift 专用 Helm 配置​

第 6 步：验证安装​

检查网关 Pod​

在控制台中检查网关实例​

发送测试请求​

暴露网关​

使用 OpenShift Route​

使用 LoadBalancer Service​

故障排查​

Pod 因违反 SCC 而启动失败​

PostgreSQL、Prometheus 或 Jaeger Pod 启动失败​

数据面无法连接控制面​

常见问题​

应使用哪个 SCC？​

能否将控制面和数据面部署到不同项目？​

如何连接外部 PostgreSQL？​

后续步骤​