Prisma Server 部署指南:自托管、Sandbox 与私有服务器全解析

原创2026-09-21 14:40:151,646 阅读
文章标签:后端数据库GraphQL

Prisma Server 部署指南:自托管、Sandbox 与私有服务器全解析

Prisma API 托管在 Prisma server 之上,服务器为其提供运行时环境。本文基于仓库 docs/1.11/04-Reference/05-Prisma-Servers-&-DBs/01-Prisma-Servers/01-Overview.md 展开,系统梳理三类 Prisma server 的适用场景、Sandbox 限流机制、prisma deploy 的 endpoint 决策流程、stable/beta/alpha 三个安装渠道,以及 Docker 与 Prisma Cloud 两种环境下的认证方案。读完本文,你将能够根据生产与开发场景选择正确的服务器形态,正确配置密钥认证,并理解限流与渠道机制背后的实现原理。

Prisma Server 的三种形态

Prisma API 可以被部署到三类服务器上,它们分别面向不同的使用阶段:

  • 本地 / 自托管服务器(Local / self-hosted):基于 Docker 自行搭建。你可以用 Docker CLI 管理底层镜像与容器,将其跑在本地开发机,或部署到你选择的云服务商主机上。这是本文后续章节讨论的重点,配套教程见 Docker.md。
  • Prisma Sandbox:Prisma Cloud 提供的免费开发服务器,面向学习和原型验证。Sandbox 中的 API 存在限流与存储上限(详见下一节)。
  • 私有服务器(Private servers):同样属于 Prisma Cloud,但它连接到你在初始化服务器时自行创建的专属数据库,与共享的 Sandbox 隔离。

注意:Prisma 1.7 之前,Prisma server 被称为 clusters(集群)。旧文档中的"集群"即指代今天的"服务器"概念。

对于生产环境,私有服务器与自托管服务器是部署 Prisma 服务的首选方案——它们不共享资源、不受限流约束,数据掌握在自己手中。

Sandbox 的限流与存储上限

当 Prisma API 部署到 Sandbox 时,会受如下约束:

  • 限流:平均每 10 秒最多 10 次请求。
  • 排队机制:超过限流后,请求先在内存中排队;一旦队列超过 25 个请求,将立即返回错误。
  • 响应头:HTTP 响应中会包含 throttled-by 字段,表示本次请求因限流被延迟的时间(单位为毫秒)。
  • 存储上限:Sandbox 中运行的 Prisma API 存储容量上限为 100 MB。

该机制的实现可以在仓库中找到佐证: RequestThrottler.scala 中通过环境变量 THROTTLING_RATE、THROTTLING_MAX_CALLS_IN_FLIGHT 构造限流器,以项目 ID 分组限流,超出的调用进入队列(Throttler 内部等待窗口),当队列溢出 ThrottleBufferFullException 时抛出 ThrottlerBufferFull 错误;成功放行的响应则会附加 Throttled-By 头(对应文档中的 throttled-by,单位为毫秒):

result.result.copy(
  headers = result.result.headers ++ Map("Throttled-By" -> (result.throttledBy.toString + "ms"))
)

同时代码支持通过 UNTHROTTLED_PROJECT_IDS 环境变量(以 | 分隔的项目 ID 列表)为特定项目免除限流——管理 API 请求本身也不会被限流。

部署时的 endpoint 决策:直接指定还是走向导

执行 prisma deploy 时,针对目标 Prisma server 存在两种情形:

  • prisma.yml 中指定了 endpoint:CLI 直接将 API 部署到该 endpoint。
  • prisma.yml 中未指定 endpoint:Prisma CLI 向导会提出几个问题,帮你构造 endpoint 并完成部署,同时把生成的 endpoint 写回 prisma.yml,作为后续部署的默认值。想再次唤起向导,可以运行:
prisma deploy --new

或者手动从 prisma.yml 中删掉 endpoint。

这一流程在 CLI 源码中有对应实现: deploy.ts 中 --new(-n)flag 的说明为 "Force interactive mode to select the cluster",当缺少 service/stage 或传入 --new 时,会调用 EndpointDialog.ts 的 getEndpoint(),通过交互式问答确定目标 cluster 与数据库,最终由 cluster.getApiEndpoint(service, stage, workspace) 构造完整 endpoint 并写回定义文件。

安装渠道:stable、beta 与 alpha

安装 Prisma 时有三个渠道可选:

渠道 定位
stable 经过充分测试的生产就绪版本,文档中的 quickstart 默认安装此渠道
beta 正在大规模测试中、尚未晋升 stable 的版本
alpha 每次有新特性或 bugfix 合入 Prisma 即更新

安装 Prisma Beta

使用 npm:

npm install -g prisma@beta

如果直接使用 Docker 镜像,可以到镜像仓库的 tags 页面查找最新 beta 镜像,或者直接使用 beta 标签始终拉取最新版。

安装 Prisma Alpha

使用 npm:

npm install -g prisma@alpha

同理,Docker 用户可直接使用 alpha 标签获取最新 alpha 镜像。

认证:Docker 与 Prisma Cloud

Docker 环境

自托管 Prisma server 支持对称与非对称两种认证方式,通过 docker-compose.yml 中的 PRISMA_CONFIG 环境变量配置。

非对称认证(公钥/私钥对)

Prisma server 通过 docker-compose.yml 中的 legacySecret 属性持有公钥;私钥保存在本地的 Prisma CLI 中,用于生成认证令牌。CLI 发起请求(如 prisma deploy)时携带该令牌,服务器用公钥验签放行。

对称认证(单一 secret)

Prisma 1.7 引入了更简洁的对称认证:管理员在部署 Prisma server 的 docker-compose.yml 中通过 managementApiSecret 设置一个 secret:

version: '3'
services:
  prisma:
    image: prismagraphql/prisma:1.11
    restart: always
    ports:
    - "4466:4466"
    environment:
      PRISMA_CONFIG: |
        managementApiSecret: my-server-secret-123
        port: 4466
        databases:
          default:
            connector: mysql  # 或 postgres
            active: true
            host: db
            port: 3306        # postgres 时为 5432
            user: root
            password: prisma
  mysql:  # 或 postgres
    container_name: prisma-db
    image: mysql:5.7
    restart: always
    environment:
      MYSQL_ROOT_PASSWORD: prisma

docker-compose.yml 的完整说明见 Docker.md。

行为规则如下:

  • 未设置 managementApiSecret:CLI 无需认证即可访问服务器。
  • 已设置:CLI 必须能访问名为 PRISMA_MANAGEMENT_API_SECRET 的环境变量(其值即该 secret),否则无法与服务器通信(例如 prisma deploy 会失败)。

底层实现可从源码确认: PrismaLocalDependencies.scala 读取 config.managementApiSecret,非空时构造 SymmetricManagementAuth.scala(基于 JWT secret 签发/校验令牌);为空时打印警告 "Management authentication is disabled..." 并退回 DummyManagementAuth。非对称路径对应 AsymmetricManagementAuth.scala,它以公钥为参数校验 CLI 令牌。配置解析集中在 ConfigLoader.scala,PRISMA_CONFIG 中的 managementApiSecret 会被提取为可选配置项。

提示:完整配置项(legacySecret、port、databases.default.connector / active / host / port / user / password 等)及其含义,请参见仓库内 Docker.md 的 "Configuration with Docker Compose" 一节。

Prisma Cloud 环境

登录

CLI 使用存储在 ~/.prisma/config.yml 中的 cloudSessionKey 对 Prisma Cloud 进行认证。首次登录时执行:

prisma login

CLI 会将该 key 写入上述文件。

登出

要从 CLI 登出,只需从 ~/.prisma/config.yml 中移除 cloudSessionKey 字段即可。

小结

  • 生产部署优先选择自托管或私有服务器;学习与原型阶段可选用带限流(10 次/10 秒、队列上限 25、throttled-by 响应头)与 100 MB 存储上限的 Sandbox。
  • prisma deploy 在 prisma.yml 缺省 endpoint 时走交互向导并回写 endpoint,也可用 prisma deploy --new 强制唤起向导。
  • 安装渠道三选一:stable(生产)、beta(待晋升)、alpha(每日更新),npm 用 @beta/@alpha 标签,Docker 用同名 tag。
  • Docker 服务器认证可选 legacySecret(非对称)或 managementApiSecret(对称);对称模式下 CLI 端必须配置 PRISMA_MANAGEMENT_API_SECRET 环境变量,而 Prisma Cloud 的会话凭证则统一存放在 ~/.prisma/config.yml。
登录后查看全文
prisma1