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

部署开发者门户

API7 开发者门户由协同工作的两个官方容器镜像组成：

镜像作用端口源代码仓库
api7/api7-ee-developer-portal门户 API（后端）——用于存储门户定义、API 产品、开发者、应用程序、订阅和凭证的 Go 服务。它与控制面的其他组件共享主 api7ee PostgreSQL 数据库。4321（HTTPS）api7ee-3-control-plane
api7/api7-ee-developer-portal-fe开发者门户前端——供开发者登录的 Next.js Web 应用程序。它使用独立的 PostgreSQL 数据库存储用户会话和开发者账户（通过 Better Auth 和 Drizzle），并使用每个门户的令牌与门户 API 通信。3001api7ee-developer-portal

一个后端为你的整个组织服务；如果需要不同的品牌或目标受众，可以部署多个前端实例（每个门户一个）。

本指南介绍如何从头部署完整技术栈。在 Kubernetes 上的大多数生产部署中，后端已作为主 api7/api7ee3 Helm Chart 的一部分安装；此时只需部署前端，并将其指向现有门户 API。

如果安装包中的 api7-ee 目录包含 portal.sh，请按照启动本地开发者门户进行本地评估。否则，请继续执行本指南中的手动步骤。Kubernetes、外部数据库、多个门户或在安装包之外管理前端的场景也应使用本指南。

前置条件​

  • 使用支持门户的许可证安装和激活 API7 Enterprise（试用许可证默认包括门户支持）。
  • 从前端主机到门户 API 端点（4321/tcp）的网络连接。
  • Docker 和 Docker Compose，或带有 Helm 的 Kubernetes 集群，具体取决于你选择的部署方法。

步骤 1：在 Provider Portal 中创建门户和令牌​

在部署开发者门户前端之前，创建门户实例并从 API7 控制台生成连接令牌。

  1. 登录 API7 控制台。
  2. 转到 Provider Portal > Add Portal。
  3. 输入 Name，并填写可访问开发者门户的 Public URL（例如 https://portal.example.com）。
  4. 创建门户后，打开 Settings > Tokens 选项卡。
  5. 单击 Generate New Token 并保存令牌（格式为 a7prt-xxxxxxxxxxxx）。在步骤 2 中，需要将该令牌填入前端配置。
信息

每个门户都有一个唯一的公共 URL。单个门户可以支持一个前端实例或共享相同令牌和用户会话数据库的多个前端副本。

步骤 2：编写配置文件​

后端和前端从单独的 YAML 文件中读取其配置。创建一个工作目录并添加这两个文件。

mkdir api7-developer-portal && cd api7-developer-portal
mkdir -p backend_conf frontend_conf

后端配置 — backend_conf/conf.yaml​

后端连接到控制面的主 api7ee 数据库。下面的 DSN 与 api7/api7ee3 Helm Chart 中的默认凭证匹配；请根据实际情况调整。

backend_conf/conf.yaml
server:
  listen:
    host: "0.0.0.0"
    port: 4321
    tls:
      enabled: true
      key_file: ""    # 可选：用于 TLS 终止的 /app/certs/tls.key
      cert_file: ""   # 可选：用于 TLS 终止的 /app/certs/tls.crt
  status:
    disable: false
    host: "127.0.0.1"
    port: 4322

log:
  level: warn
  output: stderr
  access_log: stdout

database:
  dsn: "postgres://api7ee:YOUR_DB_PASSWORD@api7-postgresql:5432/api7ee"
  max_open_conns: 30
  max_idle_time: 30s
  timeout: 5s

前端配置 — frontend_conf/config.yaml​

前端使用你在步骤 1 中生成的门户令牌指向后端，并为用户会话保留自己的小型 PostgreSQL。

frontend_conf/config.yaml
portal:
  # 门户 API 端点（后端）。根据实际情况使用公共地址或内部地址。
  url: https://api7-developer-portal-backend:4321
  # 步骤 1 中从 Provider Portal 生成的令牌。
  token: a7prt-xxxxxxxxxxxx

db:
  # 前端用户会话数据库的 PostgreSQL 连接字符串。
  url: "postgres://portal:YOUR_PORTAL_DB_PASSWORD@portal-postgres:5432/portal"

auth:
  # 生成安全值：openssl rand -base64 32
  secret: "REPLACE_WITH_SECURE_RANDOM_STRING"

app:
  # 开发者访问此门户所使用的公共 URL。
  baseURL: "https://portal.example.com"
  trustedOrigins:
    - "https://portal.example.com"
警告

在任何共享环境中运行之前，将 auth.secret 替换为安全生成的随机值。不要在生产中使用示例值。

步骤 3：部署​

选择适合你环境的部署方法。

Docker Compose 是运行自包含开发者门户技术栈以进行开发或测试的最快方式。下面的 Compose 文件会启动后端和前端两个镜像，以及用于前端用户会话的专用 PostgreSQL 数据库。

在同一目录中创建 docker-compose.yaml：

docker-compose.yaml
services:
  api7-postgresql:
    image: postgres:16
    hostname: api7-postgresql
    environment:
      POSTGRES_USER: api7ee
      POSTGRES_PASSWORD: YOUR_DB_PASSWORD
      POSTGRES_DB: api7ee
    healthcheck:
      test: ["CMD", "pg_isready", "-U", "api7ee"]
      interval: 5s
      timeout: 5s
      retries: 5
    networks:
      - portal

  portal-postgres:
    image: postgres:16
    hostname: portal-postgres
    environment:
      POSTGRES_USER: portal
      POSTGRES_PASSWORD: YOUR_PORTAL_DB_PASSWORD
      POSTGRES_DB: portal
    volumes:
      - portal_postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD", "pg_isready", "-U", "portal", "-d", "portal"]
      interval: 5s
      timeout: 5s
      retries: 5
    networks:
      - portal

  api7-developer-portal-backend:
    image: api7/api7-ee-developer-portal:${API7_VERSION}
    hostname: api7-developer-portal-backend
    restart: always
    volumes:
      - ./backend_conf/conf.yaml:/usr/local/api7/conf/conf.yaml:ro
    command:
      - /usr/local/api7/api7-ee-developer-portal
      - -c
      - /usr/local/api7/conf/conf.yaml
    ports:
      - "4321:4321"
    depends_on:
      api7-postgresql:
        condition: service_healthy
    networks:
      - portal

  api7-developer-portal-frontend:
    image: api7/api7-ee-developer-portal-fe:${API7_VERSION}
    hostname: api7-developer-portal-frontend
    restart: always
    volumes:
      - ./frontend_conf/config.yaml:/app/apps/site/config.yaml:ro
    environment:
      # 默认为 "1"（严格验证 TLS）。
      # 仅当后端在开发环境中使用自签名证书时，才设为 "0"。
      NODE_TLS_REJECT_UNAUTHORIZED: "1"
    ports:
      - "3001:3001"
    depends_on:
      portal-postgres:
        condition: service_healthy
      api7-developer-portal-backend:
        condition: service_started
    networks:
      - portal

networks:
  portal:
    driver: bridge

volumes:
  portal_postgres_data:

设置镜像版本并启动堆栈：

export API7_VERSION=3.9.10   # 固定到特定发行版；请参见“支持的版本”
docker compose up -d

检查所有四个容器是否都达到 healthy / Up 状态：

docker compose ps
备注

为使技术栈自包含，此 Compose 文件会同时部署 PostgreSQL 和后端。在实际部署中，后端通常共享控制面其他组件使用的主 api7ee PostgreSQL 数据库。请将 backend_conf/conf.yaml 指向现有数据库，并从 Compose 文件中删除 api7-postgresql 服务。

步骤 4：验证部署​

  1. 在浏览器中打开你配置的公共 URL（app.baseURL），例如 https://portal.example.com。
  2. 确认主页可以加载，且 Sign Up 按钮可见。
  3. 创建测试开发者账户以确认身份认证功能正常。
  4. 转到 API Hub，确认前端可以连接到门户 API。如果 API 产品已发布到此门户，它们将出现在此处。

部署多个门户实例​

你可以针对同一后端部署多个开发者门户前端，每个前端面向不同的受众（例如公共开发者、内部团队或合作伙伴）：

  1. 在 Provider Portal 中，创建另一个具有唯一名称和公共 URL 的门户。
  2. 为该门户生成新令牌。
  3. 使用新令牌和 config.yaml 中的公共 URL 部署另一个前端实例（Kubernetes 上的新 Deployment 或单独的 Compose 堆栈）。

API 产品发布到特定门户。发布到一个门户的 API 产品在另一个门户上不可见，除非你也明确将其发布到该门户。

后续步骤​