Preparing for releasing.
This commit is contained in:
@@ -1,140 +1,220 @@
|
||||
# MineSentinel 部署指南
|
||||
|
||||
MineSentinel 是一个 Minecraft 服务器守护进程，每 10 秒检测服务器端口状态，发现崩溃时自动重启。
|
||||
```
|
||||
🛡️ MineSentinel
|
||||
Minecraft 服务器守护进程
|
||||
```
|
||||
|
||||
MineSentinel 是一个 Minecraft 服务器守护进程，每 1.5 秒检测服务器端口状态，发现崩溃后自动重启，重启后进入冷却期（200s）防止循环重启。
|
||||
|
||||
## 环境要求
|
||||
|
||||
- **操作系统**: Linux (systemd)
|
||||
- **Ruby**: >= 3.0（用到了 `Timeout.timeout` 和 `Process.spawn`）
|
||||
- **权限**: root（需要执行 `systemctl` 管理 Minecraft 服务）
|
||||
- **Minecraft 服务**: 已注册为 systemd 服务，服务名为 `minecraft`
|
||||
| 项目 | 说明 |
|
||||
|------|------|
|
||||
| **操作系统** | Linux（需要 systemd），也支持 Windows（见下方适配指南） |
|
||||
| **Ruby** | >= 3.0 |
|
||||
| **权限** | root（systemd 场景） |
|
||||
| **Minecraft 服务** | 已注册为 systemd 服务，默认服务名 `minecraft` |
|
||||
|
||||
## 文件结构
|
||||
|
||||
```
|
||||
/opt/minesentinel/ # 推荐部署目录
|
||||
├── main.rb # 主程序入口
|
||||
├── method_executor.rb # 日志系统 + 重启逻辑
|
||||
├── server_status_detector.rb # TCP 端口检测
|
||||
└── uni_log_path.rb # 日志路径工具（可选）
|
||||
/opt/minecraft/sentinel/ # 推荐部署目录
|
||||
├── main.rb # 主程序入口 —— 检测循环 + 冷却期 + 初始宽限期
|
||||
├── method_executor.rb # 日志系统 + 重启逻辑 + 重试计数器
|
||||
└── server_status_detector.rb # TCP 端口检测模块
|
||||
|
||||
minesentinel.service # systemd 单元文件（项目源码中）
|
||||
```
|
||||
|
||||
> `uni_log_path.rb` 已废弃。
|
||||
|
||||
## 部署步骤
|
||||
|
||||
### 1. 创建目录并复制文件
|
||||
|
||||
```bash
|
||||
mkdir -p /opt/minesentinel
|
||||
cp main.rb method_executor.rb server_status_detector.rb /opt/minesentinel/
|
||||
mkdir -p /opt/minecraft/sentinel
|
||||
cp main.rb method_executor.rb server_status_detector.rb /opt/minecraft/sentinel/
|
||||
```
|
||||
|
||||
如果要用 `uni_log_path.rb` 也一并复制。
|
||||
|
||||
### 2. 确认 Minecraft systemd 服务存在
|
||||
|
||||
```bash
|
||||
systemctl status minecraft
|
||||
```
|
||||
|
||||
如果你的 Minecraft 服务名不是 `minecraft`，需要修改 `method_executor.rb` 中所有 `systemctl xxx minecraft` 为你的实际服务名。
|
||||
如果服务名不是 `minecraft`，修改 `method_executor.rb` 中所有 `systemctl xxx minecraft` 为实际服务名（共 3 处：restart / kill / start），同时修改 `minesentinel.service` 中的 `Before=minecraft.service` 和 `Wants=minecraft.service`。
|
||||
|
||||
### 3. 手动测试
|
||||
|
||||
先前台跑一次确认无报错：
|
||||
|
||||
```bash
|
||||
cd /opt/minesentinel
|
||||
cd /opt/minecraft/sentinel
|
||||
ruby main.rb
|
||||
# 调试模式：LOG_LEVEL=debug ruby main.rb
|
||||
```
|
||||
|
||||
观察日志输出，确认能正常检测端口、识别服务状态。按 `Ctrl+C` 退出。
|
||||
### 4. 注册 systemd 服务
|
||||
|
||||
调试模式（输出更详细）：
|
||||
项目源码中已提供 `minesentinel.service`，直接复制：
|
||||
|
||||
```bash
|
||||
LOG_LEVEL=debug ruby main.rb
|
||||
cp minesentinel.service /etc/systemd/system/
|
||||
```
|
||||
|
||||
### 4. 注册为 systemd 服务
|
||||
|
||||
创建 `/etc/systemd/system/minesentinel.service`：
|
||||
单元文件内容（`minesentinel.service`）：
|
||||
|
||||
```ini
|
||||
[Unit]
|
||||
Description=MineSentinel - Minecraft Server Auto-Restart Daemon
|
||||
Description=MineSentinel Minecraft Server Monitor
|
||||
After=network.target
|
||||
Before=minecraft.service
|
||||
Wants=minecraft.service
|
||||
|
||||
[Service]
|
||||
Type=simple
|
||||
WorkingDirectory=/opt/minesentinel
|
||||
ExecStart=/usr/bin/ruby /opt/minesentinel/main.rb
|
||||
WorkingDirectory=/opt/minecraft/sentinel
|
||||
ExecStart=/usr/bin/ruby /opt/minecraft/sentinel/main.rb
|
||||
Restart=always
|
||||
RestartSec=5
|
||||
RestartSec=10
|
||||
StandardOutput=journal
|
||||
StandardError=journal
|
||||
Environment=LOG_LEVEL=info
|
||||
#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
|
||||
systemctl enable minesentinel # 同时也会触发 minecraft（Wants=）
|
||||
systemctl start minesentinel
|
||||
```
|
||||
|
||||
### 5. 查看日志
|
||||
|
||||
```bash
|
||||
# 实时日志
|
||||
journalctl -u minesentinel -f
|
||||
|
||||
# 最近 50 条
|
||||
journalctl -u minesentinel -n 50
|
||||
|
||||
# 只看错误
|
||||
journalctl -u minesentinel -p err
|
||||
journalctl -u minesentinel -f # 实时
|
||||
journalctl -u minesentinel -u minecraft -f # 双服务合并
|
||||
```
|
||||
|
||||
## 日志级别说明
|
||||
|
||||
通过 `Environment=LOG_LEVEL=xxx` 控制：
|
||||
|
||||
| 级别 | 说明 |
|
||||
|------|------|
|
||||
| `debug` | 全部输出，含每次巡检结果、TCP 响应时间 |
|
||||
| `info` | 启动/重启/恢复等关键操作 |
|
||||
| `warn` | 服务器异常、超时、强制终止 |
|
||||
| `error` | 重启失败、重试次数耗尽 |
|
||||
|
||||
默认 `info`，生产环境推荐 `info`；排查问题时临时改为 `debug`。
|
||||
|
||||
## 工作流程
|
||||
|
||||
```
|
||||
每 10 秒循环：
|
||||
MineSentinel 启动：
|
||||
├─ 进入初始宽限期（300s），等待 MC 端口就绪
|
||||
└─ 宽限期结束 → 进入正常监控循环
|
||||
|
||||
每 1.5 秒循环：
|
||||
├─ TCP 连接 127.0.0.1:25565
|
||||
├─ 端口开放 → debug 日志，继续等待
|
||||
├─ 端口关闭 → 记录 warn，触发重启
|
||||
│ └─ systemctl restart minecraft（最多重试 10 次）
|
||||
│ ├─ 30 秒内完成 → 成功，计数器归零
|
||||
│ └─ 超时 → kill -9 → systemctl kill → systemctl start
|
||||
└─ 10 次全部失败 → 进入空闲等待，直到手动恢复
|
||||
├─ 端口开放 → 继续循环
|
||||
├─ 端口超时 → 仅记录日志（不重启，可能是网络抖动）
|
||||
└─ 端口关闭 → 触发重启 → 冷却 200 秒等待启动
|
||||
└─ 连续失败 10 次 → 进入空闲等待，直到手动恢复
|
||||
```
|
||||
|
||||
## 可调参数
|
||||
|
||||
| 参数 | 文件 | 行 | 默认值 |
|
||||
|------|------|-----|--------|
|
||||
| 初始宽限期 | `main.rb` | 31 | `300` s |
|
||||
| 检测间隔 | `main.rb` | 69 | `1.5` s |
|
||||
| 冷却期 | `main.rb` | 58 | `200` 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 权限执行。确认 systemd service 以 root 运行，或 `sudo ruby main.rb`。
|
||||
**Q: 报 `Errno::EPERM`？** A: 需 root 权限或 `sudo ruby main.rb`。
|
||||
|
||||
**Q: 如何修改检测端口？**
|
||||
A: 编辑 `server_status_detector.rb` 第 52 行，修改 `test_port` 的端口参数。
|
||||
**Q: 端口一直超时但不重启？** A: 设计如此。`:timeout` 只记录不重启，仅 `:closed` 触发重启。
|
||||
|
||||
**Q: 如何修改检测间隔？**
|
||||
A: 编辑 `main.rb` 第 33 行，修改 `sleep 10` 的值。
|
||||
**Q: 启动时 MineSentinel 反复重启 minecraft？** A: 检查 `INITIAL_GRACE` 是否小于 MC 实际启动时间，适当调大。
|
||||
|
||||
**Q: 如何修改重启超时时间？**
|
||||
A: 编辑 `method_executor.rb` 第 9 行，修改 `PERSISTENCE_PERIOD`。
|
||||
**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 / 项目名称）保留所有权利，未经许可不得用于衍生项目。
|
||||
|
||||
Reference in New Issue
Block a user