magentaaps/os2mo-ldap-import-export

MO-LDAP同步代理镜像文档

1. 镜像概述

MO-LDAP同步代理镜像旨在构建MO系统与LDAP目录服务之间的桥梁，通过配置化方式实现两者数据的高效同步，解决跨系统信息不一致问题，支撑企业级身份数据统一管理需求。

2. 核心功能与特性

• 灵活同步方向：支持单向（MO→LDAP或LDAP→MO）及双向数据同步，满足不同集成场景需求
• 多对象类型支持：可同步用户、组织、角色、权限等多种实体对象
• 多样化同步策略：支持定时同步（自定义时间间隔）和实时同步（事件触发）两种模式
• 自定义字段映射：允许通过配置文件定义MO与LDAP对象属性的映射关系
• 健壮的错误处理：内置数据校验、冲突解决机制及失败重试逻辑，保障同步稳定性
• 完善日志体系：提供分级日志（DEBUG/INFO/WARN/ERROR），支持问题追溯与性能分析

3. 使用场景

• 企业系统集成：在已部署MO系统和LDAP的企业环境中，实现用户身份数据跨系统统一
• 统一身份认证支撑：为基于LDAP的单点登录（SSO）体系提供MO系统用户数据同步能力
• 多系统数据一致性维护：减少人工操作，避免因信息不同步导致的权限管理混乱

4. 使用方法

4.1 基础部署（Docker Run）

bash
docker run -d \
  --name mo-ldap-sync \
  --restart unless-stopped \
  -e SYNC_DIRECTION="bidirectional" \
  -e LDAP_URL="ldap://ldap.example.com:389" \
  -e LDAP_BASE_DN="dc=example,dc=com" \
  -e LDAP_BIND_DN="cn=admin,dc=example,dc=com" \
  -e LDAP_BIND_PASSWORD="your-ldap-password" \
  -e MO_API_URL="https://mo.example.com/api/v1" \
  -e MO_API_TOKEN="your-mo-api-token" \
  -e SYNC_INTERVAL=3600 \
  -v /host/path/to/config:/app/config \
  your-registry/mo-ldap-sync:latest

4.2 核心环境变量配置

4.3 高级配置（配置文件）

对于复杂同步需求，可通过挂载配置文件（推荐YAML格式）实现精细化控制，配置文件路径：/app/config/config.yaml。示例配置：

yaml
sync:
  objects:
    - type: user
      mapping:
        mo_fields: [username, email, display_name, status]
        ldap_fields: [uid, mail, cn, userAccountControl]
        custom_maps:
          status: { active: 512, inactive: 514 }  # LDAP userAccountControl映射
      filter: "status eq 'active'"  # 仅同步活跃用户
      sync_direction: mo_to_ldap   # 覆盖全局同步方向
    - type: organization
      mapping:
        mo_fields: [org_code, org_name]
        ldap_fields: [ou, description]
      sync_direction: ldap_to_mo
  triggers:
    realtime:
      enabled: true
      event_types: [user_created, user_updated, org_deleted]  # 触发实时同步的事件
    retry:
      max_attempts: 3
      interval: 60  # 重试间隔（秒）

配置文件挂载方式

bash
-v /host/path/to/config.yaml:/app/config/config.yaml

5. 同步策略配置说明

5.1 定时同步

通过SYNC_INTERVAL环境变量设置同步周期（秒），适用于数据更新频率较低的场景。设置为0时禁用定时同步，仅通过实时触发或手动执行同步。

5.2 实时同步

在配置文件中启用realtime.enabled: true，并指定event_types，代理将监听MO系统事件通知，触发即时同步。需确保MO系统已配置事件推送端点指向代理服务。

6. 日志与故障排查

• 日志查看：通过docker logs mo-ldap-sync查看实时日志，包含同步进度、错误详情及性能指标
• 常见问题处理：
  • 同步失败：检查网络连通性（MO与LDAP服务是否可达）、凭证有效性（BIND_DN/PASSWORD、API_TOKEN）
  • 数据冲突：通过配置文件conflict_resolution策略（如overwrite_by_latest/keep_both）处理
  • 性能问题：调大SYNC_INTERVAL或减少单次同步数据量（通过filter配置）

7. 注意事项

• 数据安全：生产环境中建议通过LDAPS（端口636）加密LDAP连接，MO API使用HTTPS协议
• 资源规划：根据数据量调整容器内存配置（建议至少512MB），避免同步过程中OOM
• 数据备份：首次同步前建议备份MO和LDAP数据，避免批量同步操作导致的数据异常
• 权限最小化：LDAP绑定用户仅授予必要的读写权限，MO API令牌限制为同步所需的最小权限集