tidy the file tree

2026-06-08 12:09:53 +08:00
parent 8cd942be2d
commit 83acd3049b
13 changed files with 53 additions and 39 deletions
@@ -0,0 +1,225 @@
+# MineSentinel 部署指南
+
+```
+🛡️  MineSentinel
+Minecraft 服务器守护进程
+```
+
+MineSentinel 是一个 Minecraft 服务器守护进程，每 1.5 秒检测服务器端口状态，发现崩溃后自动重启，重启后进入冷却期（200s）防止循环重启。
+
+## 环境要求
+
+| 项目 | 说明 |
+|------|------|
+| **操作系统** | Linux（需要 systemd），也支持 Windows（见下方适配指南） |
+| **Ruby** | >= 3.0 |
+| **权限** | root（systemd 场景） |
+| **Minecraft 服务** | 已注册为 systemd 服务，默认服务名 `minecraft` |
+
+## 文件结构
+
+```
+/opt/minecraft/sentinel/   # 推荐部署目录
+└── src/                   # 源码目录
+    ├── 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/src
+cp src/main.rb src/method_executor.rb src/server_status_detector.rb src/systemd_notifier.rb src/config.rb src/updates.rb /opt/minecraft/sentinel/src/
+```
+
+### 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/src
+ruby main.rb
+# 调试模式：LOG_LEVEL=debug ruby main.rb
+```
+
+### 4. 注册 systemd 服务
+
+项目源码中已提供 `minesentinel.service`，直接复制：
+
+```bash
+cp src/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/src
+ExecStart=/usr/bin/ruby /opt/minecraft/sentinel/src/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 / 项目名称）保留所有权利，未经许可不得用于衍生项目。