folioorg/mod-marc-migrations

FOLIO - mod-marc-migrations

镜像概述和主要用途

mod-marc-migrations是一个为高性能MARC记录迁移设计的模块，主要用于图书馆系统中MARC格式记录的批量迁移处理。该模块支持分块处理、并行处理和S3兼容存储集成，适用于大规模MARC记录的高效迁移场景。

代码仓库：https://github.com/folio-org/mod-marc-migrations

核心功能和特性

• 高性能MARC记录迁移处理能力，支持大规模数据迁移
• 分块处理机制，可配置记录块大小和并行处理线程数
• 集成S3兼容存储服务，用于迁移过程中的文件存储
• 灵活的数据库连接池配置，优化数据库连接性能
• 失败重试机制，提高迁移过程的可靠性和稳定性

使用场景和适用范围

适用于图书馆管理系统（如FOLIO）中需要迁移大量MARC记录的场景，包括但不限于：

• 系统升级或数据迁移时的MARC记录批量处理
• 从外部系统导入MARC格式的bibliographic或authority记录
• 需要高性能处理的大规模MARC记录转换任务
• 跨系统MARC数据迁移与同步

详细使用方法和配置说明

Metadata

• 容器内存（字节）：536870912
• 模块端口：8081/tcp

默认环境变量

JAVA_OPTIONS

• -XX:MaxRAMPercentage=85.0

FOLIO数据库连接

• FOLIO database connection: true
• FOLIO database common environment（通用环境变量）：
  • DB_DATABASE
  • DB_HOST
  • DB_PORT
  • DB_USERNAME
  • DB_PASSWORD
  • DB_CHARSET
• FOLIO database other environment（其他环境变量）：
  • DB_CONNECTION_TIMEOUT
    • 描述：控制客户端从连接池获取连接的最大等待时间（毫秒）
    • 默认值：30000
  • DB_IDLE_TIMEOUT
    • 描述：控制连接在池中允许空闲的最长时间。仅当DB_MINIMUM_IDLE小于DB_MAXPOOLSIZE时生效
    • 默认值：600000
  • DB_INITIALIZATION_FAIL_TIMEOUT
    • 描述：控制连接池在无法成功初始化初始连接时是否"快速失败"
    • 默认值：30000
  • DB_KEEPALIVE_TIME
    • 描述：控制HikariCP尝试保持连接活跃的频率（毫秒），防止被数据库或网络基础设施超时（0表示禁用）
    • 默认值：0
  • DB_LEAK_DETECTION_THRESHOLD
    • 描述：控制连接离开池后多长时间记录可能的连接泄漏日志（0表示禁用）
    • 默认值：30000
  • DB_MAXPOOLSIZE
    • 描述：控制池允许达到的最大大小，包括空闲和使用中的连接
    • 默认值：10
  • DB_MAX_LIFETIME
    • 描述：控制池中连接的最大生存期（毫秒）
    • 默认值：1800000
  • DB_MINIMUM_IDLE
    • 描述：控制HikariCP尝试在池中维持的最小空闲连接数
    • 默认值：10
  • DB_VALIDATION_TIMEOUT
    • 描述：控制连接存活测试的最大时间（毫秒），该值必须小于DB_CONNECTION_TIMEOUT
    • 默认值：5000

分块处理配置

• CHUNK_FETCH_IDS_COUNT
  • 描述：分块准备阶段每次查询获取的记录ID数量。为保证正确的块大小，RECORDS_CHUNK_SIZE应为此值的除数
  • 默认值：500
• CHUNK_PERSIST_COUNT
  • 描述：构建多少个块后持久化到数据库
  • 默认值：1_000
• CHUNK_PROCESSING_MAX_PARALLELISM
  • 描述：分块处理的最大线程池大小
  • 默认值：4
• CHUNK_RETRYING_MAX_IDS_COUNT
  • 描述：重试的最大块ID数量
  • 默认值：1000
• RECORDS_CHUNK_SIZE
  • 描述：一个操作处理块中的记录数量
  • 默认值：500

部署环境配置

• ENV
  • 描述：部署的逻辑名称，在使用相同共享Kafka/Elasticsearch集群的所有环境中必须唯一，仅允许a-z（大小写不限）、0-9、-、_符号
  • 默认值：folio
• OKAPI_URL
  • 描述：Okapi服务URL
  • 默认值：okapi
• SYSTEM_USER_USERNAME
  • 描述：系统用户名
  • 默认值：mod-marc-migrations

S3存储配置

• S3_ACCESS_KEY_ID
  • 描述：S3兼容服务的访问密钥
• S3_BUCKET
  • 描述：S3兼容服务的存储桶名称
• S3_IS_AWS
  • 描述：指定是否使用AWS S3作为文件存储
  • 默认值：false
• S3_LOCAL_SUB_PATH
  • 描述：迁移期间本地存储Authority和Marc bib文件的S3子路径
  • 默认值：mod-marc-migrations
• S3_REGION
  • 描述：S3兼容服务的区域
  • 默认值：us-west-2
• S3_RETRY_COUNT
  • 描述：S3客户端返回错误时的重试次数
  • 默认值：3
• S3_RETRY_DELAY_MS
  • 描述：S3客户端返回错误时的重试间隔（毫秒）
  • 默认值：500
• S3_SECRET_ACCESS_KEY
  • 描述：S3兼容服务的密钥
• S3_SUB_PATH
  • 描述：文件存储的S3子路径
  • 默认值：mod-marc-migrations
• S3_URL
  • 描述：S3兼容服务的URL
  • 默认值：https://s3.amazonaws.com

Docker部署示例

docker run命令示例

bash
docker run -d \
  --name mod-marc-migrations \
  -p 8081:8081 \
  -e DB_HOST=postgres \
  -e DB_PORT=5432 \
  -e DB_DATABASE=folio_db \
  -e DB_USERNAME=folio_user \
  -e DB_PASSWORD=secure_password \
  -e S3_URL=https://s3.example.com \
  -e S3_ACCESS_KEY_ID=your_access_key \
  -e S3_SECRET_ACCESS_KEY=your_secret_key \
  -e S3_BUCKET=marc-migration-bucket \
  -e RECORDS_CHUNK_SIZE=1000 \
  -e CHUNK_PROCESSING_MAX_PARALLELISM=8 \
  folioorg/mod-marc-migrations

docker-compose配置示例

yaml
version: '3'
services:
  mod-marc-migrations:
    image: folioorg/mod-marc-migrations
    container_name: mod-marc-migrations
    ports:
      - "8081:8081"
    environment:
      - DB_HOST=postgres
      - DB_PORT=5432
      - DB_DATABASE=folio_db
      - DB_USERNAME=folio_user
      - DB_PASSWORD=secure_password
      - DB_MAXPOOLSIZE=20
      - S3_URL=[***]
      - S3_ACCESS_KEY_ID=your_access_key
      - S3_SECRET_ACCESS_KEY=your_secret_key
      - S3_BUCKET=marc-migration-bucket
      - S3_REGION=us-east-1
      - RECORDS_CHUNK_SIZE=1000
      - CHUNK_PROCESSING_MAX_PARALLELISM=8
      - ENV=production
      - OKAPI_URL=[***]
    depends_on:
      - postgres