chore: sync production runtime and docs
This commit is contained in:
@@ -0,0 +1,203 @@
|
||||
# 数据库自维护审计
|
||||
|
||||
审计日期：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、健康检查和文档。
|
||||
Reference in New Issue
Block a user