跳到主要内容
版本：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。

使用 Docker Compose 安装包快速体验​

通过快速上手指南安装或直接下载的 Docker Compose 安装包中，开发者门户与 API7 企业版的其余组件一起提供。激活包含 API7 Portal 特性的许可证后，在解压出的 api7-ee 目录下执行以下命令：

./portal.sh start

portal.sh 会替你完成本指南的第 1 步到第 3 步：创建门户实例及其令牌、写入 developer_portal_fe_conf/config.yaml、在安装包自带的 PostgreSQL 中创建前端数据库，并在 3001 端口启动前端。打开脚本输出的地址，注册开发者账号即可浏览发布到该门户的 API 产品。

如果已修改默认密码，需要传入控制台凭证；如果开发者通过其他地址访问门户，需要设置公共 URL：

ADMIN_USER=admin ADMIN_PASSWORD='<your password>' \
PORTAL_PUBLIC_URL=http://192.0.2.10:3001 ./portal.sh start
变量默认值说明
ADMIN_USER、ADMIN_PASSWORDadmin、admin用于创建门户实例和令牌的控制台凭证。
PORTAL_NAMEDeveloper Portal在 Provider Portal 中创建的门户实例名称。
PORTAL_PUBLIC_URLhttp://127.0.0.1:3001门户的公共 URL，同时写入前端的 app.baseURL。
PORTAL_FE_PORT3001前端在宿主机上暴露的端口。

重复执行该脚本会复用已有的门户实例、令牌和认证密钥，因此重启后开发者账号仍然有效。使用 ./portal.sh stop 或 ./portal.sh down 可以停止或移除前端；./run.sh start 会连同其余组件一起将其重新拉起。

警告

安装包中的这套部署仅用于本地体验：前端以明文 HTTP 提供服务，开发者的登录凭证和会话都以明文传输。在其他人注册使用之前，请为门户配置 HTTPS 反向代理，并把 PORTAL_PUBLIC_URL 指向该代理的地址。

备注

如果解压出的 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 产品在另一个门户上不可见，除非你也明确将其发布到该门户。

后续步骤​