企业官网建设流程全解析

Atlas CMMS是一款免费、自托管的 CMMS（计算机化维护管理系统）Web 与移动应用，用于管理企业级设备维护。如果你的公司已经有成熟的LDAP / Active Directory用户目录，逐个手动创建账号和邀请成员会非常低效。本篇指南手把手带你完成Atlas CMMS 接入 LDAP的全部配置：员工直接用域账号登录、首次登录自动建档、定时任务自动用户同步，并通过OU 角色映射自动分配权限——全程无需手工建号。

接入 LDAP 能解决哪些痛点

在制造业、物业、能源等行业，设备维护团队往往横跨多个部门，账号管理是常见的运维负担：

• 统一登录：员工直接复用域账号密码登录 Atlas CMMS，不用记第二套密码
• 自动建号：新入职员工首次用域账号登录即可自动创建账号，无需管理员逐人邀请
• 自动用户同步：内置 Quartz 定时任务，定期从 LDAP 同步用户的创建、更新与禁用
• 自动角色分配：按组织单元（OU）映射表自动分配工程师、财务、IT 等不同角色

LDAP 接入完成后，技术人员用域账号登录，直接进入需要处理的工单看板：

整个功能位于后端 Spring Security + Spring LDAP 技术栈中：LdapSecurityConfig.java 负责连接配置，LdapService.java 负责登录与同步逻辑，完整配置说明见 dev-docs/LDAP_SETUP.md。

工作原理：登录认证与同步流程

登录认证流程

1. 用户在登录页输入域用户名和密码
2. Atlas CMMS 使用配置的搜索基（LDAP_USER_SEARCH_BASES）和过滤条件（LDAP_USER_SEARCH_FILTER）在 LDAP 中查找用户
3. 校验成功后从 LDAP 拉取用户详细信息（邮箱、姓名等）
4. 如果该用户尚不存在，系统自动创建账号（密码为随机值，仅能通过域账号登录）
5. 从用户 DN 中提取 OU，按映射表自动分配角色
6. 签发 JWT 会话令牌

💡 登录接口自带防暴力破解保护，见 AuthController.java 中的bruteForceKey限流逻辑。

角色分配规则

• 从用户 DN 中提取所有ou=...片段
• 依次在LDAP_OU_ROLE_MAPPINGS中查找，第一个命中的 OU 决定角色
• 未命中任何映射时，使用默认角色LIMITED_TECHNICIAN
• 匹配不区分大小写

核心逻辑见 LdapService.java 的getRoleForOu()方法。

快速上手：先创建本地管理员（关键前置条件）

⚠️ 启用 LDAP之前，必须先在本地创建一个组织管理员（owner）账号，否则开启后组织将无人可管理。

1. 以LDAP_ENABLED=false启动 Atlas CMMS
2. 通过 UI 注册第一个账号，它将成为组织 owner
3. 记下该账号的邮箱（如admin@example.com）
4. 再切换到LDAP_ENABLED=true，并将LDAP_ORG_ADMIN配置为第 3 步的邮箱

环境变量配置全解：必填项与默认值一览

所有 LDAP 配置均通过环境变量注入，定义在 application.yml。

必填变量

可选变量与默认值

属性映射（适配非标准 LDAP 目录）

最小可用配置示例

LDAP_ENABLED=true LDAP_URL=ldap://ldap.example.com:389 LDAP_BASE_DN=dc=example,dc=com LDAP_MANAGER_DN=cn=svc_atlas,cn=users,dc=example,dc=com LDAP_MANAGER_PASSWORD=your-service-password LDAP_ORG_ADMIN=admin@example.com LDAP_USER_SEARCH_BASES=ou=engineering,ou=users|ou=finance,ou=users LDAP_USER_SEARCH_FILTER=(uid={0}) LDAP_OU_ROLE_MAPPINGS=Engineering=TECHNICIAN|Finance=REQUESTER|IT=ADMIN

OU 角色映射实战：让每个部门自动获得正确权限

LDAP_OU_ROLE_MAPPINGS的格式为OU名称=角色，多组映射用竖线|分隔。Atlas CMMS 提供六种角色：

例如让运维部门做技术员、财务只能提请求、IT 部门获得管理员权限：

LDAP_OU_ROLE_MAPPINGS=Operations=TECHNICIAN|Finance=REQUESTER|IT=ADMIN

映射生效后，不同角色登录后看到的维护工作台各不相同：

自动用户同步详解：离职即禁用，入职即生效

当LDAP_SYNC_ENABLED=true（默认开启）时，系统会在启动时注册一个 Quartz 定时任务：

• 默认 Cron0 0 0,12 * * ?：每天 0 点和 12 点各执行一次
• 启动即同步：应用启动完成后立即执行一次初始全量同步，见 LdapSyncJobScheduler.java
• 任务执行入口为 LdapSyncJob.java，具体同步逻辑在 LdapService.java 的syncLdapUsers()方法

每次同步执行三类操作：

1. 创建：LDAP 中存在而 Atlas CMMS 中没有的用户，自动建档（LDAP_SYNC_CREATE控制）
2. 更新：同步邮箱、姓名等字段变更（LDAP_SYNC_UPDATE控制）
3. 禁用：LDAP 中已删除的用户，禁用其在 Atlas 中的账号（LDAP_SYNC_DISABLE控制，默认关闭）

⚠️ 同步只影响ssoProvider=LDAP的账号，本地注册的账号完全不受影响，因此可以放心开启LDAP_SYNC_DISABLE=true实现"离职即禁用"。

生产环境安全部署清单

1. 强制 TLS：生产环境务必使用ldaps://加密传输
2. 最小权限服务账号：为LDAP_MANAGER_DN创建专用的只读 LDAP 账号，不要使用目录管理员
3. 密码保密：LDAP_MANAGER_PASSWORD放入 secrets manager 或通过环境变量注入，切勿写入代码库
4. 验证同步：检查日志中出现LDAP user sync completed successfully，即代表同步链路正常（LdapSyncJob.java）

三个最容易踩的配置坑

• LDAP_ORG_ADMIN必须是前置步骤创建的本地 owner 邮箱：填成任意 LDAP 用户会导致组织无人可管理
• OU 名称要与 DN 中的片段完全一致：用户 DN 为uid=zhang,ou=engineering,ou=users,dc=atlas,dc=com时，映射表写Engineering=TECHNICIAN，而不是整条 DN
• {0}是占位符：搜索过滤条件写(uid={0})，不要直接写死某个用户名

更多细节与完整变量说明，可参阅官方文档 dev-docs/LDAP_SETUP.md，以及同步任务实现 api/src/main/java/com/grash/job/ 目录下的源码。