WinSW XML 配置参数介绍

文章目录

• • [1. 基本信息](#1. 基本信息)
  • [2. 启动命令](#2. 启动命令)
  • [3. 停止命令](#3. 停止命令)
  • [4. 日志配置](#4. 日志配置)
  • • 日志配置示例
  • [5. 环境变量](#5. 环境变量)
  • [6. 启动模式](#6. 启动模式)
  • [7. 失败恢复](#7. 失败恢复)
  • [8. 服务依赖](#8. 服务依赖)
  • [9. 进程优先级](#9. 进程优先级)
  • [10. 运行账户](#10. 运行账户)
  • [11. 高级功能](#11. 高级功能)
  • 完整配置示例
  • 注意事项
  • 参考资料

WinSW（Windows Service Wrapper）是一个开源工具，用于将任意可执行文件（exe、jar、bat 等）包装成 Windows 服务。配置文件为 XML 格式（通常命名为 your-service.xml），所有参数都在 <service> 根节点下（注意：不是 <configuration>）。

以下是 WinSW 3.x 版本的完整参数列表，按功能分类整理。

---

1. 基本信息

参数	类型	必填	默认值	说明	示例
<id>	字符串	✅	无	服务唯一标识符（用于 sc.exe 和注册表）	<id>myapp</id>
<name>	字符串	✅	无	服务显示名称（在服务管理器中显示）	<name>My Spring Boot App</name>
<description>	字符串	❌	空	服务描述信息	<description>xx管理系统</description>

---

2. 启动命令

参数	类型	必填	默认值	说明	示例
<executable>	字符串	✅	无	要运行的可执行文件路径（支持环境变量）	<executable>java.exe</executable>
<arguments>	字符串	❌	空	传递给可执行文件的参数	<arguments>-jar app.jar --port=8080</arguments>
<workingdirectory>	路径	❌	%BASE%	工作目录（服务启动时的当前目录）	<workingdirectory>C:\myapp</workingdirectory>
<startarguments>	字符串	❌	同 <arguments>	启动时的额外参数（一般不用）	<startarguments>--debug</startarguments>

---

3. 停止命令

参数	类型	必填	默认值	说明	示例
<stopexecutable>	字符串	❌	无	停止服务时执行的程序（可选）	<stopexecutable>cmd</stopexecutable>
<stoparguments>	字符串	❌	空	停止程序的参数	<stoparguments>/c stop.bat</stoparguments>
<stoptimeout>	时间	❌	15 sec	停止超时时间（超时后强制终止）	<stoptimeout>30 sec</stoptimeout>

---

4. 日志配置

参数	类型	默认值	说明	示例
<logmode>	字符串	rotate	日志模式： • none - 完全禁用文件日志（stdout/stderr 被丢弃）⚠️ • append - 追加到单个日志文件 • rotate - 按大小滚动（推荐） • roll-by-size - 同 rotate • roll-by-time - 按时间滚动	<logmode>rotate</logmode>
<logpath>	路径	%BASE%\logs	日志文件保存路径	<logpath>C:\logs</logpath>
<log>	块元素	无	新版日志配置（推荐）	见下方示例

日志配置示例

<!-- 推荐：按大小滚动 -->
<log mode="roll-by-size">
  <sizeThreshold>10240</sizeThreshold>  <!-- 单位：KB，10MB -->
  <keepFiles>8</keepFiles>               <!-- 保留 8 个历史文件 -->
</log>

<!-- 按时间滚动 -->
<log mode="roll-by-time">
  <period>1</period>           <!-- 滚动周期（天） -->
  <pattern>yyyy-MM-dd</pattern> <!-- 日志文件名日期格式 -->
</log>

<!-- 完全禁用（不推荐用于生产环境） -->
<log mode="none"/>

⚠️ 关于 <logmode>none</logmode>：

• 会丢弃所有输出，无法排查问题
• 适用于无需调试的稳定服务 或程序自带日志功能
• 生产环境建议使用 roll-by-size 并合理设置保留文件数

---

5. 环境变量

参数	类型	说明	示例
<env>	块元素	设置环境变量（可配置多个）	<env name="JAVA_HOME" value="C:\jdk"/>

<env name="PATH" value="%PATH%;C:\tools"/>
<env name="SPRING_PROFILES_ACTIVE" value="prod"/>

---

6. 启动模式

参数	类型	默认值	说明	示例
<startmode>	字符串	Automatic	服务启动类型： • Automatic - 自动启动 • Manual - 手动启动 • Disabled - 禁用	<startmode>Automatic</startmode>
<delayedAutoStart>	布尔	false	是否延迟自动启动（减少启动冲突）	<delayedAutoStart>true</delayedAutoStart>

---

7. 失败恢复

参数	类型	说明	示例
<onfailure>	块元素	服务失败时的动作（新版语法，可多个）	见下方示例

<!-- 第1次失败：10秒后重启 -->
<onfailure action="restart" delay="10 sec"/>
<!-- 第2次失败：30秒后重启 -->
<onfailure action="restart" delay="30 sec"/>
<!-- 第3次及以后：不处理 -->
<onfailure action="none"/>

可用的 action 值：

• restart - 重启服务
• reboot - 重启计算机
• none - 不处理

---

8. 服务依赖

参数	类型	说明	示例
<depend>	字符串	依赖的其他服务（逗号分隔）	<depend>MySQL80,Redis</depend>

---

9. 进程优先级

参数	类型	默认值	说明	示例
<priority>	字符串	Normal	进程优先级： • Idle • BelowNormal • Normal • AboveNormal • High • Realtime（不推荐）	<priority>High</priority>

---

10. 运行账户

参数	类型	说明	示例
<serviceaccount>	块元素	指定服务运行的账户（推荐）	见下方示例

<!-- 使用本地系统账户 -->
<serviceaccount>
  <domain>NT AUTHORITY</domain>
  <user>LocalService</user>
</serviceaccount>

<!-- 使用指定用户 -->
<serviceaccount>
  <domain>.</domain>
  <user>Administrator</user>
  <password>yourpassword</password>
  <allowservicelogon>true</allowservicelogon>
</serviceaccount>

---

11. 高级功能

参数	类型	说明	示例
<download>	块元素	启动前从 URL 下载文件	<download from="https://example.com/app.jar" to="app.jar"/>
<resetfailure>	时间	失败计数器重置时间	<resetfailure>1 day</resetfailure>

---

完整配置示例

<service>
  <!-- 基本信息 -->
  <id>myapp</id>
  <name>My Application</name>
  <description>Spring Boot 应用程序</description>
  
  <!-- 启动命令 -->
  <executable>java</executable>
  <arguments>-Xms512m -Xmx1024m -jar app.jar</arguments>
  <workingdirectory>C:\myapp</workingdirectory>
  
  <!-- 停止配置 -->
  <stoptimeout>30 sec</stoptimeout>
  
  <!-- 日志 -->
  <log mode="roll-by-size">
    <sizeThreshold>10240</sizeThreshold>
    <keepFiles>8</keepFiles>
  </log>
  
  <!-- 环境变量 -->
  <env name="JAVA_HOME" value="C:\jdk"/>
  
  <!-- 启动模式 -->
  <startmode>Automatic</startmode>
  <delayedAutoStart>true</delayedAutoStart>
  
  <!-- 失败恢复 -->
  <onfailure action="restart" delay="10 sec"/>
  <onfailure action="restart" delay="30 sec"/>
  <resetfailure>1 day</resetfailure>
  
  <!-- 依赖 -->
  <depend>MySQL80</depend>
  
  <!-- 优先级 -->
  <priority>Normal</priority>
</service>

---

注意事项

1. 根节点是 <service>，不是 <configuration>
2. 路径支持环境变量 ：%BASE% 指向 exe 所在目录
3. 时间单位 ：sec、min、hour、day
4. 大小单位：KB（千字节）
5. <logmode>none</logmode> 慎用：生产环境建议保留日志便于排查问题

---

参考资料

• WinSW 官方文档
• XML 配置参考