universal-autostart

Cross-platform auto-start service manager for Windows and macOS. Supports installing, uninstalling, starting, stopping, and monitoring services with automatic restart. Use when you need to set up persistent background services that survive system reboots on Windows (sc/schtasks) or macOS (launchd).

steam2001@ahao2001

Install

openclaw skills install @ahao2001/universal-autostart

Universal AutoStart Service Manager v1.1

跨平台的自启动服务管理器，支持 Windows 和 macOS。可以安装、卸载、启动、停止和监控服务，并支持自动重启。

🚀 快速开始

Windows 安装

创建 install_windows.bat 文件（纯文本，保存为 UTF-8 编码）：

batch

@echo off
chcp 65001 >nul
echo ============================================================
echo   通用自启动服务 - 安装工具 v1.1
echo ============================================================

:: 检查管理员权限
net session >nul 2>&1
if %errorLevel% neq 0 (
    echo [ERROR] 请以管理员身份运行此脚本！
    pause
    exit /b 1
)

echo [OK] 管理员权限已获取

:: 查找配置文件
set CONFIG_FILE=%~dp0service_config.json
if not exist "%CONFIG_FILE%" (
    set CONFIG_FILE=%~dp0qwenpaw_service_config.json
)

if not exist "%CONFIG_FILE%" (
    echo [ERROR] 未找到配置文件！
    pause
    exit /b 1
)

:: 安装服务
python "%~dp0universal_service.py" install "%CONFIG_FILE%" --no-check-admin

if %errorLevel% equ 0 (
    echo [OK] 安装完成！服务将在下次开机自动启动
) else (
    echo [ERROR] 安装失败！
)

pause

右键点击 install_windows.bat → 以管理员身份运行

macOS 安装

使用已提供的 install_macos.sh：

bash

sudo ./install_macos.sh

📋 核心功能

功能	描述
跨平台支持	Windows (sc + schtasks), macOS (launchd)
自动重启	服务崩溃时自动重启（可配置最大重启次数）
日志记录	实时日志输出，支持文件轮转
健康检查	端口/进程检测，确保服务正常运行
优雅退出	支持 SIGTERM/SIGINT 信号处理
环境变量	支持加载 .env 文件

🔧 使用方式

命令行操作

bash

# 安装自启动（不立即运行）
python universal_service.py install [config.json] [--no-check-admin]

# 卸载自启动
python universal_service.py uninstall [config.json] [--no-check-admin]

# 手动启动服务
python universal_service.py start [config.json]

# 停止服务
python universal_service.py stop [config.json]

# 查看服务状态
python universal_service.py status [config.json]

# 直接运行（带自启动）
python universal_service.py [config.json]

双击脚本

Windows: install.bat / uninstall.bat
macOS: install_macos.sh / uninstall_macos.sh

⚙️ 配置文件

QwenPaw 标准配置 (`qwenpaw_service_config.json`)

json

{
  "service_name": "QwenPawService",
  "display_name": "QwenPaw 智能助手服务",
  "program": {
    "type": "python",
    "path": "python",
    "arguments": "-m qwenpaw.cli",
    "working_dir": "C:/Users/Administrator/.copaw/workspaces/default"
  },
  "environment": {
    "load_dotenv": true,
    "variables": {}
  },
  "log": {
    "enabled": true,
    "level": "INFO",
    "dir": ".logs",
    "max_size_mb": 10,
    "backup_count": 5,
    "console": true
  },
  "health_check": {
    "enabled": true,
    "type": "port",
    "port": 8765,
    "interval_seconds": 30,
    "timeout_seconds": 5,
    "max_failures": 3
  },
  "restart": {
    "auto_restart": true,
    "max_restarts": 5,
    "restart_delay": 30
  }
}

通用示例配置 (`service_config.example.json`)

json

{
  "service_name": "MyCustomService",
  "display_name": "我的自定义服务",
  "program": {
    "type": "python",
    "path": "python3",
    "arguments": "app.py",
    "working_dir": "/path/to/app"
  },
  "environment": {
    "load_dotenv": false,
    "variables": {
      "NODE_ENV": "production"
    }
  },
  "log": {
    "enabled": true,
    "level": "DEBUG",
    "dir": "./logs"
  },
  "health_check": {
    "enabled": true,
    "type": "port",
    "port": 3000,
    "interval_seconds": 10
  },
  "restart": {
    "auto_restart": true,
    "max_restarts": 3,
    "restart_delay": 60
  }
}

配置选项说明

字段	类型	说明
`service_name`	string	服务内部名称（唯一标识）
`display_name`	string	服务显示名称
`program.type`	string	程序类型：`python` / `node` / `binary` / `shell`
`program.path`	string	可执行程序路径
`program.arguments`	string	启动参数
`program.working_dir`	string	工作目录
`environment.load_dotenv`	bool	是否加载 .env 文件
`environment.variables`	object	额外环境变量
`log.enabled`	bool	是否启用日志
`log.level`	string	日志级别：DEBUG/INFO/WARNING/ERROR
`log.dir`	string	日志目录
`log.max_size_mb`	int	单文件最大大小 (MB)
`log.backup_count`	int	保留的备份文件数量
`log.console`	bool	是否输出到控制台
`health_check.enabled`	bool	是否启用健康检查
`health_check.type`	string	检查类型：`port` / `process`
`health_check.port`	int	端口号
`health_check.interval_seconds`	int	检查间隔
`health_check.timeout_seconds`	int	超时时间
`health_check.max_failures`	int	最大失败次数
`restart.auto_restart`	bool	是否自动重启
`restart.max_restarts`	int	最大重启次数
`restart.restart_delay`	int	重启延迟 (秒)

🔍 健康检查

支持两种检查方式：

端口检查 (推荐 Web 服务)

json

{
  "health_check": {
    "enabled": true,
    "type": "port",
    "port": 8765,
    "interval_seconds": 30,
    "timeout_seconds": 5,
    "max_failures": 3
  }
}

当连续 3 次无法连接到 8765 端口时，触发自动重启。

进程检查

json

{
  "health_check": {
    "enabled": true,
    "type": "process",
    "interval_seconds": 10
  }
}

定期检查子进程是否存活。

📝 日志管理

默认行为

日志文件：.logs/UniversalService_YYYY-MM-DD.log
日志级别：INFO
文件轮转：单文件 10MB，保留 5 个备份
控制台输出：是

禁用日志

json

{
  "log": {
    "enabled": false
  }
}

🔄 自动重启机制

防死循环设计

text

第 1 次崩溃: 立即重启
第 2 次崩溃: 立即重启
第 3 次崩溃: 等待 5 秒后重启
...
累计 5 次崩溃: 停止重启，记录严重错误

可通过配置调整：

json

{
  "restart": {
    "max_restarts": 5,
    "restart_delay": 30
  }
}

🛠️ 高级功能

环境变量加载

json

{
  "environment": {
    "load_dotenv": true,
    "variables": {
      "APP_MODE": "production",
      "LOG_LEVEL": "DEBUG"
    }
  }
}

会优先使用 variables 中的值，覆盖 .env 文件的设置。

多程序类型支持

json

// Python 程序
{
  "program": {
    "type": "python",
    "path": "python3",
    "arguments": "app.py"
  }
}

// Node.js 程序
{
  "program": {
    "type": "node",
    "path": "node",
    "arguments": "server.js"
  }
}

// 可执行文件
{
  "program": {
    "type": "binary",
    "path": "/usr/local/bin/myapp",
    "arguments": "--config config.yaml"
  }
}

// Shell 脚本
{
  "program": {
    "type": "shell",
    "path": "bash",
    "arguments": "scripts/start.sh"
  }
}

🐛 故障排查

问题 1: 权限不足

Windows:

text

右键 → 以管理员身份运行

macOS:

bash

sudo ./install_macos.sh

问题 2: 服务未启动

检查日志：

bash

type .logs\UniversalService_*.log    # Windows
tail -f .logs/UniversalService_*.log  # macOS

问题 3: 健康检查频繁重启

降低检查频率或增加失败阈值：

json

{
  "health_check": {
    "interval_seconds": 60,
    "max_failures": 5
  }
}

问题 4: Python 找不到

指定完整路径：

json

{
  "program": {
    "path": "C:\\Python39\\python.exe"
  }
}

📦 文件结构

text

universal-autostart/
├── universal_service.py       # 核心服务管理器
├── install.bat                # Windows 安装脚本
├── uninstall.bat              # Windows 卸载脚本
├── install_macos.sh           # macOS 安装脚本
├── uninstall_macos.sh         # macOS 卸载脚本
├── qwenpaw_service_config.json # QwenPaw 标准配置
├── service_config.example.json # 通用配置示例
└── README.md                  # 用户文档

🔄 版本历史

v1.1 (当前版本)

✅ 新增 macOS launchd 支持
✅ 改进权限检测方法
✅ 优化日志轮转机制
✅ 增加健康检查功能
✅ 修复 admin_check() 子进程问题

v1.0

✅ Windows sc/schtasks 支持
✅ 基础自动重启功能
✅ 日志记录
✅ 环境变量支持

📄 许可证

MIT License

项目地址: https://gitee.com/steam2001/universal-autostart
技能商店: skillhub.club

universal-autostart

Install

Universal AutoStart Service Manager v1.1

🚀 快速开始

Windows 安装

macOS 安装

📋 核心功能

🔧 使用方式

命令行操作

双击脚本

⚙️ 配置文件

QwenPaw 标准配置 (qwenpaw_service_config.json)

通用示例配置 (service_config.example.json)

配置选项说明

🔍 健康检查

端口检查 (推荐 Web 服务)

进程检查

📝 日志管理

默认行为

禁用日志

🔄 自动重启机制

防死循环设计

🛠️ 高级功能

环境变量加载

多程序类型支持

🐛 故障排查

问题 1: 权限不足

问题 2: 服务未启动

问题 3: 健康检查频繁重启

问题 4: Python 找不到

📦 文件结构

🔄 版本历史

v1.1 (当前版本)

v1.0

📄 许可证

QwenPaw 标准配置 (`qwenpaw_service_config.json`)

通用示例配置 (`service_config.example.json`)