企业官网建设流程全解析

• 后端
• 数据库
• GraphQL

本篇技术指南以 Prisma 1.x 官方 CLI 参考文档中prisma cluster list命令为核心，系统讲解该命令的用途、使用方式、输出语义，并结合当前仓库的 CLI 源码（cli/packages/prisma-cli-core、cli/packages/prisma-yml）剖析其底层实现：它如何枚举本地集群、如何通过 Prisma Cloud 会话密钥拉取云端集群，以及为什么未登录时输出中会附带提示。读完本文，你将彻底掌握prisma cluster list的输入输出行为，并能将它与prisma list、prisma cluster add等相邻命令正确区分使用。

命令概览：prisma cluster list是什么

prisma cluster list是 Prisma CLI 中用于**列出全部集群（Cluster）**的子命令。所谓集群，是 Prisma 服务（Service）的部署目标——一个 Prisma 服务器实例（无论是本地 Docker 启动的，还是 Prisma Cloud 托管的），其上可以承载多个 service（对应不同 stage 的服务实例）。

根据官方参考文档（docs/1.0/04-Reference/06-CLI-Command-Reference/04-Clusters/01-prisma-cluster-list.md），该命令列出所有集群，包含两类来源：

1. 集群注册表（cluster registry）中的集群：即通过prisma cluster add手动登记到本机全局配置中的集群；
2. 通过 Prisma Cloud 配置的集群：即用户登录 Prisma Cloud 后，其所属工作区（workspace）下挂载的集群。

注意：该命令与prisma list（列出所有已部署的 service）含义不同。prisma cluster list关注的是“集群”这一层（Prisma 服务器实例），而prisma list关注的是“部署在集群上的服务”。关于prisma list的更多细节可参考 prisma-list.md。

基本用法

prisma cluster list

命令无需任何位置参数，也不接受额外 flags（在 1.0 版本文档中未声明任何可选标志）。

命令的四个兄弟命令：Clusters 子命令族

prisma cluster list属于 Clusters 命令族，与其并列的还有三个命令，全部位于 docs/1.0/04-Reference/06-CLI-Command-Reference/04-Clusters 目录下：

其中，prisma cluster add会触发一个交互式提示，要求依次提供新集群的name、host与clusterSecret；prisma cluster remove则用于移除已登记的集群。这两者管理的是本地集群注册表，而prisma cluster list正是该注册表（再加上 Prisma Cloud 集群）的“只读视图”。

使用示例

官方文档给出的示例（01-prisma-cluster-list.md）：

列出所有集群

prisma cluster list

执行后，CLI 会连接本机集群注册表中的每个本地集群，并（在已登录的情况下）查询 Prisma Cloud API，最终在终端以表格形式输出集群列表。典型输出形如：

Service Name Stage Server my-service dev local

具体输出字段与登录状态密切相关，详见下文“输出语义”一节。实际输出以你安装的 CLI 版本为准。

源码解析：prisma cluster list底层是怎么工作的

虽然 1.0 参考文档对prisma cluster list的描述只有寥寥数行，但当前仓库的 CLI 源码完整地揭示了它的实现路径。理解源码有助于你预判命令在不同环境（是否登录、是否有本地集群）下的行为。

1. CLI 命令的注册与入口

在 Prisma CLI 的命令体系中，每个子命令都继承自prisma-cli-engine提供的Command基类。以prisma list命令为例，cli/packages/prisma-cli-core/src/commands/list/index.ts 中定义了：

• static topic = 'list'：命令主题；
• static aliases = ['ls']：别名prisma ls；
• 执行入口run()。

从源码结构看，cluster list属于同一套 CLI 引擎下的命令族，遵循完全相同的注册、别名与执行机制。CLI 引擎的通用命令分发逻辑位于 cli/packages/prisma-cli-engine/src。

2. 本地集群的枚举

prisma cluster list的核心逻辑是遍历this.env.clusters中所有标记为local的集群，并逐个发起查询（见 cli/packages/prisma-cli-core/src/commands/list/index.ts）：

for (const cluster of this.env.clusters.filter(c => c.local)) { try { await this.client.initClusterClient(cluster, this.definition.getWorkspace() || '*', '*', '*') this.env.setActiveCluster(cluster) const clusterProjects = await this.client.listProjects() // ...合并 name / stage / cluster 信息 } catch (e) { debug(e) } }

这里有几个关键点：

• 只遍历local集群：Cluster对象的local标志（见 cli/packages/prisma-yml/src/Cluster.ts）区分了本地集群与共享/云上集群；
• 逐个探测并容错：每个集群的查询被try/catch包裹，某个集群不可达（例如 Docker 中未启动的local集群）时不会导致整个命令崩溃，而是跳过并继续；
• 调用listProjects：集群上部署的 service 列表通过 GraphQL 查询listProjects获取——这与 Cluster.ts 中needsAuth()探活时使用的查询一致，说明listProjects是 Prisma 管理端点的标准查询之一。

3. Prisma Cloud 集群的拉取

命令的第二阶段处理 Prisma Cloud 集群（cli/packages/prisma-cli-core/src/commands/list/index.ts）：

if (this.env.cloudSessionKey) { const services = await this.client.getCloudServices() const mappedServices = services.filter(s => s.cluster).map(s => ({ name: s.name, stage: s.stage, cluster: s.cluster.name, })) projects = [...projects, ...mappedServices] gotCloud = true }

• 是否有会话密钥是关键开关：cloudSessionKey来自环境变量PRISMA_CLOUD_SESSION_KEY或全局配置文件~/.prisma/config.yml中的cloudSessionKey字段（见 cli/packages/prisma-yml/src/Environment.ts）；
• 只有登录后才显示云端服务：未登录时gotCloud保持false，命令输出末尾会追加一段提示，引导用户运行prisma1 login（见下文“输出语义”）。

此外，Environment.fetchClusters()（cli/packages/prisma-yml/src/Environment.ts）会在已登录时通过 Prisma Cloud API（https://api.cloud.prisma.sh）查询me.memberships.workspace.clusters，从而获得用户所属工作区下的全部云端集群及其连接端点。集群端点解析优先级为：connectInfo.endpoint→customConnectionInfo.endpoint→ 内置的clusterEndpointMap[cluster.name]（内置端点映射见 cli/packages/prisma-yml/src/constants.ts）。内置的共享集群prisma-eu1与prisma-us1则始终会作为默认集群出现（cli/packages/prisma-yml/src/Environment.ts）。

4. 集群注册表（cluster registry）的持久化

本地集群注册表的“增删”分别由Environment.addCluster()与Environment.removeCluster()实现，并最终写入~/.prisma/config.yml（cli/packages/prisma-yml/src/Environment.ts）。这就是prisma cluster add/prisma cluster remove修改的底层文件，而prisma cluster list则读取同一份配置：

# ~/.prisma/config.yml（示意） cloudSessionKey: <登录后的会话密钥> clusters: my-cluster: host: http://localhost:4466 clusterSecret: <cluster-secret>

持久化时只写入“非共享、非私有、且 clusterSecret 与会话密钥不同”的集群（getLocalClusterConfig()，见 Environment.ts），避免把公共集群和云上托管集群重复落盘。

输出语义：如何读懂命令结果

从printProjects()的实现（cli/packages/prisma-cli-core/src/commands/list/index.ts）可以归纳出三类输出场景：

1. 没有任何已部署服务：输出No deployed service found；
2. 存在服务：以表格形式输出三列——
   • Service Name：服务名；
   • Stage：服务阶段（如dev、default）；
   • Server：服务所在集群名；
3. 未登录（未获取到云端会话密钥）：表格下方会追加警告：

This does not include your services deployed in the cloud. In order to see them, please run prisma1 login

这意味着该命令的输出取决于登录状态：未登录时只反映本地集群注册表中的本地集群；登录后（prisma1 login或设置PRISMA_CLOUD_SESSION_KEY）才会合并展示 Prisma Cloud 上的云端服务。

常见问题与排查建议

Q1：为什么我执行prisma cluster list看不到云上的服务？A：因为未登录。命令只有在拿到cloudSessionKey时才会调用getCloudServices()拉取云端数据，否则会在输出末尾提示运行prisma1 login。请先执行登录，或设置环境变量PRISMA_CLOUD_SESSION_KEY。

Q2：为什么某个本地集群没有出现在结果里？A：从源码看，每个本地集群的查询结果都会被try/catch吞掉并仅输出 debug 日志（可通过设置 debug 环境变量开启）。如果该集群对应的 Prisma 服务器未启动、端点不可达或需要认证，它会被静默跳过。请用prisma cluster logs查看集群日志，或用prisma cluster remove+prisma cluster add重新登记正确的host与clusterSecret。

Q3：prisma cluster list和prisma list有什么区别？A：prisma list（别名ls）列出的是已部署的服务（service），其输出列即为Service Name / Stage / Server；而prisma cluster list面向的是集群注册表 + Prisma Cloud 集群这一层。两者在源码中均通过listProjects类查询获取数据，但关注对象不同，请勿混用。

小结

prisma cluster list虽是一个“轻量”子命令，但其背后连接了三条关键链路：本地集群注册表（~/.prisma/config.yml）、Prisma 服务器的管理 GraphQL 端点（listProjects）、以及 Prisma Cloud API（api.cloud.prisma.sh）。通过本文的源码级剖析，你可以清晰预判该命令在“是否登录”“是否有本地集群”“集群是否在线”等不同条件下的行为，从而在本地开发与多集群部署场景中正确地使用它，并与prisma cluster add / remove / logs组成完整的集群管理工具箱。

• 后端
• 数据库
• GraphQL