Fixity Checking Service Docker镜像文档

镜像概述和主要用途

Fixity Checking Service Docker镜像是一个专为数字保存服务设计的校验工具，旨在确保数据在长期保存过程中的完整性和一致性。该服务通过计算并校验文件的哈希值（校验和），检测数据是否因存储介质故障、传输错误或未授权篡改而损坏，是数字资源长期保存体系中的关键组件。

核心功能和特性

• 多算法支持：兼容主流校验算法，包括MD5、SHA-1、SHA-256、SHA-512，支持用户自定义默认算法。
• 批量校验能力：支持对指定目录下的单个文件或批量文件进行校验，自动递归处理子目录。
• 定时校验任务：通过Cron表达式配置周期性校验任务，实现数据完整性的自动化监控。
• 日志与报告：生成详细校验日志（包含校验结果、异常文件路径、时间戳），支持导出校验报告（JSON/CSV格式）。
• 服务集成：提供REST API接口，可与数字保存平台（如Archivematica、CKAN）或工作流系统集成，触发事件驱动型校验。
• 轻量部署：基于Alpine Linux构建，镜像体积小，资源占用低，支持容器化快速部署。

使用场景和适用范围

该镜像适用于所有需要确保数据长期完整性的场景，包括但不限于：

• 数字档案馆/图书馆：对电子档案、古籍数字化资源进行长期保存校验。
• 数据备份系统：验证备份文件在传输或存储过程中是否损坏。
• 科研数据管理：确保实验数据、论文附件等科研资源的不可篡改性。
• 长期数据保存平台：如政府开放数据平台、文化遗产数据库等需要合规性审计的场景。

详细使用方法和配置说明

基本运行方式

1. 直接使用docker run启动

docker run -d \
  --name fixity-service \
  -p 8080:8080 \
  -v /host/data:/data \          # 挂载待校验数据目录（必填）
  -v /host/logs:/var/log/fixity  # 挂载日志与报告目录（可选）
  -e CHECK_ALGORITHM=SHA256 \    # 指定默认校验算法
  -e SCHEDULE="0 0 * * *" \      # 每日凌晨执行全量校验（Cron表达式）
  fixity-checking-service:latest

2. 使用docker-compose配置

创建docker-compose.yml文件：

version: '3.8'
services:
  fixity-service:
    image: fixity-checking-service:latest
    container_name: fixity-service
    restart: unless-stopped
    ports:
      - "8080:8080"  # 服务API端口
    volumes:
      - /host/data:/data:ro          # 待校验数据目录（只读挂载，防止误改）
      - /host/config:/etc/fixity     # 自定义配置文件目录（可选）
      - /host/logs:/var/log/fixity   # 日志与报告持久化目录
    environment:
      - PORT=8080                    # 服务监听端口
      - LOG_LEVEL=INFO               # 日志级别（INFO/WARN/ERROR/DEBUG）
      - CHECK_ALGORITHM=SHA256       # 默认校验算法
      - SCAN_PATH=/data              # 待校验根目录
      - SCHEDULE="0 0 * * *"         # 定时校验任务（Cron表达式）
      - REPORT_FORMAT=JSON           # 报告输出格式（JSON/CSV）

启动服务：

docker-compose up -d

环境变量配置

数据卷挂载

配置文件说明

若需自定义高级配置（如API密钥、第三方服务集成），可在/etc/fixity目录下创建config.yaml文件，示例：

api:
  key: "your-api-key"  # 启用API认证时的访问密钥（留空则禁用认证）
  timeout: 30s         # API请求超时时间
check:
  ignore_patterns:     # 忽略校验的文件模式（支持通配符）
    - "*.tmp"
    - ".*.swp"
report:
  output_dir: "/var/log/fixity/reports"  # 报告输出目录（覆盖环境变量）

服务启停与状态查看

• 启动服务：docker start fixity-service
• 停止服务：docker stop fixity-service
• 查看日志：docker logs -f fixity-service
• 查看容器状态：docker inspect -f '{{.State.Status}}' fixity-service

API接口（可选）

服务启动后，可通过http://<容器IP>:8080访问REST API，核心接口示例：

• 触发手动校验：POST /api/check，请求体{"path": "/data/docs", "algorithm": "SHA256"}
• 获取校验报告：GET /api/reports?date=2024-01-01
• 查看任务状态：GET /api/tasks

具体接口文档可访问http://<容器IP>:8080/swagger查看（需启用Swagger，通过环境变量ENABLE_SWAGGER=true配置）。