在 Devin 中试用 DeepWiki 处理私有仓库
DeepWiki

Stirling-Tools/Stirling-PDF

菜单

用户管理

相关源文件

目的与范围

本文档描述了 Stirling-PDF 中的用户管理系统，详细介绍了用户如何被创建、认证、管理以及他们的权限如何被控制。该系统支持多种认证方法、基于角色的访问控制以及用户管理方面的管理功能。

有关具体认证方法的更多信息，请参阅 认证方法。

来源：src/main/java/stirling/software/SPDF/config/security/UserService.java33-486 src/main/java/stirling/software/SPDF/config/security/SecurityConfiguration.java45-317

系统概览

用户管理架构

来源：src/main/java/stirling/software/SPDF/config/security/SecurityConfiguration.java45-317 src/main/java/stirling/software/SPDF/controller/api/UserController.java42-384 src/main/java/stirling/software/SPDF/controller/web/AccountWebController.java48-448

用户数据模型

来源：src/main/java/stirling/software/SPDF/config/security/UserService.java33-486 src/main/java/stirling/software/SPDF/controller/web/AccountWebController.java48-448

认证系统

Stirling-PDF 支持通过配置启用或禁用多种认证方法

认证方法

  1. 用户名/密码认证:

    • 传统的基于表单的登录
    • BCrypt 密码加密
    • 带有持久化令牌的“记住我”功能

  2. OAuth2 身份验证:

    • 支持多种提供商（Google、GitHub、Keycloak）
    • 基于 OAuth2 信息自动创建用户（可配置）
    • 将 OAuth2 属性映射到用户权限

  3. SAML2 认证:

    • 企业 SSO 集成（高级功能）
    • 自定义响应认证转换器
    • 自动用户配置

  4. API 密钥身份验证:

    • 基于 UUID 的 API 密钥
    • 用于以编程方式访问 API
    • API 密钥请求的 CSRF 豁免

来源：src/main/java/stirling/software/SPDF/config/security/SecurityConfiguration.java109-290 src/main/java/stirling/software/SPDF/controller/api/UserController.java356-383

身份验证流程

来源：src/main/java/stirling/software/SPDF/config/security/SecurityConfiguration.java109-290 src/main/java/stirling/software/SPDF/controller/web/AccountWebController.java72-198

用户管理功能

用户注册与创建

用户可以通过以下方式创建：

  1. 自助注册：如果启用，用户可以自行注册
  2. 管理员创建：管理员可以创建具有特定角色的用户
  3. OAuth2/SAML2 自动创建：用户可以在首次通过 OAuth2/SAML2 登录时自动创建（可配置）
  4. 初始设置：默认管理员用户在首次启动时创建

系统使用特定模式验证用户名

  • 简单用户名模式：^<FileRef file-url="https://github.com/Stirling-Tools/Stirling-PDF/blob/c388ba73/a-zA-Z0-9" undefined file-path="a-zA-Z0-9">Hii</FileRef>[a-zA-Z0-9@._+-]{1,48}[a-zA-Z0-9]$
  • 邮箱模式：^(?=.{1,320}$)(?=.{1,64}@)<FileRef file-url="https://github.com/Stirling-Tools/Stirling-PDF/blob/c388ba73/A-Za-z0-9" undefined file-path="A-Za-z0-9">Hii</FileRef>?@[^-][A-Za-z0-9-]+(?:\\.[A-Za-z0-9-]+)*(?:\\.[A-Za-z]{2,})$

来源：src/main/java/stirling/software/SPDF/config/security/UserService.java358-374 src/main/java/stirling/software/SPDF/controller/api/UserController.java62-76 src/main/java/stirling/software/SPDF/config/security/InitialSecuritySetup.java36-95

用户账户管理

用户可以通过以下功能管理其账户：

功能描述自助服务仅管理员
更改用户名更新用户名（需要密码验证）✓
更改密码更新密码（需要旧密码验证）✓
查看/复制 API 密钥获取用于程序化访问的 API 密钥✓
刷新 API 密钥生成新的 API 密钥✓
首次登录更改密码强制首次登录更改密码✓
更改用户角色修改用户的角色和权限✓
启用/禁用用户切换用户账户激活状态✓
删除用户移除用户账户✓
同步设置将浏览器设置与账户同步✓

来源：src/main/java/stirling/software/SPDF/controller/api/UserController.java77-353 src/main/resources/templates/account.html29-253

管理员功能

管理界面提供了用户管理功能

  1. 用户列表：查看所有用户及其状态信息
  2. 用户创建：创建具有特定角色的新用户
  3. 角色管理：更改用户角色（不能修改当前管理员的角色）
  4. 账户状态：启用/禁用用户账户
  5. 会话管理：查看和终止用户会话
  6. 账户删除：移除用户账户

管理界面还显示了以下统计数据：

  • 总用户数
  • 活跃用户数
  • 禁用用户数

来源：src/main/java/stirling/software/SPDF/controller/api/UserController.java192-353 src/main/java/stirling/software/SPDF/controller/web/AccountWebController.java200-336

基于角色的访问控制

用户角色

该系统实施了基于角色的访问控制，主要角色如下：

角色描述权限
ROLE_ADMIN管理员拥有完整的系统访问权限、用户管理和配置权限
ROLE_USER标准用户可以访问 PDF 操作和个人账户管理
ROLE_DEMO_USER演示用户访问受限，无法更改凭据或使用 API 密钥
ROLE_INTERNAL_API_USER系统 API 用户用于内部 API 访问，在管理界面中不可见

来源：src/main/java/stirling/software/SPDF/config/security/UserService.java192-232 src/main/java/stirling/software/SPDF/controller/api/UserController.java216-230

授权流程

来源：src/main/java/stirling/software/SPDF/controller/api/UserController.java62-353 src/main/java/stirling/software/SPDF/config/security/SecurityConfiguration.java180-209

API 密钥管理

Stirling-PDF 提供了 API 密钥功能，用于程序的访问

  1. 生成：API 密钥是基于 UUID 的令牌
  2. 检索：用户可以查看和复制其 API 密钥
  3. 重新生成：如果需要，用户可以刷新其 API 密钥
  4. 使用：API 密钥通过 X-API-KEY 标头传递
  5. 验证：系统会验证 API 密钥并将请求与特定用户关联
  6. CSRF 排除：带有有效 API 密钥的请求会绕过 CSRF 保护

来源：src/main/java/stirling/software/SPDF/config/security/UserService.java112-168 src/main/java/stirling/software/SPDF/controller/api/UserController.java356-383 src/main/java/stirling/software/SPDF/config/security/SecurityConfiguration.java119-143

会话管理

系统实现了全面的会话管理

  1. 并发会话：每个用户最多 10 个会话
  2. 会话注册表：跟踪用户会话
  3. 会话过期：自动使不活动的会话过期
  4. 强制登出：管理员可以使用户会话失效
  5. 记住我：通过“记住我” cookie 实现持久登录
  6. 会话失效：在更改密码、登出或禁用账户时

来源： src/main/java/stirling/software/SPDF/config/security/SecurityConfiguration.java147-180 src/main/java/stirling/software/SPDF/config/security/UserService.java399-418

初始设置和默认配置

首次启动时，系统执行初始安全设置

  1. 默认管理员用户：如果不存在，则创建默认管理员用户

    • 默认凭据：用户名 admin，密码 stirling
    • 用户在首次登录时被标记为需要更改密码

  2. 基于配置的管理员：或者根据 application properties 中的设置创建管理员

    • 使用 security.initialLogin.username 和 security.initialLogin.password

  3. 内部 API 用户：为内部 API 操作创建一个特殊的系统用户

    • 使用生成的 UUID 作为密码和 API 密钥
    • 普通用户管理中不可见

  4. 数据库备份/恢复：如果存在备份，则导入数据库，而不是创建默认用户

来源： src/main/java/stirling/software/SPDF/config/security/InitialSecuritySetup.java36-95

用户设置同步

系统允许浏览器设置和用户账户设置之间的同步

  1. 浏览器设置：存储在浏览器 localStorage 中
  2. 账户设置：存储在用户数据库记录中
  3. 同步：浏览器和账户之间的双向同步
  4. 排除的设置：某些技术设置不包括在同步范围内

来源： src/main/resources/templates/account.html254-348 src/main/java/stirling/software/SPDF/controller/api/UserController.java177-190

安全考量

用户管理系统实现了多项安全措施

  1. 密码加密：BCrypt 密码哈希
  2. CSRF 防护：基于令牌的 Web 表单 CSRF 防护（API 密钥请求除外）
  3. 会话安全：安全的会话管理，具有正确的失效处理
  4. 输入验证：用户名和密码验证
  5. 身份验证失败处理：正确的错误处理和消息提示
  6. API 密钥安全：API 密钥的安全生成和验证
  7. 基于角色的限制：使用注解进行函数级授权

来源： src/main/java/stirling/software/SPDF/config/security/SecurityConfiguration.java98-317 src/main/java/stirling/software/SPDF/config/security/UserService.java98-168