使用 Provider Portal 设置开发者门户
API 门户由两个组件组成:
- Provider Portal:内置于 API7 控制台中,API 提供方可在其中管理 API 产品、门户设置和开发者订阅。
- 开发者门户:一个独立的 Web 应用,供 API 使用方发现、浏览和订阅 API 产品。
本指南演示如何将示例开发者门户与 Provider Portal 配合使用。你将使用基于 API7 Developer Portal Boilerplate 构建的 Docker 镜像部署开发者门户。该项目可作为参考实现。若要定制或自行构建开发者门户,请参阅定制开发者门户。
前置条件
- 已安装 API7 企业版 v3.9.0 或更高版本,并使用支持门户的许可证激活。试用许可证默认启用门户。参阅安装 API7 企业版。
- 根据部署方式准备以下工具:
- Docker Compose 部署:目标主机已安装 Docker 和 Docker Compose。
- Kubernetes 部署:可以访问 Kubernetes 集群,并已安装
kubectl和helm。
- 从部署开发者门户的环境可以访问 API7 企业版的门户 API。
在 Provider Portal 中创建门户
Provider Portal 是 API7 控制台的一部分。API 提供方可在其中管理 API 产品,并将产品公开到各自的开发者门户。每个在 Provider Portal 中创建的门户可以连接一个开发者门户实例,也可以连接作为副本运行的多个实例,向这些实例公开指定的 API 产品。
多个开发者门户实例共享同一个 Provider Portal 连接 Token,且配置一致(例如连接的数据库)时,它们会作为同一个门户的多个副本运行。配置不一致属于配置错误,可能导致意外行为。
在本节中,你将在 Provider Portal 中创建门户,指定开发者门户的公开 URL,并生成连接开发者门户所需的 Token。
-
打开 API7 控制台,通过左上角的按钮切换到 Provider Portal。
-
点击 添加门户。

-
为门户填写 名称,指定可访问示例开发者门户的 公开 URL,然后点击 添加。
信息目前,公开 URL 仅用于从 Provider Portal 跳转到开发者门户。每个门户都必须使用唯一的公开 URL。

-
创建门户后,点击 生成新 Token,创建用于配置开发者门户的 Token。

-
记下生成的 Token。

部署开发者门户
在本节中,你将使用基于 API7 Developer Portal Boilerplate 构建的 Docker 镜像部署开发者门户。可以使用 Docker Compose 在物理机或虚拟机上快速启动,也可以使用 Helm Chart 部署到 Kubernetes 集群。
使用 Docker Compose 部署
-
创建部署目录:
mkdir developer-portal && cd developer-portal -
创建
config.yaml文件,并根据实际环境更新配置值。config.yaml# 示例配置见 https://github.com/api7/api7-portal-boilerplate/blob/main/apps/site/config.yaml.exampleportal:# 替换为你的 API7 门户 API 端点。url: https://192.168.2.10:4321# 替换为上一节中通过 Provider Portal 生成的 Token。token: <your-portal-token>db:# 用于 PostgreSQL 兼容数据库的连接字符串。# Docker Compose 将在步骤 3 创建此数据库。url: "postgres://portal:portal123@postgres:5432/portal"auth:# 用于身份认证的密钥。# 在生产环境中,必须替换此示例值。# 可使用 `openssl rand -base64 32` 生成安全密钥。secret: "5xNGl5Ue7EV8yWjlPdYjRU2GHUrI2dXMwqF025MTS7c="app:# 替换为开发者门户的访问 URL。# 如果在本地部署,则使用你的私有 IP 地址。baseURL: "http://192.168.8.121"# CORS 信任的来源,必须包含 baseURL。trustedOrigins:- "http://192.168.8.121" -
创建 Docker Compose 文件,定义开发者门户及其数据库:
docker-compose.yamlservices:postgres:image: postgres:16environment:POSTGRES_USER: portalPOSTGRES_PASSWORD: portal123POSTGRES_DB: portalvolumes:- postgres_data:/var/lib/postgresql/datahealthcheck:test: ["CMD-SHELL", "pg_isready -U portal -d portal"]interval: 5stimeout: 5sretries: 5developer-portal:# 参阅 https://hub.docker.com/r/api7/api7-ee-developer-portal-fe 了解最新版本。image: api7/api7-ee-developer-portal-fe:v0.5.6ports:- "80:3001"volumes:- ./config.yaml:/app/apps/site/config.yamlenvironment:# 如果门户 API(例如 https://192.168.2.10:4321)使用自签名证书,# 请将此项设为 "0" 以跳过 TLS 验证。仅在开发环境中使用。NODE_TLS_REJECT_UNAUTHORIZED: "0"depends_on:postgres:condition: service_healthyvolumes:postgres_data:启动服务:
docker compose up -d
在 Kubernetes 上部署
本节介绍如何使用官方 API7 Helm Chart 在 Kubernetes 集群中部署开发者门户及其 PostgreSQL 数据库。
-
确认已安装
helm和kubectl,并且可以访问目标 Kubernetes 集群。集群网络必须能够访问 API7 企业版的门户 API。 -
添加 API7 Helm 仓库并更新:
helm repo add api7 https://charts.api7.aihelm repo update -
创建
values.yaml文件以配置开发者门户。根据实际环境更新配置值:portal:# 替换为你的 API7 企业版门户 API 端点。# 门户 API 默认使用 4321 端口,而控制台使用 7443 端口。# 在 Kubernetes 集群中使用可从集群内访问的地址,# 例如 LoadBalancer IP、NodePort 或集群内的 Service 名称。# 不要使用 host.docker.internal 或 Pod 无法访问的本机 IP。url: "https://192.168.2.10:4321"# 替换为通过 Provider Portal 生成的 Token。token: "<your-portal-token>"auth:# 在生产环境中替换为安全的随机值。# 可使用 openssl rand -base64 32 生成。secret: "5xNGl5Ue7EV8yWjlPdYjRU2GHUrI2dXMwqF025MTS7c="app:# 替换为开发者门户的访问 URL。baseURL: "https://portal.example.com"# CORS 信任的来源,必须包含 baseURL。trustedOrigins:- "https://portal.example.com"developerPortal:# API7 企业版默认使用自签名证书。# 设为 false 可跳过 TLS 验证。仅在开发环境中使用。# 在生产环境中配置可信证书,并将此项设为 true。tlsRejectUnauthorized: false提示Helm Chart 默认会自动部署内置 PostgreSQL 数据库。若要使用外部数据库,在
values.yaml中将postgresql.builtin设置为false,并配置db.url字段。 -
使用 Helm 安装开发者门户:
helm install developer-portal api7/developer-portal-fe \--namespace developer-portal \--create-namespace \-f values.yaml -
等待所有 Pod 就绪:
kubectl get pods -n developer-portal -w -
检查 Service 状态,获取访问地址:
kubectl get svc -n developer-portal开发者门户的访问 URL 取决于 Service 类型和 Ingress 配置。确保该 URL 与配置的
app.baseURL一致。如果在本地测试且没有 Ingress,可以通过
kubectl port-forward访问开发者门户:kubectl port-forward svc/developer-portal-developer-portal-fe -n developer-portal 8080:80在浏览器中打开 http://localhost:8080。确认
values.yaml中的app.baseURL为 http://localhost:8080。
验证开发者门户设置
本节将验证开发者门户的设置,包括开发者注册、与 Provider Portal 的连接,以及创建和浏览 API 产品。
-
在浏览器中访问开发者门户。地址应与
baseURL中配置的 URL 一致。在开发者门户首页点击 注册,创建账户:
填写姓名、电子邮件地址和密码,创建账户:

-
注册后,页面会提示创建组织。
信息组织来自开发者门户所用的身份认证系统(Better Auth),由该系统提供,API7 企业版不会创建或管理它。在当前的示例开发者门户实现中,每个开发者门户组织与 Provider Portal 中的一名开发者一一对应。如果你自行构建开发者门户,且没有使用 Better Auth 的组织功能,自定义实现中可能没有这一步,或无需执行这一步。

填写组织的 名称 和 Slug URL,然后点击 创建。Slug URL 是必填项,目前尚未使用。

创建组织。
-
点击 API Hub 查看可用的 API 产品。如果还没有发布 API 产品,该列表为空。

要显示 API 产品,前往 Provider Portal 创建一个 API 产品。

发布 API 产品,使其在开发者门户中可见。

-
返回开发者门户并刷新 API Hub。现在应能看到已发布的 API 产品。

点击 API 产品,查看详情。

至此,可以确认开发者门户已成功连接到 Provider Portal。
有关创建和发布 API 产品的更多说明,请参阅将服务发布为产品。
部署多个开发者门户实例
门户 API 通过域名(公开 URL)辨别不同的开发者门户。你可以为不同的受众、品牌或环境设置独立的开发者门户。
部署第二个门户实例:
-
在 Provider Portal 中,点击 添加门户创建另一个门户。

-
输入另一个 公开 URL。

-
点击 生成新 Token,记下新门户的 Token。


-
在新主机上,按照部署开发者门户中的相同步骤操作:
- 创建
config.yaml(Docker Compose)或values.yaml(Kubernetes)。 - 将
portal.token更新为新门户的 Token,将app.baseURL更新为新门户的公开 URL。 - 启动服务。
根据实际环境更新相应配置。
- 创建
-
访问第二个开发者门户。因为还没有向该门户发布 API 产品,所以 API Hub 不显示数据。

为一个开发者门户创建的 API 产品对其他门户不可见。若要在这个开发者门户提供 API 产品,请按照验证开发者门户设置中的相同步骤,将 API 产品发布到这个开发者门户。