企业官网建设流程全解析

• 后端
• 数据库
• GraphQL

prisma token是 Prisma CLI 中用于为当前 Prisma 服务生成API Token的命令，是客户端通过Authorization: Bearer请求头访问受保护 Prisma GraphQL API 的关键前置步骤。本文基于仓库中 prisma token 官方命令参考，结合 CLI 与 prisma-yml 包源码，完整讲解命令用法、prisma.yml中secret的配置方式，以及 Token 的 JWT 签名与过期机制，让你既能直接上手运行，也能深入理解其底层原理。

一、prisma token命令概述

prisma token用于为当前 Prisma 服务生成一个新的API token。该 token 是一个 JWT）。

在 命令定义源码 中，该命令的静态描述为Create a new service token，属于token主题（topic）。它的核心执行逻辑是：

1. 读取并加载当前目录下prisma.yml定义文件（可通过--env-file注入环境变量）；
2. 从prisma.yml的endpoint中解析出service与stage；
3. 读取prisma.yml中配置的secret，签发对应服务的 JWT；
4. 默认将 token 打印到终端，或通过--copy写入系统剪贴板。

使用场景

• 服务端到服务端（B2B）鉴权：在你的后端应用中调用 Prisma API 时，需要在请求头携带 token；
• GraphQL Playground 调试：在 Playground 的 HTTP HEADERS 中填入Authorization，即可带权访问受保护 API；
• 脚本与自动化：在 CI/CD 或数据脚本中动态获取 token 后调用 Prisma API。

二、命令语法与 Flags

prisma token [flags]

Flags 一览

对应 token.ts 中的 flags 定义：

• copy：布尔型 flag，用于控制输出方式；
• env-file：字符串型 flag，对应 CLI 引擎中注入 env vars 的能力；
• project：字符串型 flag，用于指向自定义位置的 Prisma 定义文件（对应 Prisma CLI 体系中通用的--project参数）。

常用示例

打印服务 token（默认行为）：

prisma token

在包含prisma.yml的目录下执行，CLI 读取prisma.yml中的secret属性并生成对应的 JWT 打印到终端（见 Prisma API 认证文档）。

将 token 复制到剪贴板：

prisma token --copy

执行后终端输出Token copied to clipboard，token 已写入系统剪贴板，可直接粘贴到 Playground 或 HTTP 客户端中。

指定 .env 文件注入密钥：

prisma token --env-file .env

当secret通过${env:MY_SECRET}引用环境变量且变量定义在.env文件中时，可用此参数完成注入（详见下文第三节）。

三、前置条件：在prisma.yml中配置secret

prisma token能否成功生成 token，完全取决于prisma.yml中是否配置了secret。该属性定义了 Prisma 服务的API secret，是签发 JWT 的签名密钥。

3.1secret属性的配置语法

依据 prisma.yml YAML 结构参考，secret属性接受一个字符串（不是字符串列表）。若需配置多个 secret，需以逗号分隔（空格会被忽略），但整体仍是一个字符串值。

单个 secret：

secret: moo4ahn3ahb4phein1eingaep

多个 secret（逗号分隔，空格忽略）：

secret: myFirstSecret, SECRET_NUMBER_2,3rd-secret

从环境变量读取（推荐，避免密钥硬编码进版本库）：

secret: ${env:MY_SECRET}

3.2 源码级解析逻辑

在 PrismaDefinition.ts 中，CLI 加载定义文件时会将secret字符串去空格后按逗号拆分：

const secrets = this.definition.secret this.secrets = secrets ? secrets.replace(/\s/g, '').split(',') : null

也就是说，myFirstSecret, SECRET_NUMBER_2,3rd-secret会被解析为['myFirstSecret', 'SECRET_NUMBER_2', '3rd-secret']。而 token 签发时使用第一个 secret（this.secrets[0]）进行签名，因此多 secret 场景下请确认排在最前的是你希望用于当前签发的密钥。

3.3 完整的最小prisma.yml示例

endpoint: http://localhost:4466/myapi/dev datamodel: datamodel.graphql secret: mysecret123 # your API secret

该示例同时出现在 Prisma API 认证概念文档 中。

四、Token 的 JWT 签名原理

4.1 服务 token（prisma token）的生成逻辑

prisma token调用 PrismaDefinition.getToken(serviceName, stageName) 完成签发：

getToken(serviceName: string, stageName: string): string | undefined { if (this.secrets) { const data = { data: { service: `${serviceName}@${stageName}`, roles: ['admin'], }, } return jwt.sign(data, this.secrets[0], { expiresIn: '7d', }) } return undefined }

由此可以明确服务 token 的几个关键事实：

• Payload 结构：JWT 的data字段中包含service（格式为服务名@阶段名，例如myapi@dev）和roles: ['admin']，即该 token 默认携带admin 角色权限；
• 签名密钥：使用prisma.yml中配置的第一个secret；
• 有效期：expiresIn: '7d'，即7 天后过期，需要重新签发；
• 无 secret 时的行为：若prisma.yml未设置 secret，getToken返回undefined，命令会输出提示There is no secret set in the prisma.yml（见 token.ts）。

4.2 服务 token 与集群 token 的区别

仓库中还存在一个相似的命令prisma cluster-token（cluster-token.ts），二者容易混淆，区别如下：

集群 token 的生成路径在 Cluster.ts 中实现，涉及PRISMA_MANAGEMENT_API_SECRET环境变量、HS256/RS256算法选择以及最长 5 年有效期的本地 token（expiresIn: '5y'）等逻辑。普通服务 API 鉴权场景下，prisma token是更常用、更轻量的选择。

五、Token 的典型使用方式

5.1 通过Authorization请求头调用 Prisma API

Prisma API 的鉴权方式为在 HTTP 请求头中携带 token（见 Prisma API 认证文档）：

Authorization: Bearer __YOUR_API_TOKEN__

5.2 在 GraphQL Playground 中配置

在 Prisma API 的 GraphQL Playground 中，点击左下角HTTP HEADERS区域，填入：

{ "Authorization": "Bearer __YOUR_API_TOKEN__" }

真实 token 示例（JWT，三段式结构：header.payload.signature）：

{ "Authorization": "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJkYXRhIjp7InNlcnZpY2UiOiJibG9nckBkZXYiLCJyb2xlcyI6WyJhZG1pbiJdfSwiaWF0IjoxNTE4NzE2NjA4LCJleHAiOjE1MTkzMjE0MDh9.zqBh_Oo4RmV4j3UQeVDYqJDxV-YHQiOR-XIlhjbWejw" }

将prisma token生成的 token 粘贴到此处即可完成鉴权，之后 Playground 中的所有查询、变更与订阅请求都会携带该凭证。

5.3 在应用代码中的典型用法

在 Node.js 等服务端应用中，可通过环境变量保存 token 并在每次请求时注入请求头；考虑到 token 有效期仅为 7 天，生产环境通常配合定时刷新（重新执行签发）或使用更长有效期的集群凭证。

六、注意事项与常见问题

1. 未配置 secret 时：执行prisma token会得到提示There is no secret set in the prisma.yml，不会输出 token。请在prisma.yml中补充secret配置后重试。
2. secret 安全性：secret相当于 API 的签名密钥，请勿提交到公开版本库。推荐使用${env:PRISMA_SECRET}引用环境变量，并配合--env-file参数在运行时注入。
3. token 过期：服务 token 有效期为 7 天，过期后需重新执行prisma token获取。
4. 多 secret 场景：签发时使用逗号分隔列表中的第一个 secret，配置多个 secret 时请留意顺序。
5. 角色权限：prisma token生成的 token 默认携带admin角色（roles: ['admin']），具有该服务的完整管理权限，请妥善保管。

七、深入阅读

• prisma token 官方命令参考：本文所依据的原始命令文档；
• Prisma API 认证概念（API secret 与 API token）：介绍 secret 与 token 的关系及 Playground 鉴权操作；
• prisma.yml YAML 结构参考：secret属性的完整语法与多 secret 示例；
• token 命令源码：prisma token的命令实现与 flag 定义；
• PrismaDefinition.getToken 实现：服务 token 的 JWT 签名、payload 与过期时间；
• Cluster.getToken / getLocalToken 实现：集群 token 的生成逻辑，便于与服务 token 对比。

• 后端
• 数据库
• GraphQL