Prisma CLI `prisma cluster add` 实战指南：把自建集群注册进 Cluster Registry

Prisma CLIprisma cluster add实战指南把自建集群注册进 Cluster Registry【免费下载链接】prisma1 Database Tools incl. ORM, Migrations and Admin UI (Postgres, MySQL MongoDB) [deprecated]项目地址: https://gitcode.com/gh_mirrors/pr/prisma1prisma cluster add是 Prisma CLI 中用于把已存在的集群登记到本地集群注册表cluster registry的命令。它通过交互式提示收集新集群的name、host与clusterSecret三个信息写入~/.prisma/config.yml之后prisma deploy即可将服务部署到该集群。本文以 Prisma 1.2 文档为骨架结合prisma-yml、prisma-cli-core源码完整讲解命令用法、字段含义、注册表文件结构以及底层实现原理。背景集群与集群注册表Cluster Registry在 Prisma 中Prisma 服务service被部署到所谓的集群cluster上。集群是承载 Prisma 服务运行的环境大体分为两类详见 docs/1.2/04-Reference/05-Clusters/01-Overview.md自托管 / 本地集群基于 Docker 运行由 Prisma CLI 管理底层 Docker 镜像与容器公共集群基于 Prisma Cloud无需自行配置集群即可将服务部署到公网但存在请求限流、存储上限等限制。Prisma CLI 首次使用时会在用户主目录创建.prisma目录其中包含集群注册表文件~/.prisma/config.yml。该文件登记了你可以部署服务的所有集群信息。运行prisma deploy时CLI 会依据注册表为你提供部署选项。prisma cluster add正是向这个注册表登记新集群的官方命令入口。prisma cluster add用法与交互流程命令本身不接受任何参数直接运行即可prisma cluster add执行后CLI 会触发一个交互式提示interactive prompt依次要求提供新集群的name、host和clusterSecret。真实交互示例根据 docs/1.2/04-Reference/05-Clusters/02-Docker.md 中记录的实操流程实际交互过程如下❯ prisma cluster add ? Please provide the cluster endpoint Define your cluster endpoint. Local: http://localhost:4466; Digital Ocean: http://droplet-ip-address:4466 ? Please provide the cluster secret Local: Leave empty (CLUSTER_PUBLIC_KEY is commented); Digital Ocean: The private key from the key pair generated via https://api.cloud.prisma.sh ? Please provide a name for your cluster your-cluster-name注意所有输入值请不要带引号直接填写。可以看到实际提示顺序是先问hostcluster endpoint再问clusterSecret最后问name与命令文档中列举字段的顺序略有不同——但三者缺一不可。三个输入字段详解字段含义取值说明name集群名称集群在注册表中的唯一标识键需与prisma.yml中cluster属性的值保持一致host集群端点地址本地集群形如http://localhost:4466Digital Ocean 等远程集群形如http://droplet-ip-address:4466clusterSecret集群密钥本地开发集群通常留空对应CLUSTER_PUBLIC_KEY被注释的场景启用认证的集群需填写密钥对中的私钥添加结果集群注册表~/.prisma/config.yml的结构添加成功后集群信息会被写入集群注册表~/.prisma/config.yml。一个典型的注册表文件示例如下clusters: local: host: http://localhost:4466 clusterSecret: -----BEGIN RSA PRIVATE KEY----- [ long key omitted ] -----END RSA PRIVATE KEY-----\r\n digital-ocean: host: http://45.55.177.154:4466 clusterSecret: -----BEGIN RSA PRIVATE KEY----- [ long key omitted ] -----END RSA PRIVATE KEY-----\r\n该结构与源码中定义的配置类型完全对应。在 cli/packages/prisma-yml/src/types/rc.ts 中注册表的 TypeScript 类型定义如下export interface RC { cloudSessionKey?: string clusters?: Clusters } export interface Clusters { [name: string]: ClusterConfig } export interface ClusterConfig { host: string clusterSecret: string }可以看到clusters是一个以集群名为键、以{ host, clusterSecret }为值的映射与文档示例逐字段吻合。注册表文件的读写实现从 cli/packages/prisma-yml/src/Environment.ts 的源码可以确认注册表文件的完整生命周期路径this.rcPath path.join(this.home, .prisma/config.yml)首次使用时fs.mkdirpSync自动创建目录加载loadGlobalRC()读取文件内容parseGlobalRC()通过js-yaml的safeLoad解析并支持在 YAML 中使用变量占位符Variables.populateJson写入saveGlobalRC()通过yaml.safeDump序列化{ cloudSessionKey, clusters }后写回文件集群合并addCluster(cluster)在写入前会先按workspaceSlug name查找已存在的同名集群若存在则先移除再追加避免重复登记。此外Environment会预置prisma-eu1、prisma-us1两个共享公共集群sharedClusters数组并可通过PRISMA_CLOUD_SESSION_KEY登录后从 Prisma Cloud 拉取你配置的集群列表fetchClusters()。注册后的工作方式prisma deploy如何找到集群注册表的核心消费场景是prisma deploy。当prisma.yml中的cluster属性被指定时CLI 直接部署到该集群其值必须是注册表clusters映射中的某个键或 Prisma Cloud 账户中配置的集群名未被指定时CLI 弹出集群交互选择选择结果会被写回prisma.yml作为默认值再次唤起选择需运行prisma deploy --interactive或手动删除prisma.yml中的cluster属性。prisma.yml中的cluster属性说明详见 docs/1.2/04-Reference/02-Service-Configuration/02-prisma.yml/02-YAML-Structure.md其约束为只含字母数字、连字符与下划线以大小写字母开头最长 64 字符。示例cluster: local注册表内的集群在运行时被映射为Cluster类实例见 cli/packages/prisma-yml/src/Cluster.ts关键行为包括端点归一化构造函数会去掉baseUrl末尾的/避免拼接出双斜杠部署端点选择getDeployEndpoint()返回${baseUrl}/management老版本集群则回退到/cluster由hasOldDeployEndpoint标记控制API 端点推导getApiEndpoint()依据集群的shared、local、isPrivate属性推导出http(s)://host/service/stage形式的 API 地址。认证原理clusterSecret 如何派上用场集群使用公钥/私钥对进行安全认证集群持有公钥私钥保存在本地由 Prisma CLI 用于生成集群令牌cluster token请求如prisma deploy携带的令牌可被集群用公钥校验。在 cli/packages/prisma-yml/src/Cluster.ts 的getLocalToken()中可以看到私钥的具体用法getLocalToken(): string | null { if (!this.clusterSecret !process.env.PRISMA_MANAGEMENT_API_SECRET) { return null } const grants [{ target: */*, action: * }] const secret process.env.PRISMA_MANAGEMENT_API_SECRET || this.clusterSecret const algorithm process.env.PRISMA_MANAGEMENT_API_SECRET ? HS256 : RS256 this.cachedToken jwt.sign({ grants }, secret, { expiresIn: 5y, algorithm, }) return this.cachedToken! }也就是说启用认证的集群其clusterSecret私钥被用于以RS256算法签发有效期 5 年的 JWT 集群令牌若设置了环境变量PRISMA_MANAGEMENT_API_SECRET则优先使用该变量并以HS256签发未提供私钥时返回null表示集群不需要认证对应本地开发时CLUSTER_PUBLIC_KEY被注释的场景。prisma cluster token命令源码见 cli/packages/prisma-cli-core/src/commands/token/cluster-token.ts封装了同样的令牌生成逻辑支持-c/--copy将令牌复制到剪贴板、-e/--env-file指定.env注入环境变量、-p/--project指定 Prisma 定义文件。实战流程从 Docker 部署到集群注册结合 docs/1.2/04-Reference/05-Clusters/02-Docker.md 的完整步骤一个典型的自建集群 注册流程如下启动本地集群运行prisma local start内部代理docker-compose up本机即拥有基于prismagraphql/prisma与mysql:5.7镜像的本地集群远程场景启用集群认证生成 RSA 公/私钥对将公钥通过CLUSTER_PUBLIC_KEY环境变量提交给 Prisma 集群注册集群运行prisma cluster add按提示输入端点、密钥与名称验证运行prisma cluster list查看注册表与 Prisma Cloud 中的所有集群部署在prisma.yml中指定cluster: name后执行prisma deploy。管理已注册集群的配套命令同属于prisma cluster子命令体系位于 docs/1.2/04-Reference/07-CLI-Command-Reference/05-Clustersprisma cluster list列出所有集群包括集群注册表中的条目以及通过 Prisma Cloud 配置的集群01-prisma-cluster-list.mdprisma cluster remove从注册表中移除集群04-prisma-cluster-remove.mdprisma cluster logs查看集群对应 Docker 容器的日志。上述增删操作也都可以通过手工编辑~/.prisma/config.yml完成在clusters映射下新增条目即等价于cluster add删除条目即等价于cluster remove。登出 Prisma CLI 则需移除注册表中的cloudSessionKey字段。常见问题与调试Error response from daemon: No such container说明 Docker 容器未在运行可用docker ps核对prismagraphql/prisma与prisma-dbmysql:5.7两个容器是否处于 Up 状态本地集群不可恢复可执行prisma local nuke彻底重置本地集群内部依次调用docker-compose kill、docker-compose down、docker-compose up注意该命令会清空本地集群的全部数据忘记集群名与prisma.yml不匹配prisma deploy会抛出ClusterNotFound对应 cli/packages/prisma-yml/src/errors/ClusterNotFound.ts此时请核对注册表键名与cluster属性值是否一致令牌生成失败getLocalToken()会抛出提示Did you provide the env var PRISMA_MANAGEMENT_API_SECRET?此时需检查是否已为集群配置clusterSecret或设置对应环境变量。小结prisma cluster add是连接自建 Prisma 集群与CLI 部署流程的枢纽它以交互方式采集name、host、clusterSecret将集群写入~/.prisma/config.yml注册表并让prisma deploy、prisma cluster list等命令能够识别并操作该集群。理解注册表文件结构与Cluster/Environment的源码实现有助于排查部署、认证与令牌相关问题也能在脱离 CLI 时通过手工编辑注册表完成同样的集群管理操作。【免费下载链接】prisma1 Database Tools incl. ORM, Migrations and Admin UI (Postgres, MySQL MongoDB) [deprecated]项目地址: https://gitcode.com/gh_mirrors/pr/prisma1创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考