Troubleshooting

Troubleshooting

Passkey 没有弹出

确认页面处于安全上下文：

• 本机使用 http://localhost:<port>
• 线上使用 HTTPS
• PASSKEY_ORIGIN 与地址栏完全一致
• 浏览器支持 WebAuthn

Origin 或 RP ID 错误

PASSKEY_ORIGIN 包含协议、主机和端口；RP ID 不包含协议和端口。反向代理部署时还要确认 Host 与 X-Forwarded-Proto。

OAuth client 校验失败

这通常不是 Passkey 本身失败，而是 token exchange 使用的 client secret 与数据库不一致。

在 Management 中轮换 secret 后，必须同步更新业务系统。Hyping 本地默认使用：

jstu-passkey-client
jstu-passkey-secret

它们只适合本地联调。生产环境使用强随机 secret。

OAuth client 或 redirect_uri 无效

callback 必须逐字符匹配白名单，包括协议、主机、端口和路径。localhost 与 127.0.0.1 不相同。

invalid_state

重新从登录入口开始。常见原因是流程过期、重复使用 callback、多标签页覆盖 state 或业务 session cookie 丢失。

Management 写操作跳去验证页

这是预期行为。可能原因包括：

• 最近一次管理员 Passkey 验证已超过 5 分钟
• 当前 action token 缺失或不匹配
• 浏览器重放了已被成功操作消费的旧 token

验证完成后会签发新的 action token，并回到原视图。再次确认操作即可；系统不会 自动重放原写请求。

数据库被拒绝

当前版本只接受 v2 schema。不要把 PASSKEY_DATABASE 指向旧 passkeys.sqlite3。默认新库是：

instance/passkeys-v2.sqlite3

开发服务器警告

python -m jstu_passkey.app 使用 Werkzeug，仅供开发。生产部署使用 Gunicorn、Waitress 或其他生产 WSGI server，并在前面配置 HTTPS 代理。

测试

.venv/bin/python -m unittest discover -s tests -v
.venv/bin/python -m compileall -q jstu_passkey tests
node --check jstu_passkey/static/main.js
node --check jstu_passkey/static/management.js