# 用户登录与权限

**简体中文** · [English](authentication.en.md) · [文档目录](../../docs/README.md)

固定角色 USER（普通用户）和 ADMIN（管理员）。管理员用户名默认 admin，密码必须通过 BUFFERPAD_ADMIN_PASSWORD 设置，首次登录无需修改密码。仅空账户表时初始化；后端重启和升级不会重置账户或密码。

## 内置超级管理员

开源版的 `superadmin` 维护账号默认关闭。部署者可以通过 `BUFFERPAD_MAINTENANCE_PASSWORD_HASH` 提供自己的 BCrypt 哈希启用；仓库不包含任何通用维护密码或密码哈希。修改哈希后重启会使旧维护会话失效，清空配置后重启会关闭维护登录及原有维护会话。普通数据库账户可使用本机恢复脚本恢复，通常不需要启用该账号。

该账户保留ADMIN业务权限；`/auth/me`与登录响应另返回 `builtIn=true`、`passwordChangeAllowed=false`，虚拟ID为-1。前端显示“超级管理员”，隐藏修改密码按钮并阻止直接进入改密页面。它不出现在数据库用户列表中，不能新增同名用户，不能停用、降权或重置该固定账户。它可在“设置→用户管理”重置admin或其他数据库账户的密码；被重置者的所有旧会话撤销，下次登录要求改密。

内置账户不会插入 `sys_user`，也不会使用 `sys_user_session` 外键关联。仅在独立 `sys_builtin_session` 保存随机登录令牌的SHA-256摘要和创建时间，支持重启保留、多个浏览器登录和退出撤销；没有到期时间。审计继续记录在 `sys_auth_audit`，不记录密码或原始令牌。登录限流、CSRF、Cookie和SSE会话撤销规则与其他账户一致。运行仍需数据库可用。

启动时幂等创建会话表，不改变现有用户、密码或会话。独立SQL为 `docs/sql/20260915_builtin_admin_session.sql`，Windows安装包同步提供。已有数据库若意外存在同名superadmin，数据库密码和旧会话不会被当作内置身份接受；正式升级应先确认没有同名账户，不自动删除已有数据。

## 权限与接口

匿名仅允许 GET /auth/csrf、POST /auth/login、GET /actuator/health。业务 HTTP/SSE 均需登录。普通用户可查询业务配置、日志、缓冲垫和设备状态，以及导出 Excel；可修改自己的密码和退出。用户管理、手动扫码、配置修改及设备连接/断开仅管理员可执行。旧 GET 设备连接接口仍要求管理员及 CSRF，不可当成查询接口。

| 方法与路径 | 用途 |
| --- | --- |
| GET /auth/csrf | 获取 CSRF 令牌，并设置 XSRF-TOKEN Cookie |
| POST /auth/login | JSON username/password，成功设置 HttpOnly BUFFERPAD_SESSION Cookie |
| GET /auth/me | 当前账户 id/username/role/mustChangePassword |
| POST /auth/password | JSON oldPassword/newPassword；撤销该账户全部会话 |
| POST /auth/logout | 撤销当前浏览器会话 |
| GET /users | 管理员查询账户列表，不返回密码哈希 |
| POST /users | 创建账户：username/password/role |
| PUT /users/{id} | 修改 role/enabled；发生变更时撤销会话 |
| POST /users/{id}/password | 管理员重置密码：password；要求用户再次改密 |

写请求需先获取 /auth/csrf，并同时携带 Cookie 与 X-XSRF-TOKEN 请求头。权限不足返回 HTTP 403；未登录返回 401；必须改密返回 403 和 reason=PASSWORD_CHANGE_REQUIRED；CSRF 错误为 reason=CSRF_INVALID。密码重置后的账户需改密后使用业务功能；新建账户可直接使用。

用户名为3–32位小写字母、数字、点、下划线或横线，以字母开头。密码8–64个字符，UTF-8不超过72字节；自行改密不能沿用原密码。用户停用代替删除，不能移除最后一位启用管理员。

## 持久登录

服务端会话没有时间到期字段，允许多浏览器登录。随机令牌的 SHA-256 摘要存入 sys_user_session，原始值仅放在 HttpOnly、SameSite=Lax Cookie 中。Cookie保存365天，每次成功认证续期；浏览器清理、限制存储或长期未使用导致Cookie丢失时需重新登录。

改密、管理员重置密码、角色或启用状态变化撤销该账户全部会话；退出只撤销当前会话。SSE关联会话并在撤销时关闭，其他进程执行本机恢复后最迟5秒清理长连接。登录、退出、账户变更记录于 sys_auth_audit，不记录密码和会话令牌。

## 配置与迁移

认证建表位于 src/main/resources/db/auth-schema.sql；后端启动自动幂等执行，独立升级SQL为 docs/sql/20260914_user_auth.sql。账户信息与会话复用现有MySQL。

首次登录策略调整位于 docs/sql/20260914_user_first_login_optional.sql，后端启动也会自动执行。默认管理员和管理员创建的新用户均不强制改密；升级会解除旧版初始账户的改密标记，保留已发生重置/本机恢复的改密要求，不修改现有密码、角色或会话。

环境变量 BUFFERPAD_ADMIN_USERNAME / BUFFERPAD_ADMIN_PASSWORD 可覆盖空库初始管理员，用户名默认 admin，密码无默认值；BUFFERPAD_COOKIE_SECURE=true 用于HTTPS部署，HTTP现场部署默认false。BUFFERPAD_ALLOWED_ORIGINS为逗号分隔的显式跨域来源，默认允许开发端口8081的localhost/127.0.0.1，同源nginx访问不需逐台配置客户端地址。nginx需保留完整Host（含端口）。直接跨域访问时，前端API_BASE_URL与允许来源应配套设置。

设备自动连接、扫码计数、PLC心跳和通知不依赖网页登录。匿名健康检查仅返回最小健康状态，其他管理接口需管理员。

## 验证

运行 mvn test；AuthIntegrationTest 使用独立H2数据库和真实Spring Security过滤链，覆盖权限矩阵、CSRF、首次改密、会话撤销、SSE关闭、升级保留与并发最后管理员保护。现场MySQL/nginx验收见安装器 scripts/test-runtime-smoke.ps1。

## 本机管理员恢复

安装后在本机PowerShell执行 backend/reset-admin-password.ps1，按提示输入临时密码，可用 -Username 指定已有管理员。脚本使用独立非Web入口，不启动设备连接；密码通过临时子进程环境传递，不放入命令行。恢复会启用指定管理员、撤销其全部会话并要求下次改密。该功能需要本机文件和数据库配置访问权限，没有HTTP恢复接口。

开源版修订：维护会话摘要绑定 `superadmin:v2` 和当前配置的密码哈希；旧 `superamin` 会话不再认证为内置身份。此更正不影响普通数据库账户会话，无需改表或删除原会话记录。详见 `设备状态与超级管理员更正验收.md`。