# LDAP同步记录功能 本文档介绍了PlayEdu系统中LDAP同步记录功能的使用方法和实现细节。 ## 功能概述 LDAP同步记录功能主要实现了以下功能： 1. 记录每次LDAP数据同步的统计数据： - 同步的部门和用户总数 - 新增、更新、删除的部门和用户数量 2. 将同步的LDAP数据保存到S3存储中，方便后续查询和下载 3. 记录执行同步操作的管理员ID 4. 通过状态控制防止短时间内多次提交同步请求 5. 记录每次同步中每个部门和用户的详细变更情况 ## 数据库表 ### 主同步记录表 系统添加了新的数据库表 `ldap_sync_record`，其结构如下： ```sql CREATE TABLE `ldap_sync_record` ( `id` int(11) NOT NULL AUTO_INCREMENT, `admin_id` int(11) NOT NULL DEFAULT 0 COMMENT '执行同步的管理员ID，0表示系统自动执行', `status` tinyint(4) NOT NULL DEFAULT 0 COMMENT '状态：0-进行中，1-成功，2-失败', `s3_file_path` varchar(255) DEFAULT NULL COMMENT 'S3存储中的文件路径', `total_department_count` int(11) NOT NULL DEFAULT 0 COMMENT '总部门数量', `created_department_count` int(11) NOT NULL DEFAULT 0 COMMENT '新增部门数量', `updated_department_count` int(11) NOT NULL DEFAULT 0 COMMENT '更新部门数量', `deleted_department_count` int(11) NOT NULL DEFAULT 0 COMMENT '删除部门数量', `total_user_count` int(11) NOT NULL DEFAULT 0 COMMENT '总用户数量', `created_user_count` int(11) NOT NULL DEFAULT 0 COMMENT '新增用户数量', `updated_user_count` int(11) NOT NULL DEFAULT 0 COMMENT '更新用户数量', `deleted_user_count` int(11) NOT NULL DEFAULT 0 COMMENT '删除用户数量', `banned_user_count` int(11) NOT NULL DEFAULT 0 COMMENT '被禁止的用户数量', `error_message` text DEFAULT NULL COMMENT '错误信息', `created_at` datetime NOT NULL, `updated_at` datetime NOT NULL, PRIMARY KEY (`id`) ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='LDAP同步记录表'; ``` ### 部门同步详情表 记录每个部门在同步过程中的详细变更情况： ```sql CREATE TABLE `ldap_sync_department_detail` ( `id` int(11) NOT NULL AUTO_INCREMENT, `record_id` int(11) NOT NULL COMMENT '关联的同步记录ID', `department_id` int(11) DEFAULT NULL COMMENT '关联的部门ID', `uuid` varchar(255) NOT NULL COMMENT 'LDAP部门UUID', `dn` varchar(255) NOT NULL COMMENT 'LDAP部门DN', `name` varchar(255) NOT NULL COMMENT '部门名称', `action` tinyint(4) NOT NULL COMMENT '操作：1-新增，2-更新，3-删除，4-无变化', `created_at` datetime NOT NULL, PRIMARY KEY (`id`), KEY `record_id` (`record_id`), KEY `department_id` (`department_id`) ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='LDAP部门同步详情表'; ``` ### 用户同步详情表 记录每个用户在同步过程中的详细变更情况： ```sql CREATE TABLE `ldap_sync_user_detail` ( `id` int(11) NOT NULL AUTO_INCREMENT, `record_id` int(11) NOT NULL COMMENT '关联的同步记录ID', `user_id` int(11) DEFAULT NULL COMMENT '关联的用户ID', `uuid` varchar(255) NOT NULL COMMENT 'LDAP用户UUID', `dn` varchar(255) NOT NULL COMMENT 'LDAP用户DN', `cn` varchar(255) NOT NULL COMMENT '用户名称', `uid` varchar(255) NOT NULL COMMENT '用户ID/登录名', `email` varchar(255) DEFAULT NULL COMMENT '用户邮箱', `ou` text DEFAULT NULL COMMENT '用户部门路径', `action` tinyint(4) NOT NULL COMMENT '操作：1-新增，2-更新，3-删除，4-无变化，5-禁止', `created_at` datetime NOT NULL, PRIMARY KEY (`id`), KEY `record_id` (`record_id`), KEY `user_id` (`user_id`) ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='LDAP用户同步详情表'; ``` ## API接口 系统提供了以下API接口用于LDAP同步操作和记录管理： ### 1. 手动触发LDAP同步 - **URL**: `/backend/v1/ldap/sync` - **方法**: POST - **权限**: `ldap:sync` - **返回数据**: ```json { "code": 0, "data": { "record_id": 1 // 同步记录ID }, "message": "success" } ``` ### 2. 获取LDAP同步记录列表 - **URL**: `/backend/v1/ldap/sync-records` - **方法**: GET - **权限**: `ldap:sync:records` - **参数**: - `page`: 页码，默认1 - `size`: 每页条数，默认10 - **返回数据**: ```json { "code": 0, "data": { "data": [ { "id": 1, "admin_id": 0, "status": 1, "s3_file_path": "ldap/sync/ldap_sync_1_1620000000000.json", "total_department_count": 10, "created_department_count": 5, "updated_department_count": 3, "deleted_department_count": 2, "total_user_count": 100, "created_user_count": 50, "updated_user_count": 30, "deleted_user_count": 20, "banned_user_count": 0, "error_message": null, "created_at": "2023-08-01 12:00:00", "updated_at": "2023-08-01 12:01:00" } ], "total": 100 }, "message": "success" } ``` ### 3. 获取LDAP同步记录详情 - **URL**: `/backend/v1/ldap/sync-records/{id}` - **方法**: GET - **权限**: `ldap:sync:records` - **返回数据**: ```json { "code": 0, "data": { "id": 1, "admin_id": 0, "status": 1, "s3_file_path": "ldap/sync/ldap_sync_1_1620000000000.json", "total_department_count": 10, "created_department_count": 5, "updated_department_count": 3, "deleted_department_count": 2, "total_user_count": 100, "created_user_count": 50, "updated_user_count": 30, "deleted_user_count": 20, "banned_user_count": 0, "error_message": null, "created_at": "2023-08-01 12:00:00", "updated_at": "2023-08-01 12:01:00" }, "message": "success" } ``` ### 4. 获取同步详情 - **URL**: `/backend/v1/ldap/sync-records/{id}/details` - **方法**: GET - **权限**: `ldap:sync:records` - **参数**: - `type`: 详情类型，`department`=部门，`user`=用户 - `action`: 操作类型，当type=department时：0=全部，1=新增，2=更新，3=删除，4=无变化；当type=user时：0=全部，1=新增，2=更新，3=删除，4=无变化，5=禁止，默认0 - `page`: 页码，默认1 - `size`: 每页条数，默认10 - **返回数据**: ```json { "code": 0, "data": { "records": [ { // 当type=department时返回部门详情 "id": 1, "record_id": 1, "department_id": 10, "uuid": "12345678-1234-1234-1234-123456789012", "dn": "ou=HR,dc=example,dc=com", "name": "HR", "action": 1, "created_at": "2023-08-01 12:00:00" } // 或当type=user时返回用户详情 { "id": 1, "record_id": 1, "user_id": 100, "uuid": "12345678-1234-1234-1234-123456789012", "dn": "cn=John Doe,ou=HR,dc=example,dc=com", "cn": "John Doe", "uid": "johndoe", "email": "john.doe@example.com", "ou": "HR", "action": 1, "created_at": "2023-08-01 12:00:00" } ], "total": 100, "size": 10, "current": 1, "pages": 10 }, "message": "success" } ``` ### 5. 下载LDAP同步记录数据 - **URL**: `/backend/v1/ldap/sync-records/{id}/download` - **方法**: GET - **权限**: `ldap:sync:records` - **返回数据**: ```json { "code": 0, "data": { "url": "https://your-s3-domain.com/ldap/sync/ldap_sync_1_1620000000000.json" }, "message": "success" } ``` ## 定时同步 系统会每小时自动执行一次LDAP同步，同步过程和统计数据会记录到 `ldap_sync_record` 表中。自动同步时 `admin_id` 字段为0。 ## 权限说明 为了使用LDAP同步记录功能，需要为管理员角色分配以下权限： - `ldap:sync`: 允许手动触发LDAP同步 - `ldap:sync:records`: 允许查看LDAP同步记录 ## 同步状态说明 LDAP同步记录的状态字段（`status`）有以下值： - `0`: 进行中 - `1`: 成功 - `2`: 失败 当状态为2（失败）时，错误信息会记录在 `error_message` 字段中。 ## 操作类型说明 详细同步记录中的操作类型（`action`）有以下值： ### 部门操作类型： - `1`: 新增 - 首次在LDAP中发现的部门 - `2`: 更新 - 已存在但信息发生变化的部门 - `3`: 删除 - 在LDAP中不再存在的部门 - `4`: 无变化 - 已存在且信息未发生变化的部门 ### 用户操作类型： - `1`: 新增 - 首次在LDAP中发现的用户 - `2`: 更新 - 已存在但信息发生变化的用户 - `3`: 删除 - 在LDAP中不再存在的用户 - `4`: 无变化 - 已存在且信息未发生变化的用户 - `5`: 禁止 - 在LDAP中被标记为禁止状态的用户 ## S3存储 同步的LDAP数据会以JSON格式保存到S3存储中，路径格式为： ``` ldap/sync/ldap_sync_{记录ID}_{时间戳}.json ``` JSON文件包含完整的同步数据，包括所有部门和用户的信息。 ## 实现细节 系统在每次LDAP同步时都会进行以下操作： 1. 创建主同步记录，初始状态为"进行中" 2. 获取LDAP配置信息并查询所有LDAP部门和用户数据 3. 收集统计信息并保存到S3 4. 收集每个部门和用户的详细变更情况 5. 执行实际的同步操作，包括部门同步和用户同步 6. 保存部门和用户的详细变更记录 7. 更新主同步记录状态为"成功" 如果同步过程中出现异常，系统会捕获异常信息并更新主同步记录状态为"失败"。