版本：3.9.x

自定义开发者门户

本指南涵盖了如何基于 API7 开发者门户脚手架自定义 开发者门户（Developer Portal）。

概览

API 开发者门户（API Portal）包含一个可自定义的开发者门户，供开发者发现和消费 API。API7 提供了一个开源的开发者门户脚手架（Developer Portal Boilerplate）作为基础，它包含：

内置组件：

基于 Next.js 构建，允许前端工程师使用熟悉的技术栈。
使用 Better Auth 构建的完整用户管理系统。
集成了 @api7/portal-sdk 以用于 API 开发者门户的 API 集成。

内置功能：

邮箱/密码认证（可启用 SSO）。
展示 API 产品并渲染 OpenAPI 文档。
支持通过 Try it Out 功能测试 API。
支持创建应用程序（Applications）和凭证（Credentials）。
支持使用 DCR 协议与身份提供商（IdP）集成。

你的前端工程师可以自定义和扩展该基础，以满足你的要求。

有关更多详细信息，请参阅脚手架仓库。

配置

所有配置均通过 apps/site/config.yaml 进行管理。从 config.yaml.example 复制并针对你的环境进行自定义。配置支持环境变量替换：

语法	行为
`${VAR}`	必填 - 如果未设置 `VAR` 则报错
`${VAR:default}`	选填 - 如果未设置 `VAR`，则使用 `default`

连接到 API 开发者门户后端

开发者门户将连接到 API 开发者门户的后端 API。请确保你的开发者门户可以访问此端点：

config.yaml
portal:
  url: ${PORTAL_URL}
  token: ${PORTAL_TOKEN}

创建 Portal Token：

登录到 API7 企业版控制台（Dashboard）并切换到 API7 提供方门户（Provider Portal）。
导航到 开发者门户设置（Developer Portal Settings）。
生成一个用于 API 访问的 Token。
复制该 Token（格式为：a7prt-xxxxxxxxxxxx）。

应用程序设置

config.yaml
app:
  name: "Your Developer Portal"      # 浏览器标题和页眉中显示的名称
  desc: "Your portal description"    # 用于 SEO 的 meta description
  baseURL: "https://your-portal.example.com"  # 用于生成链接和 SEO 的公共 URL
  trustedOrigins:                    # 允许跨域和认证回调的来源
    - "https://your-portal.example.com"

品牌化自定义

备注

本节中的更改需要重新构建并重新部署应用程序才能生效。对 config.yaml 的更改需要重新启动应用程序。

Logo 与静态资源

将以下文件替换为你组织的静态资源：

文件	位置	目的
Favicon	`apps/site/app/favicon.ico`	浏览器标签页图标
Logo	`apps/site/public/logo.svg`	页眉 Logo

主题自定义

编辑 apps/site/app/globals.css 以自定义颜色和样式。门户使用了 Tailwind CSS、Shadcn UI 和 Ant Design。

示例：自定义主色调

globals.css
:root {
  --primary: oklch(0.205 0 0);
  --primary-foreground: oklch(0.985 0 0);
}

关于可用的主题变量，请参阅脚手架仓库中的 globals.css 文件。

身份验证

脚手架使用 Better Auth 进行身份验证。

邮箱和密码

此配置控制用户注册和登录的邮箱和密码身份验证。

config.yaml
auth:
  emailAndPassword:
    enabled: true
    requireEmailVerification: false

Better Auth 不提供内置的电子邮件服务商集成。若要启用电子邮件验证，你需要在 apps/site/src/lib/auth/server.ts 中集成你首选的电子邮件服务商的 SDK。在没有此集成的情况下，设置 requireEmailVerification: true 将不会发送任何电子邮件。有关更多详细信息，请参阅 Better Auth 电子邮件文档。

SSO 集成

Better Auth 支持与各种流行的 OAuth 提供商集成，例如 GitHub 和 Google。

config.yaml
auth:
  socialProviders:
    github:
      clientId: ${GITHUB_CLIENT_ID}
      clientSecret: ${GITHUB_CLIENT_SECRET}
    google:
      clientId: ${GOOGLE_CLIENT_ID}
      clientSecret: ${GOOGLE_CLIENT_SECRET}

对于企业身份提供商，你可以配置一个通用的 OAuth 插件。这需要修改 apps/site/src/lib/auth/server.ts 中的代码。有关更多详细信息，请参阅 Better Auth OAuth 文档。

扩展门户

脚手架提供了用于自定义开发的扩展点：

扩展点	位置	描述
页面 (Pages)	`apps/site/app/`	添加或修改 Next.js 页面
组件 (Components)	`apps/site/components/`	自定义 UI 组件
认证逻辑 (Auth Logic)	`apps/site/src/lib/auth/`	身份验证自定义
API 路由 (API Routes)	`apps/site/app/api/`	自定义后端端点

有关高级自定义，请参阅 Next.js 和 Better Auth 文档。

Portal SDK

Portal SDK (@api7/portal-sdk) 提供了一个 TypeScript 客户端，用于与 API 开发者门户的后端 API 进行交互。脚手架已经预先集成了此 SDK。你也可以独立使用它来构建自定义的集成。

安装

npm install @api7/portal-sdk

服务端用法

对于后端应用程序或 BFF（Backend for Frontend，服务于前端的后端）：

import { API7Portal } from '@api7/portal-sdk'

const client = new API7Portal({
  endpoint: 'https://api7-portal-api.example.com',  // API Portal backend API URL
  token: 'a7prt-...',
  getDeveloperId: async () => await getDeveloperIdFromSession(),
});

const products = await client.apiProduct.list();

客户端用法

对于带有 BFF 代理的基于浏览器的应用程序：

import { API7Portal } from '@api7/portal-sdk/browser'

const client = new API7Portal();
const products = await client.apiProduct.list();

有关完整的 SDK 文档和可用的 API，请参阅 Portal SDK 仓库。你也可以参考脚手架仓库以获取实际使用示例。

概览​

配置​

连接到 API 开发者门户后端​

应用程序设置​

品牌化自定义​

Logo 与静态资源​

主题自定义​

身份验证​

邮箱和密码​

SSO 集成​

扩展门户​

Portal SDK​

安装​

服务端用法​

客户端用法​

更多资源​

概览

配置