企业官网建设流程全解析

Encore Local Development Dashboard：本地开发内置的可视化调试工作台

【免费下载链接】encoreThe infrastructure platform for the intelligence era项目地址: https://gitcode.com/GitHub_Trending/encor/encore

Encore 在本地开发环境中内置了 Local Development Dashboard（本地开发仪表盘），它在应用运行时自动启动，把服务目录、API 文档、API Explorer、分布式追踪与架构可视化集中在一个实时刷新的 Web 界面中。本文基于 dev-dash.md 展开，并结合仓库中 cli/daemon/dash 的实现源码，说明它的启动方式、核心功能、实时更新机制与底层架构，帮助你在一键encore run后充分用好这个内置调试工作台。

什么是 Local Development Dashboard

Encore 的本地开发工作流会自动为应用提供本地基础设施（如 PostgreSQL、对象存储模拟器等，详见 infra.md），并支持带专属测试基础设施的自动化测试。在此基础上，本地环境还内置了一个 Local Development Dashboard，将设计、开发、调试应用所需的工具统一收口到一个页面中。

从 server.go 的包注释可以看到，dash包就是用来服务 Encore Developer Dashboard 的。它本质上是：

• 一个本地 HTTP 服务，把远程托管的仪表盘前端（默认来自devdash.encore.dev）代理到localhost；
• 一组本地 RPC 能力（数据库查询、对象存储浏览、追踪查询、应用状态等），通过 WebSocket 与前端通信；
• 一个应用运行状态监听器，把编译、启动、重载、报错等事件实时推送给已打开的仪表盘页面。

快速启动：encore run打开仪表盘

在应用根目录执行encore run，Encore 会编译并启动你的应用，同时启动本地开发仪表盘。它默认会自动打开浏览器，你也可以手动点击终端中打印的链接：

$ encore run API Base URL: http://localhost:4000 Dev Dashboard URL: http://localhost:9400/hello-world-cgu2

从 cli/daemon/run.go 的实现可以看到，应用成功启动后 daemon 会向终端打印：

• Your API is running at：即应用 API 的监听地址（runInstance.ListenAddr）；
• Development Dashboard URL：由DashBaseURL（仪表盘基础地址，含端口，如http://localhost:9400）与应用 ID（app.PlatformOrLocalID()）拼接而成，因此每个应用都有自己的仪表盘路径；
• 此外还会打印MCP SSE URL（本地 MCP 服务的 SSE 端点）与当前使用的 Namespace 等运行时信息。

如果你不想让浏览器自动弹出，可以通过encore run --browser=never关闭；run.go 定义了三种浏览器打开模式：

模式的解析顺序在 cli/daemon/run.go：先看命令行参数（req.Browser），若为auto再回退到用户配置文件（BrowserModeFromConfig）。在 dash.go 的OnStart回调中，auto模式会先判断当前是否已有仪表盘客户端连接（hasClients()），已存在则不重复打开浏览器。

仪表盘的四大核心功能

原文档明确列出仪表盘包含以下功能，它们全部随应用改动实时更新：

1. Service Catalog 与自动 API 文档

仪表盘会自动解析应用元数据（meta.Data），生成完整的服务目录与 API 文档，列出每个服务暴露的 endpoint、请求/响应类型与 schema。这些元数据来自 v2/app/app.go 等解析器产物，由 daemon 侧的GetMetaRPC 提供（见 dash.go）。

2. API Explorer：直接在浏览器里调用你的 API

API Explorer 允许你从文档中直接发起请求、填写参数并查看响应，免去另开 curl 或 Postman。它的底层是api-callRPC（dash.go），转发到 run/call.go 的CallAPI实现，请求会打到运行中实例的ListenAddr上。若应用未运行，会返回明确错误提示（"app not running"）。

3. 分布式追踪：简单而强大的调试工具

仪表盘内置分布式追踪视图，可以查看每个请求在服务间的完整调用链。相关 RPC 包括：

• traces/list：按应用列出最近的追踪（默认上限 100 条，见 dash.go）；
• traces/get：按 trace ID 拉取完整事件序列；
• traces/spans/summaries/list与traces/spans/events/list：获取单个 trace 的 span 摘要与事件明细；
• traces/clear：清空本地存储的追踪记录。

追踪数据由 cli/daemon/engine/trace2 的trace2.Store统一存储，仪表盘 server 在创建时即注册为 trace 监听者（server.go），任何新 span 都会实时推送到已连接的页面。

4. Encore Flow：微服务架构可视化

Encore Flow 以架构图形式展示服务、API 调用与基础设施资源（数据库、Pub/Sub、缓存等）之间的关系。它同样基于应用元数据渲染，随代码改动实时更新。其数据链路与 Service Catalog 一致，均来自meta.Data（通过GetMeta/statusRPC 下发），只是前端展示形态不同。

实时更新的原理：WebSocket 推送 + 事件监听

"所有功能随代码改动实时更新"并非轮询实现，而是基于 WebSocket 的主动推送。从 server.go 的路由可以看出，仪表盘前端与 daemon 之间建立了一条jsonrpc2over WebSocket 通道（/__encore），由 internal/jsonrpc2 实现：

• 客户端请求：前端通过 jsonrpc2 调用db/query、objects/list、traces/list、status、api-call等 RPC（完整方法列表见 dash.go 的Handle分发）；
• 服务端推送：daemon 通过notify机制向所有在线客户端推送事件，包括trace/new（新追踪）、process/start、process/reload、process/stop、process/compile-start、process/compile-error、process/output（实时日志）等。

推送的来源主要有两路：

1. 追踪通道：listenTraces从traceCh持续读取新 span，仅当存在在线客户端时才序列化并广播（server.go）；
2. 运行事件：Server实现了run.EventListener接口（dash.go），在run.Manager上注册为监听器（server.go），因此应用启动、重载、停止、编译出错、输出日志时都会触发对应推送。

这解释了两个体验细节：编译错误会立即以process/compile-error事件出现在仪表盘（错误信息还会相对应用根目录做路径归一化，见 dash.go）；应用输出日志会通过process/output实时流式显示，且日志在推送前会复制一份，避免异步发送期间缓冲区被复用（dash.go）。

内置数据库浏览器

仪表盘内置数据库浏览器，可以在界面上直接执行 SQL。它通过db/query与db/transaction两个 RPC 暴露能力（dash.go），底层实现见 dbbrowser.go：

• db/query：执行单条 SQL，支持ArrayMode（以数组行返回）与默认的对象行（按列名返回）两种结果形态；
• db/transaction：在单个事务内依次执行多条 SQL，最后统一提交，适合验证多语句的原子性。

连接建立过程（browserConn，dbbrowser.go）：先按 app ID 解析应用与 namespace，再从ClusterMgr获取本地 SQL 集群（必要时自动Setup建库），最后用 pgx 直连数据库。查询结果会原样返回给前端渲染，整个链路完全在本地完成。

内置对象存储浏览器

对于使用了 Object Storage 的应用，仪表盘还提供存储桶浏览器（bucketbrowser.go），能力包括：

• objects/list：按前缀、分隔符分页列出对象（页面大小上限 1000）；
• objects/search：按prefix或glob模式搜索对象；
• objects/delete：批量删除（单次上限 1000 个 key）；
• objects/create-folder：创建虚拟目录；
• objects/download-url：生成带签名的下载 URL（默认有效期 15 分钟，最长 1 小时，见 bucketbrowser.go）；
• objects/open/objects/reveal：在文件管理器中打开或定位本地模拟器中的对象文件。

数据源是 pkg/emulators/storage/gcsemu 的本地存储模拟器，因此浏览的是真实存在于本地磁盘上的对象内容；对象内容本身通过/__encore/objects/content端点提供（server.go），单次代理上限 1 GiB。这些行为参数与 Encore Cloud 的存储桶浏览契约保持一致（代码注释中明确说明）。

前端与后端如何协作：双代理架构

仪表盘的 HTTP 服务在 server.go 的NewServer中组装，整体是一个"双代理 + WebSocket"架构：

• 前端静态资源代理（dashproxy.go）：默认代理到https://devdash.encore.dev，前端代码按需拉取并做磁盘缓存（缓存目录{用户缓存目录}/encore/dashcache，上限 1 GiB、gzip 压缩，见 dashproxy.go），配合stale-if-error与max-age=60的缓存策略实现离线可用。请求会带上当前 CLI 版本号，便于前端按版本匹配功能。
• WebSocket 实时通道：承载上述所有 RPC 与事件推送，是仪表盘实时性的核心。

也就是说，浏览器里看到的界面是托管的前端代码，而所有数据都来自你本机的 daemon 与本地基础设施——数据不出本机。

相关配置项

仪表盘的地址与前端来源可以通过环境变量定制（internal/conf/conf.go）：

其中CacheDevDash会自动判断：只要DevDashURL包含localhost就禁用磁盘缓存（conf.go），方便前端本地开发调试。

小结

Local Development Dashboard 是 Encore 本地开发体验的核心组成部分：encore run一条命令同时带来 API 服务、自动化的 API 文档、可交互的 API Explorer、分布式追踪与架构可视化，并且通过 WebSocket + 事件监听实现"代码一改，仪表盘即刷新"。从源码看，它的实时性与完整性来自 daemon 侧的扎实设计——trace2.Store追踪存储、run.EventListener运行事件、jsonrpc2双向通道，以及数据库/对象存储两个内嵌浏览器共同支撑。相关实现可继续深入阅读 cli/daemon/dash 目录，功能文档见 service-catalog.md、tracing.md 与 encore-flow.md。

【免费下载链接】encoreThe infrastructure platform for the intelligence era项目地址: https://gitcode.com/GitHub_Trending/encor/encore