Encore.go 全面指南在 Go 代码中声明云基础设施的开源 SDK【免费下载链接】encoreThe infrastructure platform for the intelligence era项目地址: https://gitcode.com/GitHub_Trending/encor/encoreEncore.go本仓库即其开源实现是一个开源基础设施 SDK允许开发者直接在 Go 代码中声明应用所需的云基础设施——SQL 数据库、Pub/Sub 主题、对象存储、缓存、Cron 任务与密钥secrets由编译器与运行时自动完成资源接线。本文以 docs/go/overview.md 为核心骨架结合仓库源码CLI daemon、运行管理器、本地基础设施组件深入讲解其核心模型、本地开发循环与生产部署路径读完你不仅能理解其设计理念还能掌握encore run的完整参数、本地基础设施的启动机制以及从本地到生产的两种部署方式。核心主张基础设施即 Go 代码Encore.go 要解决的核心痛点是传统云开发中基础设施与业务代码的割裂开发者通常需要同时维护 Terraform 脚本、YAML 清单和云控制台的手工配置才能把数据库、消息队列、存储桶等资源接进应用。Encore.go 的做法与此截然不同——你把这些资源声明为类型化的 Go 值并通过 SDK 方法直接使用它们import ( encore.dev/storage/sqldb // SQL 数据库 encore.dev/pubsub // Pub/Sub encore.dev/storage/objects // 对象存储 ) // 一个数据库、一个主题、一个存储桶全部以 Go 值的形式声明 var db sqldb.NewDatabase(users, sqldb.DatabaseConfig{}) var topic pubsub.NewTopic*OrderCreated var bucket objects.NewBucket(assets, objects.BucketConfig{})声明之后Encore 会在本地开发时自动运行与之匹配的基础设施并在部署时配合 Encore Cloud在你的 AWS 或 GCP 账号中预置真实的云资源。这一设计贯穿整个仓库encore.dev运行时runtimes/go提供了sqldb、pubsub、storage、cache等 SDK 包v2/parser负责从源码中解析出资源使用图cli/daemon/run/infra/infra.go则在本地为解析结果启动对应的真实或模拟服务。可声明的资源一览原文档列出的核心原语对应仓库中 docs/go/primitives 下的完整指南基础设施原语声明方式SDK 包深入指南SQL 数据库encore.dev/storage/sqldbdatabases.mdPub/Sub 主题与订阅encore.dev/pubsubpubsub.md对象存储桶encore.dev/storage/objectsobject-storage.md缓存encore.dev/storage/cachecaching.mdCron 任务encore.dev/croncron-jobs.md密钥encore.dev/config/ secrets 机制secrets.mdEncore 会理解这些资源在代码中的实际使用方式并自动生成运行时接线runtime wiring。从源码结构看这一过程的核心链路是v2/parser解析出meta.Dataproto/encore/parser/meta/v1 中定义的应用元数据包含数据库、Pub/Sub 主题、存储桶、服务、网关等全部声明然后由cli/daemon/run/infra/infra.go的ResourceManager依据这份元数据按需启动本地资源。本地基础设施自动启动encore run 的魔力原文档强调运行encore runEncore 会启动一个镜像生产环境的本地环境——真实的 Postgres、本地的 Pub/Sub 代理、本地对象存储等无需维护任何 Docker Compose 文件。encore run 的完整命令参数encore run的 CLI 定义位于 cli/cmd/encore/run.go通过 Cobra 注册完整参数如下encore run [--debug] [--watchtrue] [--levelTRACE] [--port4000] [--listenlisten-addr]参数默认值说明--watch, -wtrue监听文件变化并热重载--listen空监听地址例如0.0.0.0:4000未指定时默认监听127.0.0.1:port以避免触发 macOS 防火墙对全接口监听的权限询问--port, -p4000监听端口若--listen已含端口则忽略--jsonfalse以 JSON 格式输出日志--namespace, -n当前激活命名空间使用的命名空间--color终端检测结果是否彩色输出--redactfalse本地运行 trace 时脱敏敏感数据--level, -l空最低日志级别可选trace、debug、info、warn、error--debug空以调试模式编译可选enabled、break会关闭部分优化--browserauto启动时是否在浏览器打开本地开发仪表盘可选auto、never、always本地启动的完整链路从源码看encore run的执行流程是cli/daemon/run/run.go 的Run.start/buildAndStart解析应用Builder.Parse构建 Encore application graph分析服务拓扑得出需要哪些基础设施optracker中对应 Building Encore application graph、Analyzing service topology 两个操作。启动所需基础设施ResourceManager.StartRequiredServices依据解析出的meta.Data判断应用是否使用了 SQL、Pub/Sub、Redis、对象存储并按需启动对应服务cli/daemon/run/infra/infra.go。编译应用源码Builder.Compile将 Go 代码连同生成的运行时接线编译为二进制。拉取密钥secrets管理器并行获取应用密钥。启动进程组StartProcGroup根据构建输出决定以单进程isSingleProc还是每服务一进程方式启动并为每个进程注入运行时配置含服务发现、网关地址、Auth Key、密钥环境变量等。对外服务daemon 用h2c包装 handler 支持明文 HTTP/2用于转发 gRPC 等请求对外提供 HTTP 服务。本地基础设施的底层实现Postgres真实数据库StartSQLCluster通过sqldb.ClusterManager创建真实 Postgres 集群非测试环境下会异步执行 Running database migrationscluster.SetupAndMigrate把md.SqlDatabases中声明的迁移应用到本地数据库。连接信息Host 为localhost:dbProxyPort、用户encore、密码来自集群被写入运行时配置且每个数据库按 96 个连接均分上限。Pub/SubNSQ本地 Pub/Sub 由嵌入的 NSQ daemon 实现cli/daemon/pubsub/nsq.go。它绑定127.0.0.1:0随机空闲端口数据路径放在临时目录消息大小上限 10MB启动后会 Ping 验证就绪。运行时配置中通过config.NSQProvider写入其地址。Redis 缓存miniredis本地缓存使用 miniredis 实现cli/daemon/redis/redis.go以 ticker 快进时间并定期清理键将持久化键控制在约 100 个以内以限制内存占用。每个 Cache 集群在配置中分配KeyPrefix: 集群名/以避免键冲突。对象存储GCS 模拟器本地对象存储复用仓库自带的gcsemupkg/emulators/storage/gcsemu开发模式使用基于目录的文件存储objects.NewDirServer测试模式使用内存存储。启动时Initialize会依据md.Buckets预建所有声明的存储桶对外暴露 GCS 兼容的 HTTP 端点公共桶另经PublicBucketServer提供服务。类型安全的服务间调用原文档的核心卖点之一API 就是普通的 Go 函数调用另一个服务就是一次普通函数调用Encore 在边界处替你处理序列化、路由与校验。// 在 greeting 服务中定义 API //encore:api public func Greet(ctx context.Context, name string) (*Response, error) { return Response{Message: Hello, name}, nil } // 在另一个服务中调用就是一个普通函数调用 resp, err : greeting.Greet(ctx, world)本地运行时服务发现机制由cli/daemon/run/manager.go的generateServiceDiscoveryMap生成所有服务映射到同一个 API 基地址daemon 的监听地址协议为 HTTP本地服务间认证使用encore-auth方法。也就是说本地所有服务由 daemon 统一代理与路由而生产环境则映射到各自的服务 URL。内置可观测性Encore.go 自带一个本地开发仪表盘Local Development Dashboard包含分布式追踪、日志与数据库浏览器。其服务端实现在 cli/daemon/dash/dash.go追踪Tracing通过trace2.Store持久化 span提供traces/list、traces/get、traces/spans/summaries/list、traces/spans/events/list等 JSON-RPC 方法并可通过 WebSocket 推送新 tracetrace/new。数据库浏览器db/query、db/transaction方法支持在仪表盘内直接查询本地数据库db-migration-status展示每个数据库的迁移文件与应用状态。对象存储浏览器objects/list、objects/search、objects/delete、objects/download-url等方法支持浏览与管理本地存储桶中的对象。API 调用api-call方法允许从仪表盘直接对运行中的应用发起 API 请求。此外OnStart事件监听器会在--browseralways或auto且尚无客户端连接时自动打开浏览器访问http://localhost:dashPort/appID。应用运行期间的编译状态、进程输出与编译错误都会实时推送到仪表盘。相关文档见 dev-dash.md 与 tracing.md。AI-ready by Design因为基础设施以代码声明AI 编码助手可以理解并修改你的全栈代码。Encore.go 为此提供了两项配套能力AI 指令AI Instructions仓库根目录即包含 go_llm_instructions.txt 与 ts_llm_instructions.txt为编码助手提供 Encore 应用开发规则完整说明见 ai-integration.md。MCP 服务器Encore CLI 内置 MCP 服务器encore mcp源码位于 cli/daemon/mcp提供api_tools、db_tools、pubsub_tools、bucket_tools、cache_tools、cron_tools、secret_tools、metrics_tools、trace_tools、docs_tools等工具集让编辑器中的 Agent 能直接读写应用资源。接入方式见 mcp.md。原文档指出这让每个变更都能在本地与云端针对真实基础设施做端到端验证成为可能——这是 Encore.go 与 AI 编码 Agent 协同特别有效的原因详见 Development Workflow。本地到生产的紧密迭代循环由于 SDK 是基础设施的唯一事实来源source of truth同一套模型可以在本地、每个 PR 的预览环境与生产环境间保持一致本地encore run在你的笔记本上启动整个系统使用真实的 Postgres、真实的 Pub/Sub 语义和真实的追踪。预览环境打开 PR 时会在你自己的 VPC 中创建预览环境使用相同的基础设施模型并可选择从种子环境分支数据库见 preview-environments.md 与 neon.md。生产见下文部署章节。部署到生产两种受支持路径Encore.go 完全开源你永远不会被锁定在某一条部署路径上。原文档明确给出两种受支持的生产运行方式。方式一Encore Cloud托管平台可选Encore Cloud 读取你在代码中声明的基础设施并在你自己的 AWS 或 GCP 账号中预置匹配的真实资源RDS、Cloud SQL、SNSSQS、Pub/Sub、S3、GCS 等在此之上管理部署、环境、密钥与 IAM。关键边界在于云账号与基础设施归你所有Encore Cloud 只是从你的代码驱动这些资源的控制平面。平台相关文档位于 docs/platform部署流程见 deploying.md。方式二自托管Self-hosted你可以用encore build docker构建标准 Docker 镜像然后部署到任何环境。此时基础设施由你自己以任意方式预置Terraform、Pulumi、CloudFormation 或云控制台并通过**基础设施配置文件infrastructure config file**告诉 Encore 运行时如何连接这些资源。自托管时你需要运行标准 Docker 镜像并自行预置基础设施然后通过基础设施配置文件告诉 Encore 运行时如何连接这些资源。相关的配置参考见 configure-infra.md完整工作流见 self-host.md。关于encore build docker从源码看其实现位于 pkg/dockerbuild它从应用元数据与构建产物出发生成完整的镜像清单manifest、文件系统层tarcopy与运行时规范spec并支持跨平台特性features最终产出可在任何容器运行时启动的标准镜像。这与构建标准 Docker 镜像、随处运行的定位一致。下一步学习路径原文档给出了清晰的上手路线按需深入即可初次接触 Encore从 quick-start.mdx 开始构建并运行你的第一个应用。想先理解核心模型阅读 app-structure.md 与 services.md。查询具体原语参见 primitives 总览。想了解本地到生产的迭代循环参见 Development Workflow。准备部署参见 Encore Cloud 部署或阅读 self-host.md 走自托管路线。【免费下载链接】encoreThe infrastructure platform for the intelligence era项目地址: https://gitcode.com/GitHub_Trending/encor/encore创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Encore.go 全面指南：在 Go 代码中声明云基础设施的开源 SDK
Encore.go 全面指南在 Go 代码中声明云基础设施的开源 SDK【免费下载链接】encoreThe infrastructure platform for the intelligence era项目地址: https://gitcode.com/GitHub_Trending/encor/encoreEncore.go本仓库即其开源实现是一个开源基础设施 SDK允许开发者直接在 Go 代码中声明应用所需的云基础设施——SQL 数据库、Pub/Sub 主题、对象存储、缓存、Cron 任务与密钥secrets由编译器与运行时自动完成资源接线。本文以 docs/go/overview.md 为核心骨架结合仓库源码CLI daemon、运行管理器、本地基础设施组件深入讲解其核心模型、本地开发循环与生产部署路径读完你不仅能理解其设计理念还能掌握encore run的完整参数、本地基础设施的启动机制以及从本地到生产的两种部署方式。核心主张基础设施即 Go 代码Encore.go 要解决的核心痛点是传统云开发中基础设施与业务代码的割裂开发者通常需要同时维护 Terraform 脚本、YAML 清单和云控制台的手工配置才能把数据库、消息队列、存储桶等资源接进应用。Encore.go 的做法与此截然不同——你把这些资源声明为类型化的 Go 值并通过 SDK 方法直接使用它们import ( encore.dev/storage/sqldb // SQL 数据库 encore.dev/pubsub // Pub/Sub encore.dev/storage/objects // 对象存储 ) // 一个数据库、一个主题、一个存储桶全部以 Go 值的形式声明 var db sqldb.NewDatabase(users, sqldb.DatabaseConfig{}) var topic pubsub.NewTopic*OrderCreated var bucket objects.NewBucket(assets, objects.BucketConfig{})声明之后Encore 会在本地开发时自动运行与之匹配的基础设施并在部署时配合 Encore Cloud在你的 AWS 或 GCP 账号中预置真实的云资源。这一设计贯穿整个仓库encore.dev运行时runtimes/go提供了sqldb、pubsub、storage、cache等 SDK 包v2/parser负责从源码中解析出资源使用图cli/daemon/run/infra/infra.go则在本地为解析结果启动对应的真实或模拟服务。可声明的资源一览原文档列出的核心原语对应仓库中 docs/go/primitives 下的完整指南基础设施原语声明方式SDK 包深入指南SQL 数据库encore.dev/storage/sqldbdatabases.mdPub/Sub 主题与订阅encore.dev/pubsubpubsub.md对象存储桶encore.dev/storage/objectsobject-storage.md缓存encore.dev/storage/cachecaching.mdCron 任务encore.dev/croncron-jobs.md密钥encore.dev/config/ secrets 机制secrets.mdEncore 会理解这些资源在代码中的实际使用方式并自动生成运行时接线runtime wiring。从源码结构看这一过程的核心链路是v2/parser解析出meta.Dataproto/encore/parser/meta/v1 中定义的应用元数据包含数据库、Pub/Sub 主题、存储桶、服务、网关等全部声明然后由cli/daemon/run/infra/infra.go的ResourceManager依据这份元数据按需启动本地资源。本地基础设施自动启动encore run 的魔力原文档强调运行encore runEncore 会启动一个镜像生产环境的本地环境——真实的 Postgres、本地的 Pub/Sub 代理、本地对象存储等无需维护任何 Docker Compose 文件。encore run 的完整命令参数encore run的 CLI 定义位于 cli/cmd/encore/run.go通过 Cobra 注册完整参数如下encore run [--debug] [--watchtrue] [--levelTRACE] [--port4000] [--listenlisten-addr]参数默认值说明--watch, -wtrue监听文件变化并热重载--listen空监听地址例如0.0.0.0:4000未指定时默认监听127.0.0.1:port以避免触发 macOS 防火墙对全接口监听的权限询问--port, -p4000监听端口若--listen已含端口则忽略--jsonfalse以 JSON 格式输出日志--namespace, -n当前激活命名空间使用的命名空间--color终端检测结果是否彩色输出--redactfalse本地运行 trace 时脱敏敏感数据--level, -l空最低日志级别可选trace、debug、info、warn、error--debug空以调试模式编译可选enabled、break会关闭部分优化--browserauto启动时是否在浏览器打开本地开发仪表盘可选auto、never、always本地启动的完整链路从源码看encore run的执行流程是cli/daemon/run/run.go 的Run.start/buildAndStart解析应用Builder.Parse构建 Encore application graph分析服务拓扑得出需要哪些基础设施optracker中对应 Building Encore application graph、Analyzing service topology 两个操作。启动所需基础设施ResourceManager.StartRequiredServices依据解析出的meta.Data判断应用是否使用了 SQL、Pub/Sub、Redis、对象存储并按需启动对应服务cli/daemon/run/infra/infra.go。编译应用源码Builder.Compile将 Go 代码连同生成的运行时接线编译为二进制。拉取密钥secrets管理器并行获取应用密钥。启动进程组StartProcGroup根据构建输出决定以单进程isSingleProc还是每服务一进程方式启动并为每个进程注入运行时配置含服务发现、网关地址、Auth Key、密钥环境变量等。对外服务daemon 用h2c包装 handler 支持明文 HTTP/2用于转发 gRPC 等请求对外提供 HTTP 服务。本地基础设施的底层实现Postgres真实数据库StartSQLCluster通过sqldb.ClusterManager创建真实 Postgres 集群非测试环境下会异步执行 Running database migrationscluster.SetupAndMigrate把md.SqlDatabases中声明的迁移应用到本地数据库。连接信息Host 为localhost:dbProxyPort、用户encore、密码来自集群被写入运行时配置且每个数据库按 96 个连接均分上限。Pub/SubNSQ本地 Pub/Sub 由嵌入的 NSQ daemon 实现cli/daemon/pubsub/nsq.go。它绑定127.0.0.1:0随机空闲端口数据路径放在临时目录消息大小上限 10MB启动后会 Ping 验证就绪。运行时配置中通过config.NSQProvider写入其地址。Redis 缓存miniredis本地缓存使用 miniredis 实现cli/daemon/redis/redis.go以 ticker 快进时间并定期清理键将持久化键控制在约 100 个以内以限制内存占用。每个 Cache 集群在配置中分配KeyPrefix: 集群名/以避免键冲突。对象存储GCS 模拟器本地对象存储复用仓库自带的gcsemupkg/emulators/storage/gcsemu开发模式使用基于目录的文件存储objects.NewDirServer测试模式使用内存存储。启动时Initialize会依据md.Buckets预建所有声明的存储桶对外暴露 GCS 兼容的 HTTP 端点公共桶另经PublicBucketServer提供服务。类型安全的服务间调用原文档的核心卖点之一API 就是普通的 Go 函数调用另一个服务就是一次普通函数调用Encore 在边界处替你处理序列化、路由与校验。// 在 greeting 服务中定义 API //encore:api public func Greet(ctx context.Context, name string) (*Response, error) { return Response{Message: Hello, name}, nil } // 在另一个服务中调用就是一个普通函数调用 resp, err : greeting.Greet(ctx, world)本地运行时服务发现机制由cli/daemon/run/manager.go的generateServiceDiscoveryMap生成所有服务映射到同一个 API 基地址daemon 的监听地址协议为 HTTP本地服务间认证使用encore-auth方法。也就是说本地所有服务由 daemon 统一代理与路由而生产环境则映射到各自的服务 URL。内置可观测性Encore.go 自带一个本地开发仪表盘Local Development Dashboard包含分布式追踪、日志与数据库浏览器。其服务端实现在 cli/daemon/dash/dash.go追踪Tracing通过trace2.Store持久化 span提供traces/list、traces/get、traces/spans/summaries/list、traces/spans/events/list等 JSON-RPC 方法并可通过 WebSocket 推送新 tracetrace/new。数据库浏览器db/query、db/transaction方法支持在仪表盘内直接查询本地数据库db-migration-status展示每个数据库的迁移文件与应用状态。对象存储浏览器objects/list、objects/search、objects/delete、objects/download-url等方法支持浏览与管理本地存储桶中的对象。API 调用api-call方法允许从仪表盘直接对运行中的应用发起 API 请求。此外OnStart事件监听器会在--browseralways或auto且尚无客户端连接时自动打开浏览器访问http://localhost:dashPort/appID。应用运行期间的编译状态、进程输出与编译错误都会实时推送到仪表盘。相关文档见 dev-dash.md 与 tracing.md。AI-ready by Design因为基础设施以代码声明AI 编码助手可以理解并修改你的全栈代码。Encore.go 为此提供了两项配套能力AI 指令AI Instructions仓库根目录即包含 go_llm_instructions.txt 与 ts_llm_instructions.txt为编码助手提供 Encore 应用开发规则完整说明见 ai-integration.md。MCP 服务器Encore CLI 内置 MCP 服务器encore mcp源码位于 cli/daemon/mcp提供api_tools、db_tools、pubsub_tools、bucket_tools、cache_tools、cron_tools、secret_tools、metrics_tools、trace_tools、docs_tools等工具集让编辑器中的 Agent 能直接读写应用资源。接入方式见 mcp.md。原文档指出这让每个变更都能在本地与云端针对真实基础设施做端到端验证成为可能——这是 Encore.go 与 AI 编码 Agent 协同特别有效的原因详见 Development Workflow。本地到生产的紧密迭代循环由于 SDK 是基础设施的唯一事实来源source of truth同一套模型可以在本地、每个 PR 的预览环境与生产环境间保持一致本地encore run在你的笔记本上启动整个系统使用真实的 Postgres、真实的 Pub/Sub 语义和真实的追踪。预览环境打开 PR 时会在你自己的 VPC 中创建预览环境使用相同的基础设施模型并可选择从种子环境分支数据库见 preview-environments.md 与 neon.md。生产见下文部署章节。部署到生产两种受支持路径Encore.go 完全开源你永远不会被锁定在某一条部署路径上。原文档明确给出两种受支持的生产运行方式。方式一Encore Cloud托管平台可选Encore Cloud 读取你在代码中声明的基础设施并在你自己的 AWS 或 GCP 账号中预置匹配的真实资源RDS、Cloud SQL、SNSSQS、Pub/Sub、S3、GCS 等在此之上管理部署、环境、密钥与 IAM。关键边界在于云账号与基础设施归你所有Encore Cloud 只是从你的代码驱动这些资源的控制平面。平台相关文档位于 docs/platform部署流程见 deploying.md。方式二自托管Self-hosted你可以用encore build docker构建标准 Docker 镜像然后部署到任何环境。此时基础设施由你自己以任意方式预置Terraform、Pulumi、CloudFormation 或云控制台并通过**基础设施配置文件infrastructure config file**告诉 Encore 运行时如何连接这些资源。自托管时你需要运行标准 Docker 镜像并自行预置基础设施然后通过基础设施配置文件告诉 Encore 运行时如何连接这些资源。相关的配置参考见 configure-infra.md完整工作流见 self-host.md。关于encore build docker从源码看其实现位于 pkg/dockerbuild它从应用元数据与构建产物出发生成完整的镜像清单manifest、文件系统层tarcopy与运行时规范spec并支持跨平台特性features最终产出可在任何容器运行时启动的标准镜像。这与构建标准 Docker 镜像、随处运行的定位一致。下一步学习路径原文档给出了清晰的上手路线按需深入即可初次接触 Encore从 quick-start.mdx 开始构建并运行你的第一个应用。想先理解核心模型阅读 app-structure.md 与 services.md。查询具体原语参见 primitives 总览。想了解本地到生产的迭代循环参见 Development Workflow。准备部署参见 Encore Cloud 部署或阅读 self-host.md 走自托管路线。【免费下载链接】encoreThe infrastructure platform for the intelligence era项目地址: https://gitcode.com/GitHub_Trending/encor/encore创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考