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

定制开发者门户

开发者门户可以基于 API7 Developer Portal Boilerplate 构建。它是一个可定制的 Next.js 参考实现。本指南介绍最常见的定制方式。

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

品牌定制​

Logo 和 Favicon​

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

资源文件路径用途
Faviconapps/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、Favicon 和 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>。

通用 OAuth​

对于内置社交登录提供商未涵盖的身份提供商，请使用通用 OAuth 插件。这需要修改 apps/site/src/lib/auth/server.ts。有关详情，请参阅 Better Auth OAuth 文档。

扩展功能​

Boilerplate 提供了几个扩展点：

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

添加 SCIM 支持​

要使用 Okta 等身份提供商启用 SCIM 预配：

  1. 安装 SCIM 插件：

    pnpm add @better-auth/scim@<version>

    确保该版本与你使用的 better-auth 版本匹配。

  2. 在 apps/site/src/lib/auth/server.ts 中注册插件：

    import { scim } from '@better-auth/scim';

    export const auth = betterAuth({
      plugins: [
        // ...现有插件
        scim(),
      ],
    });

  3. 更新 apps/site/app/api/auth/[...all]/route.ts 中的路由处理程序以支持 SCIM HTTP 方法：

    export const { GET, POST, PUT, PATCH, DELETE } = toNextJsHandler(auth.handler);

  4. 运行数据库迁移：

    pnpm db:generate-schema && pnpm db:generate && pnpm db:migrate

  5. 生成 SCIM 令牌并在你的身份提供商中配置它。

有关完整的 Okta 操作步骤，包括令牌生成脚本和 Okta 预配设置，请参阅使用 Okta 为自定义开发者门户配置 SCIM 预配。

Portal SDK​

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

SDK README 涵盖安装和使用，而不是底层的端点。有关完整的请求和响应契约，请参阅 开发者门户 API 参考。

服务器端使用​

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 已针对生产构建进行了预先配置。

其他资源​