sentinel/DEPLOY.md

# 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              # 可调参数配置
└── updates.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 updates.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 / 项目名称）保留所有权利，未经许可不得用于衍生项目。