跳到主要内容
版本:3.9.x

使用 Provider Portal 设置开发者门户

API 门户由两个组件组成:

  • Provider Portal:内置于 API7 控制台中,API 提供方可在其中管理 API 产品、门户设置和开发者订阅。
  • 开发者门户:一个独立的 Web 应用,供 API 使用方发现、浏览和订阅 API 产品。

本指南演示如何将示例开发者门户与 Provider Portal 配合使用。你将使用基于 API7 Developer Portal Boilerplate 构建的 Docker 镜像部署开发者门户。该项目可作为参考实现。若要定制或自行构建开发者门户,请参阅定制开发者门户。

前置条件​

  1. 已安装 API7 企业版 v3.9.0 或更高版本,并使用支持门户的许可证激活。试用许可证默认启用门户。参阅安装 API7 企业版。
  2. 根据部署方式准备以下工具:
    • Docker Compose 部署:目标主机已安装 Docker 和 Docker Compose。
    • Kubernetes 部署:可以访问 Kubernetes 集群,并已安装 kubectl 和 helm。
  3. 从部署开发者门户的环境可以访问 API7 企业版的门户 API。

在 Provider Portal 中创建门户​

Provider Portal 是 API7 控制台的一部分。API 提供方可在其中管理 API 产品,并将产品公开到各自的开发者门户。每个在 Provider Portal 中创建的门户可以连接一个开发者门户实例,也可以连接作为副本运行的多个实例,向这些实例公开指定的 API 产品。

信息

多个开发者门户实例共享同一个 Provider Portal 连接 Token,且配置一致(例如连接的数据库)时,它们会作为同一个门户的多个副本运行。配置不一致属于配置错误,可能导致意外行为。

在本节中,你将在 Provider Portal 中创建门户,指定开发者门户的公开 URL,并生成连接开发者门户所需的 Token。

  1. 打开 API7 控制台,通过左上角的按钮切换到 Provider Portal。

  2. 点击 添加门户。

    添加门户前的界面

  3. 为门户填写 名称,指定可访问示例开发者门户的 公开 URL,然后点击 添加。

    信息

    目前,公开 URL 仅用于从 Provider Portal 跳转到开发者门户。每个门户都必须使用唯一的公开 URL。

    创建门户

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

    生成 Token

  5. 记下生成的 Token。

    复制 Token

部署开发者门户​

在本节中,你将使用基于 API7 Developer Portal Boilerplate 构建的 Docker 镜像部署开发者门户。可以使用 Docker Compose 在物理机或虚拟机上快速启动,也可以使用 Helm Chart 部署到 Kubernetes 集群。

使用 Docker Compose 部署​

  1. 创建部署目录:

    mkdir developer-portal && cd developer-portal
  2. 创建 config.yaml 文件,并根据实际环境更新配置值。

    config.yaml
    # 示例配置见 https://github.com/api7/api7-portal-boilerplate/blob/main/apps/site/config.yaml.example
    portal:
    # 替换为你的 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"
  3. 创建 Docker Compose 文件,定义开发者门户及其数据库:

    docker-compose.yaml
    services:
    postgres:
    image: postgres:16
    environment:
    POSTGRES_USER: portal
    POSTGRES_PASSWORD: portal123
    POSTGRES_DB: portal
    volumes:
    - postgres_data:/var/lib/postgresql/data
    healthcheck:
    test: ["CMD-SHELL", "pg_isready -U portal -d portal"]
    interval: 5s
    timeout: 5s
    retries: 5

    developer-portal:
    # 参阅 https://hub.docker.com/r/api7/api7-ee-developer-portal-fe 了解最新版本。
    image: api7/api7-ee-developer-portal-fe:v0.5.6
    ports:
    - "80:3001"
    volumes:
    - ./config.yaml:/app/apps/site/config.yaml
    environment:
    # 如果门户 API(例如 https://192.168.2.10:4321)使用自签名证书,
    # 请将此项设为 "0" 以跳过 TLS 验证。仅在开发环境中使用。
    NODE_TLS_REJECT_UNAUTHORIZED: "0"
    depends_on:
    postgres:
    condition: service_healthy

    volumes:
    postgres_data:

    启动服务:

    docker compose up -d

在 Kubernetes 上部署​

本节介绍如何使用官方 API7 Helm Chart 在 Kubernetes 集群中部署开发者门户及其 PostgreSQL 数据库。

  1. 确认已安装 helm 和 kubectl,并且可以访问目标 Kubernetes 集群。集群网络必须能够访问 API7 企业版的门户 API。

  2. 添加 API7 Helm 仓库并更新:

    helm repo add api7 https://charts.api7.ai
    helm repo update
  3. 创建 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 字段。

  4. 使用 Helm 安装开发者门户:

    helm install developer-portal api7/developer-portal-fe \
    --namespace developer-portal \
    --create-namespace \
    -f values.yaml
  5. 等待所有 Pod 就绪:

    kubectl get pods -n developer-portal -w
  6. 检查 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 产品。

  1. 在浏览器中访问开发者门户。地址应与 baseURL 中配置的 URL 一致。在开发者门户首页点击 注册,创建账户:

    开始注册

    填写姓名、电子邮件地址和密码,创建账户:

    注册账户

  2. 注册后,页面会提示创建组织。

    信息

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

    组织管理界面

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

    创建组织

    创建组织。

  3. 点击 API Hub 查看可用的 API 产品。如果还没有发布 API 产品,该列表为空。

    API Hub 尚无产品

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

    在 Provider Portal 中创建 API 产品

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

    在 Provider Portal 中发布 API 产品

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

    API Hub 显示 API 产品

    点击 API 产品,查看详情。

    API 产品详情

至此,可以确认开发者门户已成功连接到 Provider Portal。

有关创建和发布 API 产品的更多说明,请参阅将服务发布为产品。

部署多个开发者门户实例​

门户 API 通过域名(公开 URL)辨别不同的开发者门户。你可以为不同的受众、品牌或环境设置独立的开发者门户。

部署第二个门户实例:

  1. 在 Provider Portal 中,点击 添加门户创建另一个门户。

    添加第二个门户

  2. 输入另一个 公开 URL。

    创建第二个门户

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

    生成第二个门户的 Token

    复制第二个门户的 Token

  4. 在新主机上,按照部署开发者门户中的相同步骤操作:

    1. 创建 config.yaml(Docker Compose)或 values.yaml(Kubernetes)。
    2. 将 portal.token 更新为新门户的 Token,将 app.baseURL 更新为新门户的公开 URL。
    3. 启动服务。

    根据实际环境更新相应配置。

  5. 访问第二个开发者门户。因为还没有向该门户发布 API 产品,所以 API Hub 不显示数据。

    第二个门户尚无 API 产品

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

更多资源​