🛠️ 狐糯糯管家系统使用说明书

狐糯糯管家系统 · 运维说明书

版本：v9.9.9　生成日期：2026-08-27 适用对象：超级管理员 / 运维人员服务器：124.222.143.14（root 登录凭据不公开，请联系管理员获取）

一、系统概览

管家系统是一套多机器人 QQ 群管理系统：一个后台面板集中管理多个 QQ 机器人（NapCat 实例）加入的所有群聊与功能开关。

1.1 组件与位置

组件	说明	位置 / 端口
前端	管理面板（nginx 托管静态文件）	`/guanjia/`
高级管理页	入群审核 / 邀请码 / 管理层级独立入口	`/guanjia/manage.html`
后端	Node.js 服务（pm2 进程 `guanjia-backend`）	代码 `/opt/hunono/hunuanguanjia/backend`，监听 `127.0.0.1:3456`
主数据库	SQLite（管家自己的业务库）	`/opt/hunono/hunuanguanjia/backend/data/hunuanguanjia.db`
机器人本体库	SQLite（机器人真正支持的功能清单）	docker 卷 `hunono-qq-bot-platform_backend-data/_data/hunono.db`
机器人接入层	NapCat 容器（每个 QQ 一个），OneBot HTTP 端口	`3000–3099` 段
机器人本体平台	hunono-qq-bot-platform（真正执行机器人逻辑）	docker 容器，仅托管主 bot `2971723646`

1.2 数据流

QQ 群  ──(NapCat 3000-3099)──►  guanjia 后端  ──►  hunono.db(功能真相源)
   ▲                                │  ▲
   └──── 机器人收发消息 ◄──────────┘  └── 每5分钟 AutoSync(发现+群+功能)

guanjia 负责「展示与管理」（群列表、功能开关、用户/权限分配）。
hunono-qq-bot-platform 负责「机器人真正的能力」（24 个真实功能）。
NapCat 是 QQ 协议接入层，每个登录的 QQ 占用一个 HTTP 端口。

二、三大自动同步（核心能力）

系统做到：机器人自己同步上来、QQ 群自己同步上来、功能也自己同步上来。三者均在后端每 5 分钟 AutoSync 自动完成，无需人工干预。

2.1 机器人自动同步（发现并入库）

机制：扫描本地 NapCat 端口段 3000–3099，对每个开放端口调用 /get_login_info 探活，与 bot_instances 表对比：
本地没有该 QQ → 自动新建 bot 实例入库；
本地已有 → 刷新在线状态 / 显示昵称。
同 QQ 多端口去重：若同一 QQ 在多个端口同时登录（冗余双登录），本轮只处理首个端口，不会重复建实例。
401 ≠ 离线：探测带本地 token，返回 401（鉴权失败）只算「鉴权问题」，绝不算离线，避免因 token 问题误判机器人掉线。
安全模式（重要）：自动同步走 noRemove=true，即发现不到的机器人只标记离线，绝不删除其群数据。详见第六节。

2.2 QQ 群自动同步

每个机器人自己加入的群，都会同步进它自己的群列表（修正了「机器人加了群却找不到」的历史 bug）。
多机器人并行抓取，按 group_id 去重合并。
每次同步重建 bot_group_relations（机器人与群的归属关系），保证「A 机器人加的群只显示在 A 名下」。

2.3 功能自动同步（只显示机器人有的功能）

后台读取机器人本体库 hunono.db 的 functions 表（机器人真正实现的 24 个功能，module_key/name）。
与 guanjia 的 functions 目录对齐：
机器人支持的功能 → is_active = 1（面板显示）；
机器人不支持的桩功能 → is_active = 0（面板永不显示）。
当前状态：启用 23 / 共 41 个功能（含平台自实现的「自动入群审核」）。机器人没有的功能，面板不会出现。
匹配规则：功能键（function_key）相同或中文名相同即视为支持（兼容 music↔song、bot_master↔admin_tools、check_in↔group_checkin 这类命名差异）。
机器人本体库临时不可读时跳过本次同步、保留原状，不会误把功能全关掉。

三、机器人分配模式（重点）

「分配」指把机器人实例分配给哪个用户使用，以及谁是这个 QQ 的主人、何时到期。

3.1 关键字段（`bot_instances` 表）

字段	含义
`assigned_to`	分配给的用户 ID（0 = 未分配 / 平台公有）
`owner_qq`	该机器人对应 QQ 的「主人」QQ 号
`expire_at`	使用到期时间（Unix 时间戳，0 = 永久）
`created_by`	创建者用户 ID
`notes`	备注

3.2 分配操作（仅超级管理员）

POST /api/bots/:id/assign
{ "user_id": 12, "expire_at": 0, "notes": "分配给张三" }

user_id = 0 表示收回分配。
收回时触发级联清理（文档 9.7）：自动删除该原用户在此机器所有群上的孤儿永久权限，避免脏数据残留。

3.3 主人绑定 / 到期设置

POST /api/bots/:id/owner    { "owner_qq": "2971723646" }   # 绑定 QQ 主人
POST /api/bots/:id/expire   { "expire_at": 0 }              # 0=永久
POST /api/bots/:id/expire   { "extend_days": 30 }           # 在原到期日上顺延

3.4 权限层级（谁能看/管哪些机器人）

角色	可见范围
`super_admin`（超管）	全部机器人，可分配 / 解绑 / 设到期
`admin`（管理员）	自己被分配的、或自己创建的机器人
`user`（普通用户）	仅 `assigned_to = 自己` 的机器人

普通用户对其他机器人调用 GET /api/bots/:id/groups 会返回 403 无权限。

3.5 当前机器人实例清单（4 个，全部在线）

ID	名称（库内）	实际 QQ 昵称	QQ 号	端口	群数	来源
1	狐糯糯Bot	狐绵绵	2971723646	3000	40	平台主 bot（hunono.db 托管）
3	二号Bot	只愿伴你身边	3065425710	3024	44	NapCat 容器
4	三号Bot	代梦琳	1951957282	3028	32	NapCat 容器
5	狐糯糯	狐糯糯	3833675805	3036	22	NapCat 容器（新 bot）

合计去重群 93 个。

四、群权限 & 功能权限分配

除「机器人→用户」分配外，系统还支持细粒度授权：

群权限分配：把某用户授权管理某个群。

POST /api/users/:id/group-permission（仅超管；目标须为普通用户；只能授自己有权限的群）

功能权限分配：把某用户授权使用某个功能。

POST /api/users/:id/function-permission（仅超管；目标须为普通用户）

两类授权均带权限校验，越权返回 403。

五、新机器人接入流程

5.1 标准接入（推荐）

在服务器上新建一个 NapCat 容器，监听某个 3000–3099 段内空闲端口，登录目标 QQ。
无需手动在面板建实例——后端每 5 分钟自动发现会扫到它并自动入库。
其功能会自动从机器人本体库对齐（全局 22 个功能目录），即「功能从旧 bot 弄过来」由系统保证。

5.2 端口检查决策（关键）

新 bot 接入时务必检查端口是否冗余：

若同一个 QQ 在多个端口都登录了（如本次新 bot 3833675805 同时登录 3007 与 3036），这是冗余双登录，只需保留 1 个端口。
决策原则：
优先保留 docker 托管的 NapCat 容器端口（如 3036，容器 napcat-inst1787750098574），因为它有自动重启、随 docker 自启；
杀掉原生手工启动的进程端口（如 3007），避免两个实例抢同一 QQ 造成消息/状态混乱。
已验证：3833675805 在机器人本体库 hunono.db 中无记录（它不属于平台托管 bot），因此杀掉原生 3007 不影响任何平台功能，主 bot（端口 3000）完全无影响。

5.3 验证新 bot 生效

# 在 guanjia 后端目录运行，确认自动发现无误删、无重复
node -e "require('./src/utils/bot-sync.js').discoverAndApplyBots({dryRun:false,noRemove:true}).then(r=>console.log('added',r.added,'removed',r.removed))"
# 检查群数
sqlite3 data/hunuanguanjia.db "SELECT COUNT(*) FROM bot_group_relations WHERE bot_qq=3833675805;"

六、运维与排障

6.1 重启后端

pm2 restart guanjia-backend
pm2 logs guanjia-backend --lines 30   # 查看启动日志，确认 [AutoSync] 正常

6.2 手动触发同步（按需）

# 机器人发现（默认安全：不删除，仅标记离线）
curl -X POST http://127.0.0.1:3456/api/bots/discover   # 需鉴权 token
# 仅当确实要清理已死机器人时，才加 forceRemove:true
# { "forceRemove": true }

# 功能同步（按机器人本体库重算 is_active）
curl -X POST http://127.0.0.1:3456/api/bots/sync-functions

6.3 日志限流

已装 pm2-logrotate：max_size=50M / retain=7 / compress，防止磁盘被日志打爆（曾因日志占用导致磁盘 86%）。

6.4 安全开关 `noRemove`（防误删）

历史踩坑：自动发现曾因 3024 端口 token 返回 401 被误判离线，级联删掉 44 个群。
修复后：
自动同步链路固定 noRemove=true，NapCat 短暂重启（端口瞬间关闭）不会误删任何机器人/群，仅标记离线；
手动 /discover 默认也安全，必须显式 forceRemove:true 才真删。
含义：宁可暂时「看不见」一个重启中的机器人，也绝不丢数据。

6.5 常见坑速查

现象	原因 / 处理
机器人加了群却不显示	旧 bug 已修；现每次同步重建归属关系。若仍异常，手动 `POST /api/bots/discover`
功能列表出现没实现的功能	桩功能已被 `is_active=0` 屏蔽；若仍显示，跑 `POST /api/bots/sync-functions` 重算
调接口返回 401	需带有效登录 token；不是功能故障
调云端 API 返回 429	触发频率限制，稍等重置后再调用，或减少调用次数
文档/COS 链接下载失败	签名链接有时效，过期需重新生成

七、本期新增能力（2026-08-27 第二轮 · 全部已上线并验证）

入口：登录后在 /guanjia/manage.html 使用「高级管理」页（自动入群审核 / 邀请码 / 管理层级三个标签页）。

7.1 自动入群审核（自动同意/拒绝新人入群）

机制：NapCat 上报 group_add_request 事件 → 后端风控引擎 src/utils/join-audit.js 实时评分。
判定逻辑：
黑名单 QQ → 直接拒绝；白名单 QQ → 直接同意；
风险累计：邀请人 1 小时内邀 >5 次 +25、留言含广告词 +40、24h 内多群申请 +20、QQ 等级 <8 +15、注册 <180 天 +15；
分数 ≥ 拒绝阈值(60) → 自动拒绝；分数 ≤ 同意阈值(-20) 且开启自动同意 → 自动同意；否则转人工（不自动操作，安全）。
配置：join_audit_config 支持全局 / Bot / 群三级覆盖（群 > Bot > 全局）；所有群默认已开启（93 个群 group_functions 均 is_enabled=1）。
管理 API：GET/PUT /api/join-audit/config、/lists 黑白名单、/logs 日志、/stats 统计、POST /api/join-audit/group/:id/toggle 群级开关。
端到端已验证：白名单用户→直接同意；普通用户→转人工；均正确写入 join_audit_log。

7.2 网页安全加固

隐藏 X-Powered-By（防技术栈指纹探测）；helmet 安全头已启用。
CORS 收紧：仅放行白名单来源（默认站点自身 + localhost），未知跨域来源一律拒绝；登录/注册接口强制 credentials 同源。
登录限流：/api/auth 限流 30 次/15 分钟（防爆破）；全局 /api/ 限流 500 次/15 分钟。
账号锁定：登录失败 5 次锁定 15 分钟（users.failed_attempts / locked_until）。
请求体大小限制 2MB，防大包攻击。

7.3 机器人稳定性加固（防腐控/防掉线）

callBotApi 增加全局最小调用间隔(120ms) + 并发上限(5) + 失败自动重试(2 次)，避免突发调用触发 QQ 风控。
配合既有的 noRemove 安全同步与心跳检测，4 个机器人实例稳定在线。

7.4 注册 / 绑定 / 注销

注册：POST /api/auth/register 必须绑定邮箱 + QQ，账号唯一校验（用户名/QQ/邮箱均不重复）。支持 invite_code 邀请码，用于归建下级。
注销：DELETE /api/auth/account 校验密码后释放账号，并级联清理 QQ 绑定、群/功能权限、操作日志、强制登出。

7.5 管理层级（多超管 / 上下级可见性）

树形结构：users.parent_id + users.path 物化路径实现「超管 → 管理 → 用户」三级。
多超管：角色 super_admin 可存在多个（当前 2 个）。
可见性规则（getUserScope）：
超管：看全部；管理：仅看自己及下级子树；
用户只看自己的上级管理，看不到其他用户；管理看自己的下级（各管理下级互不相同）。
新人注册：GET /api/users/new-registrations 超管看全部、管理看自己下级。
接口：/users/hierarchy（层级树）、/users/parent（我的上级）、/users/new-registrations（新人列表）。

7.6 邀请码（发展下级）

管理/超管可用 POST /api/invite-codes 生成邀请码（普通用户 / 管理员两种角色，可设次数与有效期）；GET 查看自己名下、DELETE 撤销。
新人注册时填邀请码 → 自动归入该管理名下（parent_id 指向邀请人）。

7.7 v4 条款落地

条款	状态	说明
8.4 冲突策略	✅	批量继承支持 `replace`(覆盖) / `merge`(合并) / `add_only`(仅新增，绝不关已有功能)
8.5 安全闸门	✅	批量继承支持 `dry_run` 预览；`replace` 覆盖 ≥11 个群需 `confirm:true` 二次确认
9.5 两层分配链	✅	用户生效权限 = 直接分配 ∪ 可见群已开启功能（两层继承）
9.11 全局功能共享	✅	`global_function_config` + `GET/PUT /api/functions/global` 管理
9.12 冲突裁决	✅	`GET /api/users/:id/functions/effective` 取最宽（任一来源允许即允许）

7.8 运维备注

超管密码：为完成本轮登录验证，superadmin 初始密码已通过后台 / 邮件单独下发，请尽快在面板修改或在数据库重置为强密码，切勿在公开渠道留存。
所有新功能后端代码已部署至 pm2 guanjia-backend 并重启验证；测试产生的白名单/日志/邀请码/临时授权已清理。

八、v5 新增能力（2026-08-27 第二轮）

8.1 9.6 临时跨组授权

为某个用户临时开放一个其原本无权访问的群（带有效期、可撤销），到期自动失效，不污染常驻权限。

数据表：temp_group_grants（user_id / group_id / granted_by / can_view / can_edit / expires_at / revoked）。
生效逻辑：/api/groups 可见群 = 常驻 user_group_permissions ∪ 有效临时授权（未撤销且未过期）。临时群带 is_temp_grant=1 与 temp_expires_at 标记。
接口：
POST /api/temp-grants：超管或管理授权（自动校验目标用户在授权者作用域内、授权者对该群有 can_edit）。
GET /api/temp-grants：超管看全部；管理看自己创建或作用域内下级。
GET /api/temp-grants/my：当前用户查看自己获得的临时授权。
DELETE /api/temp-grants/:id：撤销（仅创建者或超管）。
验证：以普通用户 TestUser 实测——被授权后其 /api/groups 出现目标群（is_temp_grant:1, can_edit:1）；撤销后该群从可见列表消失。

8.2 三角色独立后台（各登各的）

新增三个独立入口页面，按角色拆分管理视角的独立地址，用户无需挤在一个地址切换：

后台	地址	适用角色	可见模块
超管后台	`/guanjia/superadmin.html`	super_admin	全部：概览/群聊/成员/入群审核/邀请码/临时授权/管理层级/资料
管理后台	`/guanjia/admin.html`	admin	概览/群聊/成员(仅下级)/入群审核/邀请码/临时授权/管理层级/资料
用户后台	`/guanjia/user.html`	user	概览/群聊(含临时授权群)/我的上级/我的临时授权/资料

实现：共享 guanjia-console.js + 内联样式，三页面仅通过 window.CONSOLE_ROLE 区分入口；服务端始终以 JWT 角色强制鉴权，页面仅做 UX 分组，无越权风险。
登录态隔离：三角色页使用独立 localStorage 键 gc_token，与移动端 App（token）互不干扰，可同时登录不同角色。
功能：临时授权创建/列表/撤销（9.13–9.15）、邀请码生成/撤销、入群审核黑白名单与日志、管理层级树、上级信息、添加下级、注销账号均已接入真实接口。

管理发展下级：超管/管理在「成员管理 → +添加下级」创建用户，自动归入自己名下（parent_id 指向当前用户），形成上下级树。

本说明书由运维整理，覆盖截至 2026-08-27 的实际运行状态。如后续代码变更，以代码与数据库为准。

九、本期新增能力（2026-08-27 第三轮 · 全部已上线并验证）

实际访问地址说明：管理面板经 nginx 反代，对外入口为 https://hunuonuo.fun:8443/（HTTP 站点 /guanjia/ 仍可用，二者指向同一前端）。本期新增的子路径均挂在 8443 站点下。

9.1 统一扫码绑定页（自助接入新机器人）

入口：https://hunuonuo.fun:8443/bind/（或 /bind/nunu/、/bind/nuonuo/，前端按路径自动选定目标大脑）。
机制：超管登录后进入绑定页 → 选择目标机器人（狐糯糯 nunu / 诺诺 nuonuo）→ 后端拉起一个临时 NapCat 容器 → 容器通过反向 WebSocket 自动连接对应大脑（狐糯糯 ws://hunono-bot:8080；诺诺 ws://172.19.0.1:8094）→ 页面轮询展示二维码 → 用手机 QQ 扫码登录 → 登录成功后点「绑定」，系统把该 QQ 写入 bot_instances 并通知系统主人。
到期：扫码新建的实例默认 expire_at = 当前 + 30 天（可在绑定时传 expire_days 覆盖；0 表示永久）。
清理：会话 10 分钟无操作或取消时自动销毁临时容器，不残留。
接口：POST /api/bots/scan/start、GET /api/bots/scan/:token/qrcode、GET /api/bots/scan/:token/status、POST /api/bots/scan/:token/bind、POST /api/bots/scan/:token/cancel（均仅超管可调用）。
验证：nunu / nuonuo 两目标均实测「启动→出码→轮询→取消清理」全链路通过，二维码为合法 PNG。

9.2 bot 级订阅到期模型 + 到期提醒

数据模型：bot_instances.expire_at（Unix 时间戳，0 = 永久）已落地；扫码绑定与 POST /api/bots/:id/expire、extend_days 均可写入。
定时任务：后端启动后挂载 initExpiryCron()，每小时检查一次（源码 src/routes/expiry-cron.js）：
临近到期（≤3 天）：向机器人所有者 QQ、创建者 QQ、系统主人私聊预警，并标记 expire_notified=1（同周期只提醒一次）；
已过期：自动将实例 is_active 置 0（停用），并通知上述对象；
若到期日被顺延到 3 天以外，自动重置 expire_notified，便于下次再提醒。
覆盖：狐糯糯与诺诺两类实例统一由 bot_instances 管理，定时任务一视同仁。
验证：用测试数据实测「临期预警（expire_notified→1）」「过期自动停用（is_active→0）」均正确触发。

9.3 系统监控（Prometheus + Grafana · 已上线）

部署：docker-compose 在 /opt/hunono/monitoring，三个容器：

组件	镜像	端口	作用
node_exporter	prom/node-exporter	9100（host 网络）	主机 CPU / 内存 / 磁盘 / 网络
prometheus	prom/prometheus	9090	抓取并存储指标，路由前缀 `/prometheus`
grafana	grafana/grafana	3100→3000	可视化面板，子路径 `/grafana`

抓取目标：node_exporter（主机）、guanjia-backend（后端 /metrics）——两者均 up。
后端指标：src/routes/metrics.js 暴露 /metrics（Prometheus 文本格式），含 guanjia_up、guanjia_total_requests、guanjia_heap_used_bytes、guanjia_rss_bytes、guanjia_bot_instances、guanjia_bot_online、guanjia_bot_expired。
nginx 反代（8443 站点）：/grafana/ → 127.0.0.1:3100/grafana/、/prometheus/ → 127.0.0.1:9090/prometheus/。
默认面板：已导入「Guanjia Host & Backend Monitor」（uid guanjia-host），含 CPU/内存/磁盘/网络/后端运行指标。数据源 prometheus 已自动配置。
登录凭据：Grafana 管理员 admin / 初始密码已通过邮件单独下发（请按需修改，切勿在公开渠道留存）。
访问：https://hunuonuo.fun:8443/grafana/、https://hunuonuo.fun:8443/prometheus/。

9.4 账号体系补全（双端已上线）

登录错误提示修正：密码错误返回「密码错误」、账号错误返回「账号错误」，不再误报「登陆超时/登录已过期」（前端直接展示后端文案）。
多 SMTP 发信：后端 utils/email.js 支持 qq / kzy / zxz 三个发信账号并自动回退；新增 sendAccountMail / sendCodeMail / sendResetEmail。
KZY 邮箱：baishiyu@kzyun.tech（KZY，此前误写为 kzy.tech）现已可发信——A / MX / SPF 已生效，SMTP 鉴权与真实测试邮件均通过（250 Ok: queued）。建议补 DKIM / DMARC 进一步优化外部到达率。
找回/重置：POST /api/auth/retrieve-account（按邮箱或 QQ 找回账号）、POST /api/auth/forgot-password（发重置邮件）均已上线并在前端接入。
绑定邮箱 / 绑定 QQ（新增邮箱验证码路径）：绑定 QQ 现支持两套机制——① 加机器人好友获取随机验证码（原机制）；② 用绑定邮箱获取随机验证码（POST /api/bind/send-code-email + POST /api/bind/confirm）。绑定邮箱同样发验证码/链接到邮箱。
三超管账号已建并绑定：superadmin(2391947486)、Hunuonuo(108888126)、Humianmian(16672616)，密码邮件已发送。

9.5 双机器人守卫（狐糯糯 + 诺诺）

陌生人强行拉群自动退群：bot_status 插件检测到「非好友且非主人」拉自己入群时，自动 set_group_leave 退群，并通知主人：

主人，陌生人（3065425710）拉我强行进入「三号云端」群，已自动退群\n时间：2026-08-26 22:57:50

狐糯糯走 notify_masters、诺诺走 notify_owners_and_group，双脑一致；无法判定时保守不误退。

临时主人踢人冲突守卫：临时主人（rental / temp_owner 体系）试图踢系统主人或原租用者时，指令被拦截并提示无权限；狐糯糯在 admin_tools 的「踢」指令加 _temp_owner_kick_guard，诺诺在 temp_owner 插件加守卫，双脑均已部署重启验证。
诺诺成为群主通知 / 临时主人添加提醒：诺诺 bot_status 与 temp_owner 在上线/绑定临时主人时向系统主人推送通知，已上线。

十、本期新增能力（2026-08-27 第四轮 · 全部已上线并验证）

本轮目标：在既有 QQ 通知之外，补齐「邮件」这条兜底通道，让掉线 / 到期 / 临时主人三类事件都能同时通知系统主人；并为监控栈补齐报警规则与邮件报警。

10.1 掉线邮箱提醒（独立周期检测）

新增文件：src/routes/offline-monitor.js，后端启动后由 initOfflineMonitor() 挂载（见 app.js 442–443 行）。
机制：每小时遍历 bot_instances，对比 is_online 状态：
掉线：向 3 位系统主人发邮件 + 已有 QQ 通知（复用 sendToSuperAdmins）；
恢复：再次发「已恢复」通知，避免静默。
防误报：沿用第二节的 noRemove/心跳逻辑——NapCat 短暂重启或 401 鉴权问题不判掉线，只在确实离线时告警。

10.2 到期提醒补邮件通道

src/routes/expiry-cron.js 在原有「QQ 私聊预警所有者/创建者/系统主人」之外，新增 sendExpiryMails()：
向超管邮箱 + 机器人所有者邮箱发信；
覆盖两类事件：临近到期（≤3 天） 与 已过期自动停用（is_active→0）；
临期标记 expire_notified=1 避免重复，顺延到 3 天外自动重置。

10.3 临时主人提醒补邮件通道

后端接口：POST /api/app/bot/notify-email（位于 src/routes/bot-api.js），botTokenAuth 鉴权（仅 bot 插件持 BOT_ACCESS_TOKEN=huonono-bot-secret 可调用），向 3 位系统主人发邮件。
插件侧：
诺诺 temp_owner 插件：绑定 / 取消临时主人分支在 QQ 通知后，额外调用该接口；
狐糯糯 rental 插件（hunono-bot 容器内 /app/plugins/rental/__init__.py）：绑定 / 取消临时主人时同步调用。
三方令牌统一为 huonono-bot-secret；容器内走 172.19.0.1:3456、诺诺宿主走 127.0.0.1:3456。

10.4 Prometheus + Grafana 报警规则（已上线）

Prometheus 规则：/opt/hunono/monitoring/prometheus/alerts.yml（5 条，已加载评估，组名 host-health）：

规则	触发条件
`HostCpuHigh`	主机 CPU > 80% 持续 2m
`HostMemoryHigh`	主机内存 > 85% 持续 2m
`HostDiskHigh`	主机磁盘 > 85% 持续 2m
`NodeExporterDown`	node_exporter 失联 1m
`GuanjiaBackendDown`	guanjia 后端 `/metrics` 失联 1m

Grafana 报警通道（unified alerting 已启用）：
邮件联系点 email-owners：收件人 3 位系统主人（2391947486@qq.com;108888126@qq.com;16672616@qq.com），发件 baishiyu@zhangxiaozhu.cn；
通知策略：group_wait 30s / group_interval 5m / repeat_interval 1h；
联系点与策略均通过 Grafana provisioning API 创建（因 Grafana 13 对 grafana 数据源的 ruler API 有 RBAC 限制，报警规则用 Prometheus 侧 alerts.yml 承载，Grafana 负责可视化 + 邮件通道 + 通知策略）。
效果：主机/后端异常 → Prometheus 触发 → Grafana 邮件联系点发信给系统主人。

10.5 KZY 邮箱整改说明（已解决 + 优化建议）

已解决：实际发信域名为 baishiyu@kzyun.tech（此前误写为 kzy.tech）。kzyun.tech 的 A / MX / SPF 记录已生效，后端 SMTP_USER_KZY 已更正为 baishiyu@kzyun.tech，SMTP 鉴权与一封真实测试邮件均已通过（250 Ok: queued）。
现有兜底：后端多 SMTP（qq / kzy / zxz）自动回退；三类关键提醒（掉线 / 到期 / 临时主人）邮件通道当前走 ZXZ，现 kzy 也可用，二者任选其一即可。
优化建议（非阻塞）：为 kzyun.tech 补 DKIM（qq._domainkey TXT，值从腾讯企业邮后台获取）与 DMARC（_dmarc TXT）记录，可显著提升发往 QQ / 163 / Gmail 等外部邮箱的到达率（避免进垃圾箱）；并确认 CNAME 验证记录 qqmail68491757 → mail.qq.com 已落在 kzyun.tech 解析区。