dev1.0 版本

2026-06-07 11:05:26 +08:00
commit 777c8b2021
10 changed files with 505 additions and 0 deletions
@@ -0,0 +1,140 @@
+# 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`。