使用 Docker 在本地部署 Prisma 集群：`prisma local` 完整实战指南

• 后端
• 数据库
• GraphQL

本指南基于 Prisma 1.x（deprecated 版本）的官方文档《Local Cluster (Docker)》，讲解如何通过prisma local在本地 Docker 环境中搭建 Prisma 集群，并完成服务的部署、升级、查看与数据迁移等全流程操作。读完本文，你将掌握在无外网依赖的离线开发环境中使用 Docker 启动 Prisma 服务端、将服务部署到本地集群、安全升级集群版本等完整实战技能。

一、本地集群（Local Cluster）是什么

Prisma 的本地集群（Local Cluster）是指通过 Docker 在本机运行的 Prisma 服务端与数据库实例。默认情况下，prisma deploy会把服务部署到 Prisma Cloud 提供的托管开发集群（如prisma-eu1、prisma-us1），但在以下场景中，本地集群是更合适的选择：

• 无网络环境开发：在没有外网连接的环境下，无法访问 Prisma Cloud，本地集群可以完全离线运行；
• 数据完全本地化：数据不经过任何第三方服务，全部存储在本机 Docker 卷中；
• 开发调试隔离：可以随时start/stop/nuke本地集群，不影响云端环境。

从 CLI 源码看，Prisma CLI 专门为本地集群注册了cluster主题（topic），其描述为 "Manage local clusters"，位于 cli/packages/prisma-cli-core/src/index.ts，同时还有init-prisma主题负责初始化本地集群。这意味着prisma local ...系列命令与prisma cluster list等集群管理命令构成了完整的本地集群工作流。

二、环境准备：安装 Docker

运行本地 Prisma 集群的前提是机器上安装了较新版本的 Docker。

Prisma 官方推荐使用免费的Docker Community Edition（Docker CE），安装指引以官方站点为准（本文以当前仓库内文档的说明为基础）。安装完成后，可以通过以下命令验证 Docker 是否就绪：

docker --version docker-compose --version

需要说明的是，docker-compose同样重要——prisma init在本地集群模式下会生成docker-compose.yml，后续的本地启动本质上依赖 Docker Compose 来编排 Prisma 与数据库容器。CLI 源码中通过isDockerComposeInstalled()检测其是否安装，未安装时会提示用户参考 Docker Compose 官方安装文档，见 cli/packages/prisma-cli-core/src/commands/init/init.ts。

三、启动本地集群：prisma local start

启动本地集群非常简单，只需一条命令：

prisma local start

该命令会：

1. 从 Docker Hub 下载 Prisma 的开源 Docker 镜像；
2. 启动两个 Docker 容器：一个 Prisma 服务容器，一个 MySQL 数据库容器；
3. 首次执行时耗时较长，耗时取决于网络状况。

启动完成后，本地集群会监听http://localhost:4466，其中/cluster是集群管理端点。

从源码角度看，本地集群的容器编排模板保存在 cli/packages/prisma-cli-core/src/commands/init/boilerplate/docker-compose.yml 中，模板内定义了两个服务：

模板中值得关注的配置细节：

• MySQL 通过mysqld --max-connections=1000等参数启动，并显式设置了兼容 Prisma 的 SQL mode；
• Prisma 容器通过SQL_CLIENT_*系列环境变量连接外部数据库（即你部署服务时实际使用的数据库），通过SQL_INTERNAL_*系列环境变量连接内部元数据数据库；
• 数据卷db-persistence保证了容器重启后数据不丢失；
• 两个容器同处prismabridge 网络，可互相通信。

四、部署服务到本地集群：prisma deploy

集群启动后，就可以把服务部署上去。在项目目录（包含prisma.yml与datamodel.prisma）执行：

❯ prisma deploy ? Please choose the cluster you want to deploy "demo@dev" to (Use arrow keys) prisma-eu1 Free development cluster (hosted on Prisma Cloud) prisma-us1 Free development cluster (hosted on Prisma Cloud) ❯ local Local cluster (requires Docker)

使用方向键选择local后，CLI 会将所选集群写入项目根目录的prisma.yml，新增一个cluster条目，形如：

endpoint: http://localhost:4466/demo/dev datamodel: datamodel.prisma cluster: local

这里的交互选择逻辑对应 cli/packages/prisma-cli-core/src/commands/deploy/deploy.ts：当prisma.yml中尚未配置 endpoint 或 service 时，deploy 命令会通过EndpointDialog拉取所有可用集群（fetchClusters()）并弹出选择列表，选中后调用replaceEndpoint()把最终 endpoint 写回prisma.yml。

部署过程中 CLI 还会做两个重要检查：

• 本地集群在线检测：如果所选集群是 local 且处于离线状态（cluster.local && !(await cluster.isOnline())），会直接抛出错误Could not connect to server at ... Please check if your server is running.——此时应先执行prisma local start；
• 私有集群登录检测：对于非 local 的私有集群，会要求先登录 Prisma Cloud（cluster.local的本地集群则无需此步骤）。

deploy 命令还提供了一些实用的 flags，均定义于 deploy.ts：

使用prisma init初始化本地项目

如果你还没有项目，可以用prisma init初始化。当交互流程中选择 local 集群时，CLI 会额外生成 docker-compose.yml 与.env文件（内含PRISMA_MANAGEMENT_API_SECRET），最终目录结构如下：

prisma.yml # Prisma 服务定义 datamodel.prisma # GraphQL SDL 数据模型 docker-compose.yml # Docker 编排文件（本地集群专属） .env # 包含 PRISMA_MANAGEMENT_API_SECRET

初始化完成后，CLI 会提示下一步操作：docker-compose up -d启动 Prisma 服务端，然后prisma deploy部署服务（对应 cli/packages/prisma-cli-core/src/commands/init/init.ts 中的 next steps 输出）。

五、查看集群信息：prisma cluster list

执行以下命令可以查看当前机器上所有可用集群及其版本：

❯ prisma cluster list name version endpoint ────────────── ───────────── ────────────────────────────────── local 1.0.0-beta4.2 http://localhost:4466/cluster

输出中的每一列含义如下：

• name：集群名称（本地集群固定为local）；
• version：当前运行的 Prisma 版本号（示例中为1.0.0-beta4.2，实际以你安装的镜像版本为准）；
• endpoint：集群的管理端点地址。

通过该命令可以快速确认本地集群是否正常运行以及服务端版本是否满足项目要求。

六、升级本地集群：prisma local upgrade

当 Prisma 发布新版本时，升级本地集群同样只需要一条命令：

prisma local upgrade

升级会拉取最新的 Prisma Docker 镜像并重建容器。强烈建议在升级前先导出数据备份，使用prisma export命令：

prisma export

prisma export会把服务数据导出到本地文件，对应的实现位于 cli/packages/prisma-cli-core/src/commands/export/index.ts，其命令描述为 "Export service data to local file"。它生成的导出文件包含nodes/、lists/、relations/三个目录的 JSON 数据，之后可用prisma import恢复。

如果升级过程中或升级后出现问题，可以彻底重置（nuke）本地集群，但请注意：nuke 会清空本地集群的所有数据。重置后需要重新执行prisma local start启动集群，并可通过prisma import导入此前导出的数据。所以导出备份是升级前的必备操作。

七、直接使用现有 MySQL 数据库

本地集群默认内置 MySQL，但你也可以让 Prisma 直接连接已有的 MySQL 数据库（包括已有数据的库）。这对应官方文档提到的数据库直连（introspection）能力：

prisma introspect

introspect命令（topic 描述为 "Introspect database schema(s) of service"，见 cli/packages/prisma-cli-core/src/index.ts）会根据现有数据库的结构自动生成对应的datamodel.prisma，实现"以数据库为起点"的数据模型导入。与本地集群搭配使用时，可以做到：本地启动 Prisma → 连接本机或局域网内已有 MySQL → introspection 生成模型 → 部署服务。

八、本地集群工作流总结

把整个生命周期串起来，本地集群的典型工作流如下：

# 1. 安装 Docker CE 与 docker-compose # 2. 启动本地集群（首次会拉取镜像，较慢） prisma local start # 3. （可选）初始化项目并生成 docker-compose.yml prisma init # 4. 部署服务到 local 集群（交互选择 local） prisma deploy # 5. 查看集群状态与版本 prisma cluster list # 6. 升级前备份数据 prisma export # 7. 升级本地集群 prisma local upgrade # 8. 出问题时彻底重置（会清空数据） # prisma local nuke（重置后重新 start，再用 prisma import 恢复数据）

相关的其他部署方式可参考同一章节的姊妹文档：Digital Ocean (Docker Machine).md)、Digital Ocean (manual).md)、Kubernetes 与 Prisma Cloud，本地集群是其中唯一完全脱离云端、可离线运行的选择。

九、注意事项与限制

1. 版本前提：本文命令与配置基于 Prisma 1.x CLI（prisma local/prisma cluster主题），当前仓库已标记为 deprecated，新项目建议评估官方后续替代方案；
2. 端口占用：本地集群默认监听4466端口，且 MySQL 容器默认映射宿主端口（模板中通过DB_PORT环境变量控制），启动前请确保相关端口未被占用；
3. 数据安全：prisma local upgrade与 nuke 操作前务必先prisma export备份，nuke 操作不可逆；
4. 离线场景：prisma local start首次需要联网拉取 Docker 镜像；镜像就绪后，日常开发可完全离线进行。

通过以上步骤，你可以在本机用 Docker 快速搭建一套完整的 Prisma 本地开发环境，实现服务的离线部署、升级与数据管理，大幅降低开发环境对云端集群的依赖。

• 后端
• 数据库
• GraphQL