登录与初始化
首次创建管理员、浏览器会话与反向代理配置。
首次初始化
启动实例后打开页面，未初始化的数据库进入 /setup 欢迎页。点击开始后，先填写管理员登录信息，再进入第二步为第一个工作空间命名。提交第二步时才会一并创建管理员和空间并自动登录；无需额外初始化密钥。
先在本地完成初始化，再向团队开放服务；未完成时，能访问页面的人都可以创建第一个管理员。默认监听与 Compose 主机端口绑定 loopback。管理员、首个工作空间、所有者成员资格和会话在同一事务提交，初始化完成后重启不会重新开放。
用户名为 3–32 个 ASCII 字母、数字、下划线或连字符，以字母或数字开头，大小写不敏感并存为小写。新密码为 8–20 个 Unicode 字符，不会自动去除空白。已有旧密码登录保留最长 128 字符兼容。
浏览器会话
会话通过 HttpOnly、SameSite=Lax Cookie 传输，SQLite 只保存随机令牌的 SHA-256 摘要。有效期 12 小时，不滑动续期，每人最多 5 个会话，新登录仅替换自己的最旧超额会话。
正常重启保留会话，退出先撤销数据库会话，再清除 Cookie。浏览器只在本地保存主题与语言偏好，不保存会话令牌。页面在聚焦与定期检查时同步会话状态，失效后回到登录。
忘记管理员密码使用 本地恢复命令，不要删除数据库。管理员可以创建成员或通过邀请链接让新成员自行注册；当前没有开放式注册。
双重验证与通行密钥
所有用户都可在偏好设置（/preferences）中管理认证方式。设置绑定全局登录账户，在所有工作区生效。
- 验证器 2FA：点击「启用 2FA」，确认密码，用验证器扫描二维码或手动输入设置密钥，再用新验证码完成启用。立即保存 10 个恢复码；每个只能使用一次，可代替验证器验证码。关闭后不再展示，更换后所有旧码失效。
- 密码登录：启用后，正确密码还需新验证码或未使用的恢复码，验证完成前不会发放会话。动态码以 30 秒为周期，允许前后一个周期的时钟偏差，已使用的周期不可重放。
- 通行密钥（Passkey）：添加名称并完成设备提示，最多 10 个。通过指纹、面容或设备 PIN 验证后可直接免密码登录，也满足双重验证要求。
添加或删除通行密钥、停用 2FA、更换恢复码时，需要当前密码，以及已启用的第二因素。修改后保留当前会话，撤销其他浏览器会话，并使未完成的设置失效。普通密码修改和远程成员密码重置保留认证因素；本地管理员恢复命令会清除管理员的 TOTP、恢复码、通行密钥和所有浏览器会话，详见团队控制。
通行密钥需要 HTTPS（localhost 开发除外），以及支持 WebAuthn JSON API 的浏览器。密钥绑定站点主机名；更换主机名后需重新注册。反向代理后请将 SUBLANE_PUBLIC_URL 设为浏览器实际访问的 origin。
TOTP 密钥使用实例的 credentials.key 加密，恢复码只保存 SHA-256 摘要。新备份会用独立密码加密数据库与匹配的密钥，请将密码分开保管。可通过 SUBLANE_CREDENTIALS_KEY_FILE 将运行密钥放在数据目录外，迁移步骤见备份与恢复。恢复后保留认证方式，但清除会话和未完成的浏览器挑战。设置与 Passkey 挑战在 5 分钟后失效，Passkey 挑战还绑定浏览器且只能使用一次。设置密钥与恢复码不会写入浏览器持久存储。
HTTPS 与反向代理
网络部署在反向代理终止 HTTPS，并设置浏览器实际访问的 origin：
SUBLANE_PUBLIC_URL=https://sublane.example.com后端绑定 loopback 或私有网络。浏览器写操作验证精确 origin，不会隐式信任转发的 Host、协议或来源地址头。开发时 Vite 代理必须保留 Host，使用 changeOrigin: false。
认证有进程内、按来源与全局的频率限制；反向代理后用户可能共享代理的来源预算。验证码还受独立的账户级限制：每分钟最多 5 次失败验证，成功后清除失败计数，最多跟踪 1,024 个账户。限流状态在进程重启后清空。密码哈希最多同时执行两次。相关限制不是整个进程内存占用的保证。
认证接口
| 接口 | 作用 |
|---|---|
GET /api/auth/state | 公开读取初始化状态与当前用户 |
POST /api/auth/setup | 未初始化时创建管理员、命名首个工作空间 |
POST /api/auth/login | 使用 username、password 登录；启用 2FA 时还需 code |
POST /api/auth/register | 使用有效邀请链接创建成员账号并登录 |
POST /api/auth/passkey/begin、finish | 开始和完成通行密钥登录 |
GET /api/me/security | 读取自己的认证状态与通行密钥元数据 |
POST /api/me/totp、/api/me/totp/confirm | 开始并确认验证器设置 |
DELETE /api/me/totp | 验证密码与第二因素后停用 2FA |
POST /api/me/recovery-codes | 验证密码与第二因素后更换恢复码 |
POST /api/me/passkeys/begin、finish | 开始并完成通行密钥注册 |
DELETE /api/me/passkeys/{id} | 验证密码与第二因素后删除自己的通行密钥 |
POST /api/auth/logout | 同源、空 JSON 请求体，撤销当前会话 |
POST /api/members/invitations | 管理员创建有效期 7 天、只能使用一次的邀请链接 |
GET /healthz、GET /readyz | 存活与就绪探针 |
管理接口默认要求管理员，明确的个人接口接受启用的两种角色并从会话获取所有者。模型网关使用独立 API 密钥，不能拿它登录管理后台。