基于Python的Windows服务安装后无法启动的问题排查

问题场景 #

• 基于Python开发Windows服务，从参考页面复制基础服务代码
• 使用PyInstaller将代码编译为单文件EXE
• 通过WiX工具制作MSI安装包，完成Windows 11服务安装
• 安装后服务始终处于STOPPED状态，无安装/启动阶段报错
• 事件查看器中出现错误：等待MyServiceTest服务连接超时（30000 ms）

错误原因 #

Windows服务控制管理器（SCM）在启动服务后，会等待服务进程主动发送启动成功的状态报告，超时时间默认30秒。如果Python服务代码未正确实现与SCM的状态交互逻辑，SCM无法收到启动确认信号，就会判定服务启动失败，最终标记为停止状态。

解决方案 #

1. 修正服务代码的SCM交互逻辑 #

必须在服务运行的核心方法中，向SCM报告服务已进入运行状态，同时完善停止时的状态通知。示例完整服务代码：

import win32serviceutil
import win32service
import win32event
import servicemanager
import time

class MyServiceTest(win32serviceutil.ServiceFramework):
    _svc_name_ = "MyServiceTest"
    _svc_display_name_ = "My Service Test"
    _svc_description_ = "Test Python Windows Service"

    def __init__(self, args):
        win32serviceutil.ServiceFramework.__init__(self, args)
        # 创建停止事件
        self.hWaitStop = win32event.CreateEvent(None, 0, 0, None)

    def SvcDoRun(self):
        # 向SCM报告服务已启动
        self.ReportServiceStatus(win32service.SERVICE_RUNNING)
        servicemanager.LogMsg(
            servicemanager.EVENTLOG_INFORMATION_TYPE,
            servicemanager.PYS_SERVICE_STARTED,
            (self._svc_name_, '')
        )
        # 服务业务逻辑示例
        while True:
            # 检查是否收到停止信号
            rc = win32event.WaitForSingleObject(self.hWaitStop, 1000)
            if rc == win32event.WAIT_OBJECT_0:
                break
            time.sleep(1)

    def SvcStop(self):
        # 报告服务即将停止
        self.ReportServiceStatus(win32service.SERVICE_STOP_PENDING)
        servicemanager.LogMsg(
            servicemanager.EVENTLOG_INFORMATION_TYPE,
            servicemanager.PYS_SERVICE_STOPPED,
            (self._svc_name_, '')
        )
        # 触发停止事件
        win32event.SetEvent(self.hWaitStop)
        # 报告服务已停止
        self.ReportServiceStatus(win32service.SERVICE_STOPPED)

if __name__ == '__main__':
    win32serviceutil.HandleCommandLine(MyServiceTest)

2. 修正PyInstaller打包参数 #

打包时必须添加--hidden-import win32timezone，避免缺失依赖导致服务初始化失败：

pyinstaller --onefile --hidden-import win32timezone --name MyServiceTest your_service.py

3. 验证WiX安装配置 #

确保WiX脚本中服务的启动类型、运行账户配置正确，示例关键配置片段：

<Component Id="ServiceComponent" Guid="YOUR-GUID-HERE">
    <File Id="ServiceExe" Source=".\dist\MyServiceTest.exe" KeyPath="yes" />
    <ServiceInstall
        Id="MyServiceTestInstaller"
        Name="MyServiceTest"
        DisplayName="My Service Test"
        Description="Test Python Windows Service"
        Start="auto"
        Account="LocalSystem"
        ErrorControl="normal"
        Type="ownProcess" />
    <ServiceControl
        Id="MyServiceTestControl"
        Name="MyServiceTest"
        Start="install"
        Stop="both"
        Remove="uninstall"
        Wait="yes" />
</Component>

内容的提问来源于stack exchange，提问作者Wason