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

定制开发者门户

API7 Developer Portal Boilerplate v0.10.0 是与此 API7 网关版本相匹配、可定制的 Next.js 参考实现。本指南介绍常见的定制方式。

本文引用该 Boilerplate，因为它是开发自定义门户的公共参考实现。API7 Enterprise 部署文档也可能引用产品部署所使用的官方前端镜像。

品牌定制​

Logo 和站点图标​

将以下文件替换为你组织的资产：

资源文件路径用途
站点图标apps/site/app/favicon.ico浏览器选项卡图标
Logoapps/site/public/logo.svg所有页面页眉中的 Logo

应用程序名称和描述​

更新 config.yaml 以更改门户名称和描述：

config.yaml
app:
  name: "Acme API Portal"
  desc: "Discover and integrate with Acme APIs"

name 会显示在浏览器标题栏和门户页眉中。desc 用作 SEO 元描述。

主题​

门户使用 Tailwind CSS 和 CSS 自定义属性来设置主题。编辑 apps/site/app/globals.css 来定制颜色：

apps/site/app/globals.css
:root {
  --primary: oklch(0.205 0 0);
  --primary-foreground: oklch(0.985 0 0);
  --background: oklch(1 0 0);
  --foreground: oklch(0.145 0 0);
  /* 其他可用变量请参阅 Boilerplate 仓库中的 globals.css */
}
备注

品牌变更（Logo、站点图标和 CSS）需要重新构建并部署应用程序。修改 config.yaml 后需要重启应用程序。

身份认证定制​

电子邮件和密码​

在 config.yaml 中控制电子邮件和密码身份认证：

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

要启用电子邮件验证，请在 apps/site/src/lib/auth/server.ts 中集成电子邮件提供商 SDK。如果未集成电子邮件提供商，设置 requireEmailVerification: true 会阻止用户注册，因为验证邮件无法发送。

社交登录提供商​

在 config.yaml 中添加基于 OAuth 的社交登录提供商：

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

向每个提供商注册 OAuth 应用程序以获取客户端 ID 和密钥。将回调 URL 设置为 https://<PORTAL_DOMAIN>/api/auth/callback/<provider>。

通用 OpenID Connect 提供商​

对于内置社交提供商未覆盖的 OpenID Connect 提供商，请在 config.yaml 中将其添加到 auth.genericOAuthProviders：

config.yaml
auth:
  genericOAuthProviders:
    - providerId: keycloak
      discoveryUrl: https://id.example.com/realms/acme/.well-known/openid-configuration
      clientId: ${OIDC_CLIENT_ID}
      clientSecret: ${OIDC_CLIENT_SECRET}
      scopes:
        - openid
        - profile
        - email

Boilerplate v0.10.0 会通过通用 OAuth 插件注册这些条目。通用提供商使用回调 URL https://<PORTAL_DOMAIN>/api/auth/oauth2/callback/<providerId>。对于此示例，请向提供商注册 https://<PORTAL_DOMAIN>/api/auth/oauth2/callback/keycloak。

扩展功能​

Boilerplate 提供了几个扩展点：

扩展点位置描述
页面apps/site/app/使用 Next.js App Router 添加或修改页面。
组件apps/site/components/创建自定义 UI 组件。
身份认证逻辑apps/site/src/lib/auth/自定义身份认证流程。
API 路由apps/site/app/api/添加自定义后端端点。

添加 SCIM 支持​

Boilerplate v0.10.0 默认不启用 SCIM。添加 SCIM 需要与该 Boilerplate 锁定的 Better Auth 1.6.19 依赖版本兼容的插件、额外的身份认证路由方法、经过审查的数据库迁移，以及由所有者控制的预配凭据。

参阅使用 Okta 为自定义开发者门户配置 SCIM 预配，了解已验证的用户创建和属性更新流程。SCIM 1.6.19 将 active 属性设为只读，并且在此基线中未建立 Okta 停用用户的流程；身份撤销和门户授权需要另外定制集成。

Portal SDK​

Portal SDK（@api7/portal-sdk）已预先集成到默认 Boilerplate 中，为门户 API 提供 TypeScript 客户端。你也可以单独使用它来构建自定义集成。

SDK README 涵盖安装和使用，而不是底层的端点。3.10.9 开发者门户 API 参考（不可用于核定 3.9 请求和响应）仅供了解当前版接口。3.9 的请求和响应契约请以所安装版本的规范或 API7 支持确认为准。

服务器端使用​

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

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

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

客户端使用​

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

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

有关完整的 SDK API 参考和使用示例，请参阅 Portal SDK 仓库。

构建和部署​

进行自定义后，构建并部署应用程序：

# 安装依赖
pnpm install

# 构建应用程序
pnpm build

# 或构建 Docker 镜像
docker build -t my-developer-portal .

Boilerplate 仓库中的 Dockerfile 已针对生产构建进行了预先配置。

其他资源​