224 lines
6.5 KiB
Markdown
224 lines
6.5 KiB
Markdown
# MineSentinel 部署指南
|
||
|
||
```
|
||
🛡️ MineSentinel
|
||
Minecraft 服务器守护进程
|
||
```
|
||
|
||
MineSentinel 是一个 Minecraft 服务器守护进程，每 1.5 秒检测服务器端口状态，发现崩溃后自动重启，重启后进入冷却期（200s）防止循环重启。
|
||
|
||
## 环境要求
|
||
|
||
| 项目 | 说明 |
|
||
|------|------|
|
||
| **操作系统** | Linux（需要 systemd），也支持 Windows（见下方适配指南） |
|
||
| **Ruby** | >= 3.0 |
|
||
| **权限** | root（systemd 场景） |
|
||
| **Minecraft 服务** | 已注册为 systemd 服务，默认服务名 `minecraft` |
|
||
|
||
## 文件结构
|
||
|
||
```
|
||
/opt/minecraft/sentinel/ # 推荐部署目录
|
||
├── main.rb # 主程序入口 —— 检测循环 + 冷却期 + 初始宽限期
|
||
├── method_executor.rb # 日志系统 + 重启逻辑 + 重试计数器
|
||
├── server_status_detector.rb # TCP 端口检测模块
|
||
├── systemd_notifier.rb # systemd watchdog 心跳发送
|
||
└── config.rb # 可调参数配置
|
||
|
||
minesentinel.service # systemd 单元文件（项目源码中）
|
||
```
|
||
|
||
> `uni_log_path.rb` 已废弃。
|
||
|
||
## 部署步骤
|
||
|
||
### 1. 创建目录并复制文件
|
||
|
||
```bash
|
||
mkdir -p /opt/minecraft/sentinel
|
||
cp main.rb method_executor.rb server_status_detector.rb systemd_notifier.rb config.rb /opt/minecraft/sentinel/
|
||
```
|
||
|
||
### 2. 确认 Minecraft systemd 服务存在
|
||
|
||
```bash
|
||
systemctl status minecraft
|
||
```
|
||
|
||
如果服务名不是 `minecraft`，修改 `method_executor.rb` 中所有 `systemctl xxx minecraft` 为实际服务名（共 3 处：restart / kill / start），同时修改 `minesentinel.service` 中的 `Before=minecraft.service` 和 `Wants=minecraft.service`。
|
||
|
||
### 3. 手动测试
|
||
|
||
```bash
|
||
cd /opt/minecraft/sentinel
|
||
ruby main.rb
|
||
# 调试模式：LOG_LEVEL=debug ruby main.rb
|
||
```
|
||
|
||
### 4. 注册 systemd 服务
|
||
|
||
项目源码中已提供 `minesentinel.service`，直接复制：
|
||
|
||
```bash
|
||
cp minesentinel.service /etc/systemd/system/
|
||
```
|
||
|
||
单元文件内容（`minesentinel.service`）：
|
||
|
||
```ini
|
||
[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
|
||
#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 启动 → 端口就绪
|
||
```
|
||
|
||
```bash
|
||
systemctl daemon-reload
|
||
systemctl enable minesentinel # 同时也会触发 minecraft（Wants=）
|
||
systemctl start minesentinel
|
||
```
|
||
|
||
### 5. 查看日志
|
||
|
||
```bash
|
||
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：**
|
||
```ruby
|
||
pid = spawn "docker restart mc-server"
|
||
```
|
||
|
||
**screen：**
|
||
```ruby
|
||
system "screen -S mc -X quit"
|
||
sleep 2
|
||
system "screen -dmS mc java -Xmx4G -jar server.jar nogui"
|
||
```
|
||
|
||
**supervisor：**
|
||
```ruby
|
||
pid = spawn "supervisorctl restart minecraft"
|
||
```
|
||
|
||
### Windows 环境
|
||
|
||
核心逻辑跨平台，仅需适配重启方式。`method_executor.rb` 修改：
|
||
|
||
```ruby
|
||
# 删除第 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 行改为：
|
||
|
||
```ruby
|
||
@@logger = Logger.new("C:\\mc\\sentinel.log", "daily")
|
||
```
|
||
|
||
以管理员身份运行终端，`ruby main.rb` 即可。
|
||
|
||
### 监控其他服务
|
||
|
||
`server_status_detector.rb` 的 `test_port` 是通用 TCP 检测，改端口和 IP 即可监控任意服务：
|
||
|
||
```ruby
|
||
# 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=`。
|
||
|
||
## 许可证
|
||
|
||
MineSentinel 源码采用 [木兰宽松许可证 v2](http://license.coscl.org.cn/MulanPubL-2.0)。品牌标识（Logo / 项目名称）保留所有权利，未经许可不得用于衍生项目。
|