- 待办:复习总览改为「上次编辑的导图」,任务页相关导图不再区分草稿/已结束 - 新增笔记:总览按所选标签列出保存过的导图 - 新增提案:prod 只保留学习记录后原地升级
14 KiB
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-1794121607192.168.123.199:5000/lpt-fe:2505edeae7155eb8ab86476c0663939245764fde-1794122526192.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:冻结与取证(维护窗口开始)
- 记录旧镜像 tag(上面已列),确认 registry 里仍能拉取。
- 停写:
kubectl -n lpt-prod scale deploy lpt-fe lpt-be lpt-ai --replicas=0,MySQL 不动。 - 在 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,数据取证件。
- 三份都写
/vol1/lpt/backup/prod/manual/<ts>/并sha256sum,再把整库那份拷到本机~/lpt-prod-backups/<ts>/。 - 还原
pre-migration-lpt_prod.sql到临时库lpt_prod_verify,核对 5 张表行数与上表一致;一致才继续,否则停。核对完删掉临时库。 - 记录基线数字(上表)到一本执行记录里,后续每一步都跟它比。
相位 1:出包与演练(维护窗口之前完成)
master → dev合并三个仓库,跑测试;再dev → master合并。三仓同批推。- 从
dev触发 lpt-be 的出包(environment=dev)。这一步会让 24 个迁移先跑在 dev 库(MySQL 9、94 条会话)上,验证 Flyway 能启动;失败就只影响 dev。 - 演练:在 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有迁移回填的标签,见「待确认」)。
- 在同一份演练库上再跑一遍清理 SQL,确认前后行数符合预期;确认后删掉演练库。
- 演练不通过:只允许新增迁移修复,不改已发布的 15 个旧迁移,重建演练库重跑。不通过不进 prod。
相位 2:升级 prod
- 确认 FE/BE/AI 仍是 0 副本、重复确认整库 dump 的 sha256。
- 从
master触发 lpt-be 的environment=prod出包。Flyway 在启动时跑 24 个迁移;观察启动日志与 readiness,失败立即停,走回滚。 - 按验收标准第 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:全栈上线
- 从
master触发 lpt-fe、lpt-ai 的environment=prod出包(三者同批)。 - 三个 Deployment 副本数恢复 1,确认 readiness。
- 走验收标准第 6~8 条,通过后结束维护窗口。
回滚
触发条件:迁移报错、行数或合计不符、关键页面 500。
- 三个 Deployment 副本数改 0。
DROP DATABASE lpt_prod; CREATE DATABASE lpt_prod CHARACTER SET utf8mb4 COLLATE utf8mb4_0900_ai_ci;,导入pre-migration-all.sql。kubectl set image把三个 Deployment 指回上面记录的旧 tag,副本数恢复 1。- 用
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
flyway_schema_history最大版本20261118.2,新增 24 条success=1,无失败行。- 行数:
user1、tasks(deleted=0)6、study_sessions30、study_reports30、study_report_fragments38。 - 合计:
SUM(actual_time)=111695、SUM(effective_time)=97495(若修正负数则为 98994),按任务的四个数字与基线表一致。 - 30 条报告
free_summary非空、session_summary与expectation_verdict全为 NULL。 - 38 条碎片:
context_type='SESSION'、context_num等于旧session_num、owner_task_num非空且指向在用的 4 个任务。 - 其余业务表 0 行:
study_expectations、review_*、task_applications、user_priority_weights、user_review_preferences、ai_tasks、ai_usage_records、test_table、markers、user_tags。 admin登录后:学习页 6 个任务、各任务累计有效学习时间与基线一致;复习详情能看到 30 条历史报告(正文在「自由总结」);知识碎片 38 条、归属正确;学习预期、导图、回忆、标签为空态。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要落成明文写清库名。
待确认
- 会话 5 的
effective_time=-1499、效率比-0.74:默认置0/0(旧缺陷产物,不是真实学习时间);要保留原值也能做,只是累计值会少 25 分钟。 markers/user_tags里迁移回填的任务名标签:默认随「其余数据」一起删;若想保留按标签回顾历史的能力,跳过这两条 DELETE。- 维护窗口时长:预计 40 分钟(冻结与备份验证 15 分钟、迁移 2 分钟、核对 5 分钟、清理 1 分钟、前端与验收 15 分钟),演练放在窗口之前。