1. 项目概述：WorkBuddy 是什么，为什么要在 Win11 上装它？
WorkBuddy 这个名字最近在技术圈和效率工具社群里出现频率明显变高，但很多人第一次看到时会下意识以为是某家大厂新出的办公套件，或者某个远程协作插件。其实它既不是微软官方产品，也不是 Zoom 或 Teams 的衍生品——它是一个轻量级、专注“本地工作流串联”的开源桌面代理工具，核心定位是让不同来源、不同协议、不同权限层级的本地服务，在 Windows 11 环境下实现安全、可控、低侵入的统一接入与状态感知。简单说，它就像给你的 Win11 桌面装了一个“工作流中枢神经”，不接管你的任何应用，但能让你一眼看清哪些服务在跑、哪些端口被占、哪些进程需要手动干预。
我最早是在一个本地开发团队的内部分享会上接触到它的。当时他们正为测试环境混乱头疼：前端调本地 mock 服务用的是 3000 端口，后端调试 API 用 8080，数据库连接走 5432，而另一个同事写的 Python 脚本又悄悄占了 8000。每次启动项目前都要手动netstat -ano | findstr :xxx查一遍，再taskkill /PID xxx杀进程，重复操作每天至少五次。后来有人把 WorkBuddy 加进启动项，配合一个 YAML 配置文件，三行定义一个服务入口，五秒内自动完成端口检查、进程唤醒、健康探活、失败重试——整个流程不再依赖人盯，也不需要改代码，更不碰系统防火墙策略。
它之所以在 Win11 上特别值得实战，是因为 Win11 的 WSL2 与 Windows 原生服务共存架构、Windows AppContainer 沙箱机制、以及默认启用的 Hyper-V 虚拟化平台，让传统“一键启动所有服务”的脚本容易踩坑。比如你用 PowerShell 启动一个 Node.js 服务，它可能在 WSL2 里跑得飞快，但在 Windows 原生终端里却因路径解析问题卡死；又比如你用 bat 脚本调用 Python，Win11 默认的 Python Launcher（py.exe）有时会优先匹配到用户目录下的旧版本，导致依赖报错。WorkBuddy 的设计恰恰绕开了这些“系统层歧义”：它不替代你的启动命令，而是作为一层“观察+协调+兜底”的中间件存在，所有服务仍由你熟悉的工具（npm、python、docker-compose）原生启动，它只负责监听、上报、触发回调、记录日志。
关键词里提到的“REA”，其实是社区对 WorkBuddy 安装流程的非正式缩写，全称是Run → Enable → Attach，对应三个不可跳过的实操阶段：Run（运行主程序并验证基础环境）、Enable（启用服务注册与自动管理能力）、Attach（将已有本地服务绑定进 WorkBuddy 的生命周期管理）。这不是安装完就完事的“单点动作”，而是一套闭环工作流。很多初学者卡在第二步 Enable，以为装完 exe 就算成功，结果发现配置文件写了半天，服务状态始终显示 “unknown”，根本原因在于没理解 Win11 下服务注册必须通过 Windows Service Control Manager（SCM）以 LocalSystem 或 NetworkService 身份运行，而普通用户双击启动的 WorkBuddy 进程默认是 Interactive 用户上下文，权限不足，连读取本机服务列表的权限都没有。
所以这篇实战笔记，不讲“下载→双击→完成”的幻觉式教程，而是带你从 Win11 系统底层逻辑出发，拆解每一个 REA 步骤背后的真实约束、常见陷阱和可验证的判断依据。无论你是刚接触本地开发的新手，还是常年用 CMD/PowerShell 写自动化脚本的老手，只要你在 Win11 上需要同时维护 3 个以上本地服务（哪怕只是前端 + 后端 + 数据库），这篇内容都能帮你省下每天至少 12 分钟的无效排查时间——这数字是我连续两周用 Windows Event Viewer 统计“服务端口冲突告警”频次后反推出来的，不是拍脑袋。
2. WorkBuddy 的设计逻辑与 Win11 兼容性深度解析
2.1 为什么不用传统方案？——对比 CMD 脚本、Task Scheduler、Docker Desktop
在动手装 WorkBuddy 之前，必须先回答一个问题：既然 Win11 已经自带任务计划程序（Task Scheduler）、PowerShell、WSL2，甚至还有 Docker Desktop 这种“一站式容器平台”，为什么还要引入一个新工具？这不是叠床架屋吗？答案藏在三个维度的失配里：权限粒度、状态可见性、故障自愈能力。
先看 CMD/PowerShell 脚本。这是最原始也最灵活的方式，你可以写一个 start-all.bat，里面依次调用npm start、python app.py、docker-compose up -d。但它最大的硬伤是“无状态”。脚本执行完就退出，它不知道npm start启动的进程是否真的监听了 3000 端口，也不知道python app.py是否在 10 秒内完成了数据库连接初始化。一旦某个服务启动慢或失败，后续服务照常启动，最终你面对的是一个“看似全绿实则半瘫”的假象。更麻烦的是，当你要查问题时，得分别打开三个终端窗口，翻各自的日志，手动比对时间戳——这种体验在 Win11 的多桌面（Virtual Desktop）环境下尤其反人类，因为你永远记不清哪个 CMD 窗口对应哪个服务。
再看 Task Scheduler。它解决了“定时启动”和“开机自启”的问题，但依然无法解决“状态联动”。比如你设定了“当网络连接就绪时启动后端服务”，但没法定制“当后端服务健康检查失败 3 次后，自动重启前端服务”。它的触发器是静态事件（如登录、时间点、事件 ID），不是动态指标（如 HTTP 200 响应、TCP 端口可连通、进程 CPU 占用率 <5%）。而且 Task Scheduler 的日志分散在 Windows Event Log 的不同通道里（Microsoft-Windows-TaskScheduler/Operational），新手根本找不到入口。
最后看 Docker Desktop。它确实提供了容器编排和状态面板，但代价是强绑定。你必须把所有服务都容器化，这意味着前端要配 nginx 镜像、后端要打 Java 镜像、数据库要拉 PostgreSQL 官方镜像。对于一个正在快速迭代的本地开发环境，每次改一行代码就要重新 build 镜像、push 到本地 registry、再 docker-compose up，光等待时间就抵得上两次 Coffee Break。更重要的是，Docker Desktop 在 Win11 上依赖 WSL2，而 WSL2 的文件系统性能在 NTFS 与 ext4 之间切换时存在已知延迟（尤其是大量小文件读写），某些 Python 包管理器（如 pip）在 WSL2 中安装依赖的速度比原生 Windows 慢 40% 以上——这个数据来自某高校实验室对 12 个主流 Python 项目的基准测试报告。
WorkBuddy 的设计哲学，就是在这三者缝隙中找平衡点：它不替代你的启动方式（保留 CMD/PowerShell 的灵活性），不强制你改变部署形态（兼容原生进程、WSL2 进程、Docker 容器），也不增加额外的虚拟化开销（纯 .NET 6 构建，无 WSL2 依赖）。它的核心机制只有四层：
进程代理层（Process Proxy）：WorkBuddy 不直接启动服务，而是 fork 出子进程，并通过 Windows Job Object 机制将其纳入统一资源管控。这样既能获取子进程 PID、CPU/内存占用，又能在其异常退出时立即捕获 exit code。
端口监听层（Port Watcher）：它不扫描全端口，而是根据配置文件中声明的
port: 3000字段，主动向该端口发起 TCP Connect 探测（超时 2 秒），并缓存最近一次成功连接时间。如果连续 3 次探测失败，才标记为 “unhealthy”。服务注册层（Service Registry）：利用 Windows SCM 的
CreateServiceAPI，以SERVICE_WIN32_OWN_PROCESS类型注册一个“影子服务”。这个服务本身不干活，只响应 SCM 的 QueryStatus 请求，返回 WorkBuddy 内部维护的真实服务状态。这样 Windows 自带的services.msc和Get-Service命令就能识别它，实现与系统生态的无缝集成。事件总线层（Event Bus）：所有状态变更（如 “frontend started”、“backend unhealthy”、“db timeout”）都发布到本地命名管道（Named Pipe），供外部工具订阅。你可以用一个简单的 PowerShell 脚本监听这个管道，收到 “backend unhealthy” 就自动发邮件，或者调用 Teams webhook 推送告警——这才是真正的“可编程可观测”。
这种分层设计，让 WorkBuddy 在 Win11 上获得了极高的适配性。它不修改系统 PATH，不劫持任何 DLL，不注入进程内存，所有操作都通过 Windows 官方公开 API 完成。这也是为什么它能在 Win11 的 Core Isolation（内核隔离）和 HVCI（基于虚拟化的安全）开启状态下稳定运行——因为它的所有行为都在微软白名单之内。
2.2 Win11 特有约束：为什么 REA 必须分三步走？
WorkBuddy 的 REA 流程（Run → Enable → Attach）不是为了制造仪式感，而是对 Win11 系统安全模型的精准响应。我们逐层拆解每一步背后的系统级约束。
第一步：Run（运行主程序）
这一步的目标是验证 WorkBuddy 二进制文件能否在当前用户上下文正常加载。表面看只是双击 exe 或执行.\workbuddy.exe，但 Win11 会在此刻触发三重校验：
- SmartScreen 筛选：如果你是从 GitHub Releases 页面下载的未签名二进制，Win11 默认会弹出“未知发布者”警告。此时不能直接点“运行”，必须右键 → “属性” → 勾选“解除锁定”（Unblock），否则后续 Enable 阶段会因文件被标记为“来自互联网”而拒绝注册服务。
- .NET 6 运行时检查：WorkBuddy 是 self-contained 的 .NET 6 应用，但它仍需 Win11 自带的
Microsoft.NETCore.App.Host.win-x64组件。Win11 22H2 及更新版本默认预装，但如果你用的是精简版系统（如某些 OEM 预装的“家庭版精简包”），可能缺失。此时 Run 阶段会直接报错：“The framework 'Microsoft.NETCore.App', version '6.0.0' was not found.” 解决方案不是装 SDK，而是单独下载并安装dotnet-runtime-6.0.31-win-x64.exe（注意是 runtime，不是 hosting bundle）。 - AVG/EDR 干预检测：某些企业级杀毒软件（如 CrowdStrike、SentinelOne）会将 WorkBuddy 的进程监控行为误判为“可疑行为”，在 Run 阶段就静默终止进程。这时你需要查看 Windows 安全中心 → “病毒和威胁防护” → “保护历史记录”，过滤“阻止的应用”事件，找到 workbuddy.exe 对应的条目，临时添加排除项。
第二步：Enable（启用服务注册）
这是 REA 中最关键的一步，也是最容易失败的环节。Enable 的本质是调用 Windows SCM API 创建一个 Windows Service。但 Win11 对此有严格限制：
- 必须以管理员权限运行：普通用户即使拥有本地管理员组成员身份，也无法直接调用
CreateService。你必须右键点击 PowerShell 或 CMD，选择“以管理员身份运行”，然后执行.\workbuddy.exe --enable。如果跳过这步，直接进第三步 Attach，配置文件里的服务永远不会出现在services.msc中。 - 服务账户选择有讲究：WorkBuddy 默认尝试用
LocalSystem账户注册，这是权限最高的内置账户，能访问几乎所有本地资源。但如果你的某些服务（如连接公司 LDAP 的 Python 脚本）需要使用当前用户凭据（比如保存在 Windows Credential Manager 里的密码），就必须改成ThisAccount模式，并在 Enable 时指定用户名密码。这里有个隐藏坑：Win11 的net user命令对密码长度有最小 8 位要求，而 WorkBuddy 的 Enable 流程会校验该规则，如果密码太短，会静默失败并返回模糊错误 “Failed to configure service account”。 - 服务名称唯一性校验：Win11 的 SCM 要求服务名全局唯一。WorkBuddy 默认生成的服务名是
workbuddy-{hash}（hash 由配置文件路径计算得出），但如果你多次 Enable 又没 Clean，旧服务残留会导致新 Enable 失败。此时必须先执行.\workbuddy.exe --clean清理，再重新 Enable。
第三步：Attach（绑定本地服务）
Attach 是把你的业务服务“挂载”到 WorkBuddy 管理体系的动作。它不启动服务，只做两件事：解析 YAML 配置、建立进程监控句柄。但 Win11 的 UAC（用户账户控制）机制会让这一步变得微妙：
- 跨会话进程监控限制：如果你在管理员权限的 PowerShell 中 Enable 了 WorkBuddy 服务，而你的前端服务是用普通用户账号在另一个 CMD 窗口中启动的，WorkBuddy 默认无法监控该进程（因为 Windows 进程句柄默认不跨会话继承）。解决方案是在 Attach 配置中显式声明
session: interactive，强制 WorkBuddy 在当前交互式会话中查找进程。 - 长路径支持开关：Win11 默认禁用长路径（>260 字符），而很多现代前端项目 node_modules 路径极易超限。如果 Attach 时 WorkBuddy 报错 “The system cannot find the path specified”，大概率是这个原因。你需要提前在注册表
HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\FileSystem下将LongPathsEnabledDWORD 值设为 1，再重启 WorkBuddy 服务。
这三步环环相扣，每一步的失败都会阻断后续流程。很多用户反馈“装不上”，其实 90% 是卡在 Enable 阶段没提权，剩下 10% 是卡在 Attach 阶段的路径或会话问题。理解这些 Win11 特有的约束，比死记硬背命令重要十倍。
3. 实战 REA：从零开始完成完整安装与验证
3.1 环境准备与前置检查清单
在敲下第一个命令之前，请花 3 分钟完成这份 Win11 专属检查清单。这不是形式主义，而是避免后续 2 小时无意义排查的必要投资。
第一步：确认系统版本与架构
打开 PowerShell（无需管理员权限），执行：
Get-ComputerInfo | Select-Object WindowsProductName, OsArchitecture, OsBuildNumber你应该看到类似输出：
WindowsProductName : Microsoft Windows 11 Pro OsArchitecture : 64-bit OsBuildNumber : 22631重点检查OsBuildNumber：WorkBuddy 要求最低 Win11 21H2（Build 22000），但强烈建议使用 22H2（Build 22621）或更新版本。如果低于此版本，请先通过 Windows Update 升级。另外，OsArchitecture必须是64-bit，WorkBuddy 不提供 32-bit 支持，这点在官网文档里写得非常隐晦，但实际编译产物里根本没有 x86 目录。
第二步：验证 .NET 6 运行时
继续在同一个 PowerShell 中执行：
dotnet --list-runtimes | findstr "Microsoft.NETCore.App 6"如果返回空，说明缺失 .NET 6 Runtime。此时不要装 SDK（Software Development Kit），那会带来不必要的组件。直接去 .NET 6 Runtime 官网下载页 找到 “Runtime” 栏目下的dotnet-runtime-6.0.31-win-x64.exe（注意版本号可能随时间更新，选最新 patch 版），下载安装。安装后重启 PowerShell，再次执行上面命令，应看到：
Microsoft.NETCore.App 6.0.31 [C:\Program Files\dotnet\shared\Microsoft.NETCore.App]第三步：关闭 SmartScreen 临时干扰（仅首次安装）
右键点击下载好的workbuddy.exe→ “属性” → 底部勾选 “解除锁定” → 点击“确定”。这一步必须做，否则 Enable 阶段会因文件被标记为“来自互联网”而失败，错误日志里只会显示模糊的 “Access is denied”，根本看不出是 SmartScreen 在作祟。
第四步：检查防病毒软件拦截
打开 Windows 安全中心 → “病毒和威胁防护” → “管理设置” → “病毒和威胁防护设置” → 滚动到底部点 “ exclusions” → “添加或删除排除项”。点击 “+ 添加排除项” → 选择 “文件夹”，添加 WorkBuddy 的安装目录（例如C:\tools\workbuddy）。这能防止 EDR 软件在 Enable 阶段静默终止进程。
第五步：准备配置文件骨架
新建一个文本文件，命名为workbuddy.yaml，放在你打算安装 WorkBuddy 的目录下（建议不要放桌面或文档，选一个无空格、无中文的路径，如C:\tools\workbuddy）。填入以下最小可行配置：
version: "1.0" services: frontend: command: ["cmd", "/c", "start", "http-server", "-p", "3000"] port: 3000 health_check: type: http url: "http://localhost:3000" timeout: 5 backend: command: ["python", "app.py"] port: 8080 health_check: type: tcp timeout: 3注意几个细节：
command字段必须是数组格式，不能写成字符串"cmd /c start http-server -p 3000"，否则 WorkBuddy 无法正确解析参数。health_check.url必须带协议（http://）和主机（localhost），不能只写/或3000。port字段是整数，不是字符串，所以port: "3000"是非法的，会解析失败。
做完这五步，你已经清除了 95% 的安装障碍。接下来的 Run → Enable → Attach 才真正进入实战节奏。
3.2 Run 阶段：验证基础运行能力
打开 PowerShell（普通用户权限即可），导航到 WorkBuddy 安装目录：
cd C:\tools\workbuddy执行：
.\workbuddy.exe --version如果看到类似WorkBuddy v1.2.0 (build 20240515)的输出，说明 Run 成功。这是最基础的验证，证明二进制文件能加载、.NET 运行时可用、没有被 AV 拦截。
接着，执行：
.\workbuddy.exe --help你会看到完整的命令列表。重点关注这几个：
--enable：启用 Windows Service 注册（需管理员权限）--disable：禁用服务（需管理员权限）--clean：清理残留服务（需管理员权限）--attach <path>：绑定配置文件（可普通权限）--status：查看当前所有服务状态（可普通权限）
现在，执行一次无参数运行，观察默认行为：
.\workbuddy.exe你会看到控制台输出类似：
[INFO] WorkBuddy starting in foreground mode... [INFO] Loading config from C:\tools\workbuddy\workbuddy.yaml [WARN] No services defined in config, exiting.这个[WARN]是预期行为，因为我们还没 Attach 配置。但关键信息是[INFO] WorkBuddy starting...和[INFO] Loading config...，这证明 WorkBuddy 能正确读取当前目录下的 YAML 文件，路径解析没问题。
提示：如果这里报错 “Could not load file or assembly 'YamlDotNet'”，说明 .NET 运行时缺失或损坏，回到 3.1 节第二步重装 runtime。
注意：Run 阶段绝对不要加
--service参数！这个参数是给 Windows Service 控制器用的，普通用户执行会直接报错 “Invalid operation for current context”。
3.3 Enable 阶段：注册 Windows Service（管理员权限必做）
这是 REA 中最易出错的环节。请务必按以下顺序操作，一步都不能省。
第一步：以管理员身份启动 PowerShell
在开始菜单搜索 “PowerShell”，右键点击 “Windows PowerShell”，选择 “以管理员身份运行”。你会看到窗口标题栏显示 “Administrator: Windows PowerShell”。这是硬性要求，没有商量余地。
第二步：导航到安装目录并执行 Enable
在管理员 PowerShell 中执行：
cd C:\tools\workbuddy .\workbuddy.exe --enable如果一切顺利，你会看到：
[INFO] Creating Windows service 'workbuddy-7a8b9c' [INFO] Service created successfully [INFO] Starting service... [INFO] Service 'workbuddy-7a8b9c' started [INFO] Enable completed. WorkBuddy is now running as a Windows service.注意workbuddy-7a8b9c这个名字，它是根据你的workbuddy.yaml文件路径哈希生成的，每次路径变化都会不同。这个服务名会出现在services.msc中。
第三步：验证服务是否真实注册
保持管理员 PowerShell 打开，执行：
Get-Service | Where-Object {$_.Name -like "workbuddy*"}你应该看到一条记录，Status为Running，Name为你刚才看到的哈希名。如果Status是Stopped，说明启动失败。此时执行：
Get-EventLog -LogName System -Source "Service Control Manager" -Newest 10 | Where-Object {$_.Message -like "*workbuddy*"}查看最近的系统服务事件日志。最常见的错误是：
Error 7000: “The workbuddy-xxx service failed to start due to the following error: Access is denied.” → 原因：没以管理员权限运行，或 SmartScreen 未解除锁定。Error 7024: “The workbuddy-xxx service terminated with the following service-specific error: Incorrect function.” → 原因：.NET 6 runtime 缺失，或配置文件语法错误（如 YAML 缩进不对）。
第四步：检查服务账户与权限
在管理员 PowerShell 中执行：
sc qc "workbuddy-7a8b9c"查看输出中的SERVICE_START_NAME字段。默认值应为LocalSystem。如果你需要访问用户凭据，可以修改为NT AUTHORITY\ThisAccount，但必须配合sc config命令设置密码：
sc config "workbuddy-7a8b9c" obj= "DOMAIN\username" password= "your_password"注意：obj=和password=后面必须有空格，且密码不能含特殊字符（如&,|,>），否则 PowerShell 会解析错误。
完成 Enable 后，WorkBuddy 已作为 Windows 服务后台运行。你可以关闭管理员 PowerShell，它不会停止。
3.4 Attach 阶段：绑定配置与服务启动
Attach 是让 WorkBuddy “认领”你本地服务的最后一步。它不启动服务，但建立监控关系。
第一步：确保配置文件路径正确
WorkBuddy 默认在服务启动时读取C:\tools\workbuddy\workbuddy.yaml。如果你把配置文件放在别处，必须显式指定路径。在普通用户 PowerShell 中执行：
cd C:\tools\workbuddy .\workbuddy.exe --attach .\workbuddy.yaml如果配置文件语法正确，你会看到：
[INFO] Attaching config from C:\tools\workbuddy\workbuddy.yaml [INFO] Service 'frontend' attached successfully [INFO] Service 'backend' attached successfully [INFO] Attach completed.第二步：验证 Attach 结果
执行：
.\workbuddy.exe --status你应该看到类似输出：
SERVICES STATUS frontend unknown n/a n/a backend unknown n/a n/a注意unknown状态是正常的，因为此时服务还没启动，WorkBuddy 只是建立了监控关系，还没开始探活。
第三步：手动启动你的服务
现在，打开两个新的 CMD 窗口（普通用户权限）：
- 窗口 1：执行
npm install -g http-server（如果还没装），然后http-server -p 3000 - 窗口 2：执行
python app.py（确保app.py存在且能监听 8080）
等两个服务都启动成功后（CMD 窗口显示 “Starting up on http://localhost:3000” 和 “Running on http://localhost:8080”），再次执行：
.\workbuddy.exe --status这次你应该看到：
SERVICES STATUS frontend healthy 3000 http://localhost:3000 backend healthy 8080 tcp://localhost:8080healthy表示 WorkBuddy 已成功探测到端口并收到健康响应。
第四步：模拟故障，验证自愈能力
在 CMD 窗口 1 中按Ctrl+C停止http-server，然后立刻执行：
.\workbuddy.exe --status你会看到frontend状态变成unhealthy。等待 10 秒（WorkBuddy 默认探活间隔），再执行--status，状态应变为failed。此时，WorkBuddy 会根据配置中的restart_policy（默认为always）自动重启服务。你可以在 CMD 窗口 1 中看到http-server被重新拉起，状态也恢复为healthy。
这就是 Attach 的真正价值：它不只是“看到”服务，而是让服务具备了可编程的生命周期管理能力。
4. 常见问题与排查技巧实录：来自真实场景的 7 个高频故障
4.1 故障一：Enable 成功但服务在 services.msc 中显示“已停止”
现象描述：
执行.\workbuddy.exe --enable返回 “Service started”，但打开services.msc，找到workbuddy-xxx服务，状态却是“已停止”，双击打开属性，启动类型是“自动”，但“服务状态”栏明确写着“已停止”。
根本原因：
这是 Win11 的服务启动超时机制在作怪。WorkBuddy 服务启动时需要加载 YAML 配置、初始化端口监听器、建立事件总线，整个过程默认有 30 秒超时。如果你的workbuddy.yaml文件路径很深（如C:\Users\YourName\Documents\Projects\workbuddy\config.yaml），或者磁盘 I/O 较慢（如机械硬盘），加载时间可能超过 30 秒，导致 SCM 强制终止服务，并记录事件 ID 7009。
排查步骤：
- 打开事件查看器 → Windows 日志 → 系统，筛选事件 ID 7009，找到对应
workbuddy-xxx的条目，查看“详细信息”里的超时秒数。 - 在管理员 PowerShell 中执行
sc queryex "workbuddy-xxx"，查看WIN32_EXIT_CODE。如果是1053，就坐实了超时问题。
解决方案：
修改服务启动超时阈值。在管理员 PowerShell 中执行：
sc config "workbuddy-xxx" start= auto sc sidtype "workbuddy-xxx" unrestricted # 关键命令：将服务超时设为 120 秒 sc failure "workbuddy-xxx" actions= restart/60000/restart/60000/restart/60000 reset= 86400然后执行sc start "workbuddy-xxx"手动启动。如果成功，再执行.\workbuddy.exe --attach绑定配置。
实操心得：我遇到过最极端的案例是配置文件放在 OneDrive 同步文件夹里，由于 OneDrive 的文件锁机制，WorkBuddy 加载 YAML 时被阻塞了 42 秒。解决方案是把配置文件移到本地磁盘（如
C:\workbuddy），彻底避开云同步干扰。
4.2 故障二：Attach 后 --status 显示 “unknown”，且 never 变成 “healthy”
现象描述：--attach成功，--status显示unknown，但等 5 分钟、10 分钟，状态始终不变，手动访问http://localhost:3000却能正常打开页面。
根本原因：
WorkBuddy 的健康检查是主动探测，不是被动监听。unknown状态意味着它还没开始第一次探活。而探活启动的前提是：服务必须处于running状态，且 WorkBuddy 服务进程必须能成功解析health_check.url。最常见的原因是health_check.url中的localhost被 DNS 解析为 IPv6 地址::1，而你的服务只监听 IPv4 的127.0.0.1，导致 TCP 连接失败。
验证方法：
在管理员 PowerShell 中执行：
Test-NetConnection -ComputerName localhost -Port 3000如果返回TcpTestSucceeded : False，但你知道服务确实在跑，那就很可能是 IPv4/IPv6 混淆。再执行：
Resolve-DnsName localhost | Select-Object IPAddress如果第一行是::1，就确认了问题。
解决方案：
修改workbuddy.yaml中的health_check.url，把localhost显式替换为127.0.0.1：
health_check: type: http url: "http://127.0.0.1:3000" # 替换这里 timeout: 5然后执行.\workbuddy.exe --clean清理，再--enable和--attach重来。
注意：不要试图用
netsh interface ipv6 set prefixpolicy ::1/128 50 0这类命令强行禁用 IPv6，这会影响 Win11 其他网络功能，得不偿失。
4.3 故障三：服务状态显示 “unhealthy”，但手动 curl 却返回 200
现象描述：--status显示backend unhealthy，但你在 CMD 中执行curl http://localhost:8080/health，返回{"status":"ok"}，完全正常。
根本原因：
WorkBuddy 的 HTTP 健康检查默认发送 GET 请求，但某些框架（如 Spring Boot Actuator）的/health端点要求特定的Accept头或User-Agent。WorkBuddy 默认不带任何头，被服务端拒绝。
排查方法：
启用 WorkBuddy 的详细日志。在管理员 PowerShell 中执行：
sc stop "workbuddy-xxx" .\workbuddy.exe --log-level debug --attach .\workbuddy.yaml观察控制台输出，找到类似HTTP GET http://localhost:8080/health failed: StatusCode=406的日志，406 Not Acceptable就是铁证。
解决方案：
在workbuddy.yaml中为 health_check 添加 headers：
health_check: type: http url: "http://localhost:8080/health" timeout: 5 headers: Accept: "application/json" User-Agent: "WorkBuddy/1.0"然后重新--enable和--attach。
4.4 故障四：WorkBuddy 服务启动后，CPU 占用率持续 25%
现象描述：
服务启动后，任务管理器中workbuddy.exe进程 CPU 占用率稳定在 25%（即一个逻辑核心满载），风扇狂转，但--status显示一切正常。
根本原因：
这是典型的“健康检查风暴”。WorkBuddy 默认每 5 秒探活一次，如果你配置了 5 个服务，每个服务都有 HTTP 和 TCP 双重检查，那么每秒会产生 2 次网络请求。在 Win11 的网络栈中，频繁的短连接会触发 TCP TIME_WAIT 状态堆积，导致内核调度压力剧增。
验证方法：
在管理员 PowerShell 中执行：
netstat -ano | findstr "TIME_WAIT" | Measure-Object | Select-Object Count如果Count超过 500，基本可以确定。
解决方案：
降低探活频率。在workbuddy.yaml的根节点添加global配置：
global: health_check_interval: 30 # 单位：秒，从默认 5 秒改为 30 秒 version: "1.0" services: # ... your services然后--clean→--enable→--attach。实测下来，30 秒间隔对开发环境完全够用，CPU 占用会降到 0.5% 以下。
4.5 故障五：Attach 后，服务启动失败，日志显示 “The system cannot find the file specified”
**现象描述
