简介WinSW是开源轻量级Windows服务包装工具主要面向开发人员和系统管理员可将Java、.NET及自定义执行程序便捷地注册为系统服务解决后台程序缺少服务管理机制、无法开机自启或异常自动恢复等常见问题。该压缩包共3个文件、约11.2MB包含WinSW-x64.exe与WinSW-x86.exe两个可执行版本分别适配64位和32位Windows系统另附sample-minimal.xml典型配置模板用于指定服务名称、启动参数与日志记录方式等核心设置。目前已有538人浏览学习适合需要让应用程序以Windows服务方式稳定运行的开发与运维场景。通过这套精简工具读者可快速上手WinSW的安装与配置流程将后台任务、定时脚本或应用进程包装为标准化服务实现统一监控和可靠运行。1. 为什么 Windows 服务总是一个玄学问题WinSW 到底帮你干了什么很多开发者在 Windows 上写好了后台程序、定时任务或者内网工具第一反应是“双击 exe 不就行了”。但放到生产环境会发现用户一注销进程就被杀掉断电重启没人去手动点开出了异常没人帮忙拉起。Windows 服务就是解决这个问题的标准机制但用 sc.exe 或者 C# 写一个 ServiceBase 项目对大多数团队来说成本太高。WinSW 做的事情很直接把一个普通 exe 包装成符合 Windows 服务管理器SCM规范的服务用一份 sample-minimal.xml 就能让任意命令行程序拥有开机自启、失败重启、日志重定向的能力。本文要拆的就是 WinSW-x64.exe、WinSW-x86.exe 和 sample-minimal.xml 这三个文件怎么配合、怎么落地以及这几年我在生产环境里替别人收拾过的几个翻车现场。2. 认清 WinSW-x64.exe、WinSW-x86.exe 和 sample-minimal.xml三个文件各自的作用2.1 为什么会有 x64 和 x86 两个包装器它们区别在哪先说结论WinSW 本身是一个原生可执行程序x64 版本运行在 64 位进程里x86 版本运行在 32 位进程里。由于 WinSW 最终会用 CreateProcess 启动你指定的程序被启动的子进程架构并不需要和 WinSW 自身的架构一致。也就是说你用 WinSW-x64.exe 去启动一个 32 位的老程序在 64 位 Windows 上通常是没问题的因为子进程会走 WOW64 兼容层。真正需要关心架构的场景有两个。第一服务进程本身要访问系统资源。如果被包装的程序依赖了 32 位驱动、32 位 ODBC 驱动或某些只能在 32 位进程里加载的 DLL那么 WinSW 的架构可能会影响服务进程的“身份”。比如服务内要调用 32 位 COM 组件而 WinSW-x64 在 64 位进程中可能加载不到 32 位的进程内组件。这时候用 x86 版本反而更省事因为整个服务进程就是 32 位子进程也是 32 位环境变量和注册表重定向都按 32 位走。第二安装服务时的注册表映射。Windows 服务在注册服务时会把 ImagePath 写入注册表。如果你在 64 位系统上使用 WinSW-x86.exe路径会被重定向到 WOW64 节点这在某些安全软件或管理工具里会产生“服务明明存在但找不到 exe”的错觉。反过来如果你用 64 位版本路径写入常规节点管理工具识别更准确。我的一般选择是不确定的时候就上 x64因为现在主流系统都是 64 位且 WinSW 的 x64 版本兼容性更好。只有当被包装程序明确是 32 位且依赖 32 位系统组件时才换 x86 版本并且安装前先确认 exe 能独立双击运行再谈注册服务的事。2.2 sample-minimal.xml 到底在配置什么最小配置逐字段解读sample-minimal.xml 是 WinSW 自带的最小配置样例文件名里的 minimal 说明它只包含注册一个服务所需的最少字段。常见做法是把它复制一份改成和你服务的名字一致比如 MyApp.xml然后让 MyApp.exe 在同一个目录下运行这样 WinSW 会自动读取同名的 XML 文件。一份最小的 sample-minimal.xml 大致长这样service idMyApp/id nameMyApp Service/name descriptionThis runs MyApp as a Windows service./description executablejava/executable arguments-jar C:\apps\MyApp\MyApp.jar/arguments startmodeAutomatic/startmode /service逐字段说明下id 是服务唯一标识注册进 SCM 后sc.exe 和 services.msc 里显示的是这个值它一旦确定最好别改因为服务注册表项、日志文件命名都会引用它。name 是服务显示名称可以更友好但不要和系统已有的服务重名。description 是服务描述写清楚这个服务干什么用避免以后接手的人靠猜。executable 是要运行的程序路径可以是绝对路径也可以是程序名如果是相对路径WinSW 会基于 XML 所在目录解析。arguments 是传给程序的命令行参数注意如果参数里包含空格或引号要用 XML 实体转义这个坑后面会专门说。startmode 控制启动方式。Automatic 表示开机自启Manual 表示手动Delayed 是延迟启动。最小配置里一般用 Automatic但如果这个服务依赖网络或数据库建议改成 Delayed让系统先完成其他初始化。另外有个很容易忽略的点sample-minimal.xml 默认不包含 workingdirectory。很多时候服务能启动但程序找不到当前目录下的配置文件就是因为服务进程的默认工作目录是 system32而不是你的 exe 所在目录。为了减少后续麻烦我在最小配置里通常立刻补上 workingdirectory把它指向程序所在目录。2.3 选型建议什么时候只改 xml什么时候要动 exeWinSW 的使用模式很简单一个 exe 加一个同名 xml。你想添加一个新服务不需要重新编译任何东西复制一份 WinSW-x64.exe改成 MyService.exe再写一份 MyService.xmlinstall 一下就好。这个模式非常适合批量管理内部工具。需要真正换 exe 的只有两种时候。第一种是平台原因被包装的程序有明确位数要求且和 WinSW 位数严重冲突导致服务拉起失败第二种是版本升级新版本的 WinSW 修复了日志滚动或失败重启的逻辑你希望整体换掉包装器。版本升级时注意先停止服务再替换 exe替换后重新 install 一次否则 SCM 里记录的 ImagePath 可能还指向旧文件。我在实际项目里见过不少团队把 sample-minimal.xml 原封不动地用起来结果程序起不来然后开始怀疑 WinSW 是不是坏了。其实大部分问题不是 WinSW 的问题而是最小配置缺少了 workingdirectory、日志目录和环境变量。先把最小配置跑通再一步步加字段是成本最低的路径。3. 用 sample-minimal.xml 把程序注册成系统服务操作步骤与命令3.1 安装服务前的目录整理与文件命名约定拿到 WinSW-x64.exe 之后最忌讳的就是把它丢在桌面或者下载目录直接执行。服务安装后SCM 会记住 ImagePath 的绝对路径如果目录后来被移动、改名、清理服务就会处于“找不到文件”的状态。常见的规范做法是给每个服务建立独立目录例如 C:\Services\MyApp目录下放这几个文件MyApp.exe即 WinSW-x64.exe 重命名后的包装器MyApp.xml即 sample-minimal.xml 修改后的配置MyApp.jar 或其他业务程序以及它依赖的配置文件命名保持一致非常关键。WinSW 的默认行为是加载与自身 exe 同名的 xml。如果 exe 叫 MyApp.exeXML 必须叫 MyApp.xml否则安装时 WinSW 会报找不到配置文件。如果你真的要把配置改成别的名字可以通过命令参数指定但大多数场景没必要保持默认即是正确姿势。目录权限上服务如果以内置 LocalSystem 运行要确保这个目录对 SYSTEM 账户至少具备读取和执行权限最好也让 SYSTEM 有写入权限方便日志输出。3.2 注册服务、启动服务、查看状态完整命令当目录准备好、xml 配置正确后注册服务只需要一条命令。假设当前目录是 C:\Services\MyApp那么打开管理员命令行注意一定是管理员权限否则 CreateService 会报拒绝访问执行cd C:\Services\MyApp MyApp.exe installinstall 命令会把服务注册进 SCM并且按照 xml 里的 startmode 设置启动策略。注册成功的输出一般会显示相关配置信息如果出现权限错误检查是否以管理员身份运行命令行。随后可以通过 sc.exe 查看服务状态sc.exe query MyApp如果状态显示 STOPPED可以用下面的命令把服务启动起来MyApp.exe startstart 走后端启动命令本身会很快返回但服务的实际启动过程是异步的。所以更好的检查方式是用 sc.exe query 多看几次或者用 PowerShell 的 Get-ServiceGet-Service -Name MyApp注意这里的 Name 对应 xml 里的 id不是显示名称。状态变成 Running 后再用任务管理器或 tasklist 确认业务进程真的起来了因为 WinSW 报告 Running 只表示它把子进程拉起来了不代表子进程一直在跑。如果业务进程秒退服务状态会在一瞬间变回 Stopped这种情况需要查业务日志。考虑一个特殊情况如果服务名在系统里已存在install 会报错误。这时要么先卸载旧服务要么改 xml 里的 id不要硬来。我一般在 install 前先跑一下 query确认服务不存在再执行安装省得系统提示“服务已经存在”。3.3 卸载服务与更新程序先删还是先停卸载服务同样不需要手动去注册表里删用 WinSW 自带的 uninstall 命令即可MyApp.exe uninstall不过 uninstall 有一个前置条件服务最好处于已停止状态。否则 SCM 会因为服务正在运行而拒绝删除或者删除过程出现异常。稳妥的顺序是MyApp.exe stop MyApp.exe uninstall如果你要更新业务程序而不是卸载服务顺序反过来先 stop再替换业务 exe最后 start。很多人图省事直接替换文件结果 Windows 提示“文件正被另一进程使用”这是因为被 WinSW 拉起的子进程还在运行句柄没释放。杀掉进程再替换是一个办法但不如用 WinSW 的 stop 命令来得干净因为 stop 会通知 SCM 正常终止服务给程序留出清理资源的机会。这里要特别提醒如果你的服务里配置了 onfailure 自动重启而你又手动停了服务SCM 不会自动再次拉起这个逻辑是安全的。但如果程序自己崩溃WinSW 的失败恢复会重新启动服务这时你替换文件很可能替换到一半就被重启的进程锁住。所以更新程序前先把失败恢复配置临时调整或直接停服务是很多老手会做的保护动作。等替换完成再恢复配置并启动。4. 把 sample-minimal.xml 扩展成可用配置日志、失败处理与环境变量4.1 日志怎么落盘并做滚动log 相关配置sample-minimal.xml 不配置日志时被包装程序的标准输出和错误流默认会丢到黑洞里程序里如果自己写文件另说但那些只往 stdout 打内容的程序出了问题只能看到服务状态异常看不到任何线索。所以在 sample-minimal.xml 基础上我第一步就是加 logmode 和 logpath。log moderoll-by-time pathC:\Services\MyApp\logs/path patternyyyy-MM-dd/pattern autoRollAtTime00:00:00/autoRollAtTime zipOlderThan7/zipOlderThan /log这段配置的含义是把服务进程的 stdout/stderr 写到 C:\Services\MyApp\logs 目录下每天零点滚动一次日志文件按日期命名超过 7 天的日志自动压缩成 zip。这里的 log 是整个 WinSW 服务的日志它捕获的是业务程序输出到标准输出和标准错误的内容。如果你的业务程序写的是自己的日志文件这边可以不配但大多数运维场景下stdout 日志依然是排查问题最快的入口。pattern 语法和 Java 的 SimpleDateFormat 一致yyy-MM-dd 会生成类似 2025-01-15.log 的文件名。autoRollAtTime 是固定时间点滚动适合需要按天归档的场景。如果希望按大小滚动把 mode 改成 roll-by-size再设置 sizeThreshold 和 rolloverSize。这两种模式各有适用场景按天滚动适合日志量稳定的服务按大小滚动适合一旦出问题日志就暴涨的服务因为大文件排查起来非常痛苦。配置完日志后服务一旦启动就能在 logs 目录下看到实时日志文件。这个文件同时也是判断服务是否真的在工作的证据如果文件为空进程多半没产生输出如果文件在持续增长而服务状态又是 Running那问题基本出在程序逻辑内部而不是 WinSW 层面。4.2 程序崩了怎么办onfailure 与 delayedAutoStart服务长期跑在后台最怕的就是进程崩了没人发现。Windows 服务管理器本身有恢复选项WinSW 通过 onfailure 字段暴露这个能力。一个比较稳妥的配置是这样onfailure actionrestart delay5 sec/ onfailure actionrestart delay10 sec/ onfailure actionnone delay1 min/ resetfailure1 day/resetfailure这段配置的意思是第一次失败后等 5 秒重启第二次失败后等 10 秒再重启第三次失败就不再自动重启并把失败计数重置周期设为 1 天。这样即避免了服务在故障点反复横跳导致日志刷屏也防止了程序一直崩溃时机器上到处都是僵尸进程。action 除了 restart 还可以是 reboot 或 nonereboot 会让服务器重启一般慎用。delay 的时间单位可以是秒sec或分钟min。另一个和生产环境关系很大的字段是 delayedAutoStart。如果服务依赖网络、数据库或另一个服务开机自启时很容易因为依赖没就绪而启动失败。配合 onfailure 重启虽然能救但不如直接让服务延迟启动startmodeAutomatic/startmode delayedAutoStarttrue/delayedAutoStartdelayedAutoStart 会让服务在系统启动后延迟约 2 分钟才启动给网络和数据库留出时间。要注意的是不是所有系统都支持 Delayed AutoStart 属性Windows Server 2012 及以后的系统基本都没问题老系统如果忽略该属性SCM 会按普通 Automatic 处理这点不用太担心。4.3 环境变量和当前目录两个最容易让程序起不来的配置我接手过很多“服务安装成功但就是起不来”的案例最后排查下来一大半是 workingdirectory 没设置一小半是环境变量缺失。Windows 服务进程的工作目录默认是 C:\Windows\System32而你的程序里写的是相对路径比如 config.ini 或 logs/程序启动后自然找不到文件直接抛异常退出。workingdirectoryC:\Services\MyApp/workingdirectory这个字段没有默认值sample-minimal.xml 里也不存在所以必须你自己加。它决定了子进程创建时的当前目录也就是程序里那个“.”指向哪里。很多 Java 程序和 Node 程序在启动时依赖相对路径这个配置是救命级别的。环境变量的配置也很直接env nameJAVA_HOME valueC:\Program Files\Java\jdk-17 / env nameAPP_MODE valueproduction /env 标签可以写多条它们在服务启动时被放进子进程的环境块。这里有两个容易踩的坑。第一个是 env 值如果包含空格或特殊字符不需要转义因为这是 XML 属性不是命令行第二个是 PATH 变量如果你需要追加而不是覆盖尽量在 xml 里写完整值因为 WinSW 追加 PATH 的语法在某些版本有点区别我见过有人配了之后把系统 PATH 搞丢服务直接起不来。如果你不确定程序到底缺什么环境变量一个笨但有效的方法是在日志配置打开的情况下先不注册服务直接使用 WinSW 的控制台命令或者用 sc.exe 创建服务后手动启动再对比日志里的报错。实在不行就在配置里临时加上一条写日志的 env让程序自己打印出来但更推荐优先排查 workingdirectory 和 JAVA_HOME 这类高频变量。5. WinSW 使用中的避坑清单5 个真实翻车现场5.1 “服务已启动但进程立刻退出”的真相现象install、start 都执行成功sc query 显示服务状态为 Running但任务管理器里找不到业务进程服务状态几秒后又变成 Stopped。原因WinSW 报告 Running 只是启动子进程成功子进程启动后立刻崩溃退出SCM 收到进程退出通知后把服务状态改成 Stopped。最常见的原因是缺少 workingdirectory程序找不到相对路径下的配置或目录。解决在 xml 中补上 workingdirectory指向程序所在目录。还要检查 arguments 中是否引用了不存在的文件路径。日志配置务必先打开崩溃原因会直接打到 out.log 或 err.log比瞎猜高效得多。这类问题占我遇到的 WinSW 问题的一半以上属于第一优先级的排查项。5.2 x64/x86 选错导致的 Access Denied现象服务安装没问题启动时报“服务无法启动”或“Access Denied”事件查看器里出现 WinSW 相关错误。原因不是所有 Access Denied 都和权限有关当 WinSW 架构和系统不匹配时会触发文件系统重定向问题。比如 32 位 WinSW 在 64 位系统上访问 C:\Windows\System32 会被重定向到 SysWOW64导致它找不到配置里指定的 executable。解决把 WinSW-x64.exe 作为默认选择只有明确需要 32 位进程身份时才使用 WinSW-x86.exe。如果在 64 位系统上一定要用 x86 版executable 的路径尽量指定完整且明确的路径并且确认该路径下的 exe 确实是 32 位可运行。另一个办法是用 Process Monitor 监控服务启动时实际访问的路径一抓一个准。5.3 路径带空格XML 里的坑现象executable 路径或 arguments 中含有空格比如 C:\Program Files\MyApp\run.exe服务启动失败或在日志中看到命令行被截断。原因XML 里对空格没有特殊要求但 WinSW 最终会把配置拼成命令行去 CreateProcess如果 executable 和 arguments 没有正确的引号包裹系统会把路径在第一个空格处截断。具体表现是 Configure 正常启动时找不到程序。解决在 xml 中给路径加引号时需要小心 XML 转义。直接写双引号是常见的写法executableC:\Program Files\MyApp\run.exe/executable但我更推荐使用 Windows 短路径或者在 arguments 中对包含空格的参数使用 XML 实体arguments-jar quot;C:\Program Files\MyApp\app.jarquot;/arguments注意executable 里的引号如果写不进属性值可以直接放在元素文本中间。养成“参数里带空格就加引号”的习惯能避开一大半启动失败。另外路径分割符前后不要写多余空格我曾经见过某同事在 arguments 里多打了一个空格导致传参错位程序报参数解析异常。5.4 权限问题LocalSystem 与网络驱动器的矛盾现象服务用默认的 LocalSystem 账户运行配置里 executable 指向映射的网络驱动器 Z:\shared\app.exe启动失败日志提示网络路径找不到。原因映射驱动器是用户会话级别的状态LocalSystem 账户运行的服务位于会话 0它根本看不到你登录用户手动映射的驱动器。服务以 LocalSystem 访问网络共享时应该使用 UNC 路径而不是盘符。解决将 executable 和 workingdirectory 都改成 \server\share\app 的 UNC 格式。同时要注意访问网络共享同样需要身份验证LocalSystem 在跨机器访问时用的是计算机账户如果共享目录没有给计算机账户授权依然会 Access Denied。更常见的做法是给服务单独配置一个域账户或本地账户并在共享目录上授予该账户读写权限。如果你不确定账户权限怎么配先在命令行下使用同样账户跑一次业务程序确认能访问网络路径后再注册服务。5.5 更新替换 exe 时服务启动失败现象业务版本升级停掉服务、替换 exe、重新启动结果服务启动失败事件日志显示路径找不到或文件被占用。原因很多团队直接在服务正在运行的时候替换文件Windows 对正在运行的可执行文件有文件锁替换其实没有真正生效。另一种情况是服务 exe 被替换成临时文件后再改回文件的 ACL 继承了临时目录的权限导致服务的执行账户没有权限访问。解决严格遵循“stop - 替换 - start”的顺序。替换后如果仍失败检查文件属性和 ACL确认 SYSTEM 或服务账户有“读取和执行”权限。如果替换过 exe 的路径或文件名需要重新运行 install 来刷新 SCM 中的 ImagePath不能只做文件替换。还有一个隐蔽点WinSW 的 executable 如果写的是相对路径替换目录后 XML 里的相对位置会变启动会失败。所以配置里尽量使用绝对路径千万别留相对路径的隐患。6. 让服务不再成为黑匣子用日志和恢复策略做收尾验证服务注册好之后我最常被问的问题不是“怎么装服务”而是“我怎么知道它现在还好用”。这里提供一个最小但完整的验证闭环。先用事件查看器确认服务生命周期打开 Windows 日志 - 系统过滤来源为 Service Control Manager能看到服务的启动和停止记录。如果服务曾经崩溃这里会有错误 ID 7031、7034旁边会注明失败次数。更直接的是用命令行工具sc.exe queryex MyAppqueryex 能看到服务进程 PID拿这个 PID 去 tasklist 确认进程存在。如果希望更自动化可以写个小 PowerShell 检查服务状态异常时触发邮件或 webhook但这已经超出今天的范围。日志验证方面我强烈建议每个服务都做一次“杀掉进程看它会不会自己复活的测试”。找到业务程序的 PID用 taskkill /F 强制终止然后观察 10 秒内 WinSW 是否按 onfailure 配置自动拉起。如果自动重启没有发生失败恢复配置多半有问题要么没生效要么 restartDelay 设太长。这种测试最好在非业务高峰期做尽量避免影响线上数据。我个人的习惯是每次更新配置后先用 sc.exe stop 再 start 一次然后立刻查看日志时间戳确认日志文件在对应时间段有新内容。接着再用 tasklist 对照 PID确认新旧进程不是同一个残留进程。这一套流程跑下来WinSW 相关的“黑匣子”基本就打开了。从 2018 年第一次用 WinSW 到现在它一直是我在 Windows 服务器上以最小成本把程序变成正规服务的首选方案只要把 sample-minimal.xml 那几个关键字段补齐服务稳定性不会比你手写 ServiceBase 差。希望这些踩坑记录能帮你在用 winsw 注册系统服务时少走几趟弯路。本文还有配套的精品资源点击获取
