# MineSentinel 部署指南

MineSentinel 是一个 Minecraft 服务器守护进程，每 10 秒检测服务器端口状态，发现崩溃时自动重启。

## 环境要求

- **操作系统**: Linux (systemd)
- **Ruby**: >= 3.0（用到了 `Timeout.timeout` 和 `Process.spawn`）
- **权限**: root（需要执行 `systemctl` 管理 Minecraft 服务）
- **Minecraft 服务**: 已注册为 systemd 服务，服务名为 `minecraft`

## 文件结构

```
/opt/minesentinel/       # 推荐部署目录
├── main.rb              # 主程序入口
├── method_executor.rb   # 日志系统 + 重启逻辑
├── server_status_detector.rb  # TCP 端口检测
└── uni_log_path.rb      # 日志路径工具（可选）
```

## 部署步骤

### 1. 创建目录并复制文件

```bash
mkdir -p /opt/minesentinel
cp main.rb method_executor.rb server_status_detector.rb /opt/minesentinel/
```

如果要用 `uni_log_path.rb` 也一并复制。

### 2. 确认 Minecraft systemd 服务存在

```bash
systemctl status minecraft
```

如果你的 Minecraft 服务名不是 `minecraft`，需要修改 `method_executor.rb` 中所有 `systemctl xxx minecraft` 为你的实际服务名。

### 3. 手动测试

先前台跑一次确认无报错：

```bash
cd /opt/minesentinel
ruby main.rb
```

观察日志输出，确认能正常检测端口、识别服务状态。按 `Ctrl+C` 退出。

调试模式（输出更详细）：

```bash
LOG_LEVEL=debug ruby main.rb
```

### 4. 注册为 systemd 服务

创建 `/etc/systemd/system/minesentinel.service`：

```ini
[Unit]
Description=MineSentinel - Minecraft Server Auto-Restart Daemon
After=network.target

[Service]
Type=simple
WorkingDirectory=/opt/minesentinel
ExecStart=/usr/bin/ruby /opt/minesentinel/main.rb
Restart=always
RestartSec=5
StandardOutput=journal
StandardError=journal
Environment=LOG_LEVEL=info

[Install]
WantedBy=multi-user.target
```

然后：

```bash
systemctl daemon-reload
systemctl enable minesentinel
systemctl start minesentinel
```

### 5. 查看日志

```bash
# 实时日志
journalctl -u minesentinel -f

# 最近 50 条
journalctl -u minesentinel -n 50

# 只看错误
journalctl -u minesentinel -p err
```

## 日志级别说明

通过 `Environment=LOG_LEVEL=xxx` 控制：

| 级别 | 说明 |
|------|------|
| `debug` | 全部输出，含每次巡检结果、TCP 响应时间 |
| `info` | 启动/重启/恢复等关键操作 |
| `warn` | 服务器异常、超时、强制终止 |
| `error` | 重启失败、重试次数耗尽 |

默认 `info`，生产环境推荐 `info`；排查问题时临时改为 `debug`。

## 工作流程

```
每 10 秒循环：
  ├─ TCP 连接 127.0.0.1:25565
  ├─ 端口开放 → debug 日志，继续等待
  ├─ 端口关闭 → 记录 warn，触发重启
  │   └─ systemctl restart minecraft（最多重试 10 次）
  │       ├─ 30 秒内完成 → 成功，计数器归零
  │       └─ 超时 → kill -9 → systemctl kill → systemctl start
  └─ 10 次全部失败 → 进入空闲等待，直到手动恢复
```

## 常见问题

**Q: 报 `Errno::EPERM`？**
A: 需要 root 权限执行。确认 systemd service 以 root 运行，或 `sudo ruby main.rb`。

**Q: 如何修改检测端口？**
A: 编辑 `server_status_detector.rb` 第 52 行，修改 `test_port` 的端口参数。

**Q: 如何修改检测间隔？**
A: 编辑 `main.rb` 第 33 行，修改 `sleep 10` 的值。

**Q: 如何修改重启超时时间？**
A: 编辑 `method_executor.rb` 第 9 行，修改 `PERSISTENCE_PERIOD`。