Files
lpt-meta/.agents/notes/proposed/process/2026-11-20-prod-keep-learning-history.md
T
cat-shark c716f5c8db docs: 补记范围相关导图与 prod 升级方案
- 待办:复习总览改为「上次编辑的导图」,任务页相关导图不再区分草稿/已结束
- 新增笔记:总览按所选标签列出保存过的导图
- 新增提案:prod 只保留学习记录后原地升级
2026-11-22 21:41:26 +08:00

14 KiB
Raw Blame History

Agent Note: prod 只保留学习记录后原地升级到新结构

Status: proposed

Problem

prod 库 lpt_prod 停在 Flyway 20260706.1(15 个迁移),dev 头是 20261118.2,中间 24 个迁移(20 个 SQL + 4 个 Java) 一次都没跑过。这批迁移里 V20261116_1 删掉旧的回忆存储、V20261118_1 清空回忆相关数据,属于破坏性变更;V20261009_7 还会把学习报告从单列 content 改名成 free_summary,并把知识碎片的 session_num 改名成 context_num、按会话回填内容归属。

同时按「分支绑定部署」规则,prod 只能从 master 出包,而 dev 头分别领先 master:lpt-be 67 个提交、lpt-fe 84 个、lpt-ai 20 个。也就是说,升级前必须先做一次显式的 master → dev → master 合并,并且三个仓库同批出包。

prod 里还有一批维护者不再需要的数据:学习预期 23 条、标准导图 3 张、3 个已软删的学习任务(名字是 1 / 123)等。维护者要求只保留学习任务(在用 6 个)、学习会话(时长)、学习报告、知识碎片,其余直接移除。这批数据只在这台机器的 MySQL 里(hostPath /vol1/lpt/mysql/prod/data),没有第二份。

两个目标要一次完成:结构升到 dev 头,数据裁剪到保留清单。

现状核对

2026-11-20 从 lpt-prod 的 MySQL 直接读出,未经任何修改:

表 行数 处理
user 1(admin,BCrypt) 保留(登录用)
tasks 9(6 在用 + 3 已软删) 保留 6 个在用;3 个软删任务删除
study_sessions 30(2025-10-20 ~ 2026-10-29,全部 ENDED) 全部保留
study_reports 30(与会话 1:1,纯文本 3~684 字) 全部保留,正文落自由总结
study_report_fragments 38(全部挂在存在的会话上) 全部保留
study_expectations 23 移除
review_standard_mind_maps 3 移除
review_mind_maps / review_recall_records / task_applications / user_priority_weights / test_table 0 移除(本就为空)

数据基线(升级后必须保持一致,负数那行见「待确认」):

项 值
会话数 30
SUM(actual_time) 111 695 秒
SUM(effective_time) 97 495 秒(负数那行按 0 算则为 98 994 秒)
花果事考(TASK-20261008-380034) 22 次会话 / 实际 94 004 秒 / 有效 83 323 秒 / 碎片 31 条
麻省理工开放课程 线性代数(TASK-20251019-383352) 4 次 / 12 470 / 12 470 / 0 条
斯坦福21秋季:实用机器学习中文版(TASK-20251019-331417) 3 次 / 2 815 / -704 / 2 条
stm32 铁头山羊课程(TASK-20261022-751979) 1 次 / 2 406 / 2 406 / 5 条

其他事实:

  • 无重复 task_num / session_num、无孤儿碎片或会话、无空正文,V20261009_3 的唯一约束与 V20261009_5 的类型转换不会因脏数据失败;唯一异常是会话 5 的有效时间 -1499 秒、效率比 -0.74。
  • 备份 CronJob 每天 03:00 全库 dump 到 /vol1/lpt/backup/prod,保留 14 天,单份 3.9 MB;磁盘剩 7.1 TB。最新一份是 2026-11-20 03:00。
  • 旧镜像 tag(回滚要用,recorded 2026-11-20):
    • 192.168.123.199:5000/lpt-be:fbc2650625f0262d8f3006f4217a1a12603281ed-1794121607
    • 192.168.123.199:5000/lpt-fe:2505edeae7155eb8ab86476c0663939245764fde-1794122526
    • 192.168.123.199:5000/lpt-ai:09670673dea326ed1161241931523bd054661513-1794122158
  • master → dev 三个仓库都能干净合并(git merge-tree 无冲突)。

Proposal

flowchart TD
  A[冻结写入<br/>lpt-fe / lpt-be / lpt-ai 副本数改 0] --> B[整库 dump + 保留表 dump<br/>NAS 与本机各一份]
  B --> C[还原到 lpt_prod_verify<br/>核对 5 张表行数与合计时长]
  C -->|不一致| R[停止,先修备份]
  C -->|一致| D[合并 master→dev→master<br/>be / fe / ai 同批]
  D --> E[dev 出包<br/>24 个迁移跑在 dev 库]
  E --> F[prod 副本演练<br/>lpt_prod_rehearsal]
  F -->|失败| G[只新增迁移修复<br/>重建演练库重跑]
  G --> F
  F -->|通过| H[部署新 lpt-be 到 prod<br/>Flyway 跑 24 个迁移]
  H -->|失败| X[回滚:还原 dump + 回退镜像]
  H --> I[按保留清单清库<br/>提交前后行数]
  I --> J[部署 lpt-fe / lpt-ai<br/>恢复副本数]
  J --> K[验收:SQL + 页面 + 导出接口]
  K -->|不通过| X
  K --> L[结束维护窗口]

相位 0:冻结与取证(维护窗口开始)

  1. 记录旧镜像 tag(上面已列),确认 registry 里仍能拉取。
  2. 停写:kubectl -n lpt-prod scale deploy lpt-fe lpt-be lpt-ai --replicas=0,MySQL 不动。
  3. 在 MySQL Pod 里取三份 dump(都带 --single-transaction --routines --events --triggers --default-character-set=utf8mb4):
    • pre-migration-all.sql:--all-databases,整库还原用;
    • pre-migration-lpt_prod.sql:只导 lpt_prod,演练用;
    • keep-only.sql:只导 user tasks study_sessions study_reports study_report_fragments,数据取证件。
  4. 三份都写 /vol1/lpt/backup/prod/manual/<ts>/ 并 sha256sum,再把整库那份拷到本机 ~/lpt-prod-backups/<ts>/。
  5. 还原 pre-migration-lpt_prod.sql 到临时库 lpt_prod_verify,核对 5 张表行数与上表一致;一致才继续,否则停。核对完删掉临时库。
  6. 记录基线数字(上表)到一本执行记录里,后续每一步都跟它比。

相位 1:出包与演练(维护窗口之前完成)

  1. master → dev 合并三个仓库,跑测试;再 dev → master 合并。三仓同批推。
  2. 从 dev 触发 lpt-be 的出包(environment=dev)。这一步会让 24 个迁移先跑在 dev 库(MySQL 9、94 条会话)上,验证 Flyway 能启动;失败就只影响 dev。
  3. 演练:在 prod 的 MySQL 8.0 上建 lpt_prod_rehearsal,导入 pre-migration-lpt_prod.sql;用第 2 步打出来的镜像起一个一次性 Pod(不改 Deployment),把 SPRING_DATASOURCE_URL 指到演练库,等日志出现 Successfully applied 24 migrations 与 Started 后核对:
    • flyway_schema_history 头为 20261118.2,24 条 success=1,无失败行;
    • 保留表行数、SUM(actual_time)、SUM(effective_time) 与基线一致;
    • 30 条报告 free_summary 全非空、session_summary / expectation_verdict 全为 NULL;
    • 38 条碎片 context_type='SESSION'、context_num 等于旧 session_num、owner_task_num 全部解析到 4 个任务(31 / 2 / 5);
    • 计时列已是 DOUBLE,负数那条仍是 -1499;
    • 其余表为空(或仅 user_tags / markers 有迁移回填的标签,见「待确认」)。
  4. 在同一份演练库上再跑一遍清理 SQL,确认前后行数符合预期;确认后删掉演练库。
  5. 演练不通过:只允许新增迁移修复,不改已发布的 15 个旧迁移,重建演练库重跑。不通过不进 prod。

相位 2:升级 prod

  1. 确认 FE/BE/AI 仍是 0 副本、重复确认整库 dump 的 sha256。
  2. 从 master 触发 lpt-be 的 environment=prod 出包。Flyway 在启动时跑 24 个迁移;观察启动日志与 readiness,失败立即停,走回滚。
  3. 按验收标准第 1~5 条核对,任何一条不符就停,不进清理。

相位 3:按保留清单清理

用一个一次性 SQL 在 lpt_prod 上执行(不写成 Flyway 迁移,理由见备选)。脚本放在 lpt-be/ops/prod-keep-learning-history.sql,只含 DELETE,前后各打一次行数:

START TRANSACTION;

DELETE FROM study_expectations;
DELETE FROM review_mind_maps;
DELETE FROM review_standard_mind_maps;
DELETE FROM review_tag_mind_maps;
DELETE FROM review_recalls;
DELETE FROM review_recall_receipts;
DELETE FROM review_recall_requests;
DELETE FROM review_recall_owner_locks;
DELETE FROM review_guidance_conversations;
DELETE FROM task_applications;
DELETE FROM user_priority_weights;
DELETE FROM user_review_preferences;
DELETE FROM ai_tasks;
DELETE FROM ai_usage_records;
DELETE FROM test_table;
DELETE FROM markers;
DELETE FROM user_tags;
DELETE FROM tasks WHERE deleted = 1;

COMMIT;
  • 会话、报告、碎片、user、6 个在用任务不动。
  • 只删行、不删表:表结构还要给新版本用。
  • markers / user_tags 里是 V20261115_5 按任务名回填的标签(38 条标记 + 至多 4 个标签名),属于「其余数据」,默认删;要保留按标签回顾历史的能力就跳过这两条 DELETE。

相位 4:全栈上线

  1. 从 master 触发 lpt-fe、lpt-ai 的 environment=prod 出包(三者同批)。
  2. 三个 Deployment 副本数恢复 1,确认 readiness。
  3. 走验收标准第 6~8 条,通过后结束维护窗口。

回滚

触发条件:迁移报错、行数或合计不符、关键页面 500。

  1. 三个 Deployment 副本数改 0。
  2. DROP DATABASE lpt_prod; CREATE DATABASE lpt_prod CHARACTER SET utf8mb4 COLLATE utf8mb4_0900_ai_ci;,导入 pre-migration-all.sql。
  3. kubectl set image 把三个 Deployment 指回上面记录的旧 tag,副本数恢复 1。
  4. 用 admin 登录、核对 5 张表行数与基线,再排查问题。

Flyway 迁移不可逆,镜像回滚不等于数据回滚:只要库被改过,就必须整库还原。dump 在 NAS 与本机各留一份,保留 30 天。

Alternatives considered

为什么不在空库重建后导入

当 baseline-on-migrate: true 时,空库会先 baseline 到版本 1,再把 39 个迁移全部跑一遍,所以「建空库」并不省迁移;反而要自己写导入脚本,并手工复刻 V20261009_7 的报告改名、碎片上下文改名和归属回填、V20261115_5 的标签回填。做的事情更多,出错面更大,收益只是表里少 0 行。

为什么不在 prod 直接升级、跳过演练

迁移一旦在 prod 上开始就没有回退键,失败只能整库还原并回退镜像,维护窗口不可控。演练用 prod 的 MySQL 8.0 和同一条 dump,成本约半小时,能提前暴露 SQL 与 Java 迁移在 8.0 上的差异(dev 是 MySQL 9)。

为什么清理不写成 Flyway 迁移

迁移会在 dev 也执行,把 dev 的测试数据删掉;而且数据裁剪不是结构变更,不该由版本化迁移驱动。写成一次性 SQL、执行前后打行数,既能审计也不污染 dev。

为什么三个仓库必须同批

V20261116_1 之后旧回忆端点与请求体都不存在,be/fe/ai 单独上线会出现 400/404;分支绑定规则也要求 master 配 master 同批发布。

为什么保留在用任务

学习时长、报告、碎片都按任务查询与展示:没有任务行,会话的 task_num、碎片的 owner_task_num 就成了指向不存在对象的字符串,三类数据在界面上没有入口。任务本身的名称也是这些记录的唯一可读归属。

Acceptance criteria

  1. flyway_schema_history 最大版本 20261118.2,新增 24 条 success=1,无失败行。
  2. 行数:user 1、tasks(deleted=0)6、study_sessions 30、study_reports 30、study_report_fragments 38。
  3. 合计:SUM(actual_time)=111695、SUM(effective_time)=97495(若修正负数则为 98994),按任务的四个数字与基线表一致。
  4. 30 条报告 free_summary 非空、session_summary 与 expectation_verdict 全为 NULL。
  5. 38 条碎片:context_type='SESSION'、context_num 等于旧 session_num、owner_task_num 非空且指向在用的 4 个任务。
  6. 其余业务表 0 行:study_expectations、review_*、task_applications、user_priority_weights、user_review_preferences、ai_tasks、ai_usage_records、test_table、markers、user_tags。
  7. admin 登录后:学习页 6 个任务、各任务累计有效学习时间与基线一致;复习详情能看到 30 条历史报告(正文在「自由总结」);知识碎片 38 条、归属正确;学习预期、导图、回忆、标签为空态。
  8. GET /export/range?format=json 返回 30 条报告、38 条碎片与对应会话,作为「数据已取到且可读」的最终证明。

Risks

  • 迁移不可回滚:MySQL 的 DDL 部分不是事务性的,失败可能停在半途。唯一兜底是整库 dump 还原;所以 dump 必须先在 lpt_prod_verify 上证明可还原。
  • V20261009_3 唯一约束:历史数据有重复编号会直接让升级失败。已核对无重复;演练会再确认一次。
  • V20261009_5 计时列改类型:30 行值都合法(含负数),失败风险低;负数不会被迁移修正。
  • 报告只剩一段:30 条历史报告只有「自由总结」,另两段永远为空。这是维护者确认过的取舍。
  • 负数会话:不修正时累计有效时间少 1 499 秒(约 25 分钟),页面按 0 显示单条但累计值会被拉低。
  • 清理脚本依赖迁移后的表名:只能在升级完成、核对通过后执行;在旧库或未升级的 dev 上会报表不存在。
  • 流水线的自动回滚只回镜像:迁移已经落库,自动回滚后旧镜像无法在新结构上正常工作,必须按「回滚」段手工还原。
  • 演练库与 prod 同实例:演练会占少量连接与磁盘(数据 50 KB 级),但绝不能指向 lpt_prod;一次性 Pod 的 SPRING_DATASOURCE_URL 要落成明文写清库名。

待确认

  1. 会话 5 的 effective_time=-1499、效率比 -0.74:默认置 0 / 0(旧缺陷产物,不是真实学习时间);要保留原值也能做,只是累计值会少 25 分钟。
  2. markers / user_tags 里迁移回填的任务名标签:默认随「其余数据」一起删;若想保留按标签回顾历史的能力,跳过这两条 DELETE。
  3. 维护窗口时长:预计 40 分钟(冻结与备份验证 15 分钟、迁移 2 分钟、核对 5 分钟、清理 1 分钟、前端与验收 15 分钟),演练放在窗口之前。