magentaaps/os2mo-init

OS2mo Fixture Loader 镜像文档

镜像概述

OS2mo Fixture Loader 是专为 OS2mo 系统设计的测试数据加载工具，用于加载预设的 fixture 数据（如组织架构、用户信息、职位配置等）到 OS2mo 实例中。该镜像旨在简化开发、测试及演示环境的初始化流程，通过标准化的数据加载策略，确保环境快速具备可用的基础数据。

核心功能与特性

核心功能

• 支持 OS2mo 核心数据类型加载，包括组织单元、用户账户、职位角色、权限配置等
• 集成 OS2mo API 客户端，自动处理认证与数据校验
• 提供数据依赖解析，确保关联数据按正确顺序加载（如先加载组织单元再加载用户）

关键特性

• 可配置性：通过环境变量自定义数据加载策略（全量/增量加载、冲突处理规则等）
• 数据验证：加载前自动校验数据格式与业务规则，避免无效数据写入
• 轻量级设计：基于 Python slim 镜像构建，体积小、启动快
• 日志输出：详细记录加载过程，支持日志级别调整（DEBUG/INFO/WARN/ERROR）

使用场景与适用范围

典型使用场景

• 开发环境初始化：快速搭建包含基础测试数据的 OS2mo 开发环境
• 自动化测试：在 CI/CD 流程中为测试用例预置标准化测试数据
• 演示环境部署：为客户演示或培训环境加载示例数据，展示系统功能
• 数据迁移验证：验证数据迁移脚本输出的 fixture 数据是否符合 OS2mo 数据规范

适用范围

• OS2mo v1.5+ 版本实例
• 基于 Docker/Kubernetes 的容器化部署环境
• 需要标准化测试数据的开发与 QA 团队

使用方法与配置说明

前置条件

• 已部署 OS2mo 实例并确保 API 可访问（需提供 API 基础地址与认证令牌）
• 宿主机或挂载卷中存在符合格式要求的 fixture 数据文件（JSON/YAML 格式）

Docker 快速启动

基础运行命令

bash
docker run -d \
  --name os2mo-fixture-loader \
  -e OS2MO_API_URL="https://os2mo.example.com/api/v1" \
  -e OS2MO_AUTH_TOKEN="your-auth-token" \
  -e FIXTURE_PATH="/fixtures" \
  -e LOAD_STRATEGY="full" \  # 可选：full（全量覆盖）/incremental（增量追加）
  -v /local/fixtures:/fixtures \  # 挂载本地 fixture 文件目录
  os2mo/fixture-loader:latest

docker-compose 配置示例

yaml
version: '3.8'
services:
  fixture-loader:
    image: os2mo/fixture-loader:latest
    container_name: os2mo-fixture-loader
    environment:
      OS2MO_API_URL: "https://os2mo.example.com/api/v1"
      OS2MO_AUTH_TOKEN: "your-auth-token"
      FIXTURE_PATH: "/fixtures"
      LOAD_STRATEGY: "incremental"
      LOG_LEVEL: "INFO"  # 可选：DEBUG/INFO/WARN/ERROR，默认 INFO
      CONFLICT_STRATEGY: "update"  # 可选：update（更新）/skip（跳过）/fail（失败退出）
    volumes:
      - ./local-fixtures:/fixtures  # 本地 fixture 文件目录挂载
    depends_on:
      - os2mo  # 确保 OS2mo 实例已启动

环境变量配置说明

Fixture 文件格式说明

Fixture 文件支持 JSON 或 YAML 格式，需按数据类型分类存放（如 organizations.yaml、users.json）。示例 YAML 文件：

yaml
# organizations.yaml
- uuid: "org-001"
  name: "技术部"
  type: "department"
  parent_uuid: null
  valid_from: "2023-01-01"
  valid_to: "9999-12-31"

- uuid: "org-002"
  name: "研发组"
  type: "team"
  parent_uuid: "org-001"
  valid_from: "2023-01-01"
  valid_to: "9999-12-31"

加载状态检查

容器启动后，可通过以下命令查看加载日志：

bash
docker logs os2mo-fixture-loader

成功加载时，日志末尾会输出：[INFO] Fixture loading completed. Total records processed: X, successful: Y, failed: Z

注意事项

• 增量加载模式下，需确保 fixture 数据包含唯一标识（如 uuid），避免重复创建
• 生产环境慎用全量加载策略，建议先在测试环境验证数据
• 大体积 fixture 文件（>100MB）建议分批次加载，避免 API 请求超时
• 如 OS2mo 启用了 HTTPS，需确保容器内可解析 API 域名并信任证书（可挂载证书到 /etc/ssl/certs/）