Encore Cloud 深入指南从应用代码声明到 AWS/GCP 基础设施的自动化预置与运维【免费下载链接】encoreThe infrastructure platform for the intelligence era项目地址: https://gitcode.com/GitHub_Trending/encor/encoreEncore Cloud 是 Encore 生态中的托管平台它与开源的 Encore.ts / Encore.go 基础设施 SDK 配对把你在代码中声明的云资源SQL 数据库、Pub/Sub、对象存储、缓存、定时任务、密钥直接预置到你自己拥有的 AWS 或 GCP 账户中并在此基础上接管部署、环境、密钥与可观测性。读完本文你将完整掌握 Encore Cloud 的架构模型、四类环境的预置策略、从本地到生产的部署流程、云账户权限的最小化配置方式以及它与 AI 编码 Agent 结合的关键设计。Encore Cloud 是什么与基础设施 SDK 配对的管理平台Encore Cloud 不是一个要求你把应用托管给它的黑盒平台而是一个基于基础设施 SDK 声明式模型的托管控制平面。它的核心定位可以拆解为三点声明在代码里通过 Encore.ts 和 Encore.go 两个开源 SDK你可以直接在 TypeScript 或 Go 业务代码中以类型化对象声明云基础设施包括 SQL 数据库、Pub/Sub 主题、对象存储、缓存、cron 任务与密钥。预置在你的云里Encore Cloud 读取这些声明在你的 AWS 或 GCP 账户中调用云厂商官方 API创建对应的托管服务RDS、Cloud SQL、SNSSQS、GCP Pub/Sub、S3、GCS 等。运营在你掌控中你拥有云账户与全部基础设施的所有权运行时对 Encore Cloud零依赖你的云中也不会运行任何专有代码应用只是一个访问标准托管服务的普通进程。这一设计的关键承诺在 docs/platform/overview.md 中表述得非常明确The resources used in production are exactly the ones your code asked for, nothing more, nothing less.生产环境使用的资源正是你的代码所请求的不多也不少。而如果你不希望使用托管平台完全可以自己用 Terraform、Pulumi 或云控制台手工接线自托管方案被完整支持参考 docs/ts/self-host/build 与 docs/ts/self-host/configure-infra。从仓库源码结构看这套声明式模型的两端都真实存在于当前仓库中SDK 端位于 runtimes/go/appruntime/Go 运行时与 runtimes/js/encore.dev/TypeScript SDK而 CLI 端encore app create等应用管理命令位于 cli/cmd/encore/app/运行时配置生成逻辑位于 pkg/rtconfgen/。声明式原语与云服务映射SDK 中声明的每一种基础设施原语在 AWS 与 GCP 上都有对应的托管服务。下表汇总了 Encore 官方文档确认的资源映射声明的原语AWS 侧实现GCP 侧实现SQL 数据库RDSPostgreSQLCloud SQL可选用 NeonPub/Sub 消息SNS SQSCloud Pub/Sub对象存储S3Cloud Storage定时任务Encore Cloud 托管CloudWatch Events 支撑Encore Cloud 托管Cloud Scheduler 支撑密钥AWS Secrets ManagerSecret Manager缓存ElastiCacheRedisMemorystoreRedis计算Fargate ECS / EKSCloud Run / GKE网络VPCVPC详细的逐服务预置说明可分别查阅 docs/platform/infrastructure/aws 与 docs/platform/infrastructure/gcp。Encore Cloud 提供的四大核心能力按 docs/platform/overview.md 的官方划分Encore Cloud 的价值集中体现在四个方面下面逐一展开。1. 从本地到生产的紧密迭代循环Encore 的核心理念是同一个基础设施模型同时驱动本地开发、每个 PR 的预览环境与生产环境。因为基础设施模型由应用代码定义所以它能在任何地方运行这让整个迭代循环对所有参与者尤其是 AI 编码 Agent都快得多。本地encore run在你的笔记本上启动整个系统——真实的 Postgres、具备真实语义的本地 Pub/Sub 代理、本地对象存储、服务间的类型安全 API 调用以及自带分布式追踪、日志和数据库浏览器的本地开发面板。无需维护 Docker Compose无需为 Pub/Sub 运行本地模拟器。每个 PR 的预览环境每次 Pull Request 都会在你的 VPC 中获得一个临时的预览环境在合并前就可以对着真实云服务做端到端验证。生产同一份声明在部署时预置生产资源。这一循环恰恰是 Terraform 式工作流在结构上缺失的——Terraform 的模型通常面向生产、存在于独立代码库、在笔记本上难以运行。对比细节见 docs/platform/workflow.md。对于并行运行的 Agent每个任务一个 Agent、每个分支一个 Agent基础设施命名空间 能为每个分支或任务提供相互隔离的本地状态encore namespace switch --create pr:123会创建一个带有独立数据库的全新命名空间切回时恢复之前的状态。2. 在你的云账户中预置基础设施Encore Cloud 通过云厂商官方 API 直接在你自己的账户中创建资源无需维护任何 IaC 文件——代码就是基础设施的单一事实来源。预置遵循几项原则经过实战检验的托管服务按云厂商差异预置 Cloud Run / Fargate、GKE / EKS、Cloud SQL / RDS、Pub/Sub / SNSSQS 等并带上各云合理的默认配置。由代码推导的最小权限 IAM权限不是手写策略而是从每个资源在代码中的实际使用方式推导出来的详见 docs/platform/deploy/security。基础设施清单与变更管理可以查看每一个已预置的资源并在基础设施变更生效前进行人工审批。3. 部署与环境管理零配置部署连接 GitHub 仓库与云账户后push 即触发部署无需维护任何 CI/CD 流水线docs/platform/deploy/deploying。每个 PR 的预览环境真实云资源自动创建、自动销毁。开箱即用的多环境staging、production 与临时环境共享同一套代码路径docs/platform/deploy/environments。密钥管理代码中按名称引用密钥Encore 将其存储在云厂商的密钥管理服务中并在运行时注入。4. 内置可观测性分布式追踪、指标与日志应用代码中无需任何 agentdocs/platform/observability/tracing、docs/platform/observability/metrics。第三方导出遥测可发送到 Datadog、Grafana 等既有工具。成本监控覆盖云资源的成本情况官方文档注明 GCP 已支持AWS 持续推进中。服务目录与架构图基础设施模型还驱动生成带 API 文档的服务目录和实时的 Flow 架构图docs/platform/observability/encore-flow对新成员入职和 AI 工具都很有用。基础设施预置的工作原理从代码到基础设施图根据 docs/platform/infrastructure/infra.md 的说明预置过程分为三步编译期解析Encore 的编译器解析应用代码生成应用模型。构建基础设施图Encore Cloud 利用这份元数据创建基础设施图infrastructure graph其中包含应用所需基础设施的高分辨率定义。调用云 API 预置Encore Cloud 基于该图通过 AWS / GCP API 在你账户中预置并管理基础设施开发与预览环境则由 Encore Cloud 托管。这一机制从源码层面也能得到印证仓库中的解析器proto/encore/parser 的 proto 定义、v2/parser/ 的解析实现负责把代码结构提取为统一的应用模型而 CLI 的本地运行编排位于 cli/daemon/run/。这种端到端集成带来两个直接收益无需基础设施配置文件应用代码中不产生任何云特定依赖以及环境间自动保持同步——Encore Cloud 持续跟踪云基础设施给你一份最新的基础设施视图避免不必要的云成本。按环境类型差异化预置Encore Cloud 会针对每种环境类型使用上下文合适的目标objectives来预置基础设施Local本地Encore Cloud HostingGCP / AWS环境类型DevelopmentPreview、DevelopmentDevelopment、Production预置目标预置速度预置速度、成本*可靠性、安全性、可扩展性* Encore Cloud Hosting 免费使用受 Fair Use 准则与用量限制约束详见 docs/platform/management/usage。开发类基础设施本地、预览与 Cloud Hosting不同开发环境的资源预置方式差异如下Local本地Preview / DevelopmentEncore Cloud HostingGCP / AWSSQL 数据库DockerEncore Cloud 托管Kubernetes可选用 Neon见生产环境配置Pub/Sub内存实现NSQGCP Pub/Sub见生产环境配置缓存内存实现Redis内存实现Redis见生产环境配置Cron 任务禁用Encore Cloud 托管见生产环境配置对象存储本地磁盘Encore Cloud 托管见生产环境配置本地开发时Encore 预置的是 Docker 与内存组件的组合SQL 数据库用 Docker本地 Pub/Sub 的 NSQ 实现位于 cli/daemon/pubsub/nsq.go 与 cli/daemon/run/nsq_names.go。此外运行测试时会预置一个独立的 SQL 数据库集群使用内存文件系统并禁用 fsync以换取消灭级的测试性能代价是可靠性下降。Cron 任务在本地默认不触发避免开发时出现意外需要时可以随时从开发面板直接调用 API 手动触发。应用代码本身直接在你的机器上原生编译运行不经过 Docker。预览环境连接 GitHub 后每个 Pull Request 都会自动获得一个临时预览环境默认由 Encore Cloud Hosting 承载以预置速度和成本效益为优化目标PR 合并或关闭后自动销毁。企业版还可将预览环境托管在你自己的云上见预览环境文档的 Self-hosted 小节。预览环境以 PR 号命名PR #72 会创建名为pr:72的环境。Encore Cloud HostingEncore 提供的零配置托管方案适合开发环境与小规模使用——不要求连接你自己的云账户就能先评估 Encore Cloud。注意它不面向业务关键场景不提供 SQL 数据库等持久存储的可靠性保证Pub/Sub 与缓存也按小规模使用设计。生产基础设施按云厂商的最佳实践生产环境按各云厂商的最佳实践与托管服务预置GCPAWS网络VPCVPC计算Cloud Run、GKEFargate ECS、EKSSQL 数据库Cloud SQL、NeonRDS、NeonPub/SubCloud Pub/SubSQS SNS对象存储GCS / Cloud CDNS3 / CloudFront缓存MemorystoreRedisElastiCacheRedisCron 任务Encore Cloud 托管Encore Cloud 托管密钥Secret ManagerAWS Secrets Manager各服务的架构细节可查阅 docs/platform/infrastructure/gcp 与 docs/platform/infrastructure/aws。配置自由应用代码中不定义任何云服务细节因此部署后你既可以直接用云厂商控制台修改已预置的资源也可以用 Encore Cloud 内置的配置 UI 调整二者会保持同步。相关说明见 docs/platform/infrastructure/configuration关于基础设施安全、升级、灾难恢复与责任共担模型见 docs/platform/infrastructure/managing-infrastructure。部署流程从encore app create到git push根据 docs/platform/deploy/deploying.mdEncore Cloud 把部署简化为一次 push完整流程分四步。Step 1创建账户与应用$ encore app create该命令会引导你先创建免费的 Encore Cloud 账户再创建新的 Encore 应用。如果你已经在本地创建过应用则按下面的方式关联到 Encore Cloudencore auth signup # 尚未创建 Encore Cloud 账户时 encore auth login # 已创建 Encore Cloud 账户时在应用根目录关联并配置 git 远程encore app init git remote add encore encore://app-idStep 2集成 GitHub可选但推荐创建应用时 Encore 会自动建立一个 Encore 托管的 git 仓库试用阶段可以直接使用。生产应用则推荐集成 GitHub在Encore Cloud dashboard App Settings Integrations GitHub中点击 Connect Account to GitHub 授权即可。接入后 push 代码会自动触发部署Pro 用户还能获得每个 PR 的预览环境。详细配置见 docs/platform/integrations/github。Step 3连接 AWS / GCP 账户可选在App Settings Integrations Connect Cloud中连接你自己的云账户。若只是试用可以跳过此步部署到 Encore Cloud Hosting 的免费开发环境受 Fair Use 限制约束。连接细节见下文连接你自己的云账户一节完整文档见 docs/platform/deploy/own-cloud。Step 4Push 即部署# 使用 Encore 托管 git $ git add -A . $ git commit -m Commit message $ git push encore # 已连接 GitHub 时 $ git add -A . $ git commit -m Commit message $ git push originpush 会触发 Encore Cloud 的部署流程包含三个阶段构建与测试阶段 → 基础设施预置阶段 → 部署阶段。进度可在Encore Cloud dashboard Deployments中实时查看。配置部署触发器与自定义构建使用 GitHub 时可在环境的Overview Settings Branch Push中配置触发部署的分支名。也可以通过 Encore Cloud API 触发部署见 docs/platform/integrations/api-reference。此外你可以在encore.app文件中覆盖 CI/CD 的部分行为包括 Docker 基础镜像、是否启用 Cgo 构建、是否把源码打包进 Docker 镜像便于 Sentry 生成堆栈跟踪。完整的可用构建配置及其默认值如下{ build: { // 在 Encore 的 CI/CD 中构建应用与运行测试时是否启用 cgo cgo_enabled: false, // Docker 相关配置 docker: { // 部署时使用的 Docker 基础镜像必须是公开可访问的镜像。 // Go 应用默认为 scratchTypeScript 应用默认为 node:24-trixie base_image: scratch, // 是否将源码打包进 Docker 镜像。 // 源码会被复制到 /workspace主要服务于需要访问源码 // 生成堆栈跟踪的工具如 Sentry bundle_source: false, // Docker 镜像启动时的工作目录。 // 为空时若打包了源码则默认为 /workspace否则为 / working_dir: }, // 构建钩子允许在构建过程中运行自定义命令。 // 可写成字符串如 cmd1 cmd2也可写成带命令与可选环境变量的对象 hooks: { // 在 Encore 构建之前、依赖拉取如 npm install之后运行 prebuild: , // 对象写法示例 // prebuild: {command: my-command, env: {MY_VAR: value}}, // 在 Encore 构建完成后运行 postbuild: // postbuild: {command: my-command, env: {MY_VAR: value}} } } }环境体系四类环境与主环境配置按 docs/platform/deploy/environments.mdEncore 自动建立并管理四类环境每个环境都完全隔离、自动预置、与代码库保持同步并按用途配置合适的基础设施环境类型预置方式local由开源 CLI 使用本地版基础设施预置preview预置在 Encore Cloud Hosting以成本与预置速度为目标development由 Encore Cloud 预置可在你的云账户或免费开发托管中production由 Encore Cloud 预置可在你的云账户或免费开发托管中环境类型同时参与密钥管理可以为不同环境类型配置不同的密钥值例如production与development各用一套。创建环境的步骤Encore Cloud dashboardEnvironments Create env然后配置名称、类型Production 或 Development、部署触发器Git 分支或手动、基础设施审批自动或手动、云厂商以及进程分配方式。关键配置项包括基础设施审批在Settings Infrastructure Approval中开启后基础设施变更必须由应用Admin手动批准部署才能继续。进程分配Single process所有服务运行在一个进程中更简单、成本更低或Separate processes每个服务独立运行隔离性更好、可独立扩缩容。可以在不改代码的前提下为生产与开发环境选择不同的部署模型。每个应用还有一个可配置的Primary environmentSettings General Primary Environment它作为应用洞察、API 文档以及 CLI 功能如 API 客户端生成的默认环境。连接你自己的云账户GCP服务账号与权限最小化Encore Cloud 为每个应用提供一个 GCP 服务账号你把相应权限授予它它就能直接在你的 GCP 账户中预置基础设施。两种认证方式信任建立方式不同授权级别相同Encore Service Account推荐Encore Cloud 使用 Google 托管的服务账号你向其授予 GCP Organization 访问权。凭据不会共享给 Encore Cloud随时可通过移除 IAM 绑定撤销访问。前提是你的组织允许修改Domain restricted sharing策略或在未强制启用时可用。Service Account JSON Key在你自己的 GCP 项目中创建服务账号、授予所需角色并上传 JSON Key。避免改动Domain restricted sharing策略但 Encore Cloud 会保存一个长期凭据需要定期轮换。最小化授权的角色清单按功能分组均为项目级角色完整版见 docs/platform/deploy/own-cloudIAM始终需要resourcemanager.projectIamAdmin、iam.serviceAccountAdmin、iam.roleAdmin、iam.serviceAccountTokenCreator、iam.serviceAccountUser服务启用始终需要serviceusage.serviceUsageAdminCloud Run部署到 Cloud Run 时需要run.admin、vpcaccess.adminGKE部署到 GKE 时需要container.admin网络入口、自定义域名、私有连接需要compute.networkAdmin、compute.loadBalancerAdmin或更宽的compute.admin、servicenetworking.networksAdmin、certificatemanager.editor数据库/缓存cloudsql.admin、redis.admin对象存储storage.admin镜像仓库始终需要artifactregistry.admin消息使用 Pub/Sub 时需要pubsub.admin密钥始终需要secretmanager.admin可观测性始终需要monitoring.editor最简方式是给项目授予roles/owner完整授权一切所需更精细的做法是只授予应用实际用到的功能对应角色。连接入口为Encore Cloud dashboard App Settings Integrations Connect Cloud。AWSIAM Role 与外部 IDAWS 侧默认通过一个 IAM Role 授予 Encore Cloud 预置与管理基础设施所需的权限推荐用专门的 AWS 子组织做清晰隔离也可配置更窄的 IAM 策略所需权限取决于应用结构与资源使用情况。在 Connect Cloud 页面按指引创建 IAM Role 并连接即可。安全要点创建角色时务必勾选Require external ID并填写指引中提供的 external ID防止角色被误用。连接完成后需要选择 Encore Cloud 预置资源的 AWS 区域。安全提醒基础设施不会自动销毁连接云账户后需要注意出于安全考虑Encore Cloud不会在基础设施不再需要时自动销毁它。无论你是从云厂商断开应用还是删除 Encore 中的环境都需要在 Encore Cloud dashboard 中显式批准删除相应基础设施。安全默认值Security by Default按照 docs/platform/deploy/security.mdEncore Cloud 把强安全做成默认路径零配置安全自动落实安全最佳实践内置密钥管理系统docs/ts/primitives/secrets。自动 IAM 管理基于最小权限原则自动生成与管理 IAM 策略IAM 权限从代码对资源的使用方式推导而非手写。强加密全部通信使用双向 TLSv1.3。数据库安全数据库访问带证书校验与强凭据每个数据库实例拥有独立凭据每个连接数据库的容器使用自己的凭据可在 dashboard 中轮换docs/platform/infrastructure/manage-db-users。基础设施安全删除保护、仅管理员可管理环境、基础设施变更的完整审计轨迹docs/platform/infrastructure/managing-infrastructure。不被锁定自托管与多云Encore Cloud 是可选组件。SDK 完全开源产物是标准的应用二进制或 Node.js 进程用encore build docker构建 Docker 镜像部署到任何环境用 Terraform、Pulumi、CloudFormation 或云控制台自行预置基础设施通过基础设施配置文件告诉 Encore 运行时如何连接你的资源。完整自托管工作流见 docs/ts/self-host/build。同时每个环境可以配置使用不同的云厂商、数量不限天然支持混合云与多云应用docs/platform/deploy/own-cloud。与 AI 编码 Agent 的结合基础设施护栏与 MCPEncore Cloud 特别强调对 AI 编码 Agent 的支撑docs/platform/ai-integration.md。当 AI 生成的代码声明数据库、Pub/Sub 主题、cron 任务等原语时Encore Cloud 会以生产就绪的默认配置自动预置正确的网络、IAM 权限与安全配置。其工作流为AI 用声明式原语写基础设施代码 → push 到 GitHub 触发部署 → Encore Cloud 带护栏地预置到你的云账户 → 在预览环境中隔离验证。AI 无需了解 AWS/GCP 的细节只需声明需要什么云侧的具体配置网络、加密、备份、死信队列、重试策略、IAM 角色、负载均衡、健康检查、自动扩缩容由 Encore Cloud 处理。同时人始终保有控制权在 PR 中审查基础设施变更、批准或拒绝资源新增、按环境定制基础设施配置。对工作流设计感兴趣可阅读 docs/platform/workflow.md。此外Encore 还提供两个 MCPModel Context Protocol服务器为 Agent 注入应用上下文本地 MCP Server 随encore run运行向 AI 工具暴露本地应用的元数据、追踪、数据库与源码docs/ts/cli/mcpCloud MCP Server 面向已部署环境提供生产追踪、部署状态、环境配置与基础设施元数据docs/platform/cloud-mcp。仓库中本地 MCP 的实现在 cli/daemon/mcp/包含 api、bucket、cache、cron、db、docs、metrics、pubsub、secret、src、trace 等工具模块CLI 侧注册入口见 cli/cmd/encore/mcp.go。适用场景与快速上手Encore Cloud 最适合那些希望基础设施与应用代码在同一代码库中定义和运营、并部署到自持 AWS/GCP 账户的团队典型场景包括消费类应用与 B2B 平台、金融科技与加密应用、电商平台、微服务后端与事件驱动系统。上手路径从 TypeScript 快速开始或 Go 快速开始开始写应用用encore app create创建应用连接你的 AWS 或 GCP 账户docs/platform/deploy/own-cloud集成 GitHub 后 push 即部署。关于本地开发面板与基础设施命名空间可继续阅读 docs/ts/observability/dev-dash 与 docs/ts/cli/infra-namespaces关于部署与 CI/CD 全流程见 docs/platform/deploy/deploying 与 docs/platform/deploy/preview-environments关于 AI 相关的指令、MCP 与 Cloud MCP见 docs/platform/ai-integration 与 docs/platform/cloud-mcp。【免费下载链接】encoreThe infrastructure platform for the intelligence era项目地址: https://gitcode.com/GitHub_Trending/encor/encore创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考