跳到主要内容
版本：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开发者门户前端——供开发者登录的 TanStack Start Web 应用程序。它使用独立的 PostgreSQL 数据库存储用户会话和开发者账户（通过 Better Auth 和 Drizzle），并使用每个门户的 Token 与门户 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 中创建门户和 Token​

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

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

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

步骤 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
  pprof:
    enable: false
    host: "127.0.0.1"
    port: 6060

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
  max_lifetime: 1h
  timeout: 5s

security:
  ssrf_protection:
    enable: false
    allow_list: []
    deny_list: []

database.max_lifetime 的默认值为 1h；该示例将其显式列出。示例还禁用了独立的 pprof 诊断监听器；该监听器默认在环回地址上启用。仅在需要时启用，并确保它不可公开访问。

SSRF 防护默认禁用。启用后，它会将出站 DCR 和审批 Webhook 请求限制为公共目标。可选的允许列表和拒绝列表填写 CIDR，而不是 URL 或主机名。允许列表条目可以覆盖被阻止的网段，因此例外应尽量收窄。无效的 CIDR 会导致启动失败。

前端配置 — frontend_conf/config.yaml​

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

frontend_conf/config.yaml
portal:
  # 门户 API 端点（后端）。根据实际情况使用公共地址或内部地址。
  url: https://api7-developer-portal-backend:4321
  # 步骤 1 中从 Provider Portal 生成的 Token。
  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:${PORTAL_API_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:${PORTAL_FE_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 PORTAL_API_VERSION=v3.10.7
export PORTAL_FE_VERSION=v0.15.3
docker compose up -d

门户 API 跟随控制面发布版本，而开发者门户前端使用独立的发布序列。不要让两个镜像共用一个版本变量。

检查所有四个容器是否都达到 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. 为该门户生成新 Token。
  3. 使用新 Token 和 config.yaml 中的公共 URL 部署另一个前端实例（Kubernetes 上的新 Deployment 或单独的 Compose 堆栈）。

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

后续步骤​