204 lines
5.7 KiB
Markdown
204 lines
5.7 KiB
Markdown
# 数据库自维护审计
|
||
|
||
审计日期：2026-04-25
|
||
|
||
## 1. 审计目标
|
||
|
||
本次审计关注两件事：
|
||
|
||
1. 当前数据库自维护机制，是否仍然符合现在的系统设计。
|
||
2. 当前现场数据库，是否已经与现有 ORM / catalog / 运行时设计对齐。
|
||
|
||
## 2. 当前自维护机制实际做什么
|
||
|
||
代码入口位于 `backend/app/db_maintenance.py`，系统启动时由 `backend/app/main.py` 调用。
|
||
|
||
当前自维护能力包括：
|
||
|
||
- 自动创建 `postgis` 扩展
|
||
- 自动创建缺失表
|
||
- 自动补齐缺失列
|
||
- 自动执行 `backend/migrations/001` 到 `006`
|
||
- 自动引导管理员账号
|
||
- 自动灌入灾害点数据
|
||
|
||
当前启动链路中的相关步骤：
|
||
|
||
1. `ensure_database_ready(...)`
|
||
2. `database.init_db()`
|
||
3. 根目录登记同步
|
||
4. manifest inventory 同步
|
||
5. D-InSAR / 时序 catalog 自举
|
||
6. pairing state 自举
|
||
7. 健康检查
|
||
|
||
## 3. 当前机制不做什么
|
||
|
||
当前实现不是完整迁移框架，它不会自动处理：
|
||
|
||
- 字段改名
|
||
- 字段类型变更
|
||
- 可空性从宽到严
|
||
- 索引 / 约束漂移修补
|
||
- 旧字段 / 旧表删除
|
||
|
||
破坏性重建只有在以下两个开关同时为 `true` 时才允许：
|
||
|
||
```env
|
||
DB_SCHEMA_RESET_ON_MISMATCH=true
|
||
DB_SCHEMA_RESET_CONFIRM=true
|
||
```
|
||
|
||
默认情况下这是关闭的，符合当前内网生产环境“保守自维护”的要求。
|
||
|
||
## 4. 本次现场检查方法
|
||
|
||
本次检查直接用当前项目代码读取现场数据库并执行：
|
||
|
||
- `inspect_database_structure(...)`
|
||
- `ensure_database_ready(settings.DATABASE_URL, bootstrap_admin=False, seed_hazard=False)`
|
||
- `get_health_status(include_external=False, include_details=True, refresh=True)`
|
||
|
||
使用的是项目当前 `.env` 中配置的 Python 解释器和数据库连接。
|
||
|
||
## 5. 现场检查结果
|
||
|
||
### 5.1 schema 结构检查
|
||
|
||
结果：
|
||
|
||
- `mismatch = false`
|
||
- `reason_count = 0`
|
||
- `required_table_count = 42`
|
||
- `missing_tables = []`
|
||
- `extra_tables = []`
|
||
- `missing_columns = {}`
|
||
- `type_mismatches = []`
|
||
- `nullable_mismatches = []`
|
||
|
||
结论：
|
||
|
||
- 现场数据库结构与当前 ORM 一致。
|
||
- 当前新增的结果包、运行时、catalog 相关字段已经在数据库中落稳。
|
||
|
||
### 5.2 自维护执行结果
|
||
|
||
结果：
|
||
|
||
- `schema_reset = false`
|
||
- `mismatch_detected = false`
|
||
- `added_columns = []`
|
||
- `bootstrap_initialized = false`
|
||
|
||
启动时仍会执行以下 SQL 文件：
|
||
|
||
- `001_st_intersection_agg.sql`
|
||
- `002_spatial_functions.sql`
|
||
- `003_pairing_enhancement.sql`
|
||
- `004_pairing_refactor.sql`
|
||
- `005_pairing_task_trace.sql`
|
||
- `006_result_pairing_trace.sql`
|
||
|
||
结论：
|
||
|
||
- 当前数据库已处于“无需修补”的稳定状态。
|
||
- 启动自维护仍会重复执行迁移 SQL，因此这些 SQL 文件必须继续保持幂等。
|
||
|
||
### 5.3 健康检查结果
|
||
|
||
结果摘要：
|
||
|
||
- `health.ok = true`
|
||
- `database.ok = true`
|
||
- `database.schema_ok = true`
|
||
- `database.postgis_ok = true`
|
||
- `dinsar_result_catalog.ok = true`
|
||
- `timeseries_result_catalog.ok = true`
|
||
- `dinsar_bridge.ok = true`
|
||
- `source_roots.ok = true`
|
||
- `product_packages.ok = true`
|
||
- `wsl_runtime.ok = true`
|
||
- `pairing_system.ok = true`
|
||
|
||
关键现场值：
|
||
|
||
- D-InSAR catalog：
|
||
- `storage_root = D:\production_results\dinsar`
|
||
- `manifest_count = 19`
|
||
- `db_count = 19`
|
||
|
||
- 时序 InSAR catalog：
|
||
- `storage_root = D:\production_results\timeseries`
|
||
- `manifest_count = 0`
|
||
- `db_count = 0`
|
||
|
||
- 产品包：
|
||
- `total_count = 19`
|
||
- `canonical_schema = insar.product-package/v1`
|
||
- 所有缺失项计数均为 0
|
||
|
||
- WSL 共享运行时：
|
||
- `shared_distro = Ubuntu-24.04`
|
||
- `shared_conda_env_name = insar_wsl_v1`
|
||
- `shared_python_path = /home/administrator/miniconda3/envs/insar_wsl_v1/bin/python`
|
||
- `required_runtime_count = 2`
|
||
- `healthy_runtime_count = 2`
|
||
|
||
## 6. 结论
|
||
|
||
结论很明确：
|
||
|
||
- 当前数据库自维护机制与当前系统状态相符。
|
||
- 对于当前这轮改造引入的新增字段、catalog、结果包、WSL runtime 信息，它是足够的。
|
||
- 当前现场数据库已经对齐当前 ORM 和结果目录设计。
|
||
|
||
这意味着：
|
||
|
||
- 现在可以继续在当前 schema 基础上推进 D-InSAR / 时序 InSAR 生产。
|
||
- 不需要为了“数据库跟不上代码”而先清空库或强制重建。
|
||
|
||
## 7. 残余风险
|
||
|
||
虽然当前是对齐的，但仍有三个明确边界：
|
||
|
||
### 7.1 它不是 migration framework
|
||
|
||
后续如果要做以下改动，不能只靠当前自维护：
|
||
|
||
- 重命名字段
|
||
- 修改字段类型
|
||
- 增加更严格的非空约束
|
||
- 重建索引或唯一约束
|
||
- 删除旧结构
|
||
|
||
### 7.2 SQL 文件必须幂等
|
||
|
||
因为启动时会重复执行 `001` 到 `006`，任何新增 SQL 文件也必须遵守同样原则。
|
||
|
||
### 7.3 健康面板已成为设计约束的一部分
|
||
|
||
当前运维自检不只是“看数据库能不能连”，而是在验证：
|
||
|
||
- catalog 是否正常
|
||
- product package 是否完整
|
||
- WSL 运行时是否齐全
|
||
- pairing trace 是否一致
|
||
|
||
因此后续只要改目录模型、结果包模型、运行时模型，就必须同步维护健康检查逻辑。
|
||
|
||
## 8. 建议
|
||
|
||
当前建议如下：
|
||
|
||
1. 保持 `DB_SCHEMA_RESET_ON_MISMATCH=false` 和 `DB_SCHEMA_RESET_CONFIRM=false`。
|
||
2. 后续涉及 schema 破坏性调整时，单独编写受控迁移，不要指望启动自维护自动兜底。
|
||
3. 新增数据库字段时，优先采用“可空 + 向后兼容 + 健康面板补校验”的方式推进。
|
||
4. 每次结果目录、运行时 registry、catalog 设计变动后，都重新跑一次：
|
||
- schema 检查
|
||
- `ensure_database_ready(...)`
|
||
- `GET /api/health`
|
||
|
||
## 9. 审计结语
|
||
|
||
截至 2026-04-25，数据库自维护机制与当前系统状态是匹配的，且现场数据库处于健康状态。当前更大的风险已经不在“数据库结构漂移”，而在后续若继续做结果模型或运行时模型重构时，是否同步维护 catalog、健康检查和文档。
|