后台认证安全¶
适用版本：v1.31.87 起；要求持久化数据目录可写，前后端使用同一版本。此变更不修改 Telegram 账号、代理和任务数据。
初始化和升级¶
匿名登录页不得输出初始用户名、密码或秘密文件内容。默认不再分发固定口令；未提供口令时使用加密随机数生成一次性口令，写入凭据同目录的 admin-bootstrap-password.txt。Linux 创建权限 0600，Windows 继承私有数据目录权限；不写入日志、HTTP、镜像或发布资产。
现有已改密的凭据保留。历史未改密且仍为固定 tgpanel123 的凭据旋转为随机口令。重启不会重新生成已保存口令。旧默认文件仍参与持久化恢复识别，不能覆盖用户已设置的真实凭据。首次登录后必须改为至少 12 位、不同于当前口令的新密码。更改用户名不能跳过此步骤。
凭据原子保存成功后才更新内存状态。完成改密后清理初始化明文文件；清理失败仅记录不含秘密的错误，后续启动重试。
登录请求和会话¶
两个登录入口共用滚动窗口：每来源地址 60 秒内最多 5 次、进程全局最多 30 次，不排队且不永久锁定账号。拒绝返回 429 与剩余窗口的 Retry-After。转发 IP 依赖可信反代，默认全局窗口也限制伪造来源地址造成的哈希负载。多实例需在可信入口部署共享限流。
未知用户名也执行相同的 PBKDF2-SHA256 口令计算，然后组合用户名与口令结果；不靠添加固定 sleep 隐藏差异。服务端表单和 JSON 登录使用 ASP.NET 防伪 Cookie 与令牌；后端在认证之后执行防伪检查，桌面环回 HTTP 登录仍支持。
Cookie 携带持久化 SecurityStamp。升级首次填充旧凭据安全版本时，旧 Cookie 需重新登录。改密码或用户名轮换该版本并刷新当前请求会话，其他浏览器 Cookie 在下次请求时失效。
首次设置阶段由后端限制后台业务 API、Cookie 后台模块、旧 Blazor 通道及下载，改密入口统一使用 Vue 页面；身份查询、登录、防伪令牌、注销、用户名及密码设置仍可访问。健康检查及独立 API Key/Webhook 按各自合同鉴权，不能把模块任意 AllowAnonymous 当作后台豁免依据。
验收与排查¶
SPA 静态资源与中间件顺序（v1.31.88 起）¶
前置条件是发布目录包含 wwwroot/panel-spa/index.html 及其引用的资源。
/ui 的公开 SPA 静态文件中间件必须先于 UseRouting 注册：路由选中
/ui/assets/{**path} 兜底端点后，ASP.NET Core 静态文件中间件会跳过已有文件，
导致入口 HTML 返回 200、所有 JS/CSS 返回 404，浏览器显示空白。
只前移 SPA 文件处理；路由、认证和强制改密检查仍按原顺序执行，默认 wwwroot 与持久化 uploads 的安全边界不变。真实 HTTP 测试须覆盖匿名及首次改密会话的 资源 GET/HEAD、正文、MIME 和缓存，以及原有 CSRF、业务接口和下载限制。
部署工作流使用 tools/check-spa-assets.py 检查入口引用的全部 JS/CSS，
请求间共享 50 秒预算，工作流另设 60 秒硬超时；任意资源失败都必须中止验收。该检查不等同于登录后的业务验收，
还需浏览器确认登录页及仪表盘渲染。回滚保留数据和凭据，仅恢复应用版本；
未包含此修复的 v1.31.87 存在上述路由冲突，不应作为已通过页面验收的回滚版本。
验收必须覆盖：匿名页面无秘密；表单/JSON 缺失、错误防伪令牌拒绝；带同浏览器令牌成功登录；登录后的匿名令牌不可用于改密；两入口共享额度、窗口恢复；未知用户名与错误密码均失败；首次登录不能读业务 API；仅改用户名仍受限；改密后当前会话可用、第二会话失效；随机口令重启后不变；旧已改密凭据恢复正常；桌面 HTTP 登录；发布目录无秘密文件。
400 INVALID_CSRF_TOKEN 时刷新页面，检查代理是否保留 Cookie 与请求头，避免混用旧前端；429 时按 Retry-After 等待；首次密码不可用时在服务器读取私有初始化文件或核对显式配置，禁止通过网页暴露文件。升级后需要重新登录属预期行为。不要删除 admin_auth.json 解决登录问题。
回滚¶
升级前备份持久化凭据和数据保护密钥，保留原镜像。代码回滚应保留当前数据目录和管理员已修改的凭据；旧代码会忽略新增安全版本字段。回滚到 v1.31.86 会重新带回匿名初始口令提示、弱限流和旧会话风险，不宜作为长期公网配置。没有发生新注册、账号换绑或数据库结构迁移。