Deployment

Deployment

必须固定的配置

生产环境至少设置：

FLASK_SECRET_KEY=<strong-random-secret>
PASSKEY_RP_ID=example.com
PASSKEY_ORIGIN=https://auth.example.com
PASSKEY_DATABASE=/var/lib/passkey-auth/passkeys-v2.sqlite3
PASSKEY_REGISTRATION_ENABLED=false
PASSKEY_OAUTH_CLIENT_SECRET=<strong-client-secret>
PASSKEY_SERVER_API_TOKEN=<strong-server-token>

FLASK_SECRET_KEY 变化会使现有 session 和签名 token 失效。不要使用开发默认 secret。

OAuth Client

全新数据库会从以下变量导入内置 OAuth Client：

PASSKEY_OAUTH_CLIENT_ID=jstu-passkey-client
PASSKEY_OAUTH_CLIENT_SECRET=<strong-secret>
PASSKEY_OAUTH_CLIENT_NAME="Your App"
PASSKEY_OAUTH_REDIRECT_URIS=https://app.example/callback

导入后在 Management 中持久化管理。旧的 PASSKEY_OAUTH_DEMO_* 不再读取。

WSGI 与反向代理

python -m jstu_passkey.app 使用 Werkzeug 开发服务器。Linux 生产环境建议 Gunicorn：

.venv/bin/python -m pip install gunicorn
.venv/bin/gunicorn \
  --workers 2 \
  --bind 127.0.0.1:5003 \
  --timeout 30 \
  jstu_passkey.app:app

由 Nginx、Caddy 或云代理终止 HTTPS。只有确定代理会清理并设置可信头时才开启：

PASSKEY_TRUST_PROXY_HEADERS=true
PASSKEY_PROXY_FIX_X_FOR=1
PASSKEY_PROXY_FIX_X_PROTO=1
PASSKEY_PROXY_FIX_X_HOST=1

数据库

默认路径：

instance/passkeys-v2.sqlite3

v2 是 fresh-start 数据结构。旧 passkeys.sqlite3 不自动迁移，显式指向旧库会拒绝启动。

SQLite 适合单机和中低写入并发。多 Gunicorn worker 会共享同一数据库文件；先从 1-2 个 worker 开始，并监控锁等待。

HTTPS 与 WebAuthn

• PASSKEY_ORIGIN 必须是浏览器真实 origin
• RP ID 通常是可注册域名或其合适父域
• 线上必须 HTTPS
• localhost 仅适用于本机开发
• LAN IP 测试应使用临时 HTTPS 域名或受信任证书

桌面构建

GitHub Actions 的 Build desktop apps 会生成 Windows、Linux 与 macOS 包。桌面模式使用本机应用数据目录保存数据库与 Flask secret；公开分发前仍需平台代码签名。

部署前再读 Security。