insar-management-system-v2/docs/DATABASE_SELF_MAINTENANCE_AUDIT_20260425.md

数据库自维护审计

审计日期：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 时才允许：

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、健康检查和文档。