Skip to content

About

db-archive 是一个面向数据库大表生命周期管理的表级归档服务。它解决的核心问题是:业务表中的订单、日志、交易、消息等历史数据持续增长,导致主库容量上涨、索引变大、查询和备份变慢,但这些数据又不能直接丢弃,需要在可控的时间窗口内迁移到归档库,或在确认安全后清理。

Resources

Stars

1 star

Watchers

0 watching

Forks

Repository files navigation

db-archive

目录

项目介绍

db-archive 是一个面向数据库大表生命周期管理的表级归档服务。它解决的核心问题是:业务表中的订单、日志、交易、消息等历史数据持续增长,导致主库容量上涨、索引变大、查询和备份变慢,但这些数据又不能直接丢弃,需要在可控的时间窗口内迁移到归档库,或在确认安全后清理。

项目把一次归档拆成“配置任务 -> 生成分片 -> 分批读取/写入 -> 核对 -> 删除(可选)”几个阶段。源库和目标库通过数据源配置解耦,任务可以按固定条件执行,也可以由周期任务结合日期宏每天生成新的单次任务。对于大表,系统按切分字段生成多个子任务,在并发、批量大小和行数/秒限速的约束下执行,从而降低对在线业务的瞬时冲击。

它适合以下场景:

  • 将生产库中已经过期的历史数据移动到独立的 MySQL、Oracle、PostgreSQL、Doris 或 OceanBase 数据源。
  • 只复制数据而保留源表(备份/冷热分层前的复制)。
  • 数据已经存在于归档库,只需要在源库安全删除(delete_safely)。
  • 按天、周或月持续处理按时间增长的订单表、流水表、审计日志表、事件表等。
  • 源表或目标表按数字后缀分表,需要批量展开并创建对应归档任务。

它不是通用 ETL 或实时同步系统:当前实现以整表/条件范围的数据搬迁为主,不提供字段映射、数据清洗、实时 CDC、复杂多表转换或对象存储导出能力;也不能替代数据库备份。归档前仍需确认表结构、索引、权限和数据一致性要求。

本文档以当前代码为准。程序入口为 cmd/db_archive.go,启动时会切换到可执行文件所在目录,从该目录读取 config.ini,并创建 logs/ 目录。

功能与数据库支持

  • 归档模式:move、copy_only、delete_only、delete_safely。
  • 写入模式:insert、upsert。
  • 支持按字段切分、时间窗口、任务内并发、批量大小和行数限速。
  • 支持周期任务日期宏、表名范围模板、模板预览、表存在性检查、配置预检、批量创建任务。
  • 支持暂停、终止、恢复和失败子任务重试;任务日志写入本地文件,结束后归档到元数据库。
  • 数据源密码通过 AES 加密保存。
db_type 源 目标 说明
mysql 是 是 MySQL 协议
oceanbase 是 是 OceanBase MySQL 租户
doris 是 是 目标端使用 Stream Load,必须配置 extra.feHttpURL
oracle 是 是 database_name 填服务名,source_db/sink_db 填 schema
pgsql 是 是 PostgreSQL;database_name 为连接数据库,schema 为空时使用 public

这些数据库都实现了项目需要的源端能力(读取、统计、分片、批量删除)和目标端能力(字段初始化、批量写入、统计);因此可以按任务选择相同或不同的源/目标类型,例如 MySQL -> Doris、Oracle -> PostgreSQL。实际可用性还取决于目标表结构、主键/唯一键、字符集和数据库用户权限。

  • MySQL 和 OceanBase 使用 MySQL 驱动及批量 SQL;upsert 使用 REPLACE INTO。
  • Doris 的目标端写入使用 Stream Load,数据源的 extra 必须提供 FE HTTP 地址(feHttpURL)。
  • Oracle 的 database_name 是服务名,任务中的库字段通常对应 schema;upsert 使用 MERGE,需要可用的键列。
  • PostgreSQL 的 database_name 是连接数据库,任务中的库字段对应 schema;空 schema 使用 public。

归档元数据库固定使用 MySQL。它只保存数据源、任务、子任务、日志、用户和审计信息,不参与业务数据搬迁。

当前功能

  • 数据源管理:新增、编辑、删除、启用/停用和连接测试。
  • 周期任务:按间隔天数和时间窗口自动生成单次归档任务,支持日期宏。
  • 单次任务:直接创建任务,或通过表名模板批量创建多个任务。
  • 大表处理:按 split_column/split_size 生成子任务,并控制任务内并发、源库并发和全局并发。
  • 数据安全控制:复制完成后核对行数再删除,支持 delete_safely 和 delete_only 两种清理模式。
  • 运行控制:暂停、终止、恢复、跳过失败子任务、重试失败子任务和重置失败分片。
  • 预检和观测:连接测试、字段结构预检、表名展开/存在性预览、任务行数统计、调度器统计和任务日志。

核心概念

归档任务有三层对象:

周期任务 archive_jobs(可选)
  └─ 单次任务 archive_tasks
       └─ 子任务 archive_sub_tasks
  • 周期任务保存可重复使用的归档配置。服务按 interval_day 生成单次任务;表名模板展开后,每一对源表/目标表对应一个单次任务。
  • 单次任务是调度器的执行单位,保存一次归档的源表、目标表、条件、模式、批量和限速参数。手动创建的单次任务可以没有周期任务关联。
  • 子任务是单次任务按切分字段生成的执行分片。未配置 split_column 时只生成一个子任务;配置后每个范围独立读取、写入和删除。

表名分片和数据范围分片是两层不同能力:表名模板解决“多张表”,split_column/split_size 解决“单张表中的多批数据”,两者可以叠加。

快速开始

环境要求

  • Go 1.25(源码编译,版本来自 go.mod)。
  • 可连接的 MySQL 元数据库。
  • 源库需要读取权限;复制需要目标库 INSERT;删除需要源库 DELETE;delete_safely 还需要目标库 SELECT。
  • 运行用户需要对可执行文件所在目录有写权限,用于创建 logs/、gorm.log 和 http.log。
  • 源库、目标库与归档服务之间需要网络连通;并发越高,连接数、网络带宽和本地日志写入压力越大。

初始化、编译、启动

mysql -h <meta-host> -P 3306 -u <meta-user> -p -e 'CREATE DATABASE IF NOT EXISTS db_archive CHARACTER SET utf8mb4 COLLATE utf8mb4_0900_ai_ci'
mysql -h <meta-host> -P 3306 -u <meta-user> -p db_archive < sql/init.sql
go build -o db_archive ./cmd
./db_archive

可执行文件所在目录必须包含 config.ini 和 web/。也可以使用:

./admin.sh start
./admin.sh status
./admin.sh stop

admin.sh 只管理名称为 db_archive 的进程,标准输出和错误输出写入 running.log。

默认页面为:

http://127.0.0.1:8080/home

页面入口:/home(数据源、周期任务、单次任务)、/history-task(历史任务)、/sub-task?task_id=<id>(子任务)。

部署目录与资源

程序启动时会切换到可执行文件所在目录,因此配置和 Web 静态资源应与二进制保持如下相对位置:

db-archive/
├── db_archive
├── config.ini
├── admin.sh
├── web/
│   ├── index.html
│   ├── history_task.html
│   ├── sub_task.html
│   └── static/
├── logs/          # 启动后自动创建,保存各任务日志
├── gorm.log       # 启动后创建,元数据库 SQL 日志
├── http.log       # 启动后创建,HTTP 日志
└── running.log    # 使用 admin.sh 启动时创建

前端资源已经随仓库提供,不需要 Node.js 或单独构建前端。服务不会自动迁移元数据库表结构;首次部署和版本升级时应人工核对并执行对应的 sql/init.sql 或迁移脚本。运行用户需要对程序目录具有创建日志和写入任务日志的权限。

自动发布 Release

推送 v 开头的 Git 标签时,GitHub Actions 会先运行测试,再为 Linux、macOS、Windows 的 amd64 和 arm64 生成完整安装包、SHA-256 校验文件及 GitHub Release。例如发布 v1.0.1:

git push origin main
git tag -a v1.0.1 -m "Release v1.0.1"
git push origin v1.0.1

安装包包含可执行文件、web/、sql/、README 和示例配置;Linux/macOS 包还包含 admin.sh,Windows 程序名为 db_archive.exe。安装包内的 config.ini 是无真实凭据的模板,首次启动前必须修改。标签推送后可在仓库的 Actions 页面查看构建进度。

配置

配置文件名固定为 config.ini。HTTP 配置位于根级,只有元数据库配置位于 [db]。

http_port = 8080
concurrency = 8
source_concurrency = 3
http_auth_enabled = false

[db]
host = 127.0.0.1
port = 3306
user = db_archive
password = <meta-password>
database = db_archive
配置项 作用 默认值
http_port HTTP 监听端口 8080
concurrency 调度器全局 worker 数 2
source_concurrency 每个 source 数据源的并发上限 1
http_auth_enabled API 身份识别和管理员校验;设为 false 时 API 直接放行 未配置时为 true
[db].host/port/user/password/database 元数据库连接 必填

修改配置后需要重启服务。任务的 concurrency 是单任务子任务并发,实际执行上限为 32。

数据源

数据源字段:name、role(source/sink/both)、db_type、host、port、user、password、database_name、extra、is_enabled、remark。

Doris 的 extra 至少为:

{"feHttpURL":"http://<fe-host>:8030"}

Oracle 的 database_name 是服务名;PostgreSQL 的 database_name 是连接数据库,任务中的 source_db/sink_db 是 schema。密码不会通过普通 JSON 响应返回。

任务配置

模式

模式 行为
copy_only 复制到目标,不删除源
move 复制到目标,核对后删除源;写入数必须等于删除数
delete_safely 不复制;删除前核对源、目标条件范围的行数
delete_only 只删除源,跳过目标库和行数核对,不需要目标数据源

insert 为严格插入;upsert 按数据库引擎执行冲突覆盖(MySQL/OceanBase 使用 REPLACE INTO)。delete_only 不初始化目标连接。

条件和切分

  • archive_condition 不要包含 WHERE,例如 create_time < '2024-01-01'。
  • split_column 为空时只生成一个子任务;否则应选择有索引、可排序的字段。
  • split_size 纯数字表示行数,或使用 1d、1m、1y 表示时间间隔,必须为正数。
  • time_window 使用 HH:MM-HH:MM,多个窗口用英文逗号分隔,支持跨午夜;00:00-00:00 表示全天。
  • priority 越小越优先;concurrency 为任务内并发。
  • insert_batch_size、delete_batch_size 为批量大小;insert_rate_limit、delete_rate_limit 为行/秒限速。

这些任务参数在任务启动时生效;修改运行中任务需先暂停,再恢复。

周期任务宏

周期任务的条件支持:

{{today}}
{{today-1}}
{{today+7}}
{{today-1|yyyymmdd}}
{{today|yyyy/mm/dd}}
{{today|yyyy-mm-dd}}

只支持 yyyymmdd、yyyy/mm/dd、yyyy-mm-dd。宏在生成任务时解析;单次任务应使用固定日期。推荐使用左闭右开条件:

create_time >= '{{today-31}}' AND create_time < '{{today-30}}'

周期任务按 interval_day 生成。服务每天 00:00 检查周期任务;也可调用 POST /api/archive-jobs/:id/generate-tasks 手动生成当天任务,同一 Job 当天已有任务时会报错。

表名模板

项目支持分表归档,适合按月份、租户、区域或哈希后缀拆分的表。例如业务表为 orders_00 到 orders_09,归档表为对应的 orders_archive_00 到 orders_archive_09,可以用一个任务配置展开为多张表:

source_table: orders_{00..09}
sink_table:   orders_archive_{00..09}

展开规则如下:

  • 源、目标展开数量相等时按顺序一一配对,以上例会生成 10 对表和 10 个单次任务。
  • 目标只有一张表时,允许多个源表写入同一个目标表,例如 orders_{00..09} -> orders_archive。
  • 源和目标数量既不相等、目标又不为单表时,创建会失败。
  • 当前模板只支持一个数字范围表达式,例如 {00..09};补零宽度由起始值决定。

表名展开发生在创建任务前,每一对表都会成为独立的归档任务,任务名称会追加 _0001、_0002 等序号。创建前可以调用 POST /api/archive-tasks/preview-tables 查看展开结果,并传入 check_exists: true 检查源表和目标表。批量创建使用 POST /api/archive-tasks/batch-create,周期任务在生成单次任务时也使用同样的展开规则。

分表归档和单表内部切分可以同时使用:先按表名模板生成多个任务,再由每个任务根据 split_column 和 split_size 继续生成子任务。例如每个月一张表、每张表再按自增 ID 每 100 万行切分。这样可以同时控制表之间的任务并发,以及单张表内部的分片并发。

使用分表归档时,应确认所有源表和目标表的字段结构兼容;多源表写入一个目标表时,还要确认主键/唯一键不会冲突,并根据目标库写入能力设置任务并发和限速。

状态

准备阶段 prepare_phase:

init -> preparing -> prepared
                  \-> failed

执行阶段 exec_phase:

init -> queueing -> running -> completed
                         \-> failed
                         \-> paused
                         \-> stopped
                         \-> resuming -> queueing

paused 表示执行超出时间窗口;stopped 表示取消或终止信号,可能留下部分结果。恢复默认跳过失败子任务;请求体传 retry_failed_sub_tasks=true 才重置失败子任务。子任务未开始为 init,成功为 completed,失败为 failed。

使用流程

1. 配置并测试数据源

在“数据源”页面分别创建 source 和 sink 数据源,确认数据库类型、地址、端口、数据库名/服务名和 schema 填写正确。Doris 目标端还要填写 extra.feHttpURL。保存后使用“测试连接”确认网络和账号权限。

2. 先预检表和任务配置

创建任务前,建议先使用表名模板预览和“归档配置预检”:

  • 表名模板任务先确认展开后的源表/目标表数量和配对关系。
  • 按需检查源表和目标表是否存在。
  • 检查源、目标字段数量和字段类型是否兼容。
  • 对 delete_only 以外的模式确认目标端可写;对删除模式确认源端删除权限。

3. 创建任务

  • 一次性归档:在“单次任务”中填写源/目标、归档条件、模式、时间窗口和切分参数。
  • 周期归档:在“周期任务”中保存可复用配置,由服务按间隔自动生成单次任务。
  • 分表归档:使用 source_table/sink_table 范围模板,预览无误后批量创建。

4. 观察和控制执行

任务先经过准备阶段生成子任务,再进入调度队列。通过任务列表、子任务详情、任务日志和 /api/scheduler-stats 查看进度。执行超出时间窗口会进入 paused;取消信号会等待当前子任务安全退出后进入 stopped,终止信号则会尽快取消正在执行的数据库操作。两种操作都可能留下部分结果,恢复前需要核对数据。

5. 完成后核对和留痕

检查任务的读取、写入、删除行数以及失败子任务。move 模式要求复制和删除数量一致;delete_safely 会在删除前核对两端条件范围的行数。完成、失败、暂停或终止后,任务日志会归档到元数据库。

Web 页面

  • 数据源:增删改、按角色/类型筛选、测试连接。
  • 周期任务:维护周期、条件宏、窗口、切分、限速,并查看关联任务。
  • 单次任务:创建单次或表模板批量任务,查看阶段、行数、子任务和日志,暂停/终止/恢复/删除。
  • 历史任务:查看包含已删除任务的历史记录。
  • 子任务:按任务、日期和状态筛选,重置失败分片。

页面会调用配置预检检查连接和字段结构;表名模板可先预览,并按需检查源表/目标表是否存在。

REST API

接口前缀为 /api。当 http_auth_enabled = true 时,除 /api/users/me 外的 API 需要 X-User-ID;创建、更新、删除、任务控制和测试连接等写操作还要求管理员用户。当 http_auth_enabled = false 时,不要求 X-User-ID,也不执行管理员校验。

状态和数据源

GET    /api/scheduler-stats
GET    /api/users/me
GET    /api/data-sources/
GET    /api/data-sources/:id
POST   /api/data-sources/
PUT    /api/data-sources/:id
DELETE /api/data-sources/:id
POST   /api/ping

/api/ping 的密码字段是 password,不是 username。

周期任务

GET    /api/archive-jobs/
GET    /api/archive-jobs/:id
POST   /api/archive-jobs/
PUT    /api/archive-jobs/:id
DELETE /api/archive-jobs/:id
POST   /api/archive-jobs/:id/generate-tasks

单次任务

GET    /api/archive-tasks/
GET    /api/archive-tasks/:id
GET    /api/archive-tasks/:id/log
POST   /api/archive-tasks/
PUT    /api/archive-tasks/:id
DELETE /api/archive-tasks/:id
POST   /api/archive-tasks/:id
POST   /api/archive-tasks/batch-create
POST   /api/archive-tasks/preview-tables
POST   /api/archive-tasks/sub-task-summary
POST   /api/cancel-archive-task/:id
POST   /api/terminate-archive-task/:id
POST   /api/test-archive-config

恢复请求体可选:

{"retry_failed_sub_tasks":true}

preview-tables 支持 source_table/sink_table 模板和 check_exists: true;batch-create 使用归档 Job 结构批量创建任务。

子任务和用户

GET    /api/archive-sub-tasks/
GET    /api/archive-sub-tasks/:id
POST   /api/archive-sub-tasks/:id/reset
GET    /api/users/
GET    /api/users/:id
PUT    /api/users/:id

子任务列表支持 task_id、start_date、end_date;任务列表支持 job_id、日期、名称、exec_phase、源库和源表等过滤条件。

常用请求示例

测试数据源连接:

curl -X POST 'http://127.0.0.1:8080/api/ping' \
  -H 'Content-Type: application/json' \
  -d '{"db_type":"mysql","host":"127.0.0.1","port":3306,"user":"archive_user","database_name":"orders","password":"<password>","extra":"{}"}'

预览分表模板:

curl -X POST 'http://127.0.0.1:8080/api/archive-tasks/preview-tables' \
  -H 'Content-Type: application/json' \
  -d '{"source_table":"orders_{00..09}","sink_table":"orders_archive_{00..09}","check_exists":false}'

恢复任务并重试失败子任务:

curl -X POST 'http://127.0.0.1:8080/api/archive-tasks/123' \
  -H 'Content-Type: application/json' \
  -d '{"retry_failed_sub_tasks":true}'

启用鉴权时,上述受保护请求还需要附带 -H 'X-User-ID: <user-id>';测试连接、创建/修改/删除任务和控制任务需要管理员身份。

鉴权配置

工作方式

项目采用“外部认证系统 + db-archive 用户授权”的方式,服务本身不负责登录、密码校验或 token 签发。开启鉴权后,请求链路应满足:

浏览器/客户端
    -> Nginx 或其他可信网关
    -> 外部 SSO/认证接口校验 cookie、token 等凭据
    -> 网关注入 X-User-ID(可选 X-User-Name)
    -> db-archive API

db-archive 收到 API 请求后只检查 X-User-ID 是否存在:

  1. 没有该请求头,返回 401 Unauthorized。
  2. 首次出现的用户会自动写入 users 表,X-User-Name 写入展示名,初始 is_admin=0。
  3. 已存在的用户会更新 last_seen_at。
  4. 标记了 RequireAdmin() 的写操作还会检查 users.is_admin;非管理员返回 403 Forbidden。

因此,不能把客户端直接传来的任意 X-User-ID 当作认证结果。生产环境必须让后端只接受来自可信网关的请求,或在网络层限制后端端口,防止调用方绕过外部认证直接伪造请求头。

开启前提

将配置改为:

http_auth_enabled = true

同时需要满足以下条件:

  • 元数据库已执行 sql/init.sql,其中包含 users 和 http_audit_logs 表。
  • 元数据库连接账号对这些表具有读写权限;服务需要自动创建用户、更新最后访问时间并写入审计日志。
  • 已部署可验证用户身份的 SSO、统一认证服务或网关。认证凭据可以是 cookie、x-token 等,但验证必须由外部系统完成。
  • 反向代理的认证接口验证成功时返回 2xx,并返回用户唯一标识响应头 X-User-Id;网关再把该值转发给后端为 X-User-ID。同时建议转发 X-User-Name。
  • 代理需要保护 /api/ 路径;静态页面和静态资源可以不经过外部认证,但页面调用受保护 API 时仍必须带上用户身份。
  • 后端监听端口不能被不可信网络直接访问,否则调用方可以伪造 X-User-ID 绕过网关。

仓库中的 nginx_config.md 展示了 auth_request 配置:/internal/auth 调用外部认证接口,认证通过后使用 auth_request_set 取出 X-User-Id,再通过 proxy_set_header X-User-Id 传给 db-archive。实际部署时应根据认证系统地址、域名和路径调整配置,并确认 Nginx 已启用 auth_request 模块。

首次管理员初始化

新用户自动创建时不是管理员。首次开启鉴权后,先让目标用户通过外部认证访问任意 API,使其出现在 users 表中,再由数据库管理员执行:

UPDATE users SET is_admin = 1 WHERE user_id = '<user-id>';

之后该用户才能创建、修改、删除数据源和任务、测试连接、控制任务以及维护其他用户。GET 查询和 POST /api/archive-tasks/preview-tables 等只读接口不要求管理员,但仍要求身份请求头。

接口和请求头

  • GET /api/users/me 在路由层不经过身份中间件,是鉴权状态查询接口。鉴权开启且没有 X-User-ID 时返回 authenticated=false,不会返回 401。
  • 其他 /api 接口在鉴权开启时都要求 X-User-ID。
  • X-User-ID 必须是外部认证系统提供的稳定、唯一用户标识;不要使用可变昵称或客户端可任意修改的字段。
  • X-User-Name 只用于首次创建用户的展示名,不用于权限判断。

关闭鉴权

测试或受控内网环境可以配置:

http_auth_enabled = false

此时 API 不要求 X-User-ID,也不执行管理员校验;/api/users/me 会返回 auth_enabled=false。这不等于匿名访问是安全的:任何能访问服务端口的请求都可以执行写操作、控制任务和读取数据。生产环境应开启鉴权,并通过防火墙或反向代理限制后端直连。

日志、审计和安全

运行目录中的主要文件:

running.log
gorm.log
http.log
logs/<task_id>.log

任务进入 completed、failed、paused 或 stopped 后,日志写入 archive_task_logs,通过 GET /api/archive-tasks/:id/log 读取;本地日志不会自动删除。

启用鉴权时,API 请求会异步写入 http_audit_logs。POST /api/ping 的请求体会固定脱敏为 [masked];其他写请求只记录最多 512 字节的请求摘要。审计写库失败不会阻塞 API 响应,因此仍应通过数据库和日志监控审计表是否正常增长。

查看任务日志

tail -f logs/123.log
tail -n 100 logs/123.log
grep -i "error\|failed" logs/123.log

任务结束后,日志内容还会保存到 archive_task_logs,适合在本地日志轮转或服务重启后从 API 查看。不要在任务运行中移动或删除 logs/ 下的文件。

调度监控

可以通过以下接口查看调度器当前状态:

curl 'http://127.0.0.1:8080/api/scheduler-stats'

返回信息包括就绪队列长度和容量、全局并发、源库并发、排队任务数、运行任务数以及按数据源统计的待执行任务数。任务长时间处于 queueing 时,优先检查全局并发、源数据源并发、同一源表的串行限制和执行时间窗口。

建议关注

  • failed 任务数量和失败子任务消息。
  • 长时间处于 preparing、queueing 或 running 的任务。
  • 源库连接数、慢查询、锁等待和线上业务负载。
  • 目标库写入延迟、Stream Load 失败和行数不一致。
  • logs/、gorm.log 和 http.log 的磁盘占用。

move、delete_safely、delete_only 都可能删除源数据;delete_only 风险最高。优先使用有索引的切分字段,从较小并发和限速开始压测;stopped 任务恢复前必须核对源、目标数据。不要把 config.ini、密码或密钥提交到版本库。

常见问题

任务长时间处于 queueing

调度器可能受到全局 concurrency、source_concurrency、同一源表串行限制或任务时间窗口限制。先查看 /api/scheduler-stats;如果当前不在 time_window 内,任务会等待或暂停到下一个窗口。

任务停留在 preparing 或进入 failed

先查看 logs/<task_id>.log 和任务 msg。常见原因包括源/目标表不存在、数据源密码或权限错误、Doris 缺少 feHttpURL、目标字段不兼容、切分字段不存在或 split_size 格式错误。

任务报主键冲突

insert 模式遇到目标端冲突会失败。确认目标表是否已经存在本批数据,或在确认业务允许覆盖的前提下改用 upsert。被强制终止后重跑前尤其要检查目标端残留数据。

报告“行数不一致”

检查源/目标条件是否完全对应、周期条件是否使用左闭右开区间,以及归档库是否已经包含上一批数据。move 会校验读取、写入和删除数量;delete_safely 会校验源端和目标端条件范围的数量。

delete_only 是否需要目标数据源

不需要。该模式只连接源库并直接删除,不检查目标表,也不做源/目标行数核对,因此风险高于 delete_safely。

周期任务没有生成单次任务

确认 Job 的 is_enabled=1、is_deleted=0、interval_day 和日期宏语法正确,并检查当天是否已经生成过任务。服务在每天 00:00 检查周期任务,也可以通过 POST /api/archive-jobs/:id/generate-tasks 手动触发。

终止后的任务能否直接恢复

可以调用恢复接口,但终止可能发生在复制或删除中间,不能假设数据完整。恢复前先核对源表和目标表;必要时清理残留数据、改用 upsert,或重新创建任务。

最佳实践

  1. 先在小范围条件和低并发下执行,确认字段结构、权限和行数,再扩大归档范围。
  2. move 优先使用有索引、非空且分布均匀的时间或自增 ID 作为 split_column。
  3. 周期任务使用左闭右开日期条件,避免相邻周期重复归档或遗漏。
  4. 生产库优先限制 source_concurrency 和任务内 concurrency,再逐步提高吞吐。
  5. 根据数据库和网络调节 insert_batch_size、delete_batch_size 及行数限速,避免大事务和锁影响。
  6. 分表归档先用 preview-tables 检查展开结果和表存在性;多个源表写入一个目标表时确认主键/唯一键不会冲突。
  7. delete_safely 比 delete_only 更适合作为已复制数据后的清理方式。
  8. 将 logs/、gorm.log、http.log 纳入日志轮转和磁盘监控,但不要删除正在执行任务的日志文件。
  9. 生产环境使用 http_auth_enabled=true,限制后端端口只允许可信反向代理访问。

当前限制

  • 归档是批处理,不提供实时 CDC、增量订阅或秒级同步。
  • 不提供字段映射、数据清洗、复杂多表 Join、数据库对象迁移或对象存储导出。
  • 不提供自动回滚;stopped 任务可能留下部分写入或删除结果,需要人工核对。
  • 表名模板只支持一个数字范围表达式,例如 {00..09};不支持多个范围组合。
  • 服务不会自动创建或迁移元数据库表结构,需人工执行 sql/init.sql 或对应迁移脚本。
  • 调度器只自动扫描最近 30 天创建且处于可执行状态的任务;长期未执行的旧任务不会自动重新入队。
  • delete_only 跳过目标端和行数核对,只适合明确确认过的数据清理场景。

开发和测试

go test ./...
go vet ./...

前端在 web/,HTTP 路由在 server/,归档执行逻辑在 archive/,数据库引擎在 engine/。

About

db-archive 是一个面向数据库大表生命周期管理的表级归档服务。它解决的核心问题是:业务表中的订单、日志、交易、消息等历史数据持续增长,导致主库容量上涨、索引变大、查询和备份变慢,但这些数据又不能直接丢弃,需要在可控的时间窗口内迁移到归档库,或在确认安全后清理。

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages