mirror of
https://github.com/moeacgx/Telegram-Panel.git
synced 2026-11-01 13:17:30 +08:00
48 lines
4.7 KiB
Markdown
48 lines
4.7 KiB
Markdown
# 后台认证安全
|
||
|
||
适用版本：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 会重新带回匿名初始口令提示、弱限流和旧会话风险，不宜作为长期公网配置。没有发生新注册、账号换绑或数据库结构迁移。
|