Prisma CLI 集群管理实战：`prisma cluster list` 命令详解与集群注册表机制剖析

Prisma CLI 集群管理实战prisma cluster list命令详解与集群注册表机制剖析【免费下载链接】prisma1 Database Tools incl. ORM, Migrations and Admin UI (Postgres, MySQL MongoDB) [deprecated]项目地址: https://gitcode.com/gh_mirrors/pr/prisma1本文面向使用 Prisma 1.x CLI 的开发者聚焦prisma cluster list命令它用于一次性列出当前环境可用的全部 Prisma 集群——既包括写入本地 cluster registry~/.prisma/config.yml的自建/自托管集群也包括通过 Prisma Cloud 账号配置的开发与私有集群。读完本文你将掌握该命令的用法、输出数据的来源与含义并通过源码理解 CLI 底层是如何聚合两类集群信息从而为后续的prisma deploy、prisma cluster add/remove等操作打好基础。命令概述prisma cluster list解决什么问题在 Prisma 中Prisma service服务总是被部署到所谓的cluster集群上集群是 Prisma 服务的运行时环境。因此在部署之前你通常需要知道当前 CLI 环境里到底有哪些集群可选这正是prisma cluster list命令的职责。根据命令参考文档docs/1.4/04-Reference/07-CLI-Command-Reference/05-Clusters/01-prisma-cluster-list.md该命令会列出两类集群来自你的cluster registry集群注册表的集群——即你通过 CLI 或手工方式配置在本地~/.prisma/config.yml中的自托管集群你在Prisma Cloud中配置的集群——包括 Prisma Cloud 免费提供的开发集群development clusters以及绑定你自己数据库的私有集群private clusters。如果 CLI 已通过 Prisma Cloud 完成认证即本地存在cloudSessionKey命令输出会额外包含云端集群否则只列出本地注册表中的集群。用法与示例命令的语法非常简单不需要任何参数或选项prisma cluster list文档中给出的示例与用法一致直接执行即可# 列出所有集群本地注册表 Prisma Cloud 集群 prisma cluster list执行后CLI 会输出当前可用的集群列表以及与之关联的信息。这个命令不需要在某个 Prisma service 目录包含prisma.yml的目录中运行它读取的是全局的集群信息而非某个服务特有的配置。输出数据从哪来cluster registry 与 Prisma Cloud 两条来源要真正读懂prisma cluster list的输出需要理解两条数据来源。来源一本地 cluster registry~/.prisma/config.ymlPrisma CLI 首次使用时会在你的 home 目录下创建一个名为.prisma的目录其中包含集群注册表文件~/.prisma/config.yml。该注册表记录了你可以部署服务的集群信息也是prisma deploy交互式选择部署目标时读取的数据源详见 docs/1.4/04-Reference/05-Clusters/01-Overview.md。一个典型的注册表示例如下出自集群概述文档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其中每个集群条目由两部分组成host集群的端点地址。本地开发集群通常为http://localhost:4466自托管在云服务器上的集群则是其公网地址与端口。clusterSecret集群的私钥。Prisma 集群通过公钥/私钥对进行安全保护——集群持有公钥CLI 本地持有私钥并用它生成cluster token来对prisma deploy等请求完成认证详见集群概述文档的 Authentication 小节。你可以通过prisma cluster add命令或手工编辑该文件来添加自定义集群同理删除集群既可以用prisma cluster remove命令也可以直接手工移除注册表中的条目。无论哪种方式改动后的结果都会反映在prisma cluster list的输出中。来源二Prisma Cloud 账号中的集群如果你使用prisma login登录过 Prisma CloudCLI 会把会话凭据cloudSessionKey写入~/.prisma/config.yml。此时prisma cluster list会额外向 Prisma Cloud API 发起请求拉取你账号下 workspace 中配置的全部集群开发集群development clustersPrisma Cloud 提供的免费开发集群适合学习、原型验证与开发阶段。注意它有速率限制平均每 10 秒最多 10 次请求内存排队上限 25 次超限立即返回错误以及 100 MB 的存储容量上限私有集群private clusters创建时绑定你自己的数据库适合生产场景。源码级原理Environment 如何聚合两类集群prisma cluster list的底层逻辑位于prisma-yml包中的Environment类cli/packages/prisma-yml/src/Environment.ts。理解这个类就等于理解了命令输出的完整数据流。1. 读取本地注册表Environment的构造函数把注册表路径固定为 home 目录下的.prisma/config.ymlEnvironment.ts#L29-L36this.rcPath path.join(this.home, .prisma/config.yml) fs.mkdirpSync(path.dirname(this.rcPath))随后loadGlobalRC()读取该文件并交给parseGlobalRC()解析Environment.ts#L197-L210解析结果通过initClusters()初始化为Cluster对象数组。这里有一个值得注意的细节initClusters()会先通过getSharedClusters()注入两个共享集群prisma-eu1与prisma-us1Environment.ts#L236-L252它们的端点来自clusterEndpointMap常量。测试快照Environment.test.ts.snap显示其 baseUrl 分别为https://eu1.prisma.sh与https://us1.prisma.sh。这两个是 Prisma Cloud 的公共共享集群端点即使本地注册表中没有显式条目也会出现在集群列表中。2. 拉取 Prisma Cloud 集群当存在cloudSessionKey来源为环境变量PRISMA_CLOUD_SESSION_KEY或注册表中的同名字段见 Environment.ts#L42-L44时fetchClusters()会向https://api.cloud.prisma.sh发送 GraphQL 查询prismaCliGetClusters获取当前登录用户所有 workspace 下的集群信息Environment.ts#L71-L136query prismaCliGetClusters { me { memberships { workspace { id slug clusters { id name connectInfo { endpoint } customConnectionInfo { endpoint } } } } } }拉取到结果后CLI 会先清理已存在的prisma-eu1与prisma-us1共享集群条目避免与云端返回的数据重复遍历每个 workspace 下的集群确定其端点——优先取connectInfo.endpoint其次customConnectionInfo.endpoint最后回退到clusterEndpointMap[cluster.name]映射逐个构造Cluster对象并通过addCluster()加入集群列表。从源码结构可以推断prisma cluster list的输出正是基于这一「本地注册表 云端拉取」合并后的集群数组。clustersFetched标志保证了同一进程内云端集群只拉取一次Environment.ts#L27。3. Cluster 对象模型每个集群在内存中对应Cluster类的实例cli/packages/prisma-yml/src/Cluster.ts其主要属性包括属性类型含义namestring集群名称如local、prisma-eu1baseUrlstring集群端点地址构造时会去掉尾部/防止拼接双斜杠localboolean是否为本地/自托管集群sharedboolean是否为共享公共集群如prisma-eu1、prisma-us1isPrivateboolean是否为 Prisma Cloud 私有集群workspaceSlugstring \| undefined集群所属的 Prisma Cloud workspace 标识clusterSecretstring \| undefined集群私钥本地集群用于生成认证 token这些属性对应Cluster.toJSON()的输出见 Cluster.ts#L300-L310解释了为什么prisma cluster list能展示每个集群的名称、端点及类型归属信息——它们分别来自本地注册表的host键与云端返回的name、endpoint字段。与集群命令家族的配合使用prisma cluster list是 Prisma CLI 集群管理命令族的一员同一目录下还有三个兄弟命令docs/1.4/04-Reference/07-CLI-Command-Reference/05-Clusters/prisma cluster add向 cluster registry 添加自定义集群prisma cluster remove从 cluster registry 移除集群prisma cluster logs查看集群的服务日志。一个典型的集群管理流程是用prisma local start启动本地开发集群 → 用prisma cluster add将其登记进注册表 → 用prisma cluster list确认集群可见 → 用prisma deploy部署服务。与prisma deploy的联动prisma cluster list的价值最终体现在部署环节。根据prisma deploy的文档说明当prisma.yml中未指定cluster属性时prisma deploy会弹出一个交互式选择器其候选项正是prisma cluster list能够列出的那些集群选定后 CLI 会把结果写回prisma.yml作为默认部署目标。若已指定cluster属性则该值必须与 cluster registry 中clusters映射的某个键完全一致或指向 Prisma Cloud 中配置的集群之一见 docs/1.4/04-Reference/05-Clusters/01-Overview.md。使用注意与常见排查认证影响输出prisma cluster list是否显示云端集群取决于 CLI 是否处于登录状态~/.prisma/config.yml中是否有cloudSessionKey或是否设置了PRISMA_CLOUD_SESSION_KEY环境变量。未登录时仅列出本地注册表与两个共享集群。注册表位置固定集群注册表始终位于 home 目录下的~/.prisma/config.yml而不是项目目录内。手工编辑该文件后重新运行prisma cluster list即可看到最新集群列表。共享集群的自动管理prisma-eu1、prisma-us1两个共享集群由 CLI 内置维护端点映射见 Environment.test.ts.snap云集群拉取时会自动去重无需手工维护。版本适用前提本文涉及的命令与源码位于本仓库docs/1.4文档目录与cli/packages/prisma-cli-core/cli/packages/prisma-yml代码中对应 Prisma 1.x 时代的 CLI该版本线已标记为 deprecated用法与 Prisma 2.x 及后续版本并不相同请以你实际安装的 CLI 版本输出为准。小结prisma cluster list虽是一个无参数的单行命令但它背后串联了 Prisma CLI 的集群配置体系本地 cluster registry~/.prisma/config.yml保存自托管集群的端点与密钥Prisma Cloud 认证状态则决定了云端集群是否出现在列表中而Environment类的initClusters与fetchClusters两条路径最终合并出完整的集群视图。掌握这个命令及其数据来源能让你在部署前快速确认可用的部署目标也是理解prisma deploy交互式选集群行为的基础。【免费下载链接】prisma1 Database Tools incl. ORM, Migrations and Admin UI (Postgres, MySQL MongoDB) [deprecated]项目地址: https://gitcode.com/gh_mirrors/pr/prisma1创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考