Encore 本地开发仪表盘Local Development Dashboard完全指南实时架构图、分布式追踪与 API 调试一体化【免费下载链接】encoreThe infrastructure platform for the intelligence era项目地址: https://gitcode.com/GitHub_Trending/encor/encoreEncore 为本地开发内置了一站式开发仪表盘Local Development Dashboard让开发者无需额外接入任何观测工具就能在浏览器中获得实时更新的服务目录、API 文档、分布式追踪和架构可视化。本文基于当前仓库的官方文档与 cli/daemon/dash 源码实现系统讲解如何启动、访问并使用仪表盘的每一项能力同时剖析其背后的 WebSocket/JSON-RPC 通信架构帮助你把它用透、用深。一、仪表盘是什么本地开发的内置生产力工具Encore 的本地开发工作流会自动为应用预置本地基础设施参见 infra#local-development并支持基于专用测试基础设施的自动化测试。在此基础上本地环境还随encore run附带一个内置的Local Development Dashboard把设计、开发、调试三个阶段需要的关键信息聚合在一个界面中。仪表盘的核心特性包括Service Catalog自动生成的服务目录与 API 文档详见 service-catalogAPI Explorer直接在界面上调用你的 API无需手写 curl分布式追踪Distributed Tracing简单而强大的跨服务请求链路调试详见 tracingEncore Flow微服务架构的实时可视化详见 flow。这些特性全部随代码变更实时更新——你保存文件、应用热重载的同时仪表盘上的服务目录、追踪数据与架构图会同步刷新让代码即真相贯穿整个开发过程。二、启动与访问从encore run到浏览器访问仪表盘非常简单在应用根目录启动应用即可。$ encore run API Base URL: http://localhost:4000 Dev Dashboard URL: http://localhost:9400/hello-world-cgu2API Base URL4000 端口应用对外暴露的 API 网关地址默认监听127.0.0.1:4000Dev Dashboard URL9400 端口仪表盘地址末尾的路径段是应用 ID示例中的hello-world-cgu2由平台或本地 ID 决定。默认情况下仪表盘会在启动时自动打开浏览器你也可以随时在终端输出中复制该链接手动访问。端口与标志位从源码看本地开发服务监听以下固定端口见 cli/cmd/encore/daemon/daemon.go#L127-L133端口服务说明9400dashboard本地开发仪表盘9500dbproxy数据库代理9600runtime运行时9700debug调试端口encore run命令支持若干与仪表盘体验直接相关的标志位见 cli/cmd/encore/run.go#L56-L87encore run [--debug] [--watchtrue] [--port4000] [--listenlisten-addr] [flags]标志位默认值说明-p, --port4000应用 API 监听的端口--listen空指定监听地址如0.0.0.0:4000指定后优先于--port-w, --watchtrue监听文件变更并热重载--browserauto是否在启动时打开仪表盘浏览器可选auto/never/always--redactfalse本地追踪中脱敏敏感数据--debug空以调试模式运行应用--debugbreak会在启动时暂停等待调试器--namespace, -n空使用的命名空间默认使用激活的命名空间控制浏览器打开行为的三种模式浏览器是否自动打开由BrowserMode决定见 cli/daemon/run/run.go#L118-L149BrowserModeAuto如果仪表盘尚未打开则自动打开默认BrowserModeNever从不自动打开BrowserModeAlways总是自动打开。除了命令行标志你还可以通过配置文件永久控制该行为。配置项run.browser详见 config-reference同样接受always、never、auto三选一默认值为autoauto 语义与命令行一致——仅在仪表盘尚未打开时自动打开。源码中BrowserModeFromConfig负责读取用户配置并转换为对应的模式见 cli/daemon/run/run.go#L127-L136。关闭仪表盘的场景不需要仪表盘时直接以encore run --browsernever启动即可阻止浏览器弹出仪表盘服务本身仍会在 9400 端口可用随时可手动访问。三、核心能力一Service Catalog 与自动 API 文档仪表盘内嵌的 Service Catalog 是基于Encore Application Model自动生成的服务目录与 API 文档见 service-catalog。它的价值在于文档从你的源码实时派生永远不会因为代码演进而过期。要让文档更丰满你只需在源码中写注释。Encore 会解析 TypeScript 源码中的//行注释与/** */JSDoc 注释并把这些注释同步呈现到 Service Catalog、生成的 API 客户端与 OpenAPI 规范中详见 api-docs。import { Service } from encore.dev/service; // Payments handles payment processing, billing, // and subscription management. export default new Service(payments);import { api } from encore.dev/api; // Charge charges the given payment method. // It is idempotent; calling it multiple times // with the same idempotency key has no additional effect. export const charge api( { expose: true, auth: true, method: POST, path: /charge }, async (params: ChargeParams): PromiseChargeResponse { // ... }, );在 OpenAPI 规范中注释第一行会成为接口的summary其余行会成为description。这意味着文档即代码API 演进时文档同步更新。四、核心能力二API Explorer 与源码级的调用链路API Explorer 允许你在仪表盘中直接对本地运行的应用发起 API 调用省去手写请求的麻烦。从源码看这个能力的后端由api-call这个 JSON-RPC 方法承载见 cli/daemon/dash/dash.go#L424-L431仪表盘前端通过 WebSocket 发送api-call请求后端调用run.CallAPI向当前运行中的应用实例发起 HTTP 请求并返回响应。run.CallAPI的实现要点见 cli/daemon/run/call.go先通过FindRunByAppID找到正在运行的应用实例如果应用未运行会返回app not running错误以http://run.ListenAddr为基础 URL 构造真实请求其中ListenAddr即encore run打印的 API Base URL请求经过本地服务发现svcproxy被路由到对应的服务进程。因此 API Explorer 本质上是对你应用的真实请求回放——调用过程中产生的日志、追踪、数据库查询都会被正常记录方便你在同一界面中验证请求并立即查看结果。五、核心能力三分布式追踪Distributed Tracing仪表盘的追踪功能让本地开发也能享受生产级观测能力Encore 会自动为整个应用捕获追踪数据无需手动埋点见 tracing。与一般 tracing 工具不同Encore 能识别每个追踪事件的语义从而捕获更丰富的信息堆栈追踪stack traces结构化日志structured loggingHTTP 请求网络连接信息API 调用数据库查询等等追踪数据的后端接口仪表盘前端通过traces/*系列 JSON-RPC 方法与后端交互见 cli/daemon/dash/dash.go#L273-L363方法作用traces/list按应用 ID 列出最近的追踪摘要默认上限 100 条支持按消息 ID 过滤与测试追踪过滤traces/get获取指定trace_id的全部追踪事件流traces/spans/summaries/list获取指定追踪的 span 摘要traces/spans/events/list获取指定 span 内的事件列表traces/clear清空某个应用的本地追踪数据这些方法由trace2.Store提供数据支撑对应 cli/daemon/engine/trace2追踪数据来自本地运行进程上报的 span。实时推送新追踪即刻出现在界面仪表盘不会让前端轮询追踪列表。在 cli/daemon/dash/server.go#L510-L535 的listenTraces中Server监听traceCh通道每当有新的 span 产生trace2.NewSpanEvent只要当前存在活跃的 WebSocket 客户端就会通过trace/new通知实时推送给浏览器。这就是为什么你在 API Explorer 里点一下请求追踪面板几乎同时就出现新链路的根本原因。敏感数据脱敏Encore 的追踪默认会捕获请求/响应载荷以方便调试。但对密码、PII个人身份信息等敏感数据你可以把端点标记为敏感详见 defining-apisexport const processPayment api( { expose: true, method: POST, path: /payments, sensitive: true }, async (params: PaymentParams): PromisePaymentResponse { return { /* ... */ }; }, );当sensitive: true时Encore 会自动从追踪中脱敏该端点的请求/响应载荷并排除 HTTP 头。本地开发时你也可以用encore run --redact直接开启全局脱敏。六、核心能力四Encore Flow 实时架构可视化Encore Flow 是仪表盘中的架构可视化面板详见 flow为你提供整个系统的上帝视角服务与 PubSub 主题显示为方框箭头表示依赖关系虚线箭头表示对主题的发布/订阅悬停任意服务或主题可即时查看其依赖的性质与规模如对某个数据库的查询、对某服务端点的调用本地开发时随代码改动实时更新让你始终清楚地知道是否引入了新的依赖。Flow 既出现在本地开发仪表盘也出现在 Encore Cloud 的云端环境仪表盘中云端环境下每次部署后自动更新。七、源码视角仪表盘的技术架构理解仪表盘如何工作能帮你更好地排查它偶发不响应之类的问题。其整体架构分为三层见 cli/daemon/dash/server.go#L31-L88前端静态资源代理dashproxy.New(conf.DevDashURL)创建反向代理将仪表盘的前端页面代码托管到本地 9400 端口。前端资源默认从https://devdash.encore.dev拉取可通过环境变量ENCORE_DEVDASH_URL覆盖见 internal/conf/conf.go#L47-L52WebSocket 数据通道路径/__encore将 WebSocket 升级为 JSON-RPC 连接使用仓库自研的 internal/jsonrpc2 实现前端通过它发起traces/list、api-call、db/query、objects/list、status、db-migration-status等数百个方法调用GraphQL 代理路径/__graphql将请求代理到平台 API带 OAuth2 令牌注入见 cli/daemon/dash/apiproxy/apiproxy.go用于拉取与平台相关的数据。在进程生命周期上Server实现了run.EventListener接口见 cli/daemon/dash/dash.go#L537-L632实时监听运行实例的以下事件并推送给前端事件通知方法触发时机OnStartprocess/start应用启动同时依据 BrowserMode 决定是否自动打开浏览器OnCompileStartprocess/compile-start开始编译状态置为 CompilingOnReloadprocess/reload热重载完成OnStopprocess/stop应用停止OnStdout/OnStderrprocess/output实时输出日志OnErrorprocess/compile-error编译错误含错误列表这套事件驱动 实时推送的设计正是仪表盘所有功能随代码变更实时更新的技术基础。八、调试与运维配套能力除四大核心特性外仪表盘还从源码层面支持若干辅助能力值得善加利用数据库查询与事务通过db/query、db/transaction方法在仪表盘中直接浏览数据库表结构、执行 SQL见 cli/daemon/dash/dbbrowser.go数据库迁移状态db-migration-status方法返回每个数据库的迁移历史文件名、编号、是否已应用源码还会正确处理不允许非顺序迁移场景下的隐式应用状态见 cli/daemon/dash/dash.go#L739-L787对象存储浏览器通过objects/list、objects/search、objects/delete、objects/download-url、objects/open、objects/reveal等方法浏览本地对象存储 bucket 的内容甚至直接打开或在本机文件管理器中定位对象见 cli/daemon/dash/bucketbrowser.goIDE 跳转editors/list与editors/open让仪表盘中的源码引用一键在你常用的编辑器中打开对应文件见 pkg/editors调试模式配合encore run --debugbreak暂停等待调试器或encore run --debug不暂停可以在 VS Code / WebStorm 中断点调试 TypeScript 应用终端会输出调试器地址ws://127.0.0.1:9229/...详见 debug。九、配置速查与常见问题配置项汇总配置/标志取值默认作用run.browser配置文件always/never/autoauto控制encore run是否自动打开仪表盘浏览器--browser命令行同上auto单次启动覆盖浏览器行为--redact布尔false本地追踪全局脱敏--port/--listen整数 / 地址4000/127.0.0.1应用 API 监听端口ENCORE_DEVDASH_URLURLhttps://devdash.encore.dev覆盖仪表盘前端资源地址常见问题排查仪表盘没有自动打开检查是否设置了--browsernever或配置了run.browser never手动访问终端打印的 Dev Dashboard URL 即可仪表盘页面空白/加载失败确认 9400 端口未被占用且网络可访问devdash.encore.dev或已正确设置ENCORE_DEVDASH_URL指向自托管资源追踪列表为空确认应用确实在运行encore run启动后 API Base URL 可用且调用过 API 产生过流量也可以使用traces/clear后重新触发请求来验证敏感信息出现在追踪中为对应端点添加sensitive: true或改用encore run --redact。结语Local Development Dashboard 把服务目录、API 调用、分布式追踪、架构可视化乃至数据库与对象存储浏览聚合在一个随代码实时刷新的界面中是 Encore 本地开发体验的核心组成部分。通过本文结合 cli/daemon/dash 源码的剖析可以看到它本质上是本地反向代理 WebSocket JSON-RPC 事件驱动推送的轻量架构前端资源走反向代理加载所有交互通过/__encore的 JSON-RPC 通道完成运行状态则由run.EventListener事件流驱动实时刷新。理解这一架构后无论是日常调试、排查追踪问题还是为团队制定统一的本地开发规范你都能游刃有余。【免费下载链接】encoreThe infrastructure platform for the intelligence era项目地址: https://gitcode.com/GitHub_Trending/encor/encore创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考