参考链接: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>
arg1
arg2
arg3
</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 官方说明文件内容进行的翻译和个人理解的各类配置的基本说明
|