nonebot-plugin-ruok 0.2.0__tar.gz → 0.3.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (64) hide show
  1. nonebot_plugin_ruok-0.2.0/README.md → nonebot_plugin_ruok-0.3.0/PKG-INFO +73 -10
  2. nonebot_plugin_ruok-0.2.0/PKG-INFO → nonebot_plugin_ruok-0.3.0/README.md +49 -31
  3. nonebot_plugin_ruok-0.3.0/pyproject.toml +158 -0
  4. nonebot_plugin_ruok-0.2.0/pyproject.toml → nonebot_plugin_ruok-0.3.0/pyproject.toml.orig +9 -4
  5. {nonebot_plugin_ruok-0.2.0 → nonebot_plugin_ruok-0.3.0}/src/nonebot_plugin_ruok/__init__.py +37 -14
  6. {nonebot_plugin_ruok-0.2.0 → nonebot_plugin_ruok-0.3.0}/src/nonebot_plugin_ruok/api.py +19 -10
  7. {nonebot_plugin_ruok-0.2.0 → nonebot_plugin_ruok-0.3.0}/src/nonebot_plugin_ruok/collector.py +81 -22
  8. {nonebot_plugin_ruok-0.2.0 → nonebot_plugin_ruok-0.3.0}/src/nonebot_plugin_ruok/collectors/__init__.py +4 -0
  9. {nonebot_plugin_ruok-0.2.0 → nonebot_plugin_ruok-0.3.0}/src/nonebot_plugin_ruok/collectors/metrics.py +53 -6
  10. {nonebot_plugin_ruok-0.2.0 → nonebot_plugin_ruok-0.3.0}/src/nonebot_plugin_ruok/collectors/modules.py +117 -72
  11. nonebot_plugin_ruok-0.3.0/src/nonebot_plugin_ruok/collectors/monitor.py +507 -0
  12. {nonebot_plugin_ruok-0.2.0 → nonebot_plugin_ruok-0.3.0}/src/nonebot_plugin_ruok/collectors/notifications.py +120 -25
  13. {nonebot_plugin_ruok-0.2.0 → nonebot_plugin_ruok-0.3.0}/src/nonebot_plugin_ruok/collectors/sessions.py +243 -134
  14. nonebot_plugin_ruok-0.3.0/src/nonebot_plugin_ruok/collectors/storage.py +59 -0
  15. {nonebot_plugin_ruok-0.2.0 → nonebot_plugin_ruok-0.3.0}/src/nonebot_plugin_ruok/config.py +8 -3
  16. {nonebot_plugin_ruok-0.2.0 → nonebot_plugin_ruok-0.3.0}/src/nonebot_plugin_ruok/webui/auth.py +52 -12
  17. {nonebot_plugin_ruok-0.2.0 → nonebot_plugin_ruok-0.3.0}/src/nonebot_plugin_ruok/webui/router.py +29 -18
  18. {nonebot_plugin_ruok-0.2.0 → nonebot_plugin_ruok-0.3.0}/src/nonebot_plugin_ruok/webui/sse.py +15 -4
  19. {nonebot_plugin_ruok-0.2.0 → nonebot_plugin_ruok-0.3.0}/src/nonebot_plugin_ruok/webui/templates/_users_panel.html.jinja2 +9 -4
  20. {nonebot_plugin_ruok-0.2.0 → nonebot_plugin_ruok-0.3.0}/src/nonebot_plugin_ruok/webui/templates/dashboard.html.jinja2 +27 -11
  21. {nonebot_plugin_ruok-0.2.0 → nonebot_plugin_ruok-0.3.0}/src/nonebot_plugin_ruok/webui/templates/dashboard_user.html.jinja2 +5 -1
  22. nonebot_plugin_ruok-0.2.0/src/nonebot_plugin_ruok/collectors/monitor.py +0 -231
  23. {nonebot_plugin_ruok-0.2.0 → nonebot_plugin_ruok-0.3.0}/src/nonebot_plugin_ruok/chat_render.py +0 -0
  24. {nonebot_plugin_ruok-0.2.0 → nonebot_plugin_ruok-0.3.0}/src/nonebot_plugin_ruok/collectors/trackers.py +0 -0
  25. {nonebot_plugin_ruok-0.2.0 → nonebot_plugin_ruok-0.3.0}/src/nonebot_plugin_ruok/protocol.py +0 -0
  26. {nonebot_plugin_ruok-0.2.0 → nonebot_plugin_ruok-0.3.0}/src/nonebot_plugin_ruok/webui/jinja.py +0 -0
  27. {nonebot_plugin_ruok-0.2.0 → nonebot_plugin_ruok-0.3.0}/src/nonebot_plugin_ruok/webui/static/vendor/chartjs/LICENSE.md +0 -0
  28. {nonebot_plugin_ruok-0.2.0 → nonebot_plugin_ruok-0.3.0}/src/nonebot_plugin_ruok/webui/static/vendor/chartjs/chart.umd.min.js +0 -0
  29. {nonebot_plugin_ruok-0.2.0 → nonebot_plugin_ruok-0.3.0}/src/nonebot_plugin_ruok/webui/static/vendor/htmx/LICENSE +0 -0
  30. {nonebot_plugin_ruok-0.2.0 → nonebot_plugin_ruok-0.3.0}/src/nonebot_plugin_ruok/webui/static/vendor/htmx/htmx.min.js +0 -0
  31. {nonebot_plugin_ruok-0.2.0 → nonebot_plugin_ruok-0.3.0}/src/nonebot_plugin_ruok/webui/static/vendor/idiomorph/LICENSE +0 -0
  32. {nonebot_plugin_ruok-0.2.0 → nonebot_plugin_ruok-0.3.0}/src/nonebot_plugin_ruok/webui/static/vendor/idiomorph/idiomorph-ext.min.js +0 -0
  33. {nonebot_plugin_ruok-0.2.0 → nonebot_plugin_ruok-0.3.0}/src/nonebot_plugin_ruok/webui/static/vendor/pico/LICENSE.md +0 -0
  34. {nonebot_plugin_ruok-0.2.0 → nonebot_plugin_ruok-0.3.0}/src/nonebot_plugin_ruok/webui/static/vendor/pico/pico.min.css +0 -0
  35. {nonebot_plugin_ruok-0.2.0 → nonebot_plugin_ruok-0.3.0}/src/nonebot_plugin_ruok/webui/templates/_auth_shell.html.jinja2 +0 -0
  36. {nonebot_plugin_ruok-0.2.0 → nonebot_plugin_ruok-0.3.0}/src/nonebot_plugin_ruok/webui/templates/_dashboard_connections.html.jinja2 +0 -0
  37. {nonebot_plugin_ruok-0.2.0 → nonebot_plugin_ruok-0.3.0}/src/nonebot_plugin_ruok/webui/templates/_dashboard_disk.html.jinja2 +0 -0
  38. {nonebot_plugin_ruok-0.2.0 → nonebot_plugin_ruok-0.3.0}/src/nonebot_plugin_ruok/webui/templates/_dashboard_hero.html.jinja2 +0 -0
  39. {nonebot_plugin_ruok-0.2.0 → nonebot_plugin_ruok-0.3.0}/src/nonebot_plugin_ruok/webui/templates/_dashboard_metrics.html.jinja2 +0 -0
  40. {nonebot_plugin_ruok-0.2.0 → nonebot_plugin_ruok-0.3.0}/src/nonebot_plugin_ruok/webui/templates/_dashboard_stats.html.jinja2 +0 -0
  41. {nonebot_plugin_ruok-0.2.0 → nonebot_plugin_ruok-0.3.0}/src/nonebot_plugin_ruok/webui/templates/_dashboard_system.html.jinja2 +0 -0
  42. {nonebot_plugin_ruok-0.2.0 → nonebot_plugin_ruok-0.3.0}/src/nonebot_plugin_ruok/webui/templates/_dashboard_trends.html.jinja2 +0 -0
  43. {nonebot_plugin_ruok-0.2.0 → nonebot_plugin_ruok-0.3.0}/src/nonebot_plugin_ruok/webui/templates/_linked_list.html.jinja2 +0 -0
  44. {nonebot_plugin_ruok-0.2.0 → nonebot_plugin_ruok-0.3.0}/src/nonebot_plugin_ruok/webui/templates/_module_form.html.jinja2 +0 -0
  45. {nonebot_plugin_ruok-0.2.0 → nonebot_plugin_ruok-0.3.0}/src/nonebot_plugin_ruok/webui/templates/_modules_table.html.jinja2 +0 -0
  46. {nonebot_plugin_ruok-0.2.0 → nonebot_plugin_ruok-0.3.0}/src/nonebot_plugin_ruok/webui/templates/_notification_form.html.jinja2 +0 -0
  47. {nonebot_plugin_ruok-0.2.0 → nonebot_plugin_ruok-0.3.0}/src/nonebot_plugin_ruok/webui/templates/_notifications_list.html.jinja2 +0 -0
  48. {nonebot_plugin_ruok-0.2.0 → nonebot_plugin_ruok-0.3.0}/src/nonebot_plugin_ruok/webui/templates/_session_card.html.jinja2 +0 -0
  49. {nonebot_plugin_ruok-0.2.0 → nonebot_plugin_ruok-0.3.0}/src/nonebot_plugin_ruok/webui/templates/_session_container.html.jinja2 +0 -0
  50. {nonebot_plugin_ruok-0.2.0 → nonebot_plugin_ruok-0.3.0}/src/nonebot_plugin_ruok/webui/templates/_sessions_list.html.jinja2 +0 -0
  51. {nonebot_plugin_ruok-0.2.0 → nonebot_plugin_ruok-0.3.0}/src/nonebot_plugin_ruok/webui/templates/_user_sessions.html.jinja2 +0 -0
  52. {nonebot_plugin_ruok-0.2.0 → nonebot_plugin_ruok-0.3.0}/src/nonebot_plugin_ruok/webui/templates/base.html.jinja2 +0 -0
  53. {nonebot_plugin_ruok-0.2.0 → nonebot_plugin_ruok-0.3.0}/src/nonebot_plugin_ruok/webui/templates/chat_session_list.html.jinja2 +0 -0
  54. {nonebot_plugin_ruok-0.2.0 → nonebot_plugin_ruok-0.3.0}/src/nonebot_plugin_ruok/webui/templates/chat_status.html.jinja2 +0 -0
  55. {nonebot_plugin_ruok-0.2.0 → nonebot_plugin_ruok-0.3.0}/src/nonebot_plugin_ruok/webui/templates/login.html.jinja2 +0 -0
  56. {nonebot_plugin_ruok-0.2.0 → nonebot_plugin_ruok-0.3.0}/src/nonebot_plugin_ruok/webui/templates/modules.html.jinja2 +0 -0
  57. {nonebot_plugin_ruok-0.2.0 → nonebot_plugin_ruok-0.3.0}/src/nonebot_plugin_ruok/webui/templates/modules_detail.html.jinja2 +0 -0
  58. {nonebot_plugin_ruok-0.2.0 → nonebot_plugin_ruok-0.3.0}/src/nonebot_plugin_ruok/webui/templates/notifications.html.jinja2 +0 -0
  59. {nonebot_plugin_ruok-0.2.0 → nonebot_plugin_ruok-0.3.0}/src/nonebot_plugin_ruok/webui/templates/notifications_detail.html.jinja2 +0 -0
  60. {nonebot_plugin_ruok-0.2.0 → nonebot_plugin_ruok-0.3.0}/src/nonebot_plugin_ruok/webui/templates/register.html.jinja2 +0 -0
  61. {nonebot_plugin_ruok-0.2.0 → nonebot_plugin_ruok-0.3.0}/src/nonebot_plugin_ruok/webui/templates/reset_password.html.jinja2 +0 -0
  62. {nonebot_plugin_ruok-0.2.0 → nonebot_plugin_ruok-0.3.0}/src/nonebot_plugin_ruok/webui/templates/sessions.html.jinja2 +0 -0
  63. {nonebot_plugin_ruok-0.2.0 → nonebot_plugin_ruok-0.3.0}/src/nonebot_plugin_ruok/webui/templates/sessions_detail.html.jinja2 +0 -0
  64. {nonebot_plugin_ruok-0.2.0 → nonebot_plugin_ruok-0.3.0}/src/nonebot_plugin_ruok/webui/templates/users.html.jinja2 +0 -0
@@ -1,3 +1,27 @@
1
+ Metadata-Version: 2.3
2
+ Name: nonebot-plugin-ruok
3
+ Version: 0.3.0
4
+ Summary: Bot health monitoring, session tracking, and WebUI for NoneBot2
5
+ Author: p0rt39
6
+ Author-email: p0rt39 <YuibataMiraa@gmail.com>
7
+ Requires-Dist: nonebot2>=2.5.0,<3.0.0
8
+ Requires-Dist: fastapi>=0.93.0,<1.0.0
9
+ Requires-Dist: httpx>=0.26.0,<1.0.0
10
+ Requires-Dist: nonebot-plugin-htmlrender>=0.7.1,<1.0.0
11
+ Requires-Dist: nonebot-plugin-localstore>=0.7.0,<1.0.0
12
+ Requires-Dist: nonebot-plugin-apscheduler>=0.5.0,<1.0.0
13
+ Requires-Dist: psutil>=6.0.0,<7.0.0
14
+ Requires-Dist: jinja2>=3.1.6
15
+ Requires-Dist: python-multipart>=0.0.32
16
+ Requires-Dist: itsdangerous>=2.2.0
17
+ Requires-Dist: nonebot-adapter-onebot>=2.4.6,<3.0.0 ; extra == 'onebot'
18
+ Requires-Python: >=3.10
19
+ Project-URL: Homepage, https://github.com/p0rt39/nonebot-plugin-ruok
20
+ Project-URL: Issues, https://github.com/p0rt39/nonebot-plugin-ruok/issues
21
+ Project-URL: Repository, https://github.com/p0rt39/nonebot-plugin-ruok.git
22
+ Provides-Extra: onebot
23
+ Description-Content-Type: text/markdown
24
+
1
25
  <div align="center">
2
26
  <a href="https://v2.nonebot.dev/store">
3
27
  <img src="https://raw.githubusercontent.com/fllesser/nonebot-plugin-template/refs/heads/resource/.docs/NoneBotPlugin.svg" width="310" alt="logo"></a>
@@ -8,7 +32,7 @@
8
32
 
9
33
  [![LICENSE](https://img.shields.io/github/license/p0rt39/nonebot-plugin-ruok.svg)](./LICENSE)
10
34
  [![pypi](https://img.shields.io/pypi/v/nonebot-plugin-ruok.svg)](https://pypi.python.org/pypi/nonebot-plugin-ruok)
11
- [![python](https://img.shields.io/badge/python-3.10|3.11|3.12|3.13-blue.svg)](https://www.python.org)
35
+ [![python](https://img.shields.io/badge/python-3.10|3.11|3.12|3.13|3.14-blue.svg)](https://www.python.org)
12
36
  [![uv](https://img.shields.io/badge/package%20manager-uv-black?style=flat-square&logo=uv)](https://github.com/astral-sh/uv)
13
37
  <br/>
14
38
  [![ruff](https://img.shields.io/badge/code%20style-ruff-black?style=flat-square&logo=ruff)](https://github.com/astral-sh/ruff)
@@ -30,7 +54,7 @@
30
54
  - WebUI:完整鉴权、实时更新、关键指标实时显示、Bot用户/Bot开发者双显示模板。
31
55
  - 账号体系:内置 admin、普通用户注册、平台账号绑定、记住登录、自助重设密码。
32
56
  - 通知规则:按状态/模块触发,支持 Bot 私聊与 Webhook,带冷却时间。
33
- - API:`/ruok/api/*` JSON 接口,支持可选 API key,为外接Status Page等留下空间。
57
+ - API:`/ruok/api/*` JSON 接口,受 API key 保护,为外接 Status Page 等留下空间。
34
58
 
35
59
 
36
60
  ## 使用前的提示
@@ -72,20 +96,28 @@ plugins = ["nonebot_plugin_ruok"]
72
96
 
73
97
  ### 3. 写入推荐最小配置
74
98
 
99
+ 本插件 **依赖** FastAPI 驱动器来正常工作,请保证驱动器安装和启用。
100
+
75
101
  本插件可以零配置加载,但为了启用 WebUI 管理员登录并保证重启后的登录体验,建议至少配置:
76
102
 
77
103
  ```dotenv
78
104
  RUOK__WEBUI_ADMIN_PASSWORD=change-me
79
105
  RUOK__WEBUI_SECRET_KEY=replace-with-a-long-random-secret
80
- RUOK__API_KEY=optional-api-token
106
+ RUOK__API_KEY=replace-with-a-long-random-api-token
81
107
  ```
82
108
 
83
- `RUOK__API_KEY` 在您需要开放或集成 `/ruok/api/*` 时需要配置,不影响插件内部调用和WebUI使用。
109
+ `RUOK__API_KEY` 是 HTTP API 的访问凭据。除 `/ruok/api/health` 外,所有 API
110
+ 端点都要求携带该 key;未配置 key 时这些端点会返回 `401`。这不会影响插件内部
111
+ 状态采集、聊天指令或 WebUI 使用。
84
112
 
85
113
  虽然 WebUI 和 API 挂载在Nonebot Uvicorn 上,Uvicorn 默认只监听 `localhost`,但考虑到您可能有通过 Tunnel、反向代理等方式向外暴露或者修改 Nonebot Uvicorn 的监听行为的需求,建议在安装阶段就配置 API key。
86
114
 
87
115
  如果`RUOK__WEBUI_ADMIN_PASSWORD`未配置,WebUI将**不可用**。
88
116
 
117
+ WebUI 签名 session 默认 3600 秒后过期。可通过 `RUOK__WEBUI_SESSION_TTL`(正整数秒)
118
+ 调整登录 session 的有效期;这不会改变“保持登录” token 的 30 天期限。WebUI 可以通过
119
+ 本地 Uvicorn、Tunnel 或反向代理访问,请根据实际入口配置 HTTPS 终止和转发策略。
120
+
89
121
  如果没有配置 `RUOK__WEBUI_SECRET_KEY`,WebUI session 会使用启动时随机密钥。这不会影响本次运行内的登录、注册、绑定等功能,但 Bot 重启后旧登录态和“保持登录”cookie 无法继续校验,用户需要重新登录。
90
122
 
91
123
  ### 4. 启动并访问 WebUI
@@ -147,9 +179,17 @@ RUOK 设计上不绑定具体适配器,但当前主要针对 OneBot V11 做了
147
179
  | :--- | :--- | :--- | :--- |
148
180
  | `RUOK__CHECK_TIMEOUT` | `float` | `5.0` | 健康检查超时时间,单位秒 |
149
181
  | `RUOK__WS_DEEP_CHECK_TIMEOUT` | `float` | `3.0` | Bot 深度检查超时时间 |
150
- | `RUOK__CACHE_TTL` | `float` | `10.0` | API 聚合状态缓存时间 |
182
+ | `RUOK__CACHE_TTL` | `float` | `10.0` | API 聚合状态缓存时间,必须为有限数且不小于 `0.5` 秒 |
151
183
  | `RUOK__ENABLE_DEEP_WS_CHECK` | `bool` | `true` | 是否调用 `bot.get_status()` 与各Bot做端到端检查 |
152
184
 
185
+ SSE 每秒发送一次轻量 tick,并按此 TTL 触发完整状态采集;小于 1 秒的值会向上取整为 1 个 tick。
186
+ 无效或小于 `0.5` 的值会在配置加载时被拒绝。
187
+
188
+ 连接列表中的 `connected` 由当前 Bot 是否存在、底层 WS 是否明确关闭以及深度检查返回的
189
+ `online` 字段共同推导。重连后会清除上一次断开的时间、错误和延迟;`ws_closed` 为 `null`
190
+ 表示当前适配器没有提供 WS 状态,不能据此判定断开。深度检查返回 `online=false` 或 WS
191
+ 明确关闭时连接显示为离线;检查异常会保留当前错误并将端到端状态视为未知。
192
+
153
193
  ### Session 与上报
154
194
 
155
195
  | 配置项 | 类型 | 默认值 | 说明 |
@@ -178,11 +218,15 @@ RUOK 设计上不绑定具体适配器,但当前主要针对 OneBot V11 做了
178
218
  | 配置项 | 类型 | 默认值 | 说明 |
179
219
  | :--- | :--- | :--- | :--- |
180
220
  | `RUOK__CORS_ORIGINS` | `list[str]` | `["*"]` | API CORS 允许源 |
181
- | `RUOK__API_KEY` | `str` | `""` | API key;为空则 API 不校验 |
221
+ | `RUOK__API_KEY` | `str` | `""` | HTTP API key;除 `/ruok/api/health` 外的 API 端点必须配置 |
182
222
  | `RUOK__WEBUI_ADMIN_PASSWORD` | `str` | `""` | 内置 `admin` 账户密码;为空则 WebUI 无法登录 |
183
223
  | `RUOK__WEBUI_SECRET_KEY` | `str` | `""` | WebUI session 签名密钥;为空则每次启动随机,重启后登录态/保持登录功能会失效 |
224
+ | `RUOK__WEBUI_SESSION_TTL` | `int` | `3600` | WebUI 签名登录 session 的有效期(秒,必须为正整数) |
184
225
  | `RUOK__SSE_PUBLIC` | `bool` | `false` | 是否允许未登录访问 SSE |
185
226
 
227
+ 仪表盘通过 SSE 更新磁盘和进程详情。主机提供的挂载点、进程名等动态值会以纯文本写入页面,
228
+ 不会作为 HTML 执行。
229
+
186
230
  API key 可通过任一方式传递:
187
231
 
188
232
  ```http
@@ -233,6 +277,10 @@ RUOK 默认依赖 `nonebot-plugin-htmlrender`,可将 `/ruok status` 和 `/ruok
233
277
  | `channels` | `list[str]` | `bot_dm`、`webhook` |
234
278
  | `webhook_url` | `str | null` | Webhook URL |
235
279
 
280
+ 冷却按“规则名 + 模块名”分别计算。发送前会在 data 目录的冷却文件中原子声明
281
+ 本次发送,短时间内并发到达的相同事件只会执行一次通知;所有通道都发送失败时会
282
+ 释放声明,以便后续事件重试。冷却锁为单进程锁,多进程部署需要文件锁或事务型存储。
283
+
236
284
  ## 聊天指令
237
285
 
238
286
  | 指令 | 权限 | 说明 |
@@ -250,8 +298,15 @@ RUOK 默认依赖 `nonebot-plugin-htmlrender`,可将 `/ruok status` 和 `/ruok
250
298
  | `/ruok raise [message]` | SUPERUSER | 触发一次受控内部异常,验证 RUOK 自监控 Session 创建流程 |
251
299
  | `/ruok test [message]` | SUPERUSER | `/ruok raise [message]` 的别名|
252
300
 
253
- 普通用户的 `list`/`lookup` 可见范围按 Session `reporter.user_id` 与当前聊天平台用户 ID
254
- 匹配,
301
+ 普通用户的 `list`/`lookup` 可见范围按 `(platform, user_id)` 与当前聊天平台身份精确匹配;
302
+ WebUI 普通用户手动上报也使用其已绑定的平台身份。不同平台的同名用户 ID 互不继承绑定
303
+ 权限。显式配置的 `SUPERUSERS` 和上报白名单仍按原有 ID 规则授权。
304
+
305
+ 旧版 `bound_qq` 或缺少平台字段的绑定记录会保留,但不再作为上报、WebUI Session 查看、
306
+ 动态管理员或密码重置的授权依据。登录 WebUI 后重新生成绑定码,并在当前聊天平台发送
307
+ `/ruok bind <auth_key>` 即可完成迁移;忘记密码的旧账号需由管理员重设密码。
308
+ 历史上未记录平台或仅标记为 `webui` 的 Session 不会自动归属给同 ID 用户,仍可由管理员
309
+ 查看。升级前签发的重置码需重新获取,换绑或清除绑定后原重置码立即失效。
255
310
 
256
311
  `/ruok confirm` 的插件参数支持空格或逗号:
257
312
 
@@ -344,7 +399,10 @@ Bot 重启后会因 session 签名密钥变化而要求重新登录。
344
399
 
345
400
  ## HTTP API
346
401
 
347
- 所有端点前缀为 `/ruok/api`,返回 JSON。API 鉴权与 WebUI 登录态相互独立:如果配置了 `RUOK__API_KEY`,请求必须带上以下任一凭据;未配置时不校验 API key。
402
+ 所有端点前缀为 `/ruok/api`,返回 JSON。API 鉴权与 WebUI 登录态相互独立。
403
+ 除 `/ruok/api/health` 外,请求必须配置 `RUOK__API_KEY` 并带上以下任一凭据;
404
+ 未配置 key 时,受保护端点默认拒绝访问。`/ruok/api/health` 只返回简单健康结果,
405
+ 可在未配置 key 时用于容器或负载均衡探针。
348
406
 
349
407
  ```http
350
408
  X-RUOK-API-Key: your-token
@@ -461,7 +519,7 @@ DELETE /ruok/api/modules/music
461
519
  | :--- | :--- |
462
520
  | `200` | 请求成功 |
463
521
  | `400` | 请求内容不合法,例如影响插件不属于 Session 原模块 |
464
- | `401` | API key 缺失或错误 |
522
+ | `401` | API key 未配置、缺失或错误 |
465
523
  | `403` | Session 系统被禁用,相关写操作不可用 |
466
524
  | `404` | Session 或模块不存在 |
467
525
  | `503` | `/health` 探针判断服务不可用 |
@@ -483,6 +541,11 @@ RUOK 使用 `nonebot-plugin-localstore` 的插件数据目录。
483
541
 
484
542
  `plugin_impacts.json` 是缓存,不是权威状态。缺失、损坏或过期时会从 Session 文件重建。
485
543
 
544
+ Session、插件影响索引和每日指标的文件写入在进程内使用锁,并通过同目录临时文件和原子替换
545
+ 完成,避免并发请求互相覆盖或留下半截 JSON。指标文件若已损坏,会先保留为带有
546
+ `.corrupt-...` 后缀的隔离副本并记录告警,再创建新的当天文件。锁只覆盖当前进程;多进程
547
+ 同时使用同一数据目录时,应改用文件锁或事务型存储。
548
+
486
549
  ## 前端静态资产及其许可证
487
550
 
488
551
  WebUI 使用随包分发的本地静态资产,不依赖运行时 CDN:
@@ -1,24 +1,3 @@
1
- Metadata-Version: 2.3
2
- Name: nonebot-plugin-ruok
3
- Version: 0.2.0
4
- Summary: Bot health monitoring, session tracking, and WebUI for NoneBot2
5
- Author: p0rt39
6
- Author-email: p0rt39 <YuibataMiraa@gmail.com>
7
- Requires-Dist: nonebot2[fastapi,httpx]>=2.5.0,<3.0.0
8
- Requires-Dist: nonebot-plugin-htmlrender>=0.7.1,<1.0.0
9
- Requires-Dist: nonebot-plugin-localstore>=0.7.0,<1.0.0
10
- Requires-Dist: psutil>=6.0.0,<7.0.0
11
- Requires-Dist: jinja2>=3.1.6
12
- Requires-Dist: python-multipart>=0.0.32
13
- Requires-Dist: itsdangerous>=2.2.0
14
- Requires-Dist: nonebot-adapter-onebot>=2.4.6,<3.0.0 ; extra == 'onebot'
15
- Requires-Python: >=3.10
16
- Project-URL: Homepage, https://github.com/p0rt39/nonebot-plugin-ruok
17
- Project-URL: Issues, https://github.com/p0rt39/nonebot-plugin-ruok/issues
18
- Project-URL: Repository, https://github.com/p0rt39/nonebot-plugin-ruok.git
19
- Provides-Extra: onebot
20
- Description-Content-Type: text/markdown
21
-
22
1
  <div align="center">
23
2
  <a href="https://v2.nonebot.dev/store">
24
3
  <img src="https://raw.githubusercontent.com/fllesser/nonebot-plugin-template/refs/heads/resource/.docs/NoneBotPlugin.svg" width="310" alt="logo"></a>
@@ -29,7 +8,7 @@ Description-Content-Type: text/markdown
29
8
 
30
9
  [![LICENSE](https://img.shields.io/github/license/p0rt39/nonebot-plugin-ruok.svg)](./LICENSE)
31
10
  [![pypi](https://img.shields.io/pypi/v/nonebot-plugin-ruok.svg)](https://pypi.python.org/pypi/nonebot-plugin-ruok)
32
- [![python](https://img.shields.io/badge/python-3.10|3.11|3.12|3.13-blue.svg)](https://www.python.org)
11
+ [![python](https://img.shields.io/badge/python-3.10|3.11|3.12|3.13|3.14-blue.svg)](https://www.python.org)
33
12
  [![uv](https://img.shields.io/badge/package%20manager-uv-black?style=flat-square&logo=uv)](https://github.com/astral-sh/uv)
34
13
  <br/>
35
14
  [![ruff](https://img.shields.io/badge/code%20style-ruff-black?style=flat-square&logo=ruff)](https://github.com/astral-sh/ruff)
@@ -51,7 +30,7 @@ Description-Content-Type: text/markdown
51
30
  - WebUI:完整鉴权、实时更新、关键指标实时显示、Bot用户/Bot开发者双显示模板。
52
31
  - 账号体系:内置 admin、普通用户注册、平台账号绑定、记住登录、自助重设密码。
53
32
  - 通知规则:按状态/模块触发,支持 Bot 私聊与 Webhook,带冷却时间。
54
- - API:`/ruok/api/*` JSON 接口,支持可选 API key,为外接Status Page等留下空间。
33
+ - API:`/ruok/api/*` JSON 接口,受 API key 保护,为外接 Status Page 等留下空间。
55
34
 
56
35
 
57
36
  ## 使用前的提示
@@ -93,20 +72,28 @@ plugins = ["nonebot_plugin_ruok"]
93
72
 
94
73
  ### 3. 写入推荐最小配置
95
74
 
75
+ 本插件 **依赖** FastAPI 驱动器来正常工作,请保证驱动器安装和启用。
76
+
96
77
  本插件可以零配置加载,但为了启用 WebUI 管理员登录并保证重启后的登录体验,建议至少配置:
97
78
 
98
79
  ```dotenv
99
80
  RUOK__WEBUI_ADMIN_PASSWORD=change-me
100
81
  RUOK__WEBUI_SECRET_KEY=replace-with-a-long-random-secret
101
- RUOK__API_KEY=optional-api-token
82
+ RUOK__API_KEY=replace-with-a-long-random-api-token
102
83
  ```
103
84
 
104
- `RUOK__API_KEY` 在您需要开放或集成 `/ruok/api/*` 时需要配置,不影响插件内部调用和WebUI使用。
85
+ `RUOK__API_KEY` 是 HTTP API 的访问凭据。除 `/ruok/api/health` 外,所有 API
86
+ 端点都要求携带该 key;未配置 key 时这些端点会返回 `401`。这不会影响插件内部
87
+ 状态采集、聊天指令或 WebUI 使用。
105
88
 
106
89
  虽然 WebUI 和 API 挂载在Nonebot Uvicorn 上,Uvicorn 默认只监听 `localhost`,但考虑到您可能有通过 Tunnel、反向代理等方式向外暴露或者修改 Nonebot Uvicorn 的监听行为的需求,建议在安装阶段就配置 API key。
107
90
 
108
91
  如果`RUOK__WEBUI_ADMIN_PASSWORD`未配置,WebUI将**不可用**。
109
92
 
93
+ WebUI 签名 session 默认 3600 秒后过期。可通过 `RUOK__WEBUI_SESSION_TTL`(正整数秒)
94
+ 调整登录 session 的有效期;这不会改变“保持登录” token 的 30 天期限。WebUI 可以通过
95
+ 本地 Uvicorn、Tunnel 或反向代理访问,请根据实际入口配置 HTTPS 终止和转发策略。
96
+
110
97
  如果没有配置 `RUOK__WEBUI_SECRET_KEY`,WebUI session 会使用启动时随机密钥。这不会影响本次运行内的登录、注册、绑定等功能,但 Bot 重启后旧登录态和“保持登录”cookie 无法继续校验,用户需要重新登录。
111
98
 
112
99
  ### 4. 启动并访问 WebUI
@@ -168,9 +155,17 @@ RUOK 设计上不绑定具体适配器,但当前主要针对 OneBot V11 做了
168
155
  | :--- | :--- | :--- | :--- |
169
156
  | `RUOK__CHECK_TIMEOUT` | `float` | `5.0` | 健康检查超时时间,单位秒 |
170
157
  | `RUOK__WS_DEEP_CHECK_TIMEOUT` | `float` | `3.0` | Bot 深度检查超时时间 |
171
- | `RUOK__CACHE_TTL` | `float` | `10.0` | API 聚合状态缓存时间 |
158
+ | `RUOK__CACHE_TTL` | `float` | `10.0` | API 聚合状态缓存时间,必须为有限数且不小于 `0.5` 秒 |
172
159
  | `RUOK__ENABLE_DEEP_WS_CHECK` | `bool` | `true` | 是否调用 `bot.get_status()` 与各Bot做端到端检查 |
173
160
 
161
+ SSE 每秒发送一次轻量 tick,并按此 TTL 触发完整状态采集;小于 1 秒的值会向上取整为 1 个 tick。
162
+ 无效或小于 `0.5` 的值会在配置加载时被拒绝。
163
+
164
+ 连接列表中的 `connected` 由当前 Bot 是否存在、底层 WS 是否明确关闭以及深度检查返回的
165
+ `online` 字段共同推导。重连后会清除上一次断开的时间、错误和延迟;`ws_closed` 为 `null`
166
+ 表示当前适配器没有提供 WS 状态,不能据此判定断开。深度检查返回 `online=false` 或 WS
167
+ 明确关闭时连接显示为离线;检查异常会保留当前错误并将端到端状态视为未知。
168
+
174
169
  ### Session 与上报
175
170
 
176
171
  | 配置项 | 类型 | 默认值 | 说明 |
@@ -199,11 +194,15 @@ RUOK 设计上不绑定具体适配器,但当前主要针对 OneBot V11 做了
199
194
  | 配置项 | 类型 | 默认值 | 说明 |
200
195
  | :--- | :--- | :--- | :--- |
201
196
  | `RUOK__CORS_ORIGINS` | `list[str]` | `["*"]` | API CORS 允许源 |
202
- | `RUOK__API_KEY` | `str` | `""` | API key;为空则 API 不校验 |
197
+ | `RUOK__API_KEY` | `str` | `""` | HTTP API key;除 `/ruok/api/health` 外的 API 端点必须配置 |
203
198
  | `RUOK__WEBUI_ADMIN_PASSWORD` | `str` | `""` | 内置 `admin` 账户密码;为空则 WebUI 无法登录 |
204
199
  | `RUOK__WEBUI_SECRET_KEY` | `str` | `""` | WebUI session 签名密钥;为空则每次启动随机,重启后登录态/保持登录功能会失效 |
200
+ | `RUOK__WEBUI_SESSION_TTL` | `int` | `3600` | WebUI 签名登录 session 的有效期(秒,必须为正整数) |
205
201
  | `RUOK__SSE_PUBLIC` | `bool` | `false` | 是否允许未登录访问 SSE |
206
202
 
203
+ 仪表盘通过 SSE 更新磁盘和进程详情。主机提供的挂载点、进程名等动态值会以纯文本写入页面,
204
+ 不会作为 HTML 执行。
205
+
207
206
  API key 可通过任一方式传递:
208
207
 
209
208
  ```http
@@ -254,6 +253,10 @@ RUOK 默认依赖 `nonebot-plugin-htmlrender`,可将 `/ruok status` 和 `/ruok
254
253
  | `channels` | `list[str]` | `bot_dm`、`webhook` |
255
254
  | `webhook_url` | `str | null` | Webhook URL |
256
255
 
256
+ 冷却按“规则名 + 模块名”分别计算。发送前会在 data 目录的冷却文件中原子声明
257
+ 本次发送,短时间内并发到达的相同事件只会执行一次通知;所有通道都发送失败时会
258
+ 释放声明,以便后续事件重试。冷却锁为单进程锁,多进程部署需要文件锁或事务型存储。
259
+
257
260
  ## 聊天指令
258
261
 
259
262
  | 指令 | 权限 | 说明 |
@@ -271,8 +274,15 @@ RUOK 默认依赖 `nonebot-plugin-htmlrender`,可将 `/ruok status` 和 `/ruok
271
274
  | `/ruok raise [message]` | SUPERUSER | 触发一次受控内部异常,验证 RUOK 自监控 Session 创建流程 |
272
275
  | `/ruok test [message]` | SUPERUSER | `/ruok raise [message]` 的别名|
273
276
 
274
- 普通用户的 `list`/`lookup` 可见范围按 Session `reporter.user_id` 与当前聊天平台用户 ID
275
- 匹配,
277
+ 普通用户的 `list`/`lookup` 可见范围按 `(platform, user_id)` 与当前聊天平台身份精确匹配;
278
+ WebUI 普通用户手动上报也使用其已绑定的平台身份。不同平台的同名用户 ID 互不继承绑定
279
+ 权限。显式配置的 `SUPERUSERS` 和上报白名单仍按原有 ID 规则授权。
280
+
281
+ 旧版 `bound_qq` 或缺少平台字段的绑定记录会保留,但不再作为上报、WebUI Session 查看、
282
+ 动态管理员或密码重置的授权依据。登录 WebUI 后重新生成绑定码,并在当前聊天平台发送
283
+ `/ruok bind <auth_key>` 即可完成迁移;忘记密码的旧账号需由管理员重设密码。
284
+ 历史上未记录平台或仅标记为 `webui` 的 Session 不会自动归属给同 ID 用户,仍可由管理员
285
+ 查看。升级前签发的重置码需重新获取,换绑或清除绑定后原重置码立即失效。
276
286
 
277
287
  `/ruok confirm` 的插件参数支持空格或逗号:
278
288
 
@@ -365,7 +375,10 @@ Bot 重启后会因 session 签名密钥变化而要求重新登录。
365
375
 
366
376
  ## HTTP API
367
377
 
368
- 所有端点前缀为 `/ruok/api`,返回 JSON。API 鉴权与 WebUI 登录态相互独立:如果配置了 `RUOK__API_KEY`,请求必须带上以下任一凭据;未配置时不校验 API key。
378
+ 所有端点前缀为 `/ruok/api`,返回 JSON。API 鉴权与 WebUI 登录态相互独立。
379
+ 除 `/ruok/api/health` 外,请求必须配置 `RUOK__API_KEY` 并带上以下任一凭据;
380
+ 未配置 key 时,受保护端点默认拒绝访问。`/ruok/api/health` 只返回简单健康结果,
381
+ 可在未配置 key 时用于容器或负载均衡探针。
369
382
 
370
383
  ```http
371
384
  X-RUOK-API-Key: your-token
@@ -482,7 +495,7 @@ DELETE /ruok/api/modules/music
482
495
  | :--- | :--- |
483
496
  | `200` | 请求成功 |
484
497
  | `400` | 请求内容不合法,例如影响插件不属于 Session 原模块 |
485
- | `401` | API key 缺失或错误 |
498
+ | `401` | API key 未配置、缺失或错误 |
486
499
  | `403` | Session 系统被禁用,相关写操作不可用 |
487
500
  | `404` | Session 或模块不存在 |
488
501
  | `503` | `/health` 探针判断服务不可用 |
@@ -504,6 +517,11 @@ RUOK 使用 `nonebot-plugin-localstore` 的插件数据目录。
504
517
 
505
518
  `plugin_impacts.json` 是缓存,不是权威状态。缺失、损坏或过期时会从 Session 文件重建。
506
519
 
520
+ Session、插件影响索引和每日指标的文件写入在进程内使用锁,并通过同目录临时文件和原子替换
521
+ 完成,避免并发请求互相覆盖或留下半截 JSON。指标文件若已损坏,会先保留为带有
522
+ `.corrupt-...` 后缀的隔离副本并记录告警,再创建新的当天文件。锁只覆盖当前进程;多进程
523
+ 同时使用同一数据目录时,应改用文件锁或事务型存储。
524
+
507
525
  ## 前端静态资产及其许可证
508
526
 
509
527
  WebUI 使用随包分发的本地静态资产,不依赖运行时 CDN:
@@ -0,0 +1,158 @@
1
+ [project]
2
+ name = "nonebot-plugin-ruok"
3
+ version = "0.3.0"
4
+ description = "Bot health monitoring, session tracking, and WebUI for NoneBot2"
5
+ readme = "README.md"
6
+ requires-python = ">=3.10"
7
+ dependencies = [
8
+ "nonebot2>=2.5.0,<3.0.0",
9
+ "fastapi>=0.93.0,<1.0.0",
10
+ "httpx>=0.26.0,<1.0.0",
11
+ "nonebot-plugin-htmlrender>=0.7.1,<1.0.0",
12
+ "nonebot-plugin-localstore>=0.7.0,<1.0.0",
13
+ "nonebot-plugin-apscheduler>=0.5.0,<1.0.0",
14
+ "psutil>=6.0.0,<7.0.0",
15
+ "jinja2>=3.1.6",
16
+ "python-multipart>=0.0.32",
17
+ "itsdangerous>=2.2.0",
18
+ ]
19
+
20
+ [[project.authors]]
21
+ name = "p0rt39"
22
+ email = "YuibataMiraa@gmail.com"
23
+
24
+ [project.optional-dependencies]
25
+ onebot = ["nonebot-adapter-onebot>=2.4.6,<3.0.0"]
26
+
27
+ [project.urls]
28
+ Homepage = "https://github.com/p0rt39/nonebot-plugin-ruok"
29
+ Issues = "https://github.com/p0rt39/nonebot-plugin-ruok/issues"
30
+ Repository = "https://github.com/p0rt39/nonebot-plugin-ruok.git"
31
+
32
+ [dependency-groups]
33
+ dev = [
34
+ "bump-my-version>=1.2.7",
35
+ "nonebot-plugin-apscheduler>=0.5.0",
36
+ "poethepoet>=0.42.1",
37
+ "ruff>=0.15.2,<1.0.0",
38
+ { include-group = "test" },
39
+ ]
40
+ test = [
41
+ "nonebot-adapter-onebot>=2.4.6,<3.0.0",
42
+ "nonebug>=0.4.4,<1.0.0",
43
+ "pytest>=9.0.2,<10.0.0",
44
+ "poethepoet>=0.42.1",
45
+ "pytest-asyncio>=1.3.0,<1.4.0",
46
+ "pytest-cov>=7.0.0",
47
+ "pytest-xdist>=3.8.0,<4.0.0",
48
+ "nonebot2[fastapi]>=2.5.0",
49
+ ]
50
+
51
+ [build-system]
52
+ requires = ["uv_build>=0.11.0,<0.12.0"]
53
+ build-backend = "uv_build"
54
+
55
+ [tool.bumpversion]
56
+ current_version = "0.3.0"
57
+ commit = true
58
+ message = "release: bump vesion from {current_version} to {new_version}"
59
+ tag = true
60
+
61
+ [[tool.bumpversion.files]]
62
+ filename = "uv.lock"
63
+ search = """
64
+ name = "nonebot-plugin-ruok"
65
+ version = "{current_version}""""
66
+ replace = """
67
+ name = "nonebot-plugin-ruok"
68
+ version = "{new_version}""""
69
+
70
+ [tool.coverage.report]
71
+ fail_under = 70
72
+ exclude_lines = [
73
+ "raise NotImplementedError",
74
+ "if TYPE_CHECKING:",
75
+ "@overload",
76
+ "except ImportError:",
77
+ ]
78
+
79
+ [tool.typos.files]
80
+ extend-exclude = ["src/nonebot_plugin_ruok/webui/static/**"]
81
+
82
+ [tool.nonebot]
83
+ plugins = ["nonebot_plugin_ruok"]
84
+
85
+ [tool.poe.tasks]
86
+ test = "pytest --cov=src --cov-report xml --junitxml=./junit.xml -n auto"
87
+ bump = "bump-my-version bump"
88
+ show-bump = "bump-my-version show-bump"
89
+
90
+ [tool.pyright]
91
+ pythonVersion = "3.10"
92
+ pythonPlatform = "All"
93
+ typeCheckingMode = "standard"
94
+ disableBytesTypePromotions = true
95
+
96
+ [tool.pyright.defineConstant]
97
+ PYDANTIC_V2 = true
98
+
99
+ [[tool.pyright.executionEnvironments]]
100
+ root = "./tests"
101
+ extraPaths = ["./src"]
102
+
103
+ [[tool.pyright.executionEnvironments]]
104
+ root = "./src"
105
+
106
+ [tool.pytest]
107
+ addopts = [
108
+ "--import-mode=prepend",
109
+ "--strict-markers",
110
+ "--tb=short",
111
+ "-ra",
112
+ "-s",
113
+ "-v",
114
+ ]
115
+ pythonpath = ["src"]
116
+ asyncio_mode = "auto"
117
+ asyncio_default_fixture_loop_scope = "session"
118
+
119
+ [tool.ruff]
120
+ line-length = 88
121
+
122
+ [tool.ruff.format]
123
+ line-ending = "lf"
124
+
125
+ [tool.ruff.lint]
126
+ select = [
127
+ "F",
128
+ "W",
129
+ "E",
130
+ "I",
131
+ "UP",
132
+ "ASYNC",
133
+ "C4",
134
+ "T10",
135
+ "T20",
136
+ "PYI",
137
+ "PT",
138
+ "Q",
139
+ "TID",
140
+ "RUF",
141
+ ]
142
+ ignore = [
143
+ "E402",
144
+ "UP037",
145
+ "RUF001",
146
+ "RUF002",
147
+ "RUF003",
148
+ "W191",
149
+ "TID252",
150
+ ]
151
+
152
+ [tool.ruff.lint.isort]
153
+ length-sort = true
154
+ known-first-party = ["tests/*"]
155
+ extra-standard-library = ["typing_extensions"]
156
+
157
+ [tool.ruff.lint.pyupgrade]
158
+ keep-runtime-typing = true
@@ -1,14 +1,17 @@
1
1
  [project]
2
2
  name = "nonebot-plugin-ruok"
3
- version = "0.2.0"
3
+ version = "0.3.0"
4
4
  description = "Bot health monitoring, session tracking, and WebUI for NoneBot2"
5
5
  readme = "README.md"
6
6
  requires-python = ">=3.10"
7
7
  authors = [{ name = "p0rt39", email = "YuibataMiraa@gmail.com" }]
8
8
  dependencies = [
9
- "nonebot2[fastapi,httpx]>=2.5.0,<3.0.0",
9
+ "nonebot2>=2.5.0,<3.0.0",
10
+ "fastapi>=0.93.0,<1.0.0",
11
+ "httpx>=0.26.0,<1.0.0",
10
12
  "nonebot-plugin-htmlrender>=0.7.1,<1.0.0",
11
13
  "nonebot-plugin-localstore>=0.7.0,<1.0.0",
14
+ "nonebot-plugin-apscheduler>=0.5.0,<1.0.0",
12
15
  "psutil>=6.0.0,<7.0.0",
13
16
  "jinja2>=3.1.6",
14
17
  "python-multipart>=0.0.32",
@@ -41,15 +44,16 @@ test = [
41
44
  "pytest-asyncio>=1.3.0,<1.4.0",
42
45
  "pytest-cov>=7.0.0",
43
46
  "pytest-xdist>=3.8.0,<4.0.0",
47
+ "nonebot2[fastapi]>=2.5.0",
44
48
  ]
45
49
 
46
50
  [build-system]
47
- requires = ["uv_build>=0.10.0,<0.11.0"]
51
+ requires = ["uv_build>=0.11.0,<0.12.0"]
48
52
  build-backend = "uv_build"
49
53
 
50
54
 
51
55
  [tool.bumpversion]
52
- current_version = "0.2.0"
56
+ current_version = "0.3.0"
53
57
  commit = true
54
58
  message = "release: bump vesion from {current_version} to {new_version}"
55
59
  tag = true
@@ -60,6 +64,7 @@ search = "name = \"nonebot-plugin-ruok\"\nversion = \"{current_version}\""
60
64
  replace = "name = \"nonebot-plugin-ruok\"\nversion = \"{new_version}\""
61
65
 
62
66
  [tool.coverage.report]
67
+ fail_under = 70
63
68
  exclude_lines = [
64
69
  "raise NotImplementedError",
65
70
  "if TYPE_CHECKING:",