主题
七、数据结构与生命周期
本章速览:读完后你会知道 —— ① 迁移为什么只能前进、163 个迁移怎么管理;② 100 张表按域怎么分组;③ 字段/主键/软删/时间/逻辑引用的约定;④ 哪些表会自动清理、哪些永久保留;⑤ 删除一条数据时会级联发生什么。
逐表列定义(列/类型/注释/索引)太大,放在 附录 M:数据字典;这里讲能指导设计与排障的规则: 迁移怎么走、表怎么分组、字段怎么约定、数据活多久、删除时会发生什么。
7.1 迁移与版本:只前进,不回改
- 结构变化只能新增
db/migration/V{n}__<说明>.sql;已有的迁移禁止修改(生产flyway_schema_history记录的是校验和,改旧文件会让应用启动失败)。 - 当前 163 个迁移(V1 → V163,无缺号);发布前
deploy/scripts/test-migrations.sh会在临时库 全量重放一遍,确认"从零建库"没问题。 - 迁移里同时负责配置键种子(
INSERTsys_config):配置键必须由迁移登记,运行期才允许写 (SysConfigServiceImpl.saveBatch会拒绝未登记的键,见 6.2)。 - 删除表/列要先确认没有读点:用"搜代码 + 查文档 + 看生产行数"三条都过一遍再写迁移; 历史出现的"删表后旧 Job 还在写"就是靠这道检查兜住的。
7.2 表分组(100 张,按域)
| 域 | 张数 | 前缀 | 内容 |
|---|---|---|---|
| AI 与记忆 | 27 | ai_* | 对话/轮次/知识库/向量块/记忆事件/关系状态/关怀/仪式/叙事/出网账本/用量/迁移游标 |
| 扩展平台 | 现存 24 张 | extension_*(23)+ webhook_delivery | 包/版本/安装/触发器/运行/能力/策略/效果/审批/密钥/预算/自愈 |
| 博客内容 | 14 | blog_* | 文章/历史/标签关系/页面/说说/相册/照片/评论/留言/友链/分类/标签/系列/片段 |
| 系统 | 13 | sys_* | 配置/用户/文件/文件夹/审计/登录/任务/邮件/搜索/订阅/访问/部件/API Key |
| 会话与采集 | 7 | agent_* | 会话/轮次/原始行/采集账本/工具调用/轮次附件/采集令牌 |
| 日程 | 5 | daily_* | 待办/重复系列/课次/节假日/提醒 |
| 笔记 | 5 | note_* | 笔记/笔记本/标签/标签关系/历史 |
| 通知与主动 | 4 | notify_*(2)+ proactive_log + proactive_compose | 通道/投递留痕/主动账本/预润色缓存 |
| 其它 | 1 | chat_attachment | 聊天附件元数据(消息本体在 ai_message) |
表名清单由文档检查器与生产库逐表核对(100 张全覆盖);每张表的列定义在附录 M。
7.3 字段与建表约定
| 约定 | 做法 | 为什么 |
|---|---|---|
| 主键 | 雪花 BIGINT(id),对外 JSON 转字符串 | 单机无自增冲突;JS 不丢精度 |
| 软删 | deleted TINYINT(0/1)+ 查询默认过滤 | 内容可恢复;日志类不软删(直接按保留期物理删) |
| 时间 | create_time/update_time DATETIME 由 DB 默认值维护;业务时间 Asia/Shanghai | 统一口径;扩展平台调度时间例外(存 UTC) |
| 无物理外键 | 引用列只建索引,关系由应用层维护 | 避免迁移顺序/锁表;删父前必须显式处理子行 |
| 自然键/幂等 | 各表用唯一索引做幂等:dedup_key、natural_key、(session_id,line_no)、run_identity | "重试/重复投递/重启"不产生第二条副作用 |
| JSON 列 | 配置/清单/快照用 JSON(MySQL 8 JSON 类型) | 灵活;但不把需要查询的字段塞进 JSON |
| 生成列 | 如 daily_course_session.natural_key 为 STORED 生成列 | 唯一索引约束需要稳定表达式 |
| 大文本 | LONGTEXT 只用于正文/摘要/历史;列表查询禁止 SELECT * 大字段 | 控制内存与带宽 |
| 注释 | 每张表/关键列有中文 COMMENT(附录 M 按注释展示) | 读库即文档 |
7.4 数据生命周期与保留策略
只增不减的表必须有人清,否则迟早撑爆磁盘。当前清理任务:
| 任务 | 清理对象 | 保留期(默认) | 配置 |
|---|---|---|---|
RawRetentionJob | agent_session_raw | 14 天 | site.conversation.raw-retention-days |
RawRetentionJob | agent_turn(只删"记忆抽取水位已覆盖"的行) | 0 = 永久(默认关) | site.conversation.agent-turn-retention-days |
LedgerRetentionJob | agent_tool_call_log、ai_egress_log | 180 天 | cosmos.ops.ledger-retention.{enabled,days} |
ExtensionRetentionJob | extension_run、extension_run_event、extension_policy_decision、extension_capability_call、extension_effect、extension_message_delivery | 180 天 | cosmos.extension.retention.{enabled,days} |
ProactiveComposeCacheService.purgeScheduled | 过期/失败预润色缓存 | 过期即删 | 每小时 :20 |
| 备份保留 | 本地 db/uploads/hindsight 备份 | 7 天 / 7 份(可配) | 备份脚本 |
永久保留的表(设计如此):sys_config、sys_audit_log(合规)、ai_token_usage(用量凭证)、 ai_memory_archive(归档快照)、proactive_log(主动账本)、extension_* 的安装/版本/授权。 sys_job_log、notify_log、mail_log 等由运维台"数据清理"手动或按需清理(保留天数参数)。
清理的安全设计:
- 分批删除(每批 N 行、单轮有上限),避免长事务锁表;
- 删除 0 行也写 job log("这一轮确实跑过");
- 孤儿文件清理先做引用反查(全部
MediaReferenceProvider),反查失败按"未知"保守保留; - 备份清理保留最新 N 份与"最后可恢复点",不会一次删光。
7.5 时区、大整数与序列化
- 业务时间:JVM 时区固定
Asia/Shanghai(TimezoneGuard+TZ环境变量);接口输出本地时间字符串。 - 扩展平台时间:
next_run_at/last_run_at统一 UTC(LocalDateTime.now(ZoneOffset.UTC)); 判断 due 必须用UTC_TIMESTAMP(),用本地NOW()会误报(审查 #83 踩过)。 - 大整数:Jackson 把
Long序列化为字符串;MCP 回执里 id 一律字符串,前端不Number(); 这是为了绕开 JS2^53精度问题(历史事故:id 被截断导致"数据不存在")。 - 枚举:库里存字符串(
status='active'),不用魔法数字;状态常量集中在实体类/常量类。
7.6 删除与级联:每处都要想清楚
| 删除对象 | 行为 |
|---|---|
| 文章/说说/相册/页面 | 软删(可恢复);门户立即不可见(SQL 过滤) |
| 笔记 | 软删进回收站;恢复时保留标签关系(审查 #55) |
| 待办 | 删除任务级联删步骤;删除未投递提醒 |
| 课程 | 删除当天课次;已生成的提醒一并取消(未投递的) |
| 记忆 | soft/hard 两档;hard 连向量一起删;幂等 |
| 文件/附件 | 先查引用(MediaReferenceProvider),无引用才删记录+磁盘 |
| 扩展 | 卸载只停用不删除历史(run/effect/审计保留) |
全库 0 个物理外键:所有
*_id/*_key都是逻辑引用。排查"这条数据属于谁"时看列注释 (附录 M)与本文档的模块章节;删除父行前必须在代码里处理子行,否则会留下孤儿数据。