Files

T

2026-06-08 13:50:07 +08:00

6.7 KiB

Raw Blame History

MineSentinel 部署指南

🛡️  MineSentinel
Minecraft 服务器守护进程

MineSentinel 是一个 Minecraft 服务器守护进程，每 1.5 秒检测服务器端口状态，发现崩溃后自动重启，重启后进入冷却期（200s）防止循环重启。

环境要求

项目	说明
操作系统	Linux（需要 systemd），也支持 Windows（见下方适配指南）
Ruby	>= 3.0
权限	root（systemd 场景）
Minecraft 服务	已注册为 systemd 服务，默认服务名 `minecraft`

文件结构

/opt/minecraft/sentinel/   # 推荐部署目录
└── src/                   # 源码目录
    ├── main.rb                # 主程序入口 —— 检测循环 + 冷却期 + 初始宽限期
    ├── method_executor.rb     # 日志系统 + 重启逻辑 + 重试计数器
    ├── server_status_detector.rb  # TCP 端口检测模块
    ├── systemd_notifier.rb    # systemd watchdog 心跳发送
    ├── config.rb              # 可调参数配置
    └── updates.rb             # 更新检查模块

minesentinel.service       # systemd 单元文件（项目源码中）

uni_log_path.rb 已废弃。

部署步骤

1. 创建目录并复制文件

mkdir -p /opt/minecraft/sentinel/src
cp src/main.rb src/method_executor.rb src/server_status_detector.rb src/systemd_notifier.rb src/config.rb src/updates.rb /opt/minecraft/sentinel/src/

2. 确认 Minecraft systemd 服务存在

systemctl status minecraft

如果服务名不是 minecraft，修改 method_executor.rb 中所有 systemctl xxx minecraft 为实际服务名（共 3 处：restart / kill / start），同时修改 minesentinel.service 中的 Before=minecraft.service 和 Wants=minecraft.service。

3. 手动测试

cd /opt/minecraft/sentinel/src
ruby main.rb
# 调试模式：LOG_LEVEL=debug ruby main.rb

4. 注册 systemd 服务

项目源码中已提供 minesentinel.service，直接复制：

cp src/minesentinel.service /etc/systemd/system/

单元文件内容（minesentinel.service）：

[Unit]
Description=MineSentinel Minecraft Server Monitor
After=network.target
Before=minecraft.service
Wants=minecraft.service

[Service]
Type=simple
WorkingDirectory=/opt/minecraft/sentinel/src
ExecStart=/usr/bin/ruby /opt/minecraft/sentinel/src/main.rb
Restart=always
RestartSec=10
StandardOutput=journal
StandardError=journal
#Environment=LOG_LEVEL=debug
#Environment=RUBY_DEBUG=1
WatchdogSec=210

[Install]
WantedBy=multi-user.target

参数	说明
`Before=minecraft.service`	MineSentinel 先于 MC 启动，消除守护盲区
`Wants=minecraft.service`	软依赖 MC 服务，MC 启动失败不影响 MineSentinel
`RestartSec=10`	MineSentinel 自身崩溃后 10s 重启
`WatchdogSec=210`	必须大于冷却期（200s），防止 watchdog 误杀

启动顺序：

开机 → network.target → MineSentinel → (300s 宽限期) → minecraft 启动 → 端口就绪

systemctl daemon-reload
systemctl enable minesentinel   # 同时也会触发 minecraft（Wants=）
systemctl start minesentinel

5. 查看日志

journalctl -u minesentinel -f          # 实时
journalctl -u minesentinel -u minecraft -f  # 双服务合并

工作流程

MineSentinel 启动：
  ├─ 进入初始宽限期（300s），等待 MC 端口就绪
  └─ 宽限期结束 → 进入正常监控循环

每 1.5 秒循环：
  ├─ TCP 连接 127.0.0.1:25565
  ├─ 端口开放 → 继续循环
  ├─ 端口超时 → 仅记录日志（不重启，可能是网络抖动）
  └─ 端口关闭 → 触发重启 → 冷却 200 秒等待启动
      └─ 连续失败 10 次 → 进入空闲等待，直到手动恢复

可调参数

参数	文件	行	默认值
初始宽限期	`config.rb`	1	`300` s
冷却期	`config.rb`	3	`200` s
尝试次数	`config.rb`	2	`3` 次
检测间隔	`config.rb`	4	`1.5` s
systemctl 超时	`method_executor.rb`	17	`30` s
最大重试	`method_executor.rb`	23	`10` 次
检测端口	`server_status_detector.rb`	60	`25565`
TCP 超时	`server_status_detector.rb`	23	`10` s

日志级别

Environment=LOG_LEVEL=xxx，默认 debug（未设置时），生产推荐 info。

级别	内容
`debug`	每次巡检、TCP 响应时间、systemctl PID
`info`	启动/宽限期/重启/恢复/冷却期
`warn`	端口超时/关闭、强制终止
`error`	重启失败、重试耗尽

跨场景适配指南

无 systemd（Docker / screen / 手动启动）

核心：替换 method_executor.rb 第 86 行的重启命令，并移除第 80-83 行 root 权限检查。

Docker：

pid = spawn "docker restart mc-server"

screen：

system "screen -S mc -X quit"
sleep 2
system "screen -dmS mc java -Xmx4G -jar server.jar nogui"

supervisor：

pid = spawn "supervisorctl restart minecraft"

Windows 环境

核心逻辑跨平台，仅需适配重启方式。method_executor.rb 修改：

# 删除第 80-83 行 root 权限检查（Windows 无 Process.euid）

# 第 86 行替换为（直接调 Java 或 bat）：
pid = spawn "cmd /c start /B java -Xmx4G -jar C:\\mc\\server.jar nogui"

日志输出到文件（Windows 无 journal）—— 在 method_executor.rb 第 26 行改为：

@@logger = Logger.new("C:\\mc\\sentinel.log", "daily")

以管理员身份运行终端，ruby main.rb 即可。

监控其他服务

server_status_detector.rb 的 test_port 是通用 TCP 检测，改端口和 IP 即可监控任意服务：

# server_status_detector.rb 第 60 行
res = test_port('192.168.1.100', 3306)  # MySQL
res = test_port('127.0.0.1', 80)        # Nginx

配合修改 method_executor.rb 中的重启命令即可适配。

常见问题

Q: 报 Errno::EPERM？ A: 需 root 权限或 sudo ruby main.rb。

Q: 端口一直超时但不重启？ A: 设计如此。:timeout 只记录不重启，仅 :closed 触发重启。

Q: 启动时 MineSentinel 反复重启 minecraft？ A: 检查 INITIAL_GRACE 是否小于 MC 实际启动时间，适当调大。

Q: 如何修改 Minecraft 服务名？ A: 编辑 method_executor.rb，搜索 systemctl xxx minecraft（3 处），替换 minecraft 为实际服务名。同时修改 minesentinel.service 中的 Before= 和 Wants=。

6.7 KiB Raw Blame History Unescape Escape