Pulse 本地开发环境搭建与贡献工作流：从 Hot-Reload Dev Loop 到提交请求式变更

Pulse 是一个单维护者驱动、配合大量自动化（含编码 Agent）维护的自托管监控项目，外部贡献者不走常规的"提 PR"流程，而是"先开 Issue、由维护者明确请求后才提交补丁"。本文基于仓库内的贡献指南，完整梳理在 Go 后端（cmd/、internal/、pkg/）与 SolidJS/TypeScript 前端（frontend-modern/）上复现、调试和验证问题的本地开发工作流，覆盖依赖安装、热重载开发循环、前后端各自的构建/测试/静态检查命令、安装脚本与文档规范，以及请求式变更的提交步骤，读完即可按仓库真实结构把开发环境跑起来并理解每个环节背后的实现机制。

贡献模式：为什么必须先开 Issue

Pulse 是单维护者项目，且开发过程高度自动化。仓库在 AI 透明度说明 中给出了长期公开披露：编码 Agent 参与代码、测试、文档、发布说明、Issue 分诊与例行仓库维护，常规变更可以在维护者设定的边界内调查、实现、测试并合并到 main；所有变更（无论人还是自动化）都以"必需检查全部通过后自动合并的 PR"形式落地，发布走固定的发布列车。

在此背景下，贡献指南（frontend-modern/public/docs/CONTRIBUTING.md）明确了以下规则：

• 不接受未经请求的外部 Pull Request。即使想法成立，未被请求的 PR 也可能被关闭而不予详细评审；如果维护者确实需要某个 Issue 上的代码帮助，会在那个 Issue 中明确提出。
• 正确路径是先开 Issue，让维护者确认变更是否符合产品方向，再决定是否值得投入开发补丁。

应该开什么 Issue

• Bug 报告：使用 bug report 表单，描述故障前的原始操作序列、受影响运行实例上的版本（或安装从未完成时尝试的版本/发布资产）、安装类型，以及安全收集到的相关证据。不要求二次复现。
• 功能请求：说明要解决的问题、想改进的工作流，以及任何重要约束。
• 问题与支持：需要帮助、排障或一般性指导时使用 GitHub Discussions，而不是作为被跟踪的缺陷。
• 安全问题：敏感问题不公开开报，遵循 SECURITY.md 的流程。

如何写一个有用的 Issue

• 开新 Issue 前先搜索现有 Issue；
• 描述故障发生前的操作。如果复现可能造成数据丢失、中断、重复变更或过量通知，不要为了制造复现步骤而重复该动作，而是说明为什么没有重复；
• 写明受影响实例上运行的版本；如果 Pulse 从未启动成功，给出尝试的版本或发布资产（或注明 "unknown"），并在已知时指明安装器或 helper。仅在运行中的容器场景附带镜像 tag 或 digest，裸机或 LXC 安装不需要；
• 附截图、脱敏日志、API 输出或诊断信息。如果 Pulse 正在运行且收集安全，对连接或数据类故障使用界面中的 Settings -> Diagnostics -> Export for GitHub (sanitized)；
• 绝不要把凭据、token、私钥或含它们的命令行粘贴进 Issue；
• 以一个主 Bug 或主操作结果开头。如果上下文中还暴露了另一个可执行主题，放进 Issue 表单的专门字段，分诊流程会以"关联处置"的方式保留它，无需重新提交已提供的文字。详见 Issue 分诊与主题完整性。

项目结构总览

贡献指南给出的仓库骨架与当前代码库一致：

部分	路径	说明
后端	cmd/、internal/、pkg/	Go 1.26 Web 服务器，内嵌构建好的前端，对外暴露 REST + WebSocket API
架构文档	ARCHITECTURE.md	高层系统设计与图解
前端	frontend-modern/	Vite + SolidJS + TypeScript 应用
Agent	cmd/pulse-*-agent	随 Pulse 分发的 Go 二进制，采集主机与 Docker 遥测
文档	docs/	面向用户发布的 Markdown 指南
脚本	scripts/	用于 curl 式分发的 Bash 安装器与辅助工具

从 go.mod 可确认后端要求 go 1.26.0（工具链 go1.26.8），依赖包括 gorilla/websocket（WebSocket API）、k8s.io/client-go（Kubernetes 接入）、shirou/gopsutil（主机指标）等，与"REST + WebSocket 监控后端"的定位吻合。当前仓库 VERSION 文件标注的版本为 6.5.0，docs/releases/ 下也保留了对应的发布说明文件。

环境准备与首次启动

克隆与依赖安装

git clone https://gitcode.com/gh_mirrors/pulse27/Pulse.git
cd Pulse

# 用你喜欢的包管理器安装 Go 1.26 与 Node.js 24

# 严格按照 lock 文件安装仓库根与前端两处的依赖
npm ci
npm --prefix frontend-modern ci

仓库根 package.json 与 frontend-modern/package.json 是两个独立的 npm 工作区，因此需要分别执行 npm ci，保证依赖与各自 lock 文件完全一致。

Hot-Reload 开发循环

npm run dev                 # 前端 shell 在 :5173，后端在 :7655
npm run mock:on             # 可选：启用 mock 数据

浏览器中应访问 http://127.0.0.1:5173 做前端开发。前端 dev shell 会把 /api 与 /ws 代理到 :7655 的后端；除非在直接调试后端本身，否则不要切到 :7655 打开浏览器。受管开发运行时的登录默认是 admin / adminadminadmin，可用 HOT_DEV_AUTH_USER 和 HOT_DEV_AUTH_PASS 覆盖。

从 scripts/hot-dev.sh 头部的注释可以确认这套受管运行时的完整环境变量面：PULSE_DEV_API_PORT（后端端口，默认 7655）、FRONTEND_DEV_PORT（前端端口，默认 5173）、PULSE_MOCK_MODE（保留真实指标历史的前提下渲染 mock UI 数据）、PULSE_DATA_DIR（数据目录覆盖）、LOG_LEVEL（默认 info）、PULSE_DEV_LAN（向局域网暴露前后端以便 agent/移动端测试）、HOT_DEV_BACKEND_HEALTH_STARTUP_GRACE_SECONDS 与 HOT_DEV_BACKEND_UNHEALTHY_THRESHOLD（后端健康探针宽限期与连续失败重启阈值）等。脚本自身采用"inotifywait 监听 Go 源码变化自动重编译 + Vite HMR"的组合，并且当存在 pulse-enterprise 模块且 HOT_DEV_USE_PRO 不为 false 时会自动构建 Pro 变体（含 SQLite 持久审计日志、RBAC、HMAC 事件签名）。

Mock 模式由 scripts/toggle-mock.sh 支撑（mock:on / mock:off / mock:status / mock:edit 四个子命令），适合在没有真实 Proxmox/PBS/Docker 环境时进行 UI 开发；指南同时说明 mock 模式的内部开发者笔记不随本仓库发布。

纯后端热重载（需要 air）

air -c .air.toml

仓库根提供了 .air.toml 配置：监听 cmd、internal、pkg 三个目录的 .go/.tpl/.html 变更，排除 vendor、node_modules、tmp、frontend-modern 与测试文件，构建命令同样是"若存在 /opt/pulse-enterprise 且 HOT_DEV_USE_PRO 为 true 则构建 Pro 二进制，否则 go build -o pulse ./cmd/pulse"，与 hot-dev.sh 的构建逻辑一致。设置 HOT_DEV_USE_PRO=true 可在模块可用时构建 Pro 变体。

后端工作流

指南规定的后端四个日常命令：

go build ./cmd/pulse                      # 构建
go test ./...                             # 测试
golangci-lint run ./...                   # Lint（缺失时通过 go install 安装）
gofmt -w ./cmd ./internal ./pkg           # 格式化

指南列出的关键入口在当前仓库中的对应情况：

• HTTP 路由位于 internal/api：该目录包含访问控制、管理员恢复、租户、行动权限（如 access_admin_handlers.go、action_authority.go 等）大量 handler 文件，是 REST API 的主体；
• 监控引擎：指南写作时写作 internal/monitor，当前仓库中对应目录为 internal/monitoring/（另有 internal/monitoring 之外的 internal/hostmetrics、internal/fleethealth 等按域划分的采集与健康模块）；
• 配置解析位于 internal/config。

新增 API 端点时，指南要求在 docs/API.md 中同步文档化并尽量提供示例。

值得注意的一个实现细节：构建产物把前端静态资源打进 Go 二进制。internal/api/frontend_embed.go 中 //go:embed all:frontend-modern/dist 指令直接内嵌 frontend-modern/dist 目录，并在运行时通过 fs.Sub 取出子树提供服务——这就是为什么"生产构建"不只是 vite build，而是必须完成 dist 到 embed 位置的同步（下文前端工作流会展开）。

前端工作流

指南列出的前端命令集与 package.json、frontend-modern/package.json 中实际定义的 scripts 一一对应：

用途	命令
受管开发运行时	npm run dev
运行状态	npm run dev:status
运行时日志	npm run dev:logs
受管重启	npm run dev:restart
受管后端重启	npm run dev:backend-restart
浏览器验证包	npm run dev:verify
前台受管启动器	npm run dev:foreground
纯前端逃生口	cd frontend-modern && npm run dev:frontend-only
测试	npm --prefix frontend-modern test
类型检查	npm --prefix frontend-modern run type-check
Lint	npm --prefix frontend-modern run lint
格式检查	npm --prefix frontend-modern run format:check
生产构建	npm run build

由于 frontend-modern/package.json 中 dev、dev:status、dev:verify 等脚本都转发到 npm --prefix ..（仓库根），从 frontend-modern/ 或仓库根启动，受管运行时包装器行为完全一致——指南中"从哪个工作区开始都一样"的说法由此得到印证。

几点实现层面的补充：

• 生产构建自动同步 Go embed 副本。npm run build 实际执行 frontend-modern/scripts/build-embed-assets.mjs：先取文件锁（tmp/locks/frontend-embed-build.lock），同步 public 文档，执行 vite build，再把 dist 同步进 internal/api/frontend-modern/dist。构建完成即可直接 go build ./cmd/pulse 得到内嵌前端的完整二进制，无需手工拷贝。
• Lint 是多重审计的组合。前端 lint 脚本串联了 eslint（含 eslint-plugin-solid）与主题、文案风格、表单标签、表格行可访问性、外部域名、计划文档状态等多个自定义审计脚本，设计系统 lint 规则作为 CI 阻断项强制执行。
• SolidJS 惯用法：使用 signals、memos、createEffect，复用 components/shared/ 下的共享设计系统组件；引入 UI 重的新特性时附截图。避免硬编码的结构化 light/dark class 和断裂的工具类链，使用 frontend-modern/DESIGN_SYSTEM.md 中的语义化 token。

安装器与脚本

• 集中指引：指南指向 docs/internal/SCRIPT_LIBRARY.md（内部脚本库说明）；
• 打包：make bundle-scripts（对应 Makefile 与 scripts/bundle.sh、scripts/bundle.manifest 的打包流程）；
• 测试：scripts/tests/run.sh 加上 scripts/tests/integration/ 下的集成套件，scripts/tests/run.sh 与集成用例在仓库中均可直接查看；
• 指南还要求在 MIGRATION_SCAFFOLDING.md 中记录推广计划与 kill switch（回滚开关），让后续贡献者知道如何禁用高风险变更。

文档规范

• 行为变化时撰写或更新 docs/ 下的指南；
• 通过 docs/README.md 组织新主题，使其出现在文档索引中；
• 技术文档避免营销文案——那属于 README.md 或外部站点；
• 保持操作说明常青（evergreen），发布特定说明放入 docs/RELEASE_NOTES.md。

提交公开文档更新前必须运行：

python3 scripts/check_public_docs.py

scripts/check_public_docs.py 会校验本地链接，并拒绝当前文档面上已退役的导航声明。这也是"文档中链接必须可解析"这一要求在 CI 侧的强制点——frontend-modern/public/docs/ 下这份 CONTRIBUTING 正是通过构建时的文档同步流程（build-embed-assets.mjs 中的 syncPublicDocs）与 docs/ 保持同源发布的。

测试期望

• 每个请求式 PR 都应注明运行了哪些测试（go test、前端测试或 scripts/tests/run.sh，视适用情况）；
• 修 Bug 时补充回归覆盖；
• 自动化覆盖不可行时，注明手动验证步骤（例如"Proxmox LXC 安装器已在 PVE 8.1 上测试"）。

仓库侧的验证面也印证了这一要求：Go 侧 internal/ 下各包大量 *_test.go、前端 vitest（npm --prefix frontend-modern test，另提供按覆盖率门槛的 test:coverage 变体）、浏览器级验证通过 npm run dev:verify 生成的 proof pack（对应 frontend-modern/browser-verification/ 下的 JSON 证据），构成"单测 + 组件测试 + 浏览器取证"三层。

编码准则

• 遵循既有格式化工具（gofmt、prettier、eslint）；
• Go 包名用短而有意义的标识符（避免 util）；
• 函数保持聚焦，偏好小 helper 而非大单体；
• 新 Go 代码优先使用 context 感知的日志（logger.Named("component")）；
• 确保秘密永不进入日志，API 响应中脱敏敏感字段。

提交请求式变更

针对维护者在某个被跟踪 Issue 上明确请求的代码帮助，流程为：

1. 链接维护者请求补丁的那个 Issue；
2. Fork 并建分支（git checkout -b feature/my-change）；
3. 完成编辑并运行相关测试；
4. 按需更新文档与 changelog 条目；
5. 开 PR，描述四件事：改了什么、为什么改、做了哪些测试、推广/迁移上的顾虑。

审查者关注正确性、安全性与升级路径，任何不寻常之处都应提前在 PR 中说明。

小结

Pulse 的贡献体系核心是"issue-first + 请求式 PR"：外部开发者不直接投 PR，而是通过高质量的 Issue（版本信息、脱敏诊断、Settings -> Diagnostics -> Export for GitHub (sanitized) 导出、主题完整性字段）驱动维护者决策；一旦被请求补丁，则按 fork/branch/测试/文档更新/四要素 PR 的固定流程提交。本地开发侧，npm ci + npm --prefix frontend-modern ci 严格锁依赖，npm run dev 拉起"Vite :5173 代理到 Go 后端 :7655"的受管运行时（默认 admin/adminadminadmin，可用 HOT_DEV_AUTH_* 覆盖），后端可选 air -c .air.toml 热重载，npm run build 通过 build-embed-assets.mjs 自动把前端产物同步进 internal/api/frontend-modern/dist 的 go:embed 目录——理解这条"前端构建 → embed 同步 → 单二进制分发"的链路，就掌握了 Pulse 开发环境最关键的机制。