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

定制开发者门户

开发者门户可以从 API7 开发者门户 Boilerplate 构建，这是一个可定制的 Next.js 参考实现。本指南涵盖了最常见的自定义。

此页面引用了样板文件，因为它是自定义门户开发的公共参考实现。API7 企业版部署文档也可能指产品部署中使用的官方前端映像。

品牌推广​

徽标和图标​

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

资产文件路径目的
网站图标apps/site/app/favicon.ico浏览器选项卡图标
标志apps/site/public/logo.svg所有页面上显示标题徽标

应用程序名称和描述​

更新 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);
  /* See globals.css in the Boilerplate repository for all available variables */
}
备注

品牌更改（徽标、图标、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: [
    // ...existing plugins
    scim(),
  ],
});

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

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

  2. 运行数据库迁移：

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

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

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

传送门 SDK​

Portal SDK (@api7/portal-sdk) 已预先集成在默认的 Boilerplate 中，并为 Portal 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 参考和使用示例，请参阅门户 SDK 存储库。

构建和部署​

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

# 安装依赖
pnpm install

# 构建应用程序
pnpm build

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

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

其他资源​