登录与安全 — Spot Monitor 文档

面板有两种登录方式：应急密码，以及可选的 GitHub 单点登录。只用应急密码同样完整可用。

配了单点登录也要保留应急密码：GitHub 不可达或 OAuth App 配错时，它是唯一的入口。

应急密码

首次启动时 hub 生成一个 24 位的随机密码。一键脚本装完直接显示在终端里；其他部署方式打印在 hub 的标准输出：

# Docker
docker logs monitor | grep Emergency
# 自己写的 systemd 单元
journalctl -u <单元名> | grep Emergency

bash

在安全页修改，最短 12 位，以 argon2id 哈希存储。改密码会注销所有登录会话，包括正开着的实时推送连接：那条连接里带着各节点的 token，不断开的话，它会比被注销的会话活得更久。

应急密码忘了

hub 没有内置的重置命令：monitor-hub --reset-password 会直接报 unknown argument（一键脚本也没有这个参数）。可以清掉数据库里的密码哈希，让 hub 下次启动当成首次运行，重新生成并打印一个：

# 1. 停服务
sudo systemctl stop monitor-hub
# 2. 删掉密码哈希；路径是一键脚本部署的数据库
sudo sqlite3 /opt/monitor/data/monitor.db \
  "DELETE FROM setting WHERE key = 'admin_password_hash';"
# 3. 启动。它像首次安装那样在标准输出里打印新密码
sudo systemctl start monitor-hub
journalctl -u monitor-hub -n 20 | grep Emergency

bash

需要机器上有 sqlite3（Debian、Ubuntu 装 sqlite3 包）。仓库里没有这个命令，是直接在数据库上操作。

只删这一行，节点、历史、设置都不动。旧密码随即失效；已经登录的其它设备不会被注销，会话是另一张表，要一起清掉就在安全页逐个注销。Docker 部署同理：先停容器，对数据卷里的 monitor.db 执行同一条 SQL（镜像里没有 shell 和 sqlite3，要在宿主机上操作），再启动容器看 docker logs。

GitHub 单点登录

1. 在 GitHub 建一个 OAuth App

Settings → Developer settings → OAuth Apps → New OAuth App

字段	填什么
Application name	随意，例如 `monitor`
Homepage URL	`https://hub.example.com`
Authorization callback URL	`https://hub.example.com/api/auth/github/callback`

回调路径必须是 /api/auth/github/callback。填错时 GitHub 授权照常成功，浏览器也回到了站点，但就是没有登录上。

2. 填进面板

在安全页填 Client ID 和 Client Secret，再填允许登录的 GitHub 用户名，多个用逗号分隔。

用户名列表留空表示拒绝所有人，不是放行所有人。

Client Secret 保存后读不回来，面板只显示「已设置」。授权只申请 read:user。

会话与限流

登录会话 14 天过期。安全页的登录会话列出所有会话，可以逐个注销，当前设备带「当前设备」标记
每条会话记录登录时间、方式、来源 IP、设备和最后活动。方式是「应急密码」或 GitHub · 用户名；设备从浏览器的 User-Agent 猜出（如 Chrome · macOS），鼠标停在上面看原始字符串；最后活动按「刚刚 / N 分钟前 / N 小时前 / N 天前」显示，每次带会话的请求都会刷新，最快一分钟写一次
已经登录的设备上，改密码、导入备份都会注销全部会话
同一来源地址 15 分钟内密码输错 5 次即锁定，登录成功清零。反代要透传 X-Forwarded-For，否则所有访客共用一个计数，见反向代理

登录不通时

失败原因都在 hub 日志里：

# 一键脚本
journalctl -u monitor-hub -f | grep sign-in
# Docker
docker logs -f monitor 2>&1 | grep sign-in

bash

日志里的话	含义
`no allowed GitHub users configured`	用户名列表是空的，空 = 拒绝所有人
`GitHub user X is not on the allowed list`	这个用户名不在列表里
`GitHub returned access_denied`	在 GitHub 授权页上点了拒绝
`state mismatch or missing`	不是从登录页发起的，或者 state cookie 已过期（10 分钟）
`The client_id and/or client_secret passed are incorrect`	Client ID 或 Client Secret 不对

同样的原因也会显示在登录页上，只是不带用户名列表：任何 GitHub 账号都能走完授权看到这句提示，列表只写进日志。

日志里一条都没有，就是回调路径填错了：请求没有进到 hub 的任何处理逻辑。未匹配的 /api/ 路径返回 404 而不是页面，所以这种错误会直接显示出来。