prisma-compute

Prisma Compute

将 TypeScript 应用部署到 Prisma Compute，并在部署后对其进行操作。每次部署都会通过 Prisma Composer 应用（module.ts 根模块）和 Prisma 8 CLI prisma 完成。

已针对 prisma 8.0.0-rc.21（以 @prisma/cli 名称发布，内容完全相同）、@prisma/composer 和 @prisma/composer-prisma-cloud 0.28.0、@prisma/compute 0.1.0-beta.0 以及 create-prisma 0.14.1 进行验证。已再次针对 prisma 8.0.0-rc.23 进行检查，其命令界面与 rc.21 一致；以及 Composer 0.30.0 进行检查，该版本新增了 node() 的 dependencies 选项（0.29.0），并缩小了支持的 Node.js 版本范围。CLI 更新很快：使用本技能未提及的标志前，请运行 npx prisma <group> --help。

与版本匹配的技能

已安装的软件包会附带与其版本匹配的 Agent 技能：

• prisma-platform-core-concepts，位于 prisma 中：项目、分支、服务、版本、环境变量、推送时部署。
• prisma-composer-core-concepts，位于 @prisma/composer 中：声明服务、模块、数据库和构建；dev、deploy 和拆除。

npx prisma skills sync 会将它们复制到 Agent 技能目录（.claude/skills、.cursor/skills、.agents/skills、.devin/skills），而 npx prisma skills list 会显示已安装的内容。npx prisma init 会执行相同操作，并添加一个用于保持技能为最新状态的 postinstall 钩子。安装这些技能后，请使用它们了解 API 详情。本技能介绍部署和运维工作流及其注意事项。

已移除的功能

Composer 之前的 Compute CLI 已不再提供。其命令会报错 CLI.UNKNOWN_COMMAND（已移除的标志会报错 CLI.INVALID_ARGUMENTS），不会读取其配置文件，也会忽略其环境变量：

已移除	替代方案
@prisma/cli app deploy、app build、app run	使用自己的构建脚本，然后运行 npx prisma deploy module.ts；运行 npx prisma dev module.ts 可在本地运行
prisma.compute.ts、prisma.compute.json、defineComputeConfig	使用 module.ts、为每个通过 compute() 声明的服务配置一个 service.ts，以及 prisma.config.ts 中的 composer 部分
init 写入 Compute 配置	现在，npx prisma init 会写入仅包含 skills 部分的 prisma.config.ts，将 prisma 添加为开发依赖，并同步技能。请自行添加 composer 部分
compute:deploy 脚本	运行 npx prisma deploy module.ts，或使用当前 create-prisma 生成的 deploy 脚本
app deploy --branch <name>	npx prisma deploy module.ts --stage <name>
app deploy --prod、--no-promote、app promote	不指定 --stage 即会部署到生产环境；service version promote <version-id>
app show、app open、app list-deploys、app show-deploy	service show <service>、service open <service>、service version list <service>、service version show <version-id>
app logs	service logs <service>
app rollback --to <id> --yes	service version rollback <service> --to <id> --confirm <id>
app domain ...	service domain ... --service <service>
app remove	从 module.ts 中移除 provision() 并部署，或运行 service delete <service> --confirm <service>
build logs <build-id>	GitHub Actions 运行日志或 Console；使用 GET /v1/builds/{buildId} 获取状态和失败步骤
database ...	postgres ...
project env remove	project env delete
auth logout --workspace <id>	auth workspace logout <id>
agent install、agent update、agent status	运行 npx skills add prisma/skills --skill prisma-compute；同步包技能请运行 npx prisma skills sync
PRISMA_PROJECT_ID、PRISMA_APP_ID、PRISMA_SERVICE_ID	使用 --project <id-or-name>、作为位置参数传入服务，以及通过 project link 创建的 .prisma/local.json
/v1/apps REST 端点	/v1/services（/v1/apps 路径已弃用）

包含 prisma.compute.ts 或 compute:deploy 脚本的代码库是为已移除的工作流设置的。请将其迁移到 Composer（app-composer-setup.md），而不要运行旧命令。

适用场景

• 将新应用或现有应用部署到 Prisma Compute
• 迁移使用 prisma.compute.ts、compute:deploy 或 @prisma/cli app deploy 的项目
• 设置预览阶段、推送时部署或 CI 部署
• 查看服务日志、列出版本、提升版本或回滚
• 在 Compute 项目中管理环境变量、自定义域名、Prisma Postgres 数据库或存储桶
• 调试部署失败、服务无法访问、504，或实例休眠时停止的任务

按优先级划分的规则类别

优先级	类别	影响	前缀
1	CLI 功能	严重	cli-
2	应用声明	严重	app-
3	运行时	严重	runtime-
4	部署	高	deploy-
5	运维	高	ops-
6	调试	高	debug-
7	自动化	中	automation-

快速参考

1. CLI 界面（关键）

• cli-prisma-8-binary - 平台和部署命令仅在 Prisma 8 CLI 中提供。在 Prisma 6 或 7 项目中，npx prisma 会运行该版本的 ORM CLI，其中没有 auth、project、service 或 deploy；Prisma 7 的 dev 会启动本地数据库。请检查 npx prisma --version；在 Prisma 8 项目之外，请使用 npx @prisma/cli@latest <command>。
• cli-help-first - 命令组包括 auth、project（含 project env）、postgres、bucket、branch、git 和 service（含 service version 和 service domain），以及 deploy、dev、init、skills 和 feedback。使用标志前，请先阅读 --help。
• cli-json - 传入 --json，并在脚本中传入 --no-interactive。根据 error.code（NAMESPACE.SUBCODE）分支处理，并遵循 nextActions；不要解析消息。
• cli-explicit-targets - 将服务名作为第一个参数，用 --project 指定项目（或关联目录），并用 --branch 指定预览环境。不传入 --branch 时，命令会针对生产分支；CLI 不会读取当前 Git 分支。
• cli-consent-tokens - 破坏性命令需要通过 --confirm <token> 指定准确的 ID、名称或主机名。--yes 无法授予同意。只有在用户要求执行该操作时才运行这些命令。

2. 应用声明（关键）

• app-composer-required - 可部署的应用需要包含 module.ts（默认导出 module(name, ...)）、每个服务器对应的 service.ts（包含 compute({ name, deps, build })），以及 prisma.config.ts 中带有 prismaCloud()、nodeBuild()（Next.js 还需 nextjsBuild()）和 state: prismaState() 的 composer 部分。
• app-build-adapter - 对于单个自包含构建包，使用 node({ module: import.meta.url, entry })；对于已构建的目录，使用 node({ module, dir, entry })；对于 Next.js standalone，使用 nextjs({ module, appDir })。如果构建会将程序包保留为导入项，请在 node() 中添加 dependencies: "external"。请参阅 app-framework-builds.md。
• app-region - 首次部署会创建项目，因此需要指定区域：prismaCloud({ region: "eu-central-1" }) 或 PRISMA_REGION。之后无法更改区域。
• app-databases - rawPostgres()（包根目录）会提供 { url }；@prisma/composer-prisma-cloud/orm 中的 postgres(contract) 会添加类型化客户端，并在部署时应用已提交的迁移。请通过 service.load() 读取这两者，而不是使用 process.env.DATABASE_URL。
• app-names - 配置 ID 和服务名仅允许使用 [A-Za-z0-9]，且平台会拒绝长度少于三个字符的 ID。根模块名称会成为项目名称。

3. 运行时（关键）

• runtime-bind-all-interfaces - 监听 service.port()（也会导出为 PORT，默认值为 3000），并绑定到 0.0.0.0。绑定到环回地址的监听器无法访问。
• runtime-bun - 服务运行在 Bun 上。默认情况下（dependencies: "bundled"），部署只会包含构建输出，不会包含项目的 node_modules，因此构建必须内联除运行时内置模块之外的所有依赖。如果构建会将程序包保留为导入项（tsc、Astro 的 Node 适配器），则需在 node() 中设置 dependencies: "external"，部署会暂存入口导入的已安装程序包。
• runtime-first-byte-60s - 如果请求在 60 秒内没有发送任何字节，就会收到 504 Gateway Time-out，并且请求会被取消。请先响应，再通过 waitUntil 或队列继续处理。
• runtime-sleep - 空闲实例会被快照并恢复。计时器和未等待的 Promise 可能会停滞。@prisma/compute 中的 waitUntil 和 KeepAwakeGuard 可尽力让实例保持唤醒；它们无法保证工作持久执行。
• runtime-no-websockets - 不支持 WebSocket 服务器。

4. 部署（高优先级）

• deploy-build-first - deploy 和 dev 不会构建。先运行构建，再执行 npx prisma deploy module.ts。
• deploy-dev-first - npx prisma dev module.ts 无需凭据即可在本地运行整个应用。部署前验证每个本地 URL。
• deploy-production-intent - 不带 --stage 的部署，以及向已连接仓库的默认分支推送，都会更改生产环境。先征得用户同意；预览环境请使用 --stage <name>。
• deploy-auth - 在工作站上，用户运行 npx prisma auth login（浏览器）。在 CI 中设置 PRISMA_SERVICE_TOKEN 和 PRISMA_WORKSPACE_ID。部署前检查 npx prisma auth whoami --json（envelope.result.authenticated、envelope.result.workspace）。
• deploy-link-after - deploy 会根据根模块名称（或 --name）查找或创建项目，且不会写入 .prisma/local.json。之后运行 npx prisma project link <app-name>，或传入 --project，再运行 service、git 或 project env 命令。
• deploy-on-push - 推送后部署需要同时运行 npx prisma git connect（交互式），并使用运行 prisma/cloud-deploy-action@v1 的工作流。仅连接不会触发部署。
• deploy-verify-url - 从部署输出（--json 结果或 --report <path>）中获取每个服务 URL，并向其发送请求。

5. 运维（高优先级）

• ops-logs - service logs <service> 读取实时版本；--version-id <id> 读取其他版本，--follow 则持续输出。构建输出位于 CI 日志或 Console 中，而非 CLI 中。
• ops-versions - service version promote <version-id> 会使用生产环境变量重新构建。service version rollback <service> --to <id> --confirm <id> 会切回指定版本，而不重新构建。
• ops-env-write-only - project env add|update|list|delete 可搭配 --role production、--role preview 或 --branch <name> 使用。变量值不会返回，并会在下次部署时生效。
• ops-domains - service domain add <hostname> --service <service>，创建命令报告的 CNAME，然后运行 service domain wait。仅限生产分支。
• ops-secrets-once - postgres create、postgres connection create|rotate 和 bucket key create 只会显示一次凭据。请妥善保存，切勿回显。

6. 调试（高优先级）

• debug-error-code-first - 修改任何内容前，先读取 --json 输出中的 error.code 和 nextActions，或读取 --report 文件中的 failure.code。
• debug-public-url - 测试输出的公共 URL，而非 localhost。部署已收敛但无响应，通常是主机绑定、端口或启动时崩溃导致的；请查看 service logs。
• debug-report-cli-bugs - 使用 npx prisma feedback "<message>" 报告无法解决的 CLI 故障，且不要包含机密信息。

7. 自动化（中优先级）

• automation-create-prisma - create-prisma 会搭建新的 Prisma 8 项目，该项目已经是 Composer 应用。其 --json 模式会执行部署，除非传入 --no-deploy。
• automation-control-api - @prisma/composer/control 提供 deploy、destroy、dev 和 log。拆除某个阶段时使用 destroy；它只读取 PRISMA_SERVICE_TOKEN 和 PRISMA_WORKSPACE_ID。
• automation-rest-api - 使用 https://api.prisma.io/v1/doc 中的 /v1/services、/v1/deployments/{deploymentId}/logs 和 /v1/builds。不要基于 @prisma/compute-sdk 构建新的部署工具。

首选工作流

1. 检查 package.json（prisma 8.x 是否为开发依赖，是否已安装 @prisma/composer 和 @prisma/composer-prisma-cloud）、module.ts、prisma.config.ts、构建脚本，以及已移除流程的残留内容（prisma.compute.ts、compute:deploy）。
2. 安装缺少的依赖并同步包技能：

   npm install @prisma/composer @prisma/composer-prisma-cloud
   npm install -D prisma
   npx prisma skills sync
   

3. 声明或迁移应用： app-composer-setup.md 和 app-framework-builds.md。
4. 构建，运行 npx prisma dev module.ts，并请求它输出的每个本地 URL。
5. 运行 npx prisma auth whoami --json。如果 envelope.result.authenticated 为 false，请用户运行 npx prisma auth login。
6. 使用 npm run build && npx prisma deploy module.ts --stage <name> --json 部署预览环境；用户确认后，也可以不带 --stage 部署生产环境。新项目需要指定区域。
7. 请求输出的每个 URL，然后运行 npx prisma project link <app-name> 和 npx prisma service list --json（预览环境需添加 --branch <stage>）。
8. 报告应用名称、阶段、服务 ID、URL 和数据库 ID。切勿报告机密值。

避免

• 不要运行 @prisma/cli app ...、build logs 或 database ...，也不要创建 prisma.compute.ts。
• 不要通过 Prisma 6 或 7 的 prisma 二进制运行平台命令。
• 不要在 Composer 服务中从 process.env 读取端口或连接字符串。
• 不要认为 deploy 会执行构建、迁移 rawPostgres() 数据库，或将生产数据复制到阶段环境。
• 不要对破坏性命令传入 --yes；它不能代替用户授权。
• 不要以非交互方式运行 auth login 或 git connect；这两项都需要有人在浏览器中操作。
• 未经用户同意，不要推送到已连接仓库的默认分支；这会部署生产环境。

参考资料

• cli-command-map.md：所有已验证的命令、全局标志、JSON 信封、目标指定和授权令牌
• app-composer-setup.md：最小声明、区域、数据库、配置和机密，以及从 prisma.compute.ts 迁移
• app-framework-builds.md：各框架的构建输出和 build: 适配器
• runtime-requirements.md：Bun、主机和端口、首字节耗时 60 秒、休眠、保持唤醒、区域
• deploy-cli-and-ci.md：prisma deploy、阶段、凭据、输出、CI、拆除
• deploy-on-push.md：GitHub 连接和 prisma/cloud-deploy-action 工作流
• ops-services-and-config.md：服务、版本、日志、域名、环境变量、数据库、存储桶
• debug-deploy-failures.md：症状、原因和修复方法
• automation-create-prisma.md：搭建新的 Composer 应用
• automation-rest-api.md：REST API 路径、控制 API，以及 @prisma/compute-sdk 的状态

文档：Compute、部署你的第一个应用、Composer、CLI 参考。

反馈

npx prisma feedback "<message>" 会向 CLI 团队发送匿名反馈，并附上 CLI 版本、Node.js 版本和操作系统平台。添加 --email <address> 可请求回复。切勿包含令牌、连接 URL 或用户数据。