koishi-plugin-mc-manager

多群多宿主 Minecraft 服务器管理插件。一个 Koishi 实例管理多个 QQ 群，每个群绑定宿主机，通过 mc 切换 指定要开哪个服务器，互不影响。

功能

| 指令 | 说明 | | --- | --- | | 原神启动 | 启动本群当前绑定的服务器 | | mc 人数 / mc | 查询在线人数与玩家名单 | | mc 状态 | 查看服务器运行状态（可选） | | mc 关服 | 手动停止服务器（可选） | | mc 列表 | 列出搜索文件夹下探测到的所有服务器（✓=当前） | | mc 切换 <服务器名> | 切换本群运行哪个服务器（不带参数则列出可用服务器） | | mc 部署 | 手动重新部署/更新宿主机上的对接脚本 | | mc 指令 [目标] | 私聊：进入指令模式，之后私聊内容作为 MC 控制台命令（RCON）执行 | | mc 指令结束 | 私聊：手动退出指令模式 | | （无需指令） | 持续无人超过设定秒数后自动 RCON stop 关服 |

私聊指令模式

在私聊里发 mc 指令 进入远程控制台模式（目标由配置页 privateUsers/privateDefault 决定，不用带群名）：

你私聊：mc 指令
机器人私回：✅ 已进入私聊指令模式，将作用于「xxx」（宿主机 mac）...

你私聊：say 大家好
→ 服务器控制台执行：say 大家好（RCON）

你私聊：list
→ 返回服务器在线玩家

你私聊：mc 人数 / mc 状态 / mc 关服 / 原神启动
→ 管理指令同样可用（作用于该目标）

你私聊：mc 指令结束    ← 手动退出
或空闲 10 分钟自动退出

要点：

• 只有 authorizedUsers 里填的 QQ 号能用（留空则私聊指令模式禁用）。
• 目标解析：mc 指令 box 用绑定名/群号；mc 指令 用 privateDefault（或唯一绑定）。
• 直接发普通文字会当作 MC 控制台命令（RCON） 执行并返回输出。
• 最后一条指令后空闲 privateTimeout 秒自动退出。

设计：只填一个文件夹

宿主机上你只需配置一个搜索文件夹，服务器就放在它下面的子文件夹里，不需要任何快捷方式：

搜索文件夹 /Users/lzc2006/opt/mc/
  ├── ATM10/run.sh      ← 一个服务器
  ├── CTI/run.sh        ← 又一个服务器
  └── NEOMOD/run.sh     ← 新添加的服务器，自动被探测到

• 插件扫描搜索文件夹的一级子文件夹，找 run.sh（macOS/Linux）或 run.bat（Windows）
• 服务器名 = run 脚本所在文件夹名（如 ATM10、NEOMOD）
• 新添加的服务器会被 mc 列表 自动列出，并默认作为新默认值（默认取最新添加的）

指定运行哪个服务器

三个机制，优先级从高到低：

1. 配置页 server：绑定的 server 字段填了名字就固定跑那个服务器（mc 切换 会被忽略并提示）。
2. mc 切换 <服务器名>：运行时切换本群服务器，选择会持久化（重启不丢）。
3. 默认：都没指定时，取最新添加的服务器（按 run 脚本修改时间）。

群A：mc 列表  → 看到 ATM10 / CTI / NEOMOD
群A：mc 切换 NEOMOD  → 以后 原神启动 就开 NEOMOD

Windows 原生适配（无需 Git Bash）

插件自动探测宿主机默认 shell：

• POSIX（macOS/Linux）→ 用 bash/python。
• Windows（cmd 或 PowerShell）→ 改用 PowerShell 原生命令执行所有操作，全部通过 powershell -EncodedCommand（base64）发送，不需要装 Git Bash、不需要改 sshd 默认 shell。
• Windows 管理脚本生成 .ps1，服务器用 run.bat。
• Windows 启动服务器通过「计划任务」拉起（Register-ScheduledTask + Start-ScheduledTask）：Task Scheduler 服务下运行、脱离 SSH 会话，否则 SSH 断开时 OpenSSH 会连坐杀掉服务器进程。
• 所有 PowerShell 脚本统一 $ProgressPreference='SilentlyContinue'，避免进度流（CLIXML）污染输出。

配置说明

宿主机 hosts

| 字段 | 说明 | | --- | --- | | id | 宿主机唯一标识（英数字） | | name | 宿主机显示名 | | hostname | SSH 地址 | | port | SSH 端口（默认 22） | | username | SSH 用户名 | | password | SSH 密码（与私钥二选一） | | privateKey | SSH 私钥内容 | | searchFolder | 搜索文件夹：里面放各服务器子文件夹，如 /Users/lzc2006/opt/mc | | platform | 宿主机系统：auto=自动检测 / windows / macos / linux（默认 auto） | | autoDeploy | 首次使用自动部署对接脚本（默认 true） | | countdownMinutes | 服务器停止后进入系统休眠的倒计时分钟数（仅 POSIX，默认 30；0=不休眠） | | frpcPath | frpc 可执行文件路径（留空不启用，仅 POSIX） | | rebootBeforeStart | 仅 Windows：启动服务器前先重启宿主机（默认 false） | | rebootCommand | 重启命令（留空默认 shutdown /r /t 0） | | rebootTimeout | 等待重启完成的最长时间秒数（默认 300） | | rconPort | RCON 端口（留空自动读 server.properties） | | rconPassword | RCON 密码（留空自动读 server.properties） |

群绑定 bindings

| 字段 | 说明 | | --- | --- | | groupName | 群名（展示；也用于按名匹配） | | groupId | 群号（精确匹配，优先于群名，建议填写） | | hostId | 绑定的宿主机 ID | | server | 服务器名（文件夹名，可留空；填了则固定跑这个） |

匹配顺序：先按群号 session.channelId 精确匹配 groupId；未命中再用群名 session.event.group_name 匹配 groupName。

全局

• authorizedUsers：允许私聊使用 mc 指令 的 QQ 号（留空则私聊指令模式禁用）
• privateUsers：私聊指令模式的目标表：用户QQ → 目标绑定名/群号。配置后该用户私聊发 mc 指令 就直接用这个目标，不用再带群名
• privateDefault：兜底默认目标（绑定名/群号；privateUsers 没配的用户、且只有一个绑定时用它）
• privateTimeout：私聊指令模式空闲超时秒数（默认 600 = 10 分钟）
• emptyThreshold：无人自动关服等待秒数（默认 600 = 10 分钟）
• checkInterval：人数检测间隔秒数（默认 30）
• forceDefaultPort：路径变化时是否强制 server-port=25565（默认 true）

对接脚本自动部署

插件会在 searchFolder/mc-manager/ 生成管理脚本，按平台自动选格式：

• macOS / Linux：check_mc_status.sh + start_mc.sh
• Windows：check_mc_status.ps1 + start_mc.ps1

脚本读取同目录 server_current.conf，插件每次开服自动把该文件写成目标服务器目录，从而一个脚本任意切换服务器。缺失或首次使用自动部署；mc 部署 可强制重装。

前置要求

• 宿主机可通过 SSH 访问。
  • macOS/Linux：默认 shell 是 POSIX，装有 python3。
  • Windows：默认 shell 是 cmd/PowerShell 均可（插件自动用 PowerShell）；MC 目录需有 run.bat。
• 在线人数 / 自动关服依赖 RCON：插件每次启动都会自动确保 enable-rcon=true、rcon.port=25575、server-port=25565；新服 RCON 密码为空时自动写入默认值 koishi_mc（可在宿主机配置 rconPassword 指定）。已有密码的服务器不会被覆盖。

启动前重启宿主机（rebootBeforeStart，仅 Windows）

只对 Windows 宿主机生效。原神启动 时先发送重启命令（默认 shutdown /r /t 0），轮询等待 SSH 恢复（最长 rebootTimeout 秒），再启动服务器。非 Windows 勾选会提示并跳过，不会误重启。

要求：Windows 的 OpenSSH Server（sshd）必须设为开机自启，否则重启后连不回来会超时。

已知说明

• 服务器子文件夹建议放在搜索文件夹的一级目录（搜索文件夹/服务器名/run.sh）。
• 同一宿主机同一时间建议只开一个服务器（mc-manager/ 下的对接脚本是共享的）。
• 后台自动关服通知依赖 groupId 能定位到群；只填 groupName 时关服仍会执行但可能无法通知（建议绑定填群号）。
• autoDeploy 默认开启：会把宿主机上缺标记的旧脚本覆盖为插件版本。
• 「mc 切换」的选择持久化到 Koishi 数据库；若未配置数据库插件则仅内存保存（重启后丢失）。