refactor: align repo layout and logging safeguards
This commit is contained in:
qzl
@@ -0,0 +1,147 @@
|
||||
# Plan: FastAPI + Celery 日志管理器系统
|
||||
|
||||
**Date:** 2026-01-29
|
||||
**Author:** AI Assistant
|
||||
**Status:** Draft
|
||||
|
||||
## Overview
|
||||
|
||||
构建一个统一、可扩展的日志管理器系统，覆盖 FastAPI 与 Celery worker 的运行时日志，提供结构化 JSON 输出、错误分离、日志轮转与上下文追踪。目标是满足生产环境可观测性需求，便于检索、关联与故障排查，并与当前项目配置体系保持一致。
|
||||
|
||||
## Requirements
|
||||
|
||||
### Functional
|
||||
- [ ] 统一管理 FastAPI 与 Celery worker 日志
|
||||
- [ ] 日志持久化到 `logs/`，错误日志单独输出到 `logs/errors/`
|
||||
- [ ] 支持按大小或按时间进行日志轮转
|
||||
- [ ] 结构化日志（JSON），包含时间戳、级别、模块/函数、消息与上下文
|
||||
- [ ] ERROR/CRITICAL 记录完整堆栈与错误上下文
|
||||
- [ ] 支持环境差异化配置（dev/test/prod）
|
||||
|
||||
### Non-Functional
|
||||
- [ ] 性能：日志写入对请求延迟影响可控，支持异步队列化扩展
|
||||
- [ ] 安全：避免记录敏感信息，支持字段脱敏
|
||||
- [ ] 可维护性：模块化、可测试、与现有配置体系一致
|
||||
|
||||
## Technical Approach
|
||||
|
||||
### 调研摘要
|
||||
- Python 官方建议使用 `logging` + `dictConfig` 管理多 handler、多 formatter 与过滤器，适用于生产环境配置化管理。
|
||||
- FastAPI 通常通过中间件注入 request_id 和上下文，并使用结构化日志输出以便集中检索。
|
||||
- Celery 官方文档建议在自定义场景下关闭 `worker_hijack_root_logger`，通过信号配置自定义 handler。
|
||||
- 结构化日志库中，structlog 更贴近标准 logging，可与 `logging` 生态协同；loguru 简化配置但替换性强、与 Celery 深度集成时可控性较弱。
|
||||
- 生产环境推荐 JSON 结构化日志 + 轮转 + 错误分离，并通过外部系统聚合与告警（如 Sentry）。
|
||||
|
||||
### 方案对比（至少两种）
|
||||
| 方案 | 描述 | 优点 | 缺点 | 结论 |
|
||||
|------|------|------|------|------|
|
||||
| 方案 A：stdlib logging + 自定义 JSON Formatter | 纯标准库实现 JSON formatter + handler/filters | 依赖最少，符合标准库，易与 Celery/FastAPI 集成 | 结构化上下文绑定与 request_id 传递需手写 | 可作为备选最小方案 |
|
||||
| 方案 B：stdlib logging + structlog | 用 structlog 生成结构化事件，输出到 logging handler | 结构化上下文与 contextvars 支持好，兼容 logging handler | 引入第三方依赖与配置复杂度 | 推荐主方案 |
|
||||
| 方案 C：loguru | 直接使用 loguru logger | 配置简单、体验好 | 与 Celery/标准 logging 生态整合成本高 | 不推荐作为主方案 |
|
||||
|
||||
### 选型结论
|
||||
- 采用方案 B：`logging` 作为底座，structlog 负责结构化事件与上下文绑定；保留可切换到方案 A 的最小实现路径。
|
||||
- 通过 `dictConfig` 做环境配置，使用 Rotating/TimedRotating handler 支持按大小或时间轮转。
|
||||
|
||||
## Implementation Steps
|
||||
|
||||
### Phase 1: 基础日志骨架与配置 (3 hours)
|
||||
1. 新增日志配置模型（Settings 扩展），支持环境、轮转方式与路径配置。
|
||||
2. 创建日志模块骨架：formatter、handler、filter、context。
|
||||
3. 集成 `dictConfig` 初始化入口，支持 dev/test/prod 配置切换。
|
||||
|
||||
### Phase 2: FastAPI 集成与上下文 (4 hours)
|
||||
1. 实现请求中间件：生成 `request_id`，绑定用户与请求上下文（IP、路径、方法）。
|
||||
2. 定义异常处理器：捕获未处理异常并记录堆栈与上下文。
|
||||
3. 添加应用启动时日志初始化流程。
|
||||
|
||||
### Phase 3: Celery 集成 (3 hours)
|
||||
1. 在 Celery 应用配置中设置 `worker_hijack_root_logger = False`。
|
||||
2. 使用 Celery 信号（`setup_logging`、`after_setup_task_logger`）初始化日志并注入 task 上下文。
|
||||
3. 统一日志格式、error 处理与 request_id 关联（如 task_id）。
|
||||
|
||||
### Phase 4: 错误分离与轮转策略 (3 hours)
|
||||
1. 添加 error handler：仅接受 ERROR/CRITICAL，输出到 `logs/errors/`。
|
||||
2. 实现轮转策略配置（按大小、按时间），并提供统一切换配置项。
|
||||
3. 增加字段脱敏与敏感字段黑名单过滤器。
|
||||
|
||||
### Phase 5: 可选增强功能 (4 hours)
|
||||
1. 日志查询与过滤接口（基础 API + 分页）。
|
||||
2. 日志聚合统计（按级别/模块/时间窗口）。
|
||||
3. Sentry 集成与异常告警。
|
||||
|
||||
## Files to Modify
|
||||
|
||||
| File | Changes |
|
||||
|------|---------|
|
||||
| api/src/core/config/settings.py | 扩展日志相关配置模型 |
|
||||
|
||||
## Files to Create
|
||||
|
||||
| File | Purpose |
|
||||
|------|---------|
|
||||
| api/src/core/logging/__init__.py | 模块导出与初始化入口 |
|
||||
| api/src/core/logging/config.py | dictConfig 构建与环境配置 |
|
||||
| api/src/core/logging/formatters.py | JSON formatter 与字段规范 |
|
||||
| api/src/core/logging/handlers.py | 文件、控制台、错误 handler |
|
||||
| api/src/core/logging/filters.py | 等级过滤、敏感字段脱敏 |
|
||||
| api/src/core/logging/context.py | contextvars 绑定与获取 |
|
||||
| api/src/core/logging/middleware.py | FastAPI 请求中间件 |
|
||||
| api/src/core/logging/celery.py | Celery 日志信号集成 |
|
||||
| api/src/core/logging/examples.py | 使用示例（可选） |
|
||||
|
||||
## Dependencies
|
||||
|
||||
- [ ] structlog: 结构化日志与 contextvars 支持
|
||||
- [ ] python-json-logger（备选）: 若需要纯 logging JSON formatter
|
||||
- [ ] sentry-sdk（可选）: 异常告警与追踪
|
||||
|
||||
## 配置示例
|
||||
|
||||
```toml
|
||||
# .env 示例（通过 pydantic settings 读取）
|
||||
SOCIAL_RUNTIME__LOG_LEVEL=INFO
|
||||
SOCIAL_RUNTIME__LOG_JSON=true
|
||||
SOCIAL_RUNTIME__LOG_ROTATION=TIME
|
||||
SOCIAL_RUNTIME__LOG_ROTATION_WHEN=midnight
|
||||
SOCIAL_RUNTIME__LOG_ROTATION_BACKUP_COUNT=14
|
||||
SOCIAL_RUNTIME__LOG_DIR=logs
|
||||
SOCIAL_RUNTIME__LOG_ERROR_DIR=logs/errors
|
||||
```
|
||||
|
||||
## 使用示例代码
|
||||
|
||||
```python
|
||||
from core.logging import configure_logging, get_logger
|
||||
|
||||
configure_logging()
|
||||
logger = get_logger(__name__)
|
||||
|
||||
logger.info("user login", extra={"user_id": "u_123"})
|
||||
```
|
||||
|
||||
## Testing Strategy
|
||||
|
||||
- **Unit Tests:** formatter 输出结构、filter 脱敏规则、context 绑定行为
|
||||
- **Integration Tests:** FastAPI 中间件注入的 request_id 与错误分离写入
|
||||
- **E2E Tests:** 关键流程触发错误，验证 error 日志输出与轮转
|
||||
|
||||
## Risks & Mitigations
|
||||
|
||||
| Risk | Impact | Likelihood | Mitigation |
|
||||
|------|--------|------------|------------|
|
||||
| Celery 日志被自动劫持导致重复或丢失 | High | Medium | 设置 `worker_hijack_root_logger=False` 并通过信号统一配置 |
|
||||
| 结构化字段不一致导致下游解析失败 | Medium | Medium | 统一 schema，增加单元测试与校验 |
|
||||
| 误记录敏感信息 | High | Medium | 增加脱敏过滤器与字段黑名单 |
|
||||
| 日志量过大影响性能 | Medium | Medium | 轮转 + 级别控制 + 可选异步队列化 |
|
||||
|
||||
## Estimated Effort
|
||||
|
||||
| Phase | Effort |
|
||||
|-------|--------|
|
||||
| Phase 1 | 3 hours |
|
||||
| Phase 2 | 4 hours |
|
||||
| Phase 3 | 3 hours |
|
||||
| Phase 4 | 3 hours |
|
||||
| Phase 5 | 4 hours |
|
||||
| **Total** | **17 hours** |
|
||||
Reference in New Issue
Block a user