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

定制开发者门户

API7 Developer Portal Boilerplate 是一款可定制的 TanStack Start 应用，使用 React、Tailwind CSS、Better Auth 和 API7 Portal SDK 构建。本指南介绍最常见的源码级定制方式。

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

品牌定制​

Logo 和站点图标​

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

资源文件路径用途
站点图标apps/site/public/favicon.ico浏览器选项卡图标和默认页眉 Logo

应用程序名称和描述​

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

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

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

主题​

门户使用 Tailwind CSS 和共享的 @api7/portal-ui 样式。编辑 apps/site/src/globals.css，添加门户专用的主题变量或覆盖项：

apps/site/src/globals.css
:root {
  --primary: oklch(0.55 0.18 255);
  --primary-foreground: oklch(0.985 0 0);
  --background: oklch(1 0 0);
  --foreground: oklch(0.145 0 0);
}

共享组件主题从 @api7/portal-ui/styles.css 导入。覆盖其自定义属性前，请先检查该软件包，确保明暗主题保持一致。

备注

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

身份认证定制​

电子邮件和密码​

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

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

要启用电子邮件验证，请在 apps/site/src/lib/auth/server.ts 的 Better Auth 配置中添加验证邮件发送器。在实现该发送器前，不要设置 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 提供商，请将其添加到 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 会通过 Better Auth 的通用 OAuth 插件注册这些条目。向身份提供商注册客户端时，请使用提供商配置中显示的回调 URL。

扩展功能​

Boilerplate 提供了几个扩展点：

扩展点位置描述
路由apps/site/src/routes/使用 TanStack Router 基于文件的路由添加页面和服务器路由。
组件apps/site/src/components/创建或替换门户 UI 组件。
身份认证逻辑apps/site/src/lib/auth/自定义身份认证流程。
数据访问apps/site/src/lib/dal/添加访问 Portal SDK 或数据库的服务器函数。
共享 UIpackages/ui/自定义门户共用的组件。

添加身份认证扩展​

已发布的 Boilerplate 通过 apps/site/src/routes/api/auth/$.ts 路由 Better Auth 请求。在 apps/site/src/lib/auth/server.ts 中添加 Better Auth 插件，然后从路由处理程序中公开该插件所需的 HTTP 方法。

例如，当前路由会将以下方法委托给 auth.handler：

apps/site/src/routes/api/auth/$.ts
const handler = ({ request }: { request: Request }) => auth.handler(request);

export const Route = createFileRoute('/api/auth/$')({
  server: {
    handlers: {
      GET: handler,
      POST: handler,
      PUT: handler,
      PATCH: handler,
      DELETE: handler,
    },
  },
});

如果扩展改变了 Better Auth 数据库 schema，请重新生成 schema 和迁移，审查生成的 SQL，并在部署新应用版本前应用迁移。

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();

从服务器函数调用 SDK​

Portal SDK 2.0.0 从 @api7/portal-sdk 导出客户端，不再提供旧的 @api7/portal-sdk/browser 导出。请将 Portal API 令牌保留在服务器端，并从 apps/site/src/lib/dal/ 下的代码或其他 TanStack Start 服务器函数调用 SDK。只向浏览器组件返回其所需的数据。

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

构建和部署​

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

# 安装依赖
pnpm install

# 构建应用程序
pnpm build

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

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

其他资源​