跳到主要内容
版本：3.9.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），并使用每个门户专用的 Token 与门户 API 通信。3001api7ee-developer-portal

一个后端为整个组织服务。你可以为不同品牌或受众部署多个前端实例，每个门户一个。

门户 API 是控制面的一部分，与 Dashboard 使用同一个数据库。本指南部署前端及其独立的会话数据库，再将前端连接到现有门户 API。如果控制面部署尚未包含门户 API，本指南也介绍如何单独运行其容器。

前置条件​

  • 已安装 API7 Enterprise，并激活支持门户的许可证（试用许可证默认包含门户支持）。
  • 前端主机可连接门户 API 端点（4321/tcp）。
  • 根据所选部署方式，准备 Docker 和 Docker Compose，或带 Helm 的 Kubernetes 集群。

创建门户和 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）。下一节要将它加入前端配置。
信息

每个门户都有唯一的公共 URL。一个门户可以对应一个前端实例，也可以对应共享同一 Token 和用户会话数据库的多个前端副本。

配置前端​

为前端配置创建工作目录：

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

前端配置​

前端使用上面生成的 Token 连接门户 API，并将身份认证和会话数据存储在独立的 PostgreSQL 数据库中。

frontend_conf/config.yaml
portal:
  url: https://YOUR_PORTAL_API_HOST:4321
  token: a7prt-xxxxxxxxxxxx

db:
  url: "postgres://portal:YOUR_PORTAL_DB_PASSWORD@portal-postgres:5432/portal"

auth:
  secret: "REPLACE_WITH_SECURE_RANDOM_STRING"

app:
  baseURL: "https://portal.example.com"
  trustedOrigins:
    - "https://portal.example.com"

❶ 将 url 设为现有门户 API 端点，其证书必须覆盖这个主机名。使用在 Provider Portal 中生成的 Token。

❷ 设置前端身份认证和会话数据库的 PostgreSQL 连接字符串。

❸ 使用 openssl rand -base64 32 生成安全的身份认证密钥。

❹ 设置开发者访问门户的公共 URL，并将相同的来源加入 trustedOrigins。

警告

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

此文件包含门户 API Token、会话数据库凭证和身份认证密钥。不要将其提交到版本控制系统。

前端会验证门户 API 证书。请使用由前端镜像信任的 CA 签发的证书。如果使用私有 CA，请将其证书挂载到前端容器，并将 NODE_EXTRA_CA_CERTS 设置为挂载文件的路径。生产部署不要关闭 TLS 验证。

如果 Docker Compose 部署使用私有 CA，请先创建 certs 目录，并将签发 CA 证书保存为 certs/portal-api-ca.crt，再将它添加到前端服务：

mkdir -p certs
# 前端以用户 ID 1001 运行，必须能读取此文件。
chmod 644 certs/portal-api-ca.crt
docker-compose.yaml (private CA excerpt)
services:
  api7-developer-portal-frontend:
    environment:
      NODE_EXTRA_CA_CERTS: /app/certs/portal-api-ca.crt
    volumes:
      - ./frontend_conf/config.yaml:/app/apps/site/config.yaml:ro
      - ./certs/portal-api-ca.crt:/app/certs/portal-api-ca.crt:ro

部署​

选择适合环境的部署方式。

Docker Compose 可快速运行前端及其会话数据库，用于开发或测试。现有门户 API 仍作为控制面的一部分运行。

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

docker-compose.yaml
services:
  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-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
    ports:
      - "3001:3001"
    depends_on:
      portal-postgres:
        condition: service_healthy
    networks:
      - portal

networks:
  portal:
    driver: bridge

volumes:
  portal_postgres_data:

编辑文件后，将所有权交给前端容器用户。Compose 会保留宿主机上的文件所有者和权限模式：

# 前端以用户 ID 1001 运行。
sudo chown 1001 frontend_conf/config.yaml
# 600 权限模式可保护 Token 和数据库密码。
sudo chmod 600 frontend_conf/config.yaml

设置前端镜像标签，然后启动容器：

export PORTAL_FE_VERSION=v0.10.0
docker compose up -d

前端 v0.10.0 与 API7 网关 3.9.22 同期发布。门户 API 跟随控制面版本，并且已经在现有控制面中运行。

确认 PostgreSQL 报告 healthy、前端报告 Up：

docker compose ps

单独运行门户 API​

如果控制面部署没有运行门户 API，可以单独运行匹配的 api7/api7-ee-developer-portal:v3.9.22 镜像。将其 database.dsn 指向包含前面创建的门户和 Token 的现有控制面数据库。不要为此服务新建空的 api7ee 数据库：Token 存储在控制面数据库中，门户 API 读不到它时身份认证会失败。

创建后端配置和 TLS 文件目录：

mkdir -p backend_conf certs

创建 backend_conf/conf.yaml，填入现有数据库 DSN 和 TLS 文件路径：

backend_conf/conf.yaml
server:
  listen:
    host: "0.0.0.0"
    port: 4321
    tls:
      enabled: true
      key_file: /app/certs/tls.key
      cert_file: /app/certs/tls.crt
  status:
    disable: false
    host: "127.0.0.1"
    port: 4322
  pprof:
    enable: false
    host: "127.0.0.1"
    port: 6060
database:
  dsn: "postgres://api7ee:YOUR_DB_PASSWORD@YOUR_CONTROL_PLANE_DB:5432/api7ee"
security:
  ssrf_protection:
    enable: false
    allow_list: []
    deny_list: []

❶ 状态监听器仍可通过环回地址供本地健康检查使用。

❷ pprof 监听器默认在环回地址启用；此示例将其禁用。仅在诊断时启用，并保持私有。

❸ 将门户 API 指向包含门户和 Token 的现有控制面数据库。

❹ SSRF 防护默认禁用。启用后可限制出站 DCR 和审批 Webhook 请求。允许和拒绝列表使用 CIDR；无效 CIDR 会导致启动失败。

将服务添加到 docker-compose.yaml：

docker-compose.yaml (separate Portal API excerpt)
services:
  api7-developer-portal-backend:
    image: api7/api7-ee-developer-portal:v3.9.22
    volumes:
      - ./backend_conf/conf.yaml:/usr/local/api7/conf/conf.yaml:ro
      - ./certs:/app/certs:ro
    command:
      - -c
      - /usr/local/api7/conf/conf.yaml
    ports:
      - "4321:4321"
    networks:
      - portal

启动服务前，将密钥和证书放入 certs 目录：

# 门户 API 以用户 ID 65532 运行。
sudo chown 65532 certs/tls.key
# 600 权限模式只允许文件所有者读取。
sudo chmod 600 certs/tls.key
# 确保门户 API 和前端均可读取证书及 CA。
chmod 644 certs/tls.crt certs/portal-api-ca.crt

通过 NODE_EXTRA_CA_CERTS 将签发 CA 提供给前端。如果两个容器都加入 portal 网络，请将 portal.url 设为证书覆盖的后端服务名，例如 https://api7-developer-portal-backend:4321。

验证部署​

  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 产品发布到特定门户。除非明确也将产品发布到另一个门户，否则该门户不会显示该产品。

后续步骤​