太阳当空照-Windows服务化方式Winsw基本配置

参考链接：https://github.com/winsw/winsw/blob/v3/docs/xml-config-file.md

依据官网，包含以下几个部分：

文件结构

service

文件根节点必须为<service></service>，该根节点下，包含对应的子节点内容配置

<service><id></id><description></description><env name="" value=""/><excutable></excutable><arguments></arguments><log mode="roll"></log>
</service>

环境变量

env

能够提取name中对应的系统环境变量值，设置到对应的本地内置value变量中，如果环境变量不存在，则本地变量将不会发生替换，当前自定义变量名称为Winsw.exe程序自动去生成，在当前同级节点中可以使用，也可以在服务启动的子进程中使用

.....
<env name="环境变量名称" value="%本地自定义变量名称%"/>
.....

示例：

.....
<env name="JAVA_HOME" value="%Base%"/>
<excutable>java %Base%/xxx.jar</excutable>
.....

相对路径和默认路径

workingdirectory

相对路径能够被工作路径覆盖，同时，默认情况下，默认路径是对应目标子程序加载的配置文件appname.xml的所在路径

.......
<workingdirectory>相对路径/绝对路径</workingdirectory>
.......

示例：

.......
<workingdirectory>E:\Study\Servers\winswtest</workingdirectory>
.......

配置实体节点

id

必须配置项，设定Windows内部用于识别改服务的id，作为唯一值，必须在系统服务中唯一，由字母和数字组成

......
<id></id>
......

executable

必须配置项，用于设定可执行文件或者需要执行的指令配置，路径和Winsw.exe可能不一致

......
<executable></executable>
......

name

服务显示名称的简写，可以添加其他的字符，名称不宜太长，如id一般是需要当前服务系统中保持唯一

......
<name></name>
......

description

服务具体描述，可以添加其他字符，当服务被选择时，能够在Windows服务管理中显示出来

.....
<description></description>
.....

startmode

设置服务的启动模式，包含常用包含如下值：

Automatic，Manual，Disabled

其他查阅[官方地址]https://docs.microsoft.com/en-us/windows/win32/cimwin32prov/changestartmode-method-in-class-win32-service，默认为Automatic

....
<startmode>Automatic</startmode>
....

delayedAutoStart

如果服务启动方式为自启方式，设置是否延时启动服务程序

<delayedAutoStart>true</delayedAutoStart>

该配置对Windows 7以前老版本以及Windows Server 2008及其以前的系统版本无效，可能会因为该配置，造成服务无法安装

depend

当前注册服务依赖其他的服务时，需要设定对应的其他服务id配置

......
<depend>X</depend>
......

如果存在多个依赖，则配置多个依赖的相关服务id

.....
<depend>X</depend>
<depend>Y</depend>
.....

日志操作

logpath

用于设置日志的输出路径，默认情况为日志输出路径与配置文件.xml加载所在路径目录相同

.....
<logpath>path</logpath>
.....

Append mode (default)

附加模式，为默认服务执行模式，日志会以复加方式添加到对应日志文件内容中

.....
<log mode="append"/>
.....

Reset mode

重置模式，当前模式下，日志输出方式与append类似，当时在每次服务重启后，服务将截断当前旧日志，

.....
<log mode="reset"/>
.....

Ignore mode

该模式下，忽略掉运行输出和运行错误，不做任何日志记录

.....
<log mode="ignore"/>
.....

Roll mode

工作原理与附加模式类似，通过配置设置的单日志文件大小，超出限制后，自动对停止满足单文件限制的日志文件写入，在新的日志文件中写入日志信息，文件一次一滚动方式进行日志文件名称设定和自增，例如，一个日志文件第一个叫roll.1.log，当超过单文件设定大小后，会关闭roll.1.log，向新的roll.2.log日志中写入日志内容

.....
<log mode="roll-by-size"><sizeThreshold>102400</sizeThreshold><keepFiles>8</keepFiles>
</log>
.....

其中sizeThreshold单文件大小阀值，以kb作为最小单位，keepFiles保留历史日志文件数目

Roll by time mode

运行原理类似Roll模式，但是不再是以单文件大小作为阀值，而是以时间段作为阀值，

.......
<log mode="roll-by-time"><pattern>yyyyMMdd</pattern>
</log>
.......

pattern作为正则方式控制，对应输出文件的日志文件名称

Roll by size and time mode

同时设置时间段阀值和单文件大小阀值，保证在目标时间段范围内限制单文件大小，实现日志文件的生成和日志记录

.......
<log mode="roll-by-size-time"><sizeThreshold>10240</sizeThreshold><pattern>yyyyMMdd</pattern><autoRollAtTime>00:00:00</autoRollAtTime>
</log>
.......

autoRollAtTime设置在00:00:00自动生成新的日志文件

Automatic archiving of logs

日志自动存档功能，最近版本已经弃用，未来可能会去掉该功能

.......
<log mode="roll-by-size-time"><zipOlderThanNumDays>5</zipOlderThanNumDays><zipDateFormat>yyyyMM</zipDateFormat>
</log>
.......

zipOlderThanNumDays历史天数压缩保留的阀值天数，仅仅能够用于自动滚动时间模式的日志配置

........
<log mode="roll-by-size-time"><autoRollAtTime>00:00:00</autoRollAtTime><zipOlderThanNumDays>5</zipOlderThanNumDays>
</log>
........

zipDateFormat历史压缩文件命名格式，仅仅能够用于自动滚动时间模式的日志配置

.....
<log mode="roll-by-size-time"><autoRollAtTime>00:00:00</autoRollAtTime><zipDateFormat>yyyyMM</zipDateFormat>
</log>
.....

Error reporting

程序运行出现异常时，输出的错误编码，对应的错误清单，可以参考[微软文档]https://docs.microsoft.com/windows/win32/debug/system-error-codes

参数

arguments

参数传入节点，用于设定在服务子程序执行时需要传入的参数

.....
<arguments>arg1 arg2 arg3</arguments>
.....

或者

.....
<arguments>arg1arg2arg3
</arguments>
.....

executable/startarguments

执行程序和启动带有的参数内容，startarguments用于替代arguments，用于服务启动进行特定参数的设置和服务的启动

....
<executable>command01</executable>
<startarguments></startarguments>
....

stopexecutable/stoparguments

停止执行和停止时带有的参数内容，stoparguments用于替代arguments，用于停止服务时特定的停止参数设置和服务的停止

....
<stopexecutable>command01</stopexecutable>
<stoparguments></stoparguments>
....

其他指令

prestart

在当前服务执行之前需要执行的指令和相关参数，实际配置结构与服务启动和停止一致

<prestart><executable></executable><arguments></arguments><stdoutPath></stdoutPath><stderrPath></stderrPath>
</prestart>

stdoutPath设定当前部分执行指令的输出目录路径

stderrPath设定当前部分异常信息输出目录路径

poststart

在当前服务开始之后，执行的相关部分，处理相关逻辑

<poststart><!-- ... -->
</poststart>

prestop

在当前服务停止之前执行的指令和相关参数，实际配置结构与服务启动和停止一致

<prestop><!-- ... -->
</prestop>

poststop

在当前服务主进程停止之后，执行相关部分，处理相关逻辑

<prestop><!-- ... -->
</prestop>

当给stdoutPath和stderrPath设置为null值时，相关输出仅仅会以流的形式保存在运行内存中

Preshutdown

当服务进行停止时，给予服务更多的时间，进行服务服务停止操作

<preshutdown>false</preshutdown>
<preshutdownTimeout>3 min</preshutdown>

preshutdown是否开启预停止操作，默认为false

preshutdownTimeout预停止超时时间，默认为分钟

stoptimeout

When the service is requested to stop, winsw first attempts to send a Ctrl+C signal to a console application, or post a close message to a Windows application, then wait for up to 15 seconds for the process to exit by itself gracefully. If the timeout expires or the signal or message can’t be sent, then winsw resorts to terminate the service instantly

原文以个人理解翻译出来就是，当服务执行停止操作时，Winsw第一次尝试执行Ctrl+C到控制台应用或发送关闭消息到Windows应用，等待15秒流程的正常退出，如果超时无响应或无法发送消息，Winsw会立即终止服务操作

<stoptimeout>10sec</stoptimeout>

环境配置

Environment

如果服务进程有必要的话，可以多次指定环境变量的变量值

<env name="HOME" value="C:\Test"/>

interactive

可选配置，在有需要该服务需要和Windows桌面进行交互时，服务包含GUI可视化界面，添加当前配置节点，设置为true

<interactive>true</interactive>

beeponshutdown

可选项，该配置作为允许调试期间使用，笔者没弄明白配置用途，不建议在项目中使用，可能出现硬件和系统的不支持

<beeponshutdown>true</beeponshutdown>

download

用于在执行过程中，执行资源链接的下载相关操作以及下载之后对资源的加载和执行

<download from="http://example.com/some.dat" to="%BASE%\some.dat" />

对于需要认证才能访问的资源，可以使用属性auth，none为默认值，sspi作为需要通过Windows提供的安全认证机制，包括Kerberos、NTML等，basic主要为登录用户名和密码实现远程访问

<download from="https://example.com/some.dat" to="%BASE%\some.dat" auth="none" />
<download from="https://example.com/some.dat" to="%BASE%\some.dat" auth="sspi" />
<download from="https://example.com/some.dat" to="%BASE%\some.dat" failOnError="true"auth="basic" user="aUser" password="aPassw0rd" />
<download from="http://example.com/some.dat" to="%BASE%\some.dat"proxy="http://aUser:aPassw0rd@192.168.1.5:80/"auth="basic" unsecureAuth="true"user="aUser" password="aPassw0rd" />

download同时支持代理proxy下载，可以多次进行设置

log

查阅当前文章日志操作部分内容

onfailure

可选参数，可以多次设定用于控制服务启动失败时的行为，属性action包含none默认值无任何操作，restart重启服务，reboot重启系统，并且出现蓝屏/绿屏重启画面，并显示CRITICAL_PROCESS_DIED错误检查代码

<onfailure action="restart" delay="10 sec"/>
<onfailure action="restart" delay="20 sec"/>
<onfailure action="reboot" />

resetfailure

可选配置，可以控制当前服务在Windows中重置故障计数器的时间，持续正常运行时间操作重置故障技术时间时，故障计数器将重置故障次数，默认值为1天

<resetfailure>1 hour</resetfailure>
<resetfailure>1 day</resetfailure>

安全描述

遵循SDDL 格式的服务安全描述字符串

[参考链接]https://docs.microsoft.com/windows/win32/secauthz/security-descriptor-definition-language

<securityDescriptor></securityDescriptor>

Service account

服务默认以本地系统账户进行安装，如果对权限要求不高，可以考虑本地系统用户、网络服务账户和普通用户帐户

<serviceaccount><username>DomainName\UserName</username><password>Password</password><allowservicelogon>true</allowservicelogon>
</serviceaccount>

username中，如果当前用户属于内置域，可以直接使用.\UserName进行用户的账户设置，普通账户一般为DomainName\UserName或DomainName@UserName

allowservicelogon可选参数，设置为true时，将自动将选中将当前账户设置为所选服务登录账户

LocalSystem account

设置服务运行账户为本地系统账户

<serviceaccount><username>LocalSystem</username>
</serviceaccount>

LocalService account

设置服务运行账户为本地服务账户

<serviceaccount><username>NT AUTHORITY\LocalService</username>
</serviceaccount>

NetworkService account

设置服务运行账户为网络服务账户

<serviceaccount><username>NT AUTHORITY\NetworkService</username>
</serviceaccount>

prompt

可选操作，设置用户名用户密码输入提示

<serviceaccount><prompt>dialog|console</prompt>
</serviceaccount>

dialog弹出对话框提示

console控制台提示

Working directory

设置服务进程执行时的执行目录，查看本章中的相对路径和默认路径描述

Priority

可选项，设置服务调度的优先等级，可用值为：idle, belownormal, normal, abovenormal, high, realtime

<priority>idle</priority>

相关[参考链接]https://docs.microsoft.com/dotnet/api/system.diagnostics.processpriorityclass

Auto refresh

可选项，是否设置服务在执行start、stop、restart操作时，自动刷新服务状态，默认为true

<autorefresh>true</autorefresh>

sharedDirectoryMapping

可选设置，默认情况下，Windows不会为服务创建共享目录映射，有时候，即使是已经配置了对应的映射，也可能由于域策略被屏蔽，以下是在执行服务之前，配置共享目录的映射操作配置

<shareDirectoryMapping><map label="N:" uncpath="\\UNC" />
</shareDirectoryMapping>

以上为基于Winsw官方说明文件内容进行的翻译和个人理解的各类配置的基本说明