🛡️ MineSentinel

Minecraft 服务器智能守护进程

TCP 检测 · 自动重启 · 防循环冷却

由 SCU 团队 拥有 · 编写者 S.A. [@SNOWARE]

当前版本 60176fa · 频道 master

🔍 高频检测

每 1.5 秒对 127.0.0.1:25565 发起 TCP 连接，毫秒级感知服务器状态变化。

🧠 智能判断

严格区分端口超时与端口关闭——超时仅记录日志（避免网络抖动误判），关闭才触发重启。

⏳ 冷却期保护

重启后等待 200 秒，初次启动有 300 秒宽限期，彻底防止 MC 启动缓慢导致循环重启。Watchdog 同步适配（210s）。

🛡️ 重试上限

连续 10 次重启失败后进入空闲等待模式，每 10 秒检测端口，恢复后自动退出。

🌍 跨平台

核心逻辑纯 Ruby 实现，支持 systemd / Docker / screen / Windows，轻松适配任意进程管理器。

📝 日志完备

四级日志（debug / info / warn / error），输出到 systemd journal，排查问题一目了然。

📋 日志示例

通过 journalctl -u minesentinel -f 实时查看，以下为一次完整崩溃恢复过程的日志输出：

18:16:17DEBUG self_diag: TCP check OK — 0.0002s

18:16:17DEBUG mainloop: Server health check passed.

18:16:18DEBUG self_diag: TCP check OK — 0.0003s

18:16:18DEBUG mainloop: Server health check passed.

18:16:20WARN self_diag: TCP port closed — server is down.

18:16:21WARN mainloop: Server health check FAILED: Server died for unknown reason, and will be restarted.

18:16:21WARN mainloop: Action: Record → Server died!

18:16:21INFO mainloop: Action: ForceResetServerProcess triggered.

18:16:21INFO reset: Attempt #1 to reset Minecraft server.

18:16:21INFO reset: Spawning 'systemctl restart minecraft' (PID will be captured)...

18:16:21DEBUG reset: systemctl restart spawned with new PID.

18:16:51WARN reset: 'systemctl restart' timed out after 30s. Force-killing process...

18:16:51WARN reset: Running 'systemctl kill minecraft' (last resort)...

18:16:52INFO reset: Running 'systemctl start minecraft' (rebirth)...

18:16:52INFO reset: Force-reset sequence completed.

18:16:52INFO mainloop: Cooling down 200s for server startup...

... ... ...

18:20:12INFO mainloop: Cooldown finished, resuming monitoring.

18:20:14DEBUG self_diag: TCP check OK — 0.0002s

18:20:15DEBUG mainloop: Server health check passed.

💡 日志中 PID、精确时间戳等敏感信息已脱敏。实际输出格式与 journald 一致，支持 --since、-f 等标准过滤参数。

📦 部署教程

1. 环境要求

项目	说明
操作系统	Linux（需 systemd），也支持 Windows
Ruby	>= 3.0
权限	root（systemctl 需要）
MC 服务	已注册为 systemd 服务，默认名 `minecraft`

2. 获取源码

方式一：Git 克隆（推荐，仅拉取必要文件，排除仓库冗余）

git clone --depth 1 --single-branch \
  https://gitee.com/SCU_team/mine-sentinel.git \
  /opt/minecraft/sentinel
# --depth 1      仅拉取最新提交，不下载历史记录
# --single-branch 仅拉取 master 分支

方式二：手动复制

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

3. 手动测试

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

4. 注册 systemd 服务

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

cp minesentinel.service /etc/systemd/system/

单元文件内容：

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

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

[Install]
WantedBy=multi-user.target

🔗 启动顺序

MineSentinel 通过 Before=minecraft.service 确保先于 MC 启动，消除守护盲区。首次启动有 300 秒宽限期等待端口就绪：

开机 → network.target │ ├─ MineSentinel 启动（最先） │ └─ 进入 300s 宽限期，等待 MC 端口就绪 │ └─ minecraft 随后启动（Before=） └─ 端口打开 → MineSentinel 恢复正常监控

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

5. 查看日志

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

⚙️ 可调参数

参数	文件	行	默认
初始宽限期	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

🔄 工作流程

MineSentinel 启动： └─ 300s 宽限期 → 等待 MC 端口就绪（避免误判）每 1.5 秒循环： ├─ TCP 连接 127.0.0.1:25565 ├─ 端口开放 → 继续循环 ├─ 端口超时 → 仅记录日志（不重启） └─ 端口关闭 → 触发重启 → 冷却 200 秒 └─ 连续 10 次失败 → 空闲等待

🪟 Windows / Docker / 其他场景

Docker：替换重启命令为 spawn "docker restart mc-server"
screen：system "screen -S mc -X quit"; system "screen -dmS mc java ..."
Windows：删除 root 检查，替换为 spawn "cmd /c start /B java ..."，日志输出到文件
监控其他服务：修改 test_port 的 IP 和端口即可

详细适配指南见 DEPLOY.md

⭐ Gitee 仓库 📖 完整文档