docs(install): add Windows hosts section to edge.md - #233
Draft
anrenlx2025 wants to merge 5 commits into
Draft
anrenlx2025 wants to merge 5 commits into
anrenlx2025 wants to merge 5 commits into
Conversation
added 5 commits
July 19, 2026 20:06
为 Windows edge agent 奠定平台基础，包含： - internal/edgeagent/dpapi: DPAPI CRYPTPROTECT_LOCAL_MACHINE 加密 + round-trip 验证 - internal/edgeagent/edgedirs: Windows 平台目录抽象（InstallDir / DataDir / StageDir / LogDir） - internal/edgeagent/install: supervisor --install 入口拆分为 SecretStore / ServiceController / EnvWriter 三接口，支持 schtasks SYSTEM 身份执行 - internal/edgeagent/config: secrets.enc 加载 + token 轮转周期检查（默认 90 天） - internal/edgeagent/host_files: 平台抽象（owner_windows / owner_unix / times_windows） 本 PR 仅加新文件，不改 main.go / config.go / tunnel/*。后续 PR 将引入： - PR2: cmd/ongrid-edge-supervisor（Windows Service 包装 + worker 监控） - PR3: upgradebundle + upgrademachine（rename-aside 自升级机制） - PR4: Windows host skills + plugins（hostmetrics/logs Windows 分支） 测试：dpapi + install + config 单元测试通过；GOOS=linux + GOOS=windows 双向编译通过。
引入 Windows edge supervisor（Windows Service 包装层）+ rename-aside 自升级机制， 对称消费 PR1 scaffolding（DPAPI/edgedirs/install）。 包含： - cmd/ongrid-edge-supervisor: Windows Service 入口（main/service/worker/upgrade_windows/install_windows） - supervisor.exe --install/--uninstall/--upgrade 子命令 - worker 进程生命周期管理（启动/监控/重启） - schtasks SYSTEM 身份执行 DPAPI install - internal/edgeagent/supervisorhealth: supervisor 健康检查 + health.json 写入 - internal/edgeagent/upgradebundle: bundle 下载 + SHA256 校验 + 健康标记写入 - internal/edgeagent/upgrademachine: 深模块 rename-aside 自升级状态机 - Machine 接口（4 个）：ProcessController / State / IPC / Manifest - supervisor self-swap（运行中 .exe 自我替换） - W1-W5 加固：orphan worker race / Defender 锁文件 / brick rollback / SCM recovery / pending bundle 解压 依赖：PR1 ongridio#228（DPAPI + install + edgedirs） 验证： - GOOS=linux + GOOS=windows 双向编译通过 - 单元测试：cmd-supervisor + supervisorhealth + upgradebundle + upgrademachine 全部通过 - upgrademachine 含 10 循环稳定性 + 并行 race condition 测试 后续：PR3 将加 Windows host skills + plugins Windows 分支（hostmetrics/logs/skill/quota）。
PR1 (ongridio#228) + PR2 (ongridio#229) 推送后发现注释含内部死引用（upstream 无对应文档）， 此 follow-up 把它们清理掉： 清理范围： - ADR-0XX / ADR-033 U3 I2 / ADR-035 Q7 C5 / ADR-037 A2 CR4 等内部 ADR 编号 - MVP-1/2/3 + ongridio#4/ongridio#7/ongridio#9/ongridio#13/ongridio#18-1/ongridio#20/ongridio#21/ongridio#23 等内部 issue 编号 - W1-W5 加固编号（保留具体描述，仅删编号） - dogfood / P5 dogfood / YAGNI / 对抗式审核 等内部审核术语 - CR4 子编号 仅注释改动，零功能变化。32 文件 / +120 / -240。 验证： - GOOS=linux + GOOS=windows 双向编译通过 - 单元测试全部通过（cmd-supervisor + supervisorhealth + upgradebundle + upgrademachine） - grep 完整性扫描零匹配（ADR/MVP/#issue/dogfood/YAGNI/CR4 全清）
为 Windows edge 加 5 个 host skill（对标 Linux host_* skills）+ plugins 平台拆分， 完成 Windows edge agent 的运营可观测能力。Stacked on PR2 ongridio#229 + cleanup ongridio#230。 包含： - internal/skill/builtin/windows/: 5 个 RCA 必需 skill - event_log: Windows 事件日志查询（含 psQuote 受控注入 + adversarial test） - services: 查询 Windows 服务列表 + 状态 - processes: 查询进程列表 + 资源占用 - network: 查询 TCP 连接（Get-NetTCPConnection） - hotfix: 查询已安装补丁（Get-HotFix） - 公共：psquery（PS 5.1 JSON 序列化集中）/ metadata / powershell / skeleton / enum - internal/skill/builtin/windows_catalog_other.go + windows_import_windows.go: skill 注册 - internal/edgeagent/plugins/hostmetrics/: 平台分离 - plugin.go 缩为 14 行 doc（删除 New 实现） - plugin_linux.go: node_exporter subprocess + textfile producer - plugin_windows.go: windows_exporter.exe subprocess（collector 白名单 hardcode） - internal/edgeagent/plugins/logs/: 平台分离 - render.go 删除（被 render_common/render_linux/render_windows 替代） - binary_name_linux.go + binary_name_windows.go: promtail binary name 平台差异 - plugin.go: 使用 promtailBinaryName 变量替代 hardcoded "promtail" - internal/edgeagent/skill/quota*: 资源配额自适应（CPU 10% / GOMAXPROCS 上限 4 / 内存自适配） 依赖：PR1 ongridio#228（基础）+ PR2 ongridio#229（supervisor）+ ongridio#230（注释清理） 验证： - GOOS=linux + GOOS=windows 双向编译通过 - 单元测试：windows skills (含 adversarial) + hostmetrics + logs + skill/quota 全部通过 - 注释清理完整：grep ADR/MVP/#issue/dogfood/YAGNI/CR4 零匹配
为 Windows edge agent（PR1 ongridio#228 + PR2 ongridio#229 + cleanup ongridio#230 + PR3 ongridio#232）配套安装文档。 Stacked on PR3 head，与代码 PR 同步 review。 包含： - Quick start (release zip)：PowerShell 解压到 Program Files - Build and stage the Windows binaries：源码构建（make build-edge-windows-amd64） - Install the service：supervisor.exe --install 通过 schtasks SYSTEM 身份执行 （DPAPI CRYPTPROTECT_LOCAL_MACHINE 要求 SystemCredential profile） - Configuration notes 3 子节： - Service account (SYSTEM required)：解释 DPAPI 约束 + 出站 40012 防火墙 - Microsoft Defender exclusions：Add-MpPreference 防止升级 brick - Time synchronization (NTP)：token rotation grace 窗口要求漂移 < 5min - Verify the connection：Get-Service + worker 日志 tunnel: connected - Uninstall：supervisor.exe --uninstall（不需 DPAPI） Windows agent 镜像 Linux dial-out 模型（主机无需入站端口）。
Contributor
Author
|
Heads-up: the Windows edge chain this docs PR depends on has now landed on main — #228 (platform scaffolding), #229 (Windows Service supervisor + upgrade state machine), and #231 (test fix). Now that the underlying feature is merged, a |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Add Windows hosts section to
docs/install/edge.md. Stacked on the Windows edge PR chain (#228 / #229 / #230 / #232). Depends on those PRs merging first.Scope (this PR)
Appends a
## Windows hostssection (~150 lines) to the existing Linux-focused install guide. Mirrors the Linux section's structure for symmetry:make build-edge-windows-amd64supervisor.exe --installviaschtasksSYSTEM identity (DPAPICRYPTPROTECT_LOCAL_MACHINErequiresSystemCredentialprofile)Add-MpPreferenceto prevent upgrade brickGet-Service+ worker log inspection fortunnel: connectedsupervisor.exe --uninstallWhy a section, not a new file
upstream's
docs/install/convention is a singleedge.mdcovering the Edge Agent. Adding a Windows section (rather thanedge-windows.md) keeps the install guide unified and matches how Linux + macOS already coexist in the file.Stacked chain
This PR's branch includes commits
b705400(PR1) +2e1b996(PR2) +b6d4351(cleanup) +55d46f3(PR3, with the render.go deletion fix) +fcd850b(this docs PR). Once #228 + #229 + #230 + #232 merge, this PR auto-rebases and the diff collapses to just the Windows hosts section.Verification
Out of scope
edge.md(upstreamdocs/is English-only by convention; multi-language is reserved for README)