將 Python 腳本註冊為 Windows 服務(自動啟動、後台運行、無用戶登錄)時,常需在服務內**啟動並管理子進程**(如 Web 服務器、工作進程、代理程序)。關鍵難點:
# 僅需 pywin32(含 win32service, win32event, win32api)
pip install pywin32
# Python 3.8+ 推薦
# windows_service.py
import win32serviceutil
import win32service
import win32event
import win32api
import win32process
import win32con
import servicemanager
import subprocess
import os
import sys
import json
import signal
import time
import atexit
from pathlib import Path
from typing import Optional, List
class PythonService(win32serviceutil.ServiceFramework):
_svc_name_ = "MyPythonService"
_svc_display_name_ = "My Python Service with Child Process"
_svc_description_ = "啟動並管理子進程的 Windows 服務示例"
def __init__(self, args):
win32serviceutil.ServiceFramework.__init__(self, args)
self.hWaitStop = win32event.CreateEvent(None, 0, 0, None)
self.child_process: Optional[subprocess.Popen] = None
self.config_path = Path(__file__).with_name('service_config.json')
self.config = self._load_config()
def _load_config(self) -> dict:
default = {
"python_exe": sys.executable,
"script_path": str(Path(__file__).with_name('worker.py')),
"work_dir": str(Path(__file__).parent),
"env": {},
"stop_timeout_sec": 10,
"restart_on_failure": True,
"max_restarts": 3,
"restart_delay_sec": 5
}
if self.config_path.exists():
with open(self.config_path, 'r', encoding='utf-8') as f:
user_cfg = json.load(f)
default.update(user_cfg)
return default
def SvcStop(self):
"""服務管理器調用停止服務"""
self.ReportServiceStatus(win32service.SERVICE_STOP_PENDING)
win32event.SetEvent(self.hWaitStop)
self._stop_child_process()
def SvcDoRun(self):
"""服務主循環"""
servicemanager.LogMsg(
servicemanager.EVENTLOG_INFORMATION_TYPE,
servicemanager.PYS_SERVICE_STARTED,
(self._svc_name_, '')
)
self._run_main_loop()
def _run_main_loop(self):
restart_count = 0
while True:
# 等待停止事件或子進程結束
rc = win32event.WaitForSingleObject(self.hWaitStop, 1000) # 1秒輪詢
if rc == win32event.WAIT_OBJECT_0:
# 收到停止信號
break
# 檢查子進程狀態
if self.child_process and self.child_process.poll() is not None:
exit_code = self.child_process.returncode
servicemanager.LogWarningMsg(f"子進程意外退出, code={exit_code}, 重啟計數={restart_count}")
if self.config['restart_on_failure'] and restart_count < self.config['max_restarts']:
time.sleep(self.config['restart_delay_sec'])
restart_count += 1
self._start_child_process()
else:
break
elif not self.child_process:
self._start_child_process()
# 正常退出循環,確保子進程已停止
self._stop_child_process()
servicemanager.LogMsg(
servicemanager.EVENTLOG_INFORMATION_TYPE,
servicemanager.PYS_SERVICE_STOPPED,
(self._svc_name_, '')
)
def _start_child_process(self):
"""啟動子進程,關鍵參數全控制"""
cmd = [self.config['python_exe'], self.config['script_path']]
work_dir = self.config['work_dir']
env = os.environ.copy()
env.update(self.config.get('env', {}))
# 關鍵:創建新進程組,便於後續整組終止
creation_flags = win32process.CREATE_NEW_PROCESS_GROUP | win32con.CREATE_NO_WINDOW
self.child_process = subprocess.Popen(
cmd,
cwd=work_dir,
env=env,
stdin=subprocess.PIPE,
stdout=subprocess.PIPE,
stderr=subprocess.PIPE,
creationflags=creation_flags,
# Python 3.7+ 支持 start_new_session (Unix), Windows 用 creationflags
)
servicemanager.LogInfoMsg(f"子進程已啟動: PID={self.child_process.pid}, CMD={' '.join(cmd)}")
def _stop_child_process(self):
"""可靠終止子進程樹"""
if not self.child_process:
return
pid = self.child_process.pid
try:
# 1. 嘗試優雅終止(發送 CTRL_BREAK_EVENT 到進程組,僅限控制台程序)
# 注意:僅當子進程也是控制台程序且共享控制台時有效
# win32api.GenerateConsoleCtrlEvent(win32con.CTRL_BREAK_EVENT, pid)
# 2. 標準 terminate(發送 SIGTERM 等價)
self.child_process.terminate()
# 3. 等待優雅退出
try:
self.child_process.wait(timeout=self.config['stop_timeout_sec'])
servicemanager.LogInfoMsg(f"子進程 {pid} 優雅退出")
return
except subprocess.TimeoutExpired:
pass
# 4. 強制殺死(Windows: TerminateProcess)
self.child_process.kill()
self.child_process.wait(timeout=5)
servicemanager.LogWarningMsg(f"子進程 {pid} 被強制終止")
except Exception as e:
servicemanager.LogErrorMsg(f"停止子進程 {pid} 失敗: {e}")
finally:
self.child_process = None
# ========== 入口點 ==========
if __name__ == '__main__':
# 支持命令行參數: install, remove, start, stop, restart, debug
win32serviceutil.HandleCommandLine(PythonService)
service_config.json
{
"python_exe": "C:\\Python311\\python.exe",
"script_path": "C:\\MyApp\\worker.py",
"work_dir": "C:\\MyApp",
"env": {
"PYTHONPATH": "C:\\MyApp",
"ENVIRONMENT": "production"
},
"stop_timeout_sec": 15,
"restart_on_failure": true,
"max_restarts": 5,
"restart_delay_sec": 10
}
worker.py 示例
# worker.py - 作為服務管理的子進程運行
import time
import logging
import signal
import sys
logging.basicConfig(
level=logging.INFO,
format='%(asctime)s [%(process)d] %(levelname)s %(message)s',
handlers=[
logging.FileHandler('worker.log', encoding='utf-8'),
logging.StreamHandler()
]
)
logger = logging.getLogger(__name__)
shutdown = False
def signal_handler(signum, frame):
global shutdown
logger.info(f"收到信號 {signum}, 準備關閉...")
shutdown = True
# Windows 不支持 SIGTERM/SIGINT 信號處理器,但可捕獲 CTRL_BREAK_EVENT
# 此處演示邏輯,實際 Windows 服務子進程收到 terminate() 會直接退出
signal.signal(signal.SIGTERM, signal_handler)
signal.signal(signal.SIGINT, signal_handler)
def main():
logger.info("Worker 啟動")
counter = 0
while not shutdown:
logger.info(f"工作中... 計數={counter}")
counter += 1
time.sleep(5)
logger.info("Worker 正常退出")
if __name__ == '__main__':
main()
# 以管理員身份運行 CMD/PowerShell
# 1. 安裝服務
python windows_service.py install
# 2. 設置啟動類型為自動(可選)
sc config MyPythonService start= auto
# 3. 啟動服務
python windows_service.py start
# 或: net start MyPythonService
# 4. 停止服務
python windows_service.py stop
# 或: net stop MyPythonService
# 5. 除錯模式(前台運行,輸出到控制台)
python windows_service.py debug
# 6. 移除服務
python windows_service.py remove
CREATE_NEW_PROCESS_GROUP:創建新進程組,子進程成為組長。配合 `GenerateConsoleCtrlEvent(CTRL_BREAK_EVENT, pid)` 可向整組發送 Ctrl+Break(類似 Unix 進程組信號)。
import psutil
def kill_process_tree(pid: int):
try:
parent = psutil.Process(pid)
for child in parent.children(recursive=True):
child.kill()
parent.kill()
except psutil.NoSuchProcess:
pass
with open('child_stdout.log', 'a') as out, open('child_stderr.log', 'a') as err:
proc = subprocess.Popen(cmd, stdout=out, stderr=err, ...)
使用 `servicemanager.LogMsg` 寫入 Windows 事件查看器(Application 日誌),便於集中監控。級別:`EVENTLOG_INFORMATION_TYPE`, `EVENTLOG_WARNING_TYPE`, `EVENTLOG_ERROR_TYPE`。
在 Windows 服務中管理子進程,核心模式是:
此框架已在生產環境穩定運行,可直接作為模板擴展業務邏輯。