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

使用提供方门户设置开发者门户

API 开发者门户由两个组件构成：

  • 提供方门户（Provider Portal）：内置于 API7 控制台（Dashboard）中，API 提供方可以在此管理 API 产品、门户设置和开发者订阅。
  • 开发者门户（Developer Portal）：一个独立的 Web 应用程序，API 消费者可以在此发现、浏览和订阅 API 产品。

本指南演示了如何将示例开发者门户与提供方门户结合使用。你将使用基于 API7 开发者门户脚手架 构建的 Docker 镜像部署开发者门户，它可作为一个参考实现。若要自定义或构建自己的开发者门户，请参阅自定义开发者门户。

前置条件​

  1. 已安装并激活带有门户许可证的 API7 企业版 v3.9.0 或更高版本。如果你使用的是试用许可证，则门户默认启用。请参阅安装 API7 企业版。
  2. 在将要部署开发者门户的系统上安装了 Docker 和 Docker Compose。
  3. 你部署的 API7 企业版的 Portal API 必须可以从将要部署开发者门户的环境中进行访问。

在提供方门户中创建门户​

提供方门户是 API7 控制台的一部分，允许 API 提供方管理 API 产品并将其公开到对应的开发者门户。在提供方门户中创建的每个门户可以连接到一个单独的开发者门户实例，或者连接到配置为副本的多个开发者门户实例，从而暴露一组定义好的 API 产品。

信息

当多个开发者门户实例共享相同的提供方门户连接 Token 并保持一致的配置（例如连接的数据库）时，它们将作为同一门户的副本运行。如果配置不同，这将被视为错误配置，并可能导致意外行为。

在本节中，你将在提供方门户中创建一个门户，指定开发者门户的公共 URL，并生成与开发者门户建立连接所需的 Token。

  1. 访问 API7 控制台并使用左上角的按钮切换到 提供方门户（Provider Portal）。

  2. 点击 添加门户（Add Portal）。

    Create Portal Before

  3. 为门户提供一个 名称（Name） 并指定示例开发者门户预期可访问的 公共 URL（Public URL），然后点击 添加（Add）。

    信息

    公共 URL 目前仅用于从提供方门户重定向到开发者门户。每个门户必须具有唯一的公共 URL。

    Create Portal

  4. 创建门户后，点击 生成新 Token（Generate New Token） 为你的开发者门户配置创建一个 Token。

    Generate Token

  5. 记下生成的 Token。

    Copy Token

部署开发者门户​

在本节中，你将使用基于 API7 开发者门户脚手架构建的 Docker 镜像部署开发者门户。

  1. 为部署创建一个新目录：

    mkdir developer-portal && cd developer-portal

  2. 创建 config.yaml 文件并根据你的环境更新对应的值。

    config.yaml
    # Example: https://github.com/api7/api7-portal-boilerplate/blob/main/apps/site/config.yaml.example
    portal:
      # Replace with your API7 Portal API endpoint.
      url: https://192.168.2.10:4321
      # Replace with the token generated from Provider Portal in the previous section.
      token: <your-portal-token>
    db:
       # Connection string for a PostgreSQL-compatible database.
       # This database will be created by Docker Compose in step 3.
       url: "postgres://portal:portal123@postgres:5432/portal"
    auth:
       # Secret key used for authentication.
       # In a production environment, this example value must be replaced.
       # You can generate a secure secret using `openssl rand -base64 32`.
       secret: "5xNGl5Ue7EV8yWjlPdYjRU2GHUrI2dXMwqF025MTS7c="
    app:
      # Replace with the URL where Developer Portal will be accessible.
      # This should be your private IP if deploying locally.
      baseURL: "http://192.168.8.121"
      # Trusted origins for CORS. Must include the 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:
        # Check https://hub.docker.com/r/api7/api7-ee-developer-portal-fe for the latest version.
        image: api7/api7-ee-developer-portal-fe:v0.5.6
        ports:
          - "80:3001"
        volumes:
          - ./config.yaml:/app/apps/site/config.yaml
        environment:
          # If your Portal API (e.g., https://192.168.2.10:4321) uses a self-signed certificate,
          # set this to "0" to skip TLS verification. Only use this in development.
          NODE_TLS_REJECT_UNAUTHORIZED: "0"
        depends_on:
          postgres:
            condition: service_healthy

    volumes:
      postgres_data:

    启动服务：

    docker compose up -d

验证开发者门户设置​

在本节中，你将验证开发者门户的设置，包括开发者注册、与提供方门户的连接以及创建和浏览 API 产品。

  1. 在浏览器中访问开发者门户。该地址应与 baseURL 配置中指定的 URL 相同。在开发者门户主页上，点击 注册（Sign Up） 以创建新帐户：

    Start Sign Up

    填写姓名、电子邮件和密码以创建新帐户：

    Sign Up

  2. 注册后，系统将提示你创建一个组织。

    信息

    组织（Organization）的概念来自开发者门户使用的身份验证系统（Better Auth），并非由 API7 企业版创建或管理。在当前的脚手架开发者门户实现中，每个开发者门户组织与提供方门户中的一个开发者建立一对一的映射。如果你构建自己的开发者门户并且不使用 Better Auth 的组织功能，则在你的自定义实现中可能不会出现或不需要此步骤。

    Organization Dashboard

    为组织输入 名称（Name） 和 Slug URL，然后点击 创建（Create）。Slug URL 是必填配置，但目前尚未使用。

    Create Organization

    创建组织。

  3. 点击 API Hub 查看可用的 API 产品。如果尚未发布任何 API 产品，最初它将是空的。

    API Hub Empty

    要查看 API 产品，请转到提供方门户并创建一个 API 产品。

    Provider Portal Add Product

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

    Provider Portal Publish Product

  4. 返回开发者门户并刷新 API Hub。已发布的 API 产品现在应该可见了。

    API Hub with Products

    点击 API 产品以查看其详情。

    API Product Detail

这确认了开发者门户已成功连接到提供方门户。

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

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

Portal API 通过其域名（公共 URL）识别不同的开发者门户。这允许你为不同的受众、品牌或环境提供独立的开发者门户。

要部署第二个门户实例：

  1. 在提供方门户中，点击 添加门户（Add Portal） 以创建另一个门户。

    Add Second Portal

  2. 输入不同的 公共 URL（Public URL）。

    Create Second Portal

  3. 点击 生成新 Token（Generate New Token） 并记下新门户的 Token。

    Generate Second Token

    Copy Second Token

  4. 在新主机上，遵循部署开发者门户中的相同步骤以：

    1. 创建 config.yaml。
    2. 创建 Docker Compose 文件以定义开发者门户及其数据库。
    3. 启动服务。

    根据你的环境相应地更新配置。

  5. 访问第二个开发者门户。由于尚未向此门户发布任何 API 产品，因此 API Hub 不显示任何数据。

    Second Portal no API Product yet

    为一个开发者门户创建的 API 产品对其他门户不可见。若要使 API 产品在此开发者门户中可用，请遵循验证开发者门户设置中的相同步骤将 API 产品发布到该开发者门户。

更多资源​