Keystone 双服务器架构实战:Next.js 前端与 Keystone 后端 API 分离部署

原创2026-09-23 13:47:261,353 阅读
文章标签:后端

Keystone 双服务器架构实战:Next.js 前端与 Keystone 后端 API 分离部署

本指南以 examples/framework-nextjs-two-servers 示例为蓝本,讲解如何将 Keystone(GraphQL API + Admin UI)与 Next.js 前端拆分为两个独立服务器进程协同运行。读完本文,你将掌握双服务器架构的目录组织、端口分配、依赖安装与并行启动方式,并理解后端 schema 定义、数据库种子脚本与前端 GraphQL 数据拉取之间的完整调用链。

示例概览:为什么需要"双服务器"架构

在 Keystone 的典型集成方式中,前端框架与 Keystone 常常运行在同一个 Node 进程中。而 framework-nextjs-two-servers 这个示例(其英文自述为 "An example of a frontend nextjs server and backend API server")展示了一种更解耦的部署形态:

  • Keystone 后端:负责 GraphQL API、Admin UI 与数据持久化,是一个独立的 API 服务器;
  • Next.js 前端:通过 HTTP 请求调用后端 GraphQL 接口,渲染博客页面,本身不直接接触数据库。

这种分离让前后端可以独立开发、独立部署、独立扩容。整个示例由三个目录组成,其核心入口文档为 keystone-server/README.md,配套的前端说明见 nextjs-frontend/README.md,顶层聚合说明见 README.md。

快速运行:三步启动双服务器

依据 keystone-server/README.md 与顶层 README.md,运行步骤如下。

1. 安装依赖

确保处于仓库根目录,用 pnpm 安装所有 workspace 依赖:

pnpm install

本仓库是 pnpm workspace 结构,pnpm-workspace.yaml 声明了 packages/* 与 examples/* 等目录,因此一次安装即可同时覆盖后端与前端两个子包的依赖。

2. 启动双服务器

从仓库根目录进入示例目录并执行:

cd examples/framework-nextjs-two-servers
pnpm dev

顶层 package.json 中定义了并行启动脚本:

{
  "scripts": {
    "dev": "pnpm --parallel --filter ./keystone-server --filter ./nextjs-frontend dev"
  }
}

pnpm --parallel --filter 会同时以并行方式运行 keystone-server 与 nextjs-frontend 两个子包的 dev 脚本。

3. 访问服务

启动成功后两个服务分别监听不同端口:

  • GraphQL Server 与 Admin UI:http://localhost:3000(Keystone 默认端口);
  • Next.js 首页:http://localhost:8000(由前端脚本显式指定)。

如果一切正常(示例 README 用 🤞 表示),即可在 3000 端口进入 Admin UI 管理数据,在 8000 端口浏览由 GraphQL 数据渲染的博客首页。

4. 备选:双终端分别启动

如果你更习惯分别观察日志,可以打开两个终端,分别进入 keystone-server 与 nextjs-frontend 目录执行 pnpm dev,效果相同。

后端服务器:Keystone API 实例剖析

keystone-server 是纯 Keystone 后端,其脚本定义在 package.json:

{
  "scripts": {
    "dev": "keystone dev --seed-database",
    "start": "keystone start --seed-database",
    "build": "keystone build",
    "check": "keystone postinstall"
  }
}

值得注意的两点:

  • dev 与 start 都携带 --seed-database 参数,用于触发数据库种子数据的写入;
  • 后端依赖 @keystone-6/auth、@keystone-6/core、@keystone-6/fields-document、@prisma/adapter-better-sqlite3 与 better-sqlite3,说明该示例采用 SQLite + 文档字段的组合。

配置入口:keystone.ts

后端配置在 keystone.ts 中定义,核心逻辑如下:

const db: KeystoneConfigPre<TypeInfo>['db'] = {
  provider: 'sqlite',
  prismaClientOptions: () => ({
    adapter: new PrismaBetterSqlite3({ url: process.env.DATABASE_URL || 'file:./database.db' }),
  }),
  async onConnect(context: Context) {
    if (process.argv.includes('--seed-database')) {
      await seedDatabase(context)
    }
  },
}

export default config({
  db,
  lists,
})

配置要点:

  • provider: 'sqlite':数据库类型为 SQLite,对应文件默认为 ./database.db,可通过环境变量 DATABASE_URL 覆盖;
  • Prisma 驱动适配器:使用 @prisma/adapter-better-sqlite3 提供的 PrismaBetterSqlite3 适配器作为 Prisma Client 的底层驱动,这也是示例引入 better-sqlite3 依赖的原因;
  • onConnect 钩子 + --seed-database 参数:keystone dev --seed-database 会将参数透传进进程的 process.argv,onConnect 检测到该标志后调用 seedDatabase(context) 完成种子数据写入——这正是"命令参数 → 配置钩子 → 数据初始化"的完整调用链。

数据模型:schema.ts

列表模型定义在 src/schema.ts,包含两个列表:

  • User:email(必填、唯一索引)、name(必填),并通过 posts 关系字段与 Post 建立一对多关系(ref: 'Post.author');
  • Post:title(必填)、slug(唯一索引、必填)、content(文档字段,启用 formatting、dividers、links,并支持 [1,1] 与 [1,1,1] 两种网格布局)、publishDate(时间戳,默认值 { kind: 'now' },即创建时自动取当前时间)、author(多对一关系,ref: 'User.posts')。

两个列表的 access 均设置为 allowAll,便于示例演示,生产环境应替换为基于会话的访问控制。

种子数据脚本:src/seed/index.ts

种子逻辑位于 src/seed/index.ts,其幂等策略值得借鉴:

  • 从 ./src/seed/users.json 与 ./src/seed/posts.json 读取 JSON 数据;
  • 先按 email(User)与 slug(Post)查询已存在记录,仅插入数据库中不存在的数据,避免重复执行造成脏数据;
  • 写入时使用 context.sudo() 获得超级权限上下文,绕过访问控制限制;
  • 对 Post 的 content 字段,将 JSON 中的 document 结构赋值给文档字段。

Prisma 配置:prisma.config.ts

数据库相关配置见 prisma.config.ts:

export default defineConfig({
  schema: 'schema.prisma',
  migrations: {
    path: 'migrations',
  },
  datasource: {
    url: process.env.DATABASE_URL || 'file:./database.db',
  },
})

该文件声明了 Prisma schema 位置(schema.prisma)、迁移目录(migrations)与数据源 URL,与 keystone.ts 中的 DATABASE_URL 默认值保持一致。仓库中已生成 schema.graphql 与 schema.prisma,可作为 GraphQL API 与底层表结构的参考。

前端服务器:Next.js 消费 GraphQL 数据

nextjs-frontend 是标准的 Next.js Pages Router 应用,脚本见 package.json:

{
  "scripts": {
    "dev": "next dev --port 8000",
    "build": "next build",
    "start": "next start --port 8000"
  }
}

前端显式指定 --port 8000,与后端 3000 端口区分,这正是双服务器架构的关键协调点。

GraphQL 客户端封装

前端通过 src/graphql.ts 与后端通信:

const API_URI = process.env.API_URI || 'http://localhost:3000/api/graphql'

export async function fetchGraphQL(query: string, variables?: Record<string, any>) {
  return fetch(API_URI, {
    method: 'POST',
    body: JSON.stringify({ query, variables }),
    headers: { 'Content-Type': 'application/json' },
  })
    .then(x => x.json())
    .then(({ data, errors }) => {
      if (errors) {
        throw new Error(`GraphQL errors occurred:\n${errors.map((x: any) => x.message).join('\n')}`)
      }
      return data
    })
}

要点:

  • 后端 GraphQL 端点默认为 http://localhost:3000/api/graphql(Keystone 默认挂载路径),可通过环境变量 API_URI 覆盖——生产环境下可指向独立域名或负载均衡器;
  • 使用原生 fetch 以 POST 方式发送 JSON 请求体,并对 GraphQL errors 做统一抛出处理;
  • gql 只是一个模板字符串标签函数,用于获得 IDE 语法高亮。

首页:getStaticProps 拉取文章列表

src/pages/index.tsx 在 getStaticProps 中查询所有文章:

query posts {
  posts {
    id
    title
    slug
    publishDate
    author { name }
  }
}

页面将文章渲染为列表,并展示发布日期与作者信息;若请求失败则渲染错误信息。这里体现了 SSG(静态生成)与远程 GraphQL API 的组合用法——构建或刷新时向后端发请求,结果作为静态 props 输出。

文章详情页:动态路由 + DocumentRenderer

src/pages/blog/[slug].tsx 演示了动态路由的完整流程:

  • getStaticPaths 先查询所有文章的 slug 生成静态路径,fallback: false 表示未匹配的路径直接返回 404;
  • getStaticProps 按 slug 参数查询单篇文章,包含 content { document } 字段;
  • 正文渲染使用 @keystone-6/document-renderer 包的 DocumentRenderer 组件,将 Keystone 文档字段的 document 数据结构渲染为 React 元素——这是 Keystone 文档字段在前端正确显示的关键配套组件。

架构要点总结

从 keystone-server/README.md 与配套源码可以总结出双服务器架构的核心经验:

  1. 端口规划清晰:后端 3000(Keystone 默认)、前端 8000(--port 8000 显式指定),前端通过 API_URI 指向后端 GraphQL 端点;
  2. 一键并行启动:顶层 package.json 用 pnpm --parallel --filter 同时拉起两个子包,也可双终端分别启动便于分离日志;
  3. 数据初始化自动化:--seed-database 参数 + onConnect 钩子实现幂等种子数据写入,SQLite + better-sqlite3 适配器让示例开箱即用;
  4. 前端零数据库依赖:Next.js 通过 GraphQL 查询获取数据,文档字段用 DocumentRenderer 渲染,前后端仅通过 HTTP 契约耦合,可独立部署与扩容。

该示例位于 examples/framework-nextjs-two-servers,后端实现可参考 keystone.ts、src/schema.ts 与 src/seed/index.ts,前端实现可参考 src/graphql.ts、src/pages/index.tsx 与 src/pages/blog/[slug].tsx,以此作为独立部署 Keystone API 与 Next.js 前端架构的起点模板。

登录后查看全文
keystone