功能简介

学院的各类 QQ 通知（监考通知、信息发送、催办等）都通过本学院的 QQ 机器人发送，每个学院使用一台机器人。机器人管理分两部分：

• 学院管理员：状态查看与日常维护。页面右上角「QQbot」按钮随时显示本学院机器人是否在线；离线时可自行启动/重启，在「QQbot 维护中心」获取扫码二维码重新登录、查看近期日志、更改安全码。
• 超级管理员：登记与开通（半自助）。在「QQ机器人管理」页为学院登记机器人 QQ、下发令牌、获取二维码；在旧服务器上起机器人容器仍由运维执行页面给出的固定命令，本系统不直接操作容器。学院管理员不能自行登记或更换机器人 QQ。

以前保存学院或安全码时，系统会用学院管理员的 QQ 自动建一条机器人记录，形成「占位记录」（容器名是学院代码，如 napcat_jy），这类记录发不出消息。现在系统不再自动建立或改写机器人 QQ，统一由超管登记。

系统有两种部署模式，页面按模式显示不同入口：远端中继模式（机器人跑在旧服务器，维护指令由旧服务器领取执行）和本机直连模式（机器人与系统在同一服务器，用 NapCat WebUI 维护）。另有部署可能未启用 QQ 通知。

入口与权限

• QQbot 状态按钮：页面右上角「QQbot」，学院管理员和超级管理员可见（质量科代管代登录态下隐藏）。机器人图标亮起表示在线、变暗表示离线。
• QQbot 维护中心（/college/qqbot-maintenance，远端中继模式）：从「QQbot」下拉进入，学院管理员与超管可用，只能维护当前学院的机器人。
• QQ机器人安全码设置（/college/napcat-settings，本机直连模式）：从「QQbot」下拉进入，学院管理员与超管可用。
• QQ机器人管理（/admin/qqbots，仅超级管理员）：「用户管理」→「学院及部门管理」→ 目标学院「详情」→「机器人登记与开通」（会带 ?focus=<学院 id> 自动定位并高亮该学院行）；一次处理多个学院时点「学院及部门管理」页右上角「QQ机器人批量维护」。2026-09-20 起顶部菜单不再单列「QQ机器人管理」，旧地址仍可直接访问与收藏。学院管理员访问返回 403。
• 代登录会话：「QQ机器人管理」页只读，登记、下发令牌、获取二维码按钮不显示，手工提交也会被拒绝。
• 系统配置禁用机器人管理入口时，下拉中的相关项显示「（系统配置暂时禁用）」且不可点。

操作步骤（分角色）

学院管理员：查看机器人状态

1. 点右上角「QQbot」按钮。
2. 在下拉菜单查看「当前状态」（在线 / 离线）和「机器人QQ」；显示「未绑定」表示本学院尚未登记机器人。
3. 若提示「当前学院尚未设置QQ机器人安全码」，需先完成安全码设置。

图中标记：① 右上角「QQbot」按钮。图中为本机直连模式且学院尚未登记机器人的状态，因此「启动/重启（待配置）」和「登录管理界面」不可用。

下拉菜单各项：

学院管理员：启动、重启与扫码登录（远端中继模式）

1. 机器人离线时，在「QQbot」下拉点「启动」；在线但发送异常时点「重启」，在确认框点「确认执行」。
2. 仍离线时点「QQbot 维护中心」（或「扫码登录与日志」），进入维护中心页。
3. 在「运行状态」卡片查看 QQ 状态（在线 / 离线 / 维护中 / 中继失联 / 未启用）和旧机中继心跳。
4. 点「获取扫码二维码」，用机器人 QQ 所在手机扫码登录。二维码只临时保留几分钟，过期请重新获取。
5. 需要排查时点「查看近期日志」，显示已脱敏的 NapCat 近期日志。
6. 页面下方「最近维护记录」列出最近 8 条指令的时间、动作、状态、操作者与结果。
7. 状态恢复为「在线」后再发送消息。

• 维护中心「更改安全码」卡片：输入不少于 10 位的新安全码，点「提交并同步到旧机」。新安全码加密暂存，只有旧服务器写入成功后才正式切换。更改安全码会影响机器人与系统的连接，非必要不要修改。
• 当前学院未登记机器人时，维护中心提示「当前学院尚未绑定 QQbot」，请联系超级管理员登记。
• 显示「中继失联」（旧机中继心跳超时）时学院侧无法自行恢复，请联系超级管理员检查。
• 同一台机器人的维护指令串行执行，上一条未完成时会提示「该机器人已有维护指令等待执行，请稍后再试」。

学院管理员：本机直连模式

• 在「QQ机器人安全码设置」页填写「QQ机器人安全码（不少于10位的字母、符号、数字组合）」，点「保存安全码」。学院尚未维护简称时按钮不可用，需超管先在学院管理中维护学院简称。
• 学院尚未登记机器人时，保存安全码会提示「当前学院尚未登记 QQ 机器人……请由超管在「QQ机器人管理」登记」。
• 扫码登录通过「登录管理界面」进入 NapCat WebUI。

超级管理员：为学院登记并开通机器人（远端中继模式）

1. 进入「QQ机器人管理」，找到目标学院行。没有机器人记录时「状态」显示「未登记」。
2. 在该行「操作」列填写机器人 QQ（5–12 位纯数字，不以 0 开头），点「登记」（已有记录时为「覆盖登记」），在确认框点确定。

• 学院已有记录：原位覆盖同一条记录，写入新 QQ，容器名改为 napcat_<QQ>，状态重置为「离线」，清空最近上报时间，备注写入「超管登记 <账号> <时间>（原 qq_id=<旧 QQ>）」。
• 学院没有记录：新建一条记录，备注写「超管登记 <账号> <时间>（新建）」。
• 同一 QQ 重复登记不会重置状态，提示「无需重复登记」。

3. 登记成功后，该行显示「旧机命令」，例如 sudo bash /opt/qq-relay/napcat-provision.sh <QQ> <学院id>，交给运维在旧服务器执行。
4. 刷新页面，等「最近上报（北京时间）」出现时间、「状态」下方不再显示「旧机未上报」，表示旧机已登记该机器人。
5. 点「下发令牌」并确认。仅在扫码登录前执行；已登录的机器人执行会重启容器，可能掉登录。「状态」下方显示「最近指令 #编号 rotate_token/状态」，变为 succeeded 后令牌才正式切换。
6. 点「获取二维码」并确认（会重启该机器人容器）。页面上方出现二维码卡片，用该 QQ 的手机扫码登录；二维码只临时保留约 3 分钟。
7. 状态变为「在线」后，学院即可正常发送 QQ 通知；催办等功能按各自页面继续开启。

登记、下发令牌都会写操作日志（模块「QQ机器人」，落系统默认库），可在 操作日志查询 查询。

超级管理员：本机直连模式或未启用 QQ 通知

页面顶部提示当前模式，只提供登记，不显示「下发令牌」「获取二维码」。安全码请在学院「QQ机器人安全码设置」维护，扫码登录走 NapCat WebUI。

字段与状态口径

「QQ机器人管理」页列为「学院」「机器人 QQ」「容器名」「状态」「最近上报（北京时间）」「操作」。

常见问题

• 机器人显示在线，但部分老师收不到消息：多为该老师在教师信息库中没有 QQ 号或号码有误，或未添加机器人为好友。可在操作日志的「查看明细」看失败原因，补全信息后重发。
• 「启动/重启」是灰色的：显示「启动/重启（待配置）」表示本学院尚未登记机器人，请联系超级管理员。
• 学院管理员能不能自己换机器人 QQ：不能，机器人登记与更换由超级管理员完成。
• 登记提示「已被某学院的机器人记录占用」：一个机器人 QQ 只能登记给一个学院，先核对是否填错，或先处理对方学院的记录。
• 登记提示「名下仍有未完成的发件/维护命令」：原记录的 QQ 下还有 pending 或 leased 状态的发件或维护指令，覆盖后会永久挂起，请先由运维处置再登记。
• 「下发令牌」「获取二维码」是灰色：旧机尚未上报该机器人（运维未执行旧机命令或中继未重启），或 QQ 中继令牌未配置。
• 下发令牌提示「已有维护指令未完成」：同一机器人的维护指令串行执行；上一条结果未知（unknown）时也会阻止再次下发，需先确认机器人状态。
• 登记时提示正在备份：备份窗口内登记与令牌下发可能被拦截，等备份结束后再操作。

相关页面

• 用户管理 「学院及部门管理」维护学院本身，并从学院详情进入机器人登记
• 信息发送 机器人在线后，信息发送与各类通知才能送达
• 首页与导航 顶部导航与 QQbot 状态按钮的位置
• 操作日志查询 机器人登记、令牌下发、远程维护指令都会记日志