历史迁移

历史迁移从一个源后端分页读取已有日志，再写入一个或多个目标。它需要显式调用，不会因为配置开启而自动运行。

本例将 MongoDB 中的系统日志归档为 CSV。应用已通过 Business BOM 管理版本，源 MongoDB 连接可用。

1. 添加迁移模块

<dependencies>
    <dependency>
        <groupId>com.own.business</groupId>
        <artifactId>springboot-business-system-log-migration-core</artifactId>
    </dependency>
    <dependency>
        <groupId>com.own.business</groupId>
        <artifactId>springboot-business-system-log-migration-mongodb</artifactId>
    </dependency>
    <dependency>
        <groupId>com.own.business</groupId>
        <artifactId>springboot-business-system-log-migration-file-csv</artifactId>
    </dependency>
</dependencies>

migration-core 负责执行编排，另外两个模块分别提供读取源和写入目标。后端迁移模块会传递引入对应 persistence，无需重复添加存储依赖。

2. 配置源和目标

own:
  system-log:
    enabled: false
    migration:
      enable: true
      origin: MONGODB
      target:
        - FILE_CSV
      page-size: 1000
      interval: 0
    mongodb:
      persistence:
        enabled: false
    file-csv:
      save-path: ./logs/archive/csv
      persistence: false

本例关闭本机采集与实时保存器，保留迁移所需的读取和显式写入服务。迁移开关是 migration.enable，不是 migration.enabled。

3. 显式执行

在业务或调度入口注入 SystemLogBackupHookCore：

import com.own.business.system.log.migration.core.hook.SystemLogBackupHookCore;
import java.time.LocalDateTime;
import org.springframework.stereotype.Service;

@Service
public class SystemLogArchiveService {
    private final SystemLogBackupHookCore backup;

    public SystemLogArchiveService(SystemLogBackupHookCore backup) {
        this.backup = backup;
    }

    public void archive(LocalDateTime start, LocalDateTime end) {
        backup.run(start, end);
    }
}

由调用方确定起止时间后调用 archive。时间按 Asia/Shanghai 理解，边界与游标遵循源后端实现。run(start, end) 使用配置分页大小，也可调用 run(start, end, pageSize) 指定单次分页大小。

执行完成后检查目标文件的时间范围、记录数量和 extra.systemLog 内容。模块不提供自动定时任务或持久化断点。

可选源与目标

枚举	迁移模块后缀	可作源	可作目标
MONGODB	mongodb	是	是
ELASTIC	elastic	是	是
CLICKHOUSE	clickhouse	是	是
RDBMS	rdbms	是	是
FILE_JSON	file-json	否	是，须有完整快照
FILE_CSV	file-csv	否	是
FILE_RDBMS	file-rdbms	否	是

模块前缀为 springboot-business-system-log-migration-。增加目标时，应同时添加目标依赖、配置存储并将枚举加入 target 列表。

目标不能包含源。一个枚举表示一种适配器，不表示任意命名的多个同类数据库连接。MQ 不支持迁移读取或写入。file-json 通过独立迁移适配器接收完整日志快照，仅支持作为目标。

迁移到 JSON Lines 文件

在上述 MongoDB 迁移示例中，将 CSV 目标依赖替换为 JSON 迁移适配器，保留 migration-core 和 migration-mongodb：

<dependency>
    <groupId>com.own.business</groupId>
    <artifactId>springboot-business-system-log-migration-file-json</artifactId>
</dependency>

该依赖自动引入 JSON 文件存储，无需再单独声明 persistence。源数据库须有完整 extra.systemLog 对象快照，且连接已经配置。使用：

own:
  system-log:
    enabled: false
    migration:
      enable: true
      origin: MONGODB
      target: [FILE_JSON]
      page-size: 1000
      interval: 0
    mongodb:
      persistence:
        enabled: false
    file-json:
      save-path: ./logs/archive/json
      write-batch-size: 32
      persistence: false

按前文显式执行调用 SystemLogBackupHookCore.run(startTime, endTime)。JSON 迁移使用文件服务，不受实时保存器开关影响。需要同时迁移到 CSV、SQL 或另一个数据库时，添加对应迁移模块和存储配置，再将其枚举加入 target。

检查输出的 system-log_yyyy-MM-dd.jsonl：每行直接保存原始 SystemLog。适配器从标准记录的 extra.systemLog 恢复事件，保留原始 ID、服务名、身份、时间与快照状态。源查询范围仍由数据库投影时间决定；输出日期依据完整快照的操作开始时间，而非投影时间。

extra 可为对象或 JSON 文本，其 systemLog 必须是对象。缺少完整快照、JSON 损坏、原始 ID 为空或缺少身份、操作开始时间、响应完成时间时，本次迁移明确失败。不会用数据库主键和投影字段补造事件，也不会静默跳过；旧数据须先完成结构转换。

文件服务消费当前小批时才转换对应记录，避免创建整页的转换列表。错误会中断迁移，已经追加的记录不回滚；重跑可能重复写入。JSON 只支持作为迁移目标，不能读取文件作为源。

配置与失败处理

配置	默认值	说明
migration.enable	false	初始化源和目标路由
migration.origin	空	单个源
migration.target	[]	按顺序写入的目标列表
migration.page-size	1000	每次从源读取的条数
migration.interval	0	两次源查询的间隔，单位毫秒

以上配置均位于 own.system-log 下。文件 write-batch-size 控制文件追加批次，与源分页大小独立。

任一目标写入失败会中断本次执行，后续目标、分页和结束 Hook 不再保证执行。已经成功的写入不回滚，也不会自动重试。重跑前应核对已完成范围及后端主键规则，文件目标会重复追加。

旧版本升级

从旧模块切换时，需要同步调整 Maven 依赖和配置：

原用法	当前用法
persistence-<backend>-business	persistence-<backend>
persistence-<backend>-migration	migration-<backend>
后端专属 Controller	公共 controller-admin / controller-app
own.log-operation-backup	own.system-log.migration

上表依赖后缀均属于 springboot-business-system-log-。迁移 Java 包从 com.own.business.system.log.persistence.<backend>.migration 改为 com.own.business.system.log.migration.<backend>。

修改依赖不会自动转换已有库表。旧登录日志需要单独转换发起人、操作和响应结构，不能只改表名。登录限制和最后登录时间仍由各自业务服务维护，与系统日志开关独立。