folioorg/mod-circulation-storage

FOLIO - mod-circulation-storage 镜像文档

1. 镜像概述和主要用途

1.1 概述

FOLIO - mod-circulation-storage 是 FOLIO (The Future of Libraries Is Open) 项目的核心模块之一，专注于图书馆流通业务（如借阅、归还、续借等）相关数据的存储与管理。该模块提供标准化的数据持久化服务，支持流通业务数据的高效读写与查询，是 FOLIO 流通模块的底层存储支撑。

1.2 主要用途

• 存储图书馆流通业务核心数据（如借阅记录、用户借阅权限、馆藏状态等）
• 提供流通数据的结构化访问接口，支撑上层流通业务逻辑模块（如 mod-circulation）的运行
• 维护流通数据的一致性与完整性，确保图书馆业务流程的稳定执行

代码仓库：https://github.com/folio-org/mod-circulation-storage

2. 核心功能和特性

2.1 核心功能

• 流通数据存储：提供借阅、归还、续借等流通业务数据的持久化存储能力
• 数据访问接口：通过标准化 API 向上层模块暴露流通数据的读写与查询能力
• 消息集成：支持与 Kafka 消息队列集成，实现流通事件的异步通知与处理

2.2 关键特性

• 数据库依赖：强制依赖外部数据库（需配置数据库连接参数），确保数据持久化
• Java 运行环境：基于 Java 构建，支持通过 JAVA_OPTIONS 优化 JVM 运行参数
• 可配置化：支持通过环境变量灵活配置 Kafka 连接、数据库参数、内存资源等

3. 使用场景和适用范围

3.1 使用场景

• FOLIO 图书馆服务平台的流通模块数据存储层部署
• 图书馆自动化系统中流通业务数据的集中管理
• 与上层流通业务逻辑模块（如 mod-circulation）协同，支撑借阅流程的全生命周期管理

3.2 适用范围

• 基于 FOLIO 平台构建的图书馆自动化系统
• 需要标准化流通数据存储方案的图书馆信息化项目
• 对流通数据一致性、可扩展性有较高要求的场景

4. 使用方法和配置说明

4.1 基础环境要求

• 外部数据库（如 PostgreSQL，需提前部署并配置访问权限）
• Kafka 集群（用于消息通知，可选但推荐部署）
• Docker 环境（19.03+）或 Docker Compose（2.0+）

4.2 Docker 运行命令

4.2.1 基本运行示例

bash
docker run -d \
  --name mod-circulation-storage \
  -p 8081:8081 \
  -e DB_HOST=postgres \
  -e DB_PORT=5432 \
  -e DB_NAME=folio_circulation \
  -e DB_USER=folio_user \
  -e DB_PASSWORD=folio_password \
  -e KAFKA_HOST=kafka \
  -e KAFKA_PORT=9092 \
  -e REPLICATION_FACTOR=1 \
  -e ENV=folio \
  -e JAVA_OPTIONS="-XX:MaxRAMPercentage=66.0" \
  folioorg/mod-circulation-storage:latest

4.2.2 参数说明

• -p 8081:8081：端口映射，将容器内 8081 端口（模块默认端口）映射到主机
• 环境变量（见 4.4 节详细说明）：需配置数据库连接、Kafka 连接、JVM 参数等

4.3 Docker Compose 配置示例

以下为包含数据库（PostgreSQL）、Kafka 及 mod-circulation-storage 的完整部署示例：

yaml
version: '3.8'

services:
  # PostgreSQL 数据库（流通数据存储）
  postgres:
    image: postgres:13-alpine
    environment:
      POSTGRES_DB: folio_circulation
      POSTGRES_USER: folio_user
      POSTGRES_PASSWORD: folio_password
    volumes:
      - postgres-data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U folio_user -d folio_circulation"]
      interval: 10s
      timeout: 5s
      retries: 5

  # Kafka 消息队列（可选，用于事件通知）
  kafka:
    image: confluentinc/cp-kafka:7.3.0
    depends_on:
      zookeeper:
        condition: service_healthy
    environment:
      KAFKA_BROKER_ID: 1
      KAFKA_ZOOKEEPER_CONNECT: zookeeper:2181
      KAFKA_LISTENER_SECURITY_PROTOCOL_MAP: PLAINTEXT:PLAINTEXT,PLAINTEXT_HOST:PLAINTEXT
      KAFKA_ADVERTISED_LISTENERS: PLAINTEXT://kafka:9092,PLAINTEXT_HOST://localhost:29092
      KAFKA_OFFSETS_TOPIC_REPLICATION_FACTOR: 1
    ports:
      - "9092:9092"

  zookeeper:
    image: confluentinc/cp-zookeeper:7.3.0
    environment:
      ZOOKEEPER_CLIENT_PORT: 2181
      ZOOKEEPER_TICK_TIME: 2000
    healthcheck:
      test: ["CMD", "echo", "ruok", "|", "nc", "localhost", "2181"]
      interval: 10s
      timeout: 5s
      retries: 5

  # mod-circulation-storage 服务
  mod-circulation-storage:
    image: folioorg/mod-circulation-storage:latest
    depends_on:
      postgres:
        condition: service_healthy
      kafka:
        condition: service_started
    ports:
      - "8081:8081"
    environment:
      # 数据库连接参数（必填）
      DB_HOST: postgres
      DB_PORT: 5432
      DB_NAME: folio_circulation
      DB_USER: folio_user
      DB_PASSWORD: folio_password
      # Kafka 连接参数（可选，若启用消息通知则必填）
      KAFKA_HOST: kafka
      KAFKA_PORT: 9092
      REPLICATION_FACTOR: 1
      # 环境标识（必填）
      ENV: folio
      # JVM 配置（可选，默认 -XX:MaxRAMPercentage=66.0）
      JAVA_OPTIONS: "-XX:MaxRAMPercentage=66.0 -Xms256m"
    deploy:
      resources:
        limits:
          memory: 512M  # 对应容器内存 536870912 字节（512MB）

volumes:
  postgres-data:

4.4 环境变量说明

4.5 资源配置建议

• 内存限制：建议配置不低于 512MB（对应容器内存 536870912 字节），避免因内存不足导致服务异常
• 数据库性能：流通数据读写频繁，建议数据库配置高性能磁盘（如 SSD）并优化连接池参数
• Kafka 集群：生产环境建议部署 Kafka 集群（≥3 节点），并将 REPLICATION_FACTOR 设为 2 或以上，提高消息可靠性

5. 验证部署

服务启动后，可通过访问模块健康检查接口验证部署状态：

bash
curl http://<host>:8081/admin/health

若返回 {"status":"OK"}，表示服务部署成功并正常运行。