- 待办:复习总览改为「上次编辑的导图」,任务页相关导图不再区分草稿/已结束 - 新增笔记:总览按所选标签列出保存过的导图 - 新增提案:prod 只保留学习记录后原地升级
204 lines
14 KiB
Markdown
204 lines
14 KiB
Markdown
# 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
|
||
|
||
```mermaid
|
||
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,前后各打一次行数:
|
||
|
||
```sql
|
||
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 分钟),演练放在窗口之前。
|