middleware.py 4.3 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103
  1. """全局 HTTP 中间件与降级异常处理器(main.py 拆分:阶段 2)。
  2. 本模块只定义处理函数和显式的 ``register(app)`` 接线入口;导入模块本身不修改
  3. FastAPI 应用,避免隐藏的 import 副作用。维护白名单集中在这里,路径字符串属于
  4. 排空协议的一部分,修改时必须同步跑维护与备份事务专项测试。
  5. """
  6. from __future__ import annotations
  7. import logging
  8. from fastapi import FastAPI, Request
  9. from fastapi.responses import JSONResponse
  10. from fithealth_agent.health_store import HealthStoreDegradedError
  11. from fithealth_agent.info_store import MemoryStoreDegradedError
  12. from fithealth_agent.maintenance import MAINTENANCE
  13. logger = logging.getLogger("fithealth")
  14. #: 维护期间仍然放行的路径。诊断接口必须能访问,否则用户被 503 挡住之后
  15. #: 连“系统现在在干什么”都看不到;页面本身也要能打开。
  16. MAINTENANCE_ALLOWED_PATHS = frozenset({"/", "/health/storage-status"})
  17. #: 发起维护的请求自己不计入在飞计数,否则排空会等它自己,直接死等。
  18. MAINTENANCE_UNTRACKED_PATHS = frozenset({"/data/backup/import", "/data/reset"})
  19. async def maintenance_guard(request: Request, call_next):
  20. """DATA-12:恢复备份期间拒绝其他请求,并统计在飞请求供排空使用。
  21. 只有先让**新**请求拿到 503,在飞计数才有可能归零;两件事都在这里做,
  22. 才不会漏掉任何一条路由。
  23. """
  24. path = request.url.path
  25. if MAINTENANCE.active and path not in MAINTENANCE_ALLOWED_PATHS:
  26. return JSONResponse(
  27. {
  28. "error": f"系统正在执行维护操作({MAINTENANCE.status['reason']}),请稍后重试。",
  29. "maintenance": MAINTENANCE.status,
  30. },
  31. status_code=503,
  32. )
  33. if path in MAINTENANCE_UNTRACKED_PATHS:
  34. return await call_next(request)
  35. with MAINTENANCE.track_request():
  36. return await call_next(request)
  37. async def health_store_degraded_handler(
  38. request: Request, exc: HealthStoreDegradedError
  39. ) -> JSONResponse:
  40. """健康数据库只读降级时统一回 503。
  41. DATA-09:原实现在数据目录不可用时切到系统临时目录后仍然允许写入,
  42. 用户看到“导入成功”,而 Windows 清理 %TEMP% 时那些数据直接蒸发。
  43. """
  44. logger.error("健康数据库写入被拒绝:%s", exc)
  45. return JSONResponse(
  46. {
  47. "error": str(exc),
  48. "health_store_degraded": True,
  49. "database_path": str(exc.database_path) if exc.database_path else None,
  50. "recovery_hint": (
  51. "健康数据库当前不可写,已停止一切写入以避免把新数据写进注定消失的临时目录。"
  52. "请检查 data 目录的写入权限或修复 health.db,"
  53. "然后调用 /health/storage-status 重新校验(无需重启)。"
  54. ),
  55. },
  56. status_code=503,
  57. )
  58. async def memory_store_degraded_handler(
  59. request: Request, exc: MemoryStoreDegradedError
  60. ) -> JSONResponse:
  61. """记忆库只读降级时统一回 503,而不是把写入失败伪装成 500。
  62. DATA-08:读失败绝不能变成“读到空库”,写入必须显式失败,否则一次意外
  63. 就会把整个记忆库覆盖掉。这里同时把隔离副本路径告诉用户,便于人工恢复。
  64. """
  65. logger.error("记忆库写入被拒绝:%s", exc)
  66. return JSONResponse(
  67. {
  68. "error": str(exc),
  69. "memory_store_degraded": True,
  70. "quarantine_path": str(exc.quarantine_path) if exc.quarantine_path else None,
  71. "recovery_hint": (
  72. "记忆库文件当前无法解析,已停止一切写入以保护原有记忆。"
  73. "请修复 data/info_store.json(可参考同目录下的 .corrupt-* 隔离副本),"
  74. "然后重启服务或调用 /health/storage-status 重新校验。"
  75. ),
  76. },
  77. status_code=503,
  78. )
  79. def register(app: FastAPI) -> None:
  80. """把全局中间件和异常处理器显式注册到应用。"""
  81. app.middleware("http")(maintenance_guard)
  82. app.add_exception_handler(HealthStoreDegradedError, health_store_degraded_handler)
  83. app.add_exception_handler(MemoryStoreDegradedError, memory_store_degraded_handler)