Keystone 双服务器架构实战:Next.js 前端与 Keystone 后端 API 分离部署
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 请求体,并对 GraphQLerrors做统一抛出处理; 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 与配套源码可以总结出双服务器架构的核心经验:
- 端口规划清晰:后端 3000(Keystone 默认)、前端 8000(
--port 8000显式指定),前端通过API_URI指向后端 GraphQL 端点; - 一键并行启动:顶层 package.json 用
pnpm --parallel --filter同时拉起两个子包,也可双终端分别启动便于分离日志; - 数据初始化自动化:
--seed-database参数 +onConnect钩子实现幂等种子数据写入,SQLite + better-sqlite3 适配器让示例开箱即用; - 前端零数据库依赖: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 前端架构的起点模板。