FastapiAdmin生产级日志体系：结构化、可审计、可告警

1. 这不是个“后台管理模板”，而是一套可审计、可追溯、可告警的生产级日志中枢

FastapiAdmin 不是那种装完就能跑、跑起来就不管的玩具型后台框架。我用它搭过三个中型 SaaS 项目的运营后台，从零用户到日活 2 万+，最深的体会是：系统日志体系不是锦上添花的装饰，而是整个后台系统的神经末梢和记忆中枢。你点一个按钮、改一条数据、导出一份报表——这些操作背后，必须有清晰、结构化、带上下文的日志记录。否则，当客户投诉“我昨天改的价格怎么又变回去了”，或者运维半夜被报警电话叫醒说“订单状态批量异常”，你打开日志文件看到的只会是一堆时间戳混杂的 JSON 字符串，连哪个请求触发了哪段逻辑都得靠猜。

FastapiAdmin 的日志体系，核心价值在于它把“谁在什么时间、以什么身份、通过什么接口、做了什么操作、影响了哪些数据、结果是否成功”这六个维度全部结构化落地，而不是简单地把logger.info()打印到控制台。它默认集成的是 Python 标准库的logging模块，但做了关键增强：自动注入请求 ID（request_id）、用户 ID（user_id）、操作路径（endpoint）、HTTP 方法（method）、响应状态码（status_code）和耗时（duration_ms）。这意味着你不用在每个 CRUD 接口里手动拼接日志字符串，框架已经帮你把骨架搭好了。比如一个用户修改商品库存的操作，日志会自动生成类似这样的结构体：

{ "timestamp": "2024-06-15T14:22:38.123Z", "level": "INFO", "request_id": "a1b2c3d4-e5f6-7890-g1h2-i3j4k5l6m7n8", "user_id": 1024, "username": "ops_admin", "endpoint": "/api/v1/products/123", "method": "PATCH", "status_code": 200, "duration_ms": 42.7, "action": "update_inventory", "data": {"old_stock": 100, "new_stock": 95, "reason": "促销活动补货"}, "ip_address": "192.168.1.105" }

这个结构，直接决定了你后续做审计分析、行为追踪、性能瓶颈定位的效率。我见过太多团队，前期图省事用print()或裸logging，等业务量上来后，光是日志清洗和字段提取就花了两个工程师一周时间。FastapiAdmin 的这套设计，本质上是在项目启动阶段就帮你把日志的“契约”定死了。它不强制你用 ELK 或 Loki，但保证你输出的日志格式是标准、稳定、可解析的。所以，当你看到“FastapiAdmin 系统日志体系”这个标题时，别只把它当成配置项列表，它其实是整套后台系统可观测性的第一道防线，是开发、测试、运维、安全、合规所有角色共同依赖的单一事实来源。

2. 日志体系的三层架构：从采集、过滤到落盘，每层都藏着关键决策点

FastapiAdmin 的日志体系不是扁平的，它天然分成了三层：采集层（Capture）→ 过滤与丰富层（Enrich & Filter）→ 落盘与分发层（Sink）。理解这三层，才能真正驾驭它的配置参数，而不是盲目复制粘贴settings.py里的几行代码。

2.1 采集层：不是所有日志都值得记录，也不是所有请求都该被埋点

采集层的核心任务，是决定“什么事件需要被记录”。FastapiAdmin 默认只对 Admin 后台的 API 请求进行结构化日志记录，这是非常务实的设计。它不会去记录静态资源（CSS/JS）的访问，也不会记录健康检查/healthz这类探针请求——因为这些日志量巨大，但业务价值极低。它的采集入口在fastapi_admin/app.py的AdminApp类中，通过一个LogMiddleware中间件实现。这个中间件会拦截所有经过 Admin Router 的请求，并在请求结束时（无论成功或失败）生成一条日志。

但这里有个关键细节：它只记录 Admin Router 下的路由，不记录你项目里其他 FastAPI 应用的路由。比如你有一个/api/v1/orders的订单服务，它和 Admin 是同一个 FastAPI 实例，但如果你没把订单路由挂载到 Admin 的 Router 下，那么订单操作就不会被自动记录。这是很多新手踩的第一个坑——以为装了 FastapiAdmin 就万事大吉，结果发现核心业务操作日志一片空白。解决方案有两个：一是把业务 API 显式挂载到 Admin 的 Router（适合内部管理类接口），二是为业务 API 单独编写一个类似的中间件，复用 FastapiAdmin 的日志格式器（Formatter）和处理器（Handler），保持日志风格统一。

另一个常被忽略的采集点是“异常日志”。FastapiAdmin 会捕获未处理的异常，并生成ERROR级别的日志，其中包含完整的 traceback。但注意，它不会捕获你主动抛出的HTTPException。比如你在某个视图函数里写了raise HTTPException(status_code=403, detail="权限不足")，这会被 FastAPI 框架正常处理并返回 403 响应，但不会触发日志中间件的 ERROR 记录。因为HTTPException是预期中的业务异常，不是程序崩溃。如果你希望这类权限拒绝也记为一条WARNING日志，就需要在你的视图函数里手动调用logger.warning()，或者写一个全局的异常处理器来统一处理。

2.2 过滤与丰富层：让日志从“发生了什么”升级为“为什么发生”

这一层是 FastapiAdmin 日志体系的灵魂所在。它不只是打个时间戳，而是动态注入关键上下文，让日志具备真正的可追溯性。其核心机制是LogRecord对象的extra字典。FastapiAdmin 在创建LogRecord时，会将当前请求的request.state和request.user（如果已认证）中的信息，一股脑塞进extra里。这就意味着，只要你能在request.state里存东西，它就会自动出现在日志里。

我实际项目中最常用的一个技巧，就是在中间件里给request.state添加一个trace_id。我们用的是 OpenTelemetry，但 FastapiAdmin 并不原生支持 OTel，所以我在app.py里加了一个简单的中间件：

from opentelemetry import trace from opentelemetry.context import get_current_context async def trace_middleware(request: Request, call_next): # 从请求头获取 trace_id，或生成新的 trace_id = request.headers.get("x-trace-id", str(uuid.uuid4())) request.state.trace_id = trace_id # 将 trace_id 注入当前上下文，方便后续 span 使用 context = trace.set_span_in_context(trace.get_current_span()) response = await call_next(request) response.headers["X-Trace-ID"] = trace_id return response

然后，在日志配置里，只要 Formatter 的format字符串里包含%(trace_id)s，这个字段就会自动从request.state.trace_id取值。这样，前端一次点击产生的所有后台请求（Admin 接口、订单接口、用户接口），只要都经过这个中间件，就会拥有同一个trace_id，你就能在日志系统里一键串联起整个调用链。这比单纯看request_id强得多，因为request_id只在一个请求内有效，而trace_id跨服务、跨进程。

另一个重要的丰富点是敏感数据脱敏。FastapiAdmin 默认不会对日志中的data字段做任何处理。如果你在data里直接传了用户的手机号、身份证号，它们就会明文出现在日志里，这是严重的安全风险。官方文档没提，但实践中的标准做法是：在日志处理器（Handler）层面做脱敏，而不是在业务代码里手动删字段。你可以继承logging.Handler，重写emit()方法，在把日志写入文件前，用正则表达式匹配并替换掉phone,id_card,password等关键词对应的值。这样，业务代码永远是干净的，脱敏规则集中管理，一改全改。

2.3 落盘与分发层：日志不是写完就完事，而是要能被找到、被分析

落盘层决定了日志的最终归宿和可用性。FastapiAdmin 默认使用RotatingFileHandler，按文件大小轮转（默认 10MB），最多保留 5 个历史文件。这个配置看似简单，但背后有很深的权衡。

首先，为什么是文件，而不是直接发到 Kafka 或 Elasticsearch？因为 FastapiAdmin 定位是轻量级后台框架，它假设你的部署环境可能没有成熟的日志收集基础设施。文件是最通用、最低门槛的存储方式。但这也意味着，如果你的服务器有多个实例（比如 Docker Swarm 或 Kubernetes 部署了 3 个副本），每个实例都会写自己的日志文件，你要查一条日志就得登录三台机器分别 grep。所以，生产环境强烈建议你用syslogHandler 或SocketHandler，把日志统一发送到一个中心化的日志收集器（如 Fluentd、Filebeat），再由它转发到 ES 或 Loki。

其次，轮转大小和数量不是随便定的。10MB 看似合理，但如果你的后台每天产生 500MB 日志，那 5 个文件只能保存不到一天的数据，老日志就被覆盖了。我通常会根据预估的日志量来反推：先用logging.basicConfig(level=logging.INFO)启动服务，运行 1 小时，用du -sh *.log查看实际日志体积，再乘以 24，得到日均日志量。如果日均是 2GB，那maxBytes至少设为 100MB，backupCount设为 30，确保至少保留一周。另外，RotatingFileHandler的轮转是基于文件大小，不是时间，所以它无法保证“每天一个文件”。如果你需要按天归档（便于运维按日期清理），就必须换用TimedRotatingFileHandler，并设置when='midnight'。

最后，也是最容易被忽视的一点：日志级别（level）的设置，本质是成本与价值的平衡。DEBUG级别会记录每一个 SQL 查询、每一个 Redis 命令，信息量爆炸，但磁盘 IO 和存储成本极高；WARNING级别只记录异常和警告，成本最低，但你会丢失大量用于性能分析的黄金数据。我的经验是：生产环境用INFO，但把数据库查询日志单独抽出来，用DEBUG级别写到另一个文件里。这样，主日志文件干净，DB 日志详尽，互不干扰。

3. 核心配置参数详解：从LOGGING_CONFIG到ADMIN_LOG_LEVEL，每个参数都是一个开关

FastapiAdmin 的日志配置，主要通过两个地方控制：一个是全局的LOGGING_CONFIG字典，它遵循 Pythonlogging.config.dictConfig的标准格式；另一个是 FastapiAdmin 自己定义的几个特定配置项，如ADMIN_LOG_LEVEL。下面我逐个拆解，告诉你每个参数的真实作用、常见陷阱和最佳实践。

3.1LOGGING_CONFIG: 不是“抄过来就行”，而是要读懂它的拓扑结构

LOGGING_CONFIG是一个嵌套字典，它定义了整个日志系统的“地图”。很多人直接复制官方示例，却不知道里面的handlers、formatters、loggers三者是如何协作的。我画了一个简化的拓扑关系图（文字描述）：

[Root Logger] --(propagate=True)--> [fastapi_admin Logger] --(handlers=[file, console])--> [FileHandler] & [ConsoleHandler] ↓ [sqlalchemy Logger] --(level=WARNING, handlers=[]) --> (不输出，除非显式配置)

• version: 必须是 1，这是dictConfig的协议版本，固定写死。
• disable_existing_loggers: 这个参数极其关键！默认是True，意味着它会禁用所有已存在的 logger（包括 SQLAlchemy、Uvicorn 自带的 logger）。如果你的应用里用了 SQLAlchemy ORM，又没给sqlalchemylogger 单独配置 handler，那么 ORM 的 SQL 日志就完全消失了。生产环境务必设为False，然后手动为sqlalchemy和uvicorn.access配置独立的 handler，避免“一锅端”。
• formatters: 定义日志的“长相”。FastapiAdmin 默认提供standard和colored两种。standard用于文件，格式是纯文本，便于 grep 和日志分析工具解析；colored用于终端，用 ANSI 颜色高亮不同级别。注意，coloredformatter 依赖colorama库，如果你的容器镜像里没装，终端日志会变成一堆乱码。解决方案是：在Dockerfile里pip install colorama，或者干脆在生产环境只用standard。
• handlers: 定义日志的“去向”。filehandler 写文件，consolehandler 输出到 stdout。关键参数：
  • class:logging.handlers.RotatingFileHandler是默认，但如果你想用TimedRotatingFileHandler，这里就要改。
  • filename: 日志文件路径。绝对不要写相对路径，比如logs/admin.log。因为 Uvicorn 启动时的工作目录可能是任意的。必须用绝对路径，比如/var/log/fastapi-admin/admin.log，并在 Dockerfile 里RUN mkdir -p /var/log/fastapi-admin。
  • maxBytes和backupCount: 如前所述，按需调整。
• loggers: 定义“谁来记录”。fastapi_admin是主 logger，sqlalchemy和uvicorn是常见的第三方 logger。fastapi_admin的level设为INFO，propagate设为True，意味着它的日志会向上交给 root logger 处理。而 root logger 的handlers里包含了file和console，所以最终日志会同时写文件和输出到终端。如果你只想写文件，就把 root logger 的handlers列表清空，只留下file。

3.2ADMIN_LOG_LEVEL: 全局开关，但不是万能的

ADMIN_LOG_LEVEL是 FastapiAdmin 自定义的配置项，类型是字符串，如"INFO"、"WARNING"。它的作用是设置fastapi_adminlogger 的最低记录级别。看起来很简单，但要注意两点：

第一，它只影响fastapi_admin这个 logger，不影响sqlalchemy或uvicorn。所以，即使你把ADMIN_LOG_LEVEL设为DEBUG，SQLAlchemy 的 SQL 日志依然不会出现，除非你同时把sqlalchemylogger 的 level 也设为DEBUG。

第二，它和LOGGING_CONFIG里的loggers.fastapi_admin.level是二选一的关系。如果你在LOGGING_CONFIG里已经显式设置了loggers.fastapi_admin.level，那么ADMIN_LOG_LEVEL就会被忽略。官方文档没说清楚这点，导致很多人改了ADMIN_LOG_LEVEL发现没效果。我的建议是：只用LOGGING_CONFIG来统一管理所有 logger 的 level，把ADMIN_LOG_LEVEL当作一个备用开关，或者干脆不用。这样逻辑更清晰，不会产生冲突。

3.3LOG_FILE_PATH和LOG_FILE_MAX_SIZE: 文件路径与大小的硬编码陷阱

这两个参数看起来是LOGGING_CONFIG的简化版，但它们的存在本身就是一个设计妥协。LOG_FILE_PATH直接指定了日志文件的绝对路径，LOG_FILE_MAX_SIZE直接指定了单个文件的最大大小（单位是字节）。它们的好处是简单，坏处是绕过了dictConfig的灵活性。

最大的陷阱是：如果你同时设置了LOGGING_CONFIG和LOG_FILE_PATH，FastapiAdmin 的源码里会优先使用LOG_FILE_PATH，并用它动态生成一个RotatingFileHandler，然后把这个 handler 加到fastapi_adminlogger 上。这意味着，你LOGGING_CONFIG里为fastapi_admin配置的 handler 就被覆盖了！我曾经遇到一个诡异问题：LOGGING_CONFIG里明明配置了consolehandler，但日志就是不输出到终端。最后发现，是因为LOG_FILE_PATH被设置了，框架自动添加了一个 file handler，并且没有把 console handler 也加上去。

所以，我的实操心得是：要么彻底放弃LOG_FILE_PATH和LOG_FILE_MAX_SIZE，完全用LOGGING_CONFIG；要么就只用这两个参数，把LOGGING_CONFIG设为空字典{}。二者不可混用。前者更推荐，因为LOGGING_CONFIG支持TimedRotatingFileHandler、SysLogHandler等高级功能，而那两个参数只支持最基础的RotatingFileHandler。

3.4LOG_REQUEST_BODY: 一把双刃剑，开之前想清楚代价

LOG_REQUEST_BODY是一个布尔值，默认是False。设为True后，FastapiAdmin 会在日志里记录请求的完整 body（POST/PUT/PATCH 的 JSON 数据）。这听起来很诱人，调试时能一眼看到用户提交了什么。

但请务必三思。原因有三：

1. 性能损耗：读取request.body()是一个异步操作，会阻塞事件循环。对于高并发的后台，每个请求都多一次 I/O，QPS 会明显下降。我做过压测，开启后，单机 QPS 从 1200 降到 850。
2. 隐私泄露：body 里可能包含密码、token、身份证号等敏感信息。即使你做了脱敏，也难保万无一失。日志文件一旦被未授权访问，后果严重。
3. 存储爆炸：一个复杂的表单提交，body 可能有几 KB，日志量会指数级增长。原本一天 100MB 的日志，可能变成 1GB。

我的建议是：永远不要在生产环境开启LOG_REQUEST_BODY。调试时，可以在本地开发环境临时开启，或者用 Postman 发送请求时，把 body 复制粘贴到一个临时文本里，手动和日志比对。如果真需要记录某些关键字段（比如订单号、商品 ID），应该在业务代码里，把它们显式提取出来，放到日志的extra字典里，而不是记录整个 body。

4. 实操：从零搭建一个可审计、可告警的生产级日志方案

光讲理论不够，下面我带你走一遍完整的实操流程。这不是一个“Hello World”式的演示，而是我在线上环境真实部署的方案，涵盖了从配置、测试到监控的全链条。

4.1 步骤一：初始化配置，避开默认陷阱

首先，创建一个logging_config.py文件，内容如下。这个配置是我经过多次迭代后的“生产就绪”版本：

import os from pathlib import Path # 日志根目录，确保存在 LOG_DIR = Path("/var/log/fastapi-admin") LOG_DIR.mkdir(parents=True, exist_ok=True) LOGGING_CONFIG = { "version": 1, "disable_existing_loggers": False, # 关键！不关闭 SQLAlchemy 等 logger "formatters": { "standard": { "format": "%(asctime)s [%(levelname)s] %(name)s: %(message)s", "datefmt": "%Y-%m-%d %H:%M:%S" }, "json": { # 新增 JSON 格式，便于 ELK 解析 "class": "pythonjsonlogger.jsonlogger.JsonFormatter", "format": "%(asctime)s %(name)s %(levelname)s %(request_id)s %(user_id)s %(endpoint)s %(method)s %(status_code)d %(duration_ms).2f %(action)s %(ip_address)s %(data)s" } }, "handlers": { "file": { "level": "INFO", "class": "logging.handlers.TimedRotatingFileHandler", "filename": str(LOG_DIR / "admin.log"), "when": "midnight", # 每天午夜轮转 "interval": 1, "backupCount": 30, # 保留 30 天 "formatter": "json", # 使用 JSON 格式 "encoding": "utf8" }, "error_file": { # 单独的错误日志文件 "level": "ERROR", "class": "logging.handlers.RotatingFileHandler", "filename": str(LOG_DIR / "admin_error.log"), "maxBytes": 10 * 1024 * 1024, # 10MB "backupCount": 10, "formatter": "standard", "encoding": "utf8" }, "console": { "level": "INFO", "class": "logging.StreamHandler", "formatter": "standard" } }, "loggers": { "fastapi_admin": { "handlers": ["file", "error_file", "console"], "level": "INFO", "propagate": False # 关键！防止日志重复写入 root logger }, "sqlalchemy": { "handlers": ["file"], # SQL 日志只写文件，不输出到 console "level": "WARNING", # 生产环境只记录 WARNING 及以上 "propagate": False }, "uvicorn.access": { "handlers": ["file"], "level": "INFO", "propagate": False } }, "root": { "level": "WARNING", # root logger 只记录 WARNING 及以上，避免噪音 "handlers": [] } }

注意几个关键点：

• disable_existing_loggers设为False；
• fastapi_adminlogger 的propagate设为False，避免日志被 root logger 重复处理；
• 为sqlalchemy和uvicorn.access单独配置了 handler 和 level；
• 新增了jsonformatter，为未来接入 ELK 做准备；
• error_filehandler 专门捕获 ERROR 级别日志，方便快速定位故障。

然后，在你的main.py或app.py中，加载这个配置：

import logging.config from fastapi_admin.app import AdminApp from .logging_config import LOGGING_CONFIG # 在创建 app 实例之前，先配置日志 logging.config.dictConfig(LOGGING_CONFIG) app = AdminApp()

4.2 步骤二：注入关键上下文，让日志“活”起来

仅仅有格式还不够，日志必须有灵魂。我们在app.py里添加一个中间件，注入request_id和trace_id：

import uuid from fastapi import Request, Response from starlette.middleware.base import BaseHTTPMiddleware class ContextMiddleware(BaseHTTPMiddleware): async def dispatch(self, request: Request, call_next) -> Response: # 生成 request_id request_id = str(uuid.uuid4()) request.state.request_id = request_id # 从 header 获取 trace_id，或生成新的 trace_id = request.headers.get("x-trace-id", str(uuid.uuid4())) request.state.trace_id = trace_id # 记录客户端 IP（考虑代理） ip_address = request.client.host if "x-forwarded-for" in request.headers: ip_address = request.headers["x-forwarded-for"].split(",")[0].strip() request.state.ip_address = ip_address response = await call_next(request) response.headers["X-Request-ID"] = request_id response.headers["X-Trace-ID"] = trace_id return response # 在 app 实例化后，注册中间件 app = AdminApp() app.add_middleware(ContextMiddleware)

这样，所有日志都会自动带上request_id、trace_id和ip_address。你甚至可以在日志里搜索request_id: a1b2c3d4...，就能精准定位某一次请求的全部日志。

4.3 步骤三：编写一个“审计日志”专用的 Action Log

FastapiAdmin 的默认日志记录了“技术操作”，但业务上还需要“业务操作”的审计日志。比如，“用户 A 将订单状态从‘待支付’改为‘已取消’”，这需要记录操作人、操作前状态、操作后状态、操作原因。我们可以通过自定义 Admin Model 的save方法来实现：

from fastapi_admin.models import AbstractAdmin from fastapi_admin.contrib.sqlmodel import ModelAdmin from sqlmodel import SQLModel, Field from datetime import datetime class Order(SQLModel, table=True): id: int = Field(default=None, primary_key=True) status: str = Field(default="pending") # pending, paid, shipped, cancelled updated_at: datetime = Field(default_factory=datetime.utcnow) class OrderAdmin(ModelAdmin, model=Order): # ... 其他配置 ... async def save(self, obj, is_new: bool = False): # 保存前，记录审计日志 if not is_new and hasattr(obj, "_old_status"): old_status = getattr(obj, "_old_status") new_status = obj.status if old_status != new_status: # 构造审计日志数据 audit_data = { "action": "order_status_change", "order_id": obj.id, "old_status": old_status, "new_status": new_status, "reason": getattr(obj, "_change_reason", "unknown") } # 使用 fastapi_admin 的 logger logger = logging.getLogger("fastapi_admin") logger.info("Order status changed", extra=audit_data) return await super().save(obj, is_new)

这样，每次管理员在后台修改订单状态，都会生成一条结构化的审计日志，和普通的 API 请求日志分开，便于合规审计。

4.4 步骤四：对接 Prometheus + Grafana，实现日志驱动的告警

日志写出来只是第一步，让它产生价值才是关键。我们用prometheus-fastapi-instrumentator库，把关键日志指标暴露给 Prometheus：

pip install prometheus-fastapi-instrumentator

在app.py中：

from prometheus_fastapi_instrumentator import Instrumentator # 在 app 创建后，初始化 Instrumentator instrumentator = Instrumentator( should_group_status_codes=True, should_ignore_untemplated=True, should_respect_env_var=True, excluded_handlers=["/metrics", "/healthz"] ) instrumentator.instrument(app).expose(app)

然后，写一个简单的 Grafana Dashboard，监控以下指标：

• http_requests_total{handler="fastapi_admin"}：Admin 接口总请求数
• http_request_duration_seconds_bucket{handler="fastapi_admin",le="0.1"}：100ms 内完成的请求占比（反映性能）
• fastapi_admin_log_count_total{level="ERROR"}：ERROR 日志数量（直接关联故障）

最后，配置 Prometheus Alert Rule：

groups: - name: fastapi-admin-alerts rules: - alert: AdminErrorRateHigh expr: sum(rate(fastapi_admin_log_count_total{level="ERROR"}[5m])) / sum(rate(http_requests_total{handler="fastapi_admin"}[5m])) > 0.01 for: 2m labels: severity: critical annotations: summary: "FastapiAdmin 错误率过高" description: "过去 5 分钟内，Admin 接口错误率超过 1%，当前值 {{ $value }}%"

当错误率持续 2 分钟超过 1%，就会触发企业微信/钉钉告警。这才是日志体系的终极形态：从被动记录，走向主动预警。

5. 常见问题与排查技巧实录：那些只有踩过坑才知道的真相

在 FastapiAdmin 日志体系的实战中，我整理了 7 个最典型、最高频的问题，以及我摸索出来的独家排查技巧。这些问题，官方文档不会写，Stack Overflow 上也找不到答案，全是血泪教训。

5.1 问题一：“日志文件是空的！”——不是没写，是写到了你找不到的地方

现象：配置了LOG_FILE_PATH，启动服务后，日志文件创建了，但一直是空的，ls -la看大小是 0。

排查思路：

1. 首先确认LOG_FILE_PATH的路径是否有写入权限。ls -ld /var/log/fastapi-admin，看 owner 是否是运行 Uvicorn 的用户（通常是www-data或app）。如果不是，sudo chown www-data:www-data /var/log/fastapi-admin。
2. 更隐蔽的原因是：RotatingFileHandler在首次写入时，会尝试open(filename, 'a')。如果父目录/var/log/fastapi-admin不存在，它不会报错，而是静默失败。所以，必须确保LOG_FILE_PATH的父目录在服务启动前就已存在，并且有权限。Dockerfile 里一定要有RUN mkdir -p /var/log/fastapi-admin && chown app:app /var/log/fastapi-admin。
3. 如果用了TimedRotatingFileHandler，检查when参数。when='midnight'意味着它只在午夜 0 点第一次写入时创建文件。白天你启动服务，它不会立刻创建文件，要等到第二天凌晨。解决办法：把when暂时改成'S'（seconds），interval=1，测试通了再改回去。

独家技巧：在app.py开头，加一行logging.info("App started, logging test.")。如果这行日志都没出现，说明日志配置根本没生效，问题出在dictConfig加载时机上。

5.2 问题二：“SQL 日志不见了！”——不是框架不支持，是你关掉了它

现象：LOGGING_CONFIG里配置了sqlalchemylogger，但日志里看不到任何SELECT、UPDATE语句。

根本原因：disable_existing_loggers=True（默认值）会禁用 SQLAlchemy 初始化时创建的 logger。即使你在loggers里重新定义了sqlalchemy，它也只是一个新对象，和 SQLAlchemy 内部使用的 logger 不是同一个。

解决方案：disable_existing_loggers=False，并且确保sqlalchemylogger 的propagate=False，避免日志被 root logger 重复处理。另外，SQLAlchemy 的日志级别默认是WARN，所以echo=True只在DEBUG级别下才生效。因此，sqlalchemylogger 的level必须设为DEBUG，并且在创建create_engine时，显式设置echo=False（因为echo=True会把日志打到stdout，和你的日志体系冲突）。

5.3 问题三：“日志里没有 user_id！”——不是没传，是认证中间件没执行

现象：日志里user_id字段总是None或0。

排查步骤：

1. 检查你的 Admin 登录是否成功。打开浏览器开发者工具，看/admin/login的响应，确认返回了有效的access_token。
2. 检查Authorizationheader 是否正确传递。FastapiAdmin 默认从Bearer <token>中解析 token。确保你的前端在请求头里写了Authorization: Bearer xxxxx。
3. 最关键的一步：检查AdminApp的auth参数。你必须在创建AdminApp时，传入一个实现了authenticate方法的认证类实例。如果auth=None或者auth类的authenticate方法没返回user_id，那么request.user就是None，日志自然没有user_id。

独家技巧：在ContextMiddleware里，加一行logger.debug("User info: %s", getattr(request, 'user', None))，可以直观看到request.user是什么。

5.4 问题四：“日志格式乱码！”——不是字体问题，是编码没指定

现象：日志文件里中文显示为u'\u4f60\u597d'这样的 Unicode 转义序列。

原因：RotatingFileHandler默认使用locale.getpreferredencoding()作为文件编码，但在 Docker 容器里，这个值常常是ANSI_X3.4-1968（即 ASCII），不支持 UTF-8。TimedRotatingFileHandler同理。

解决方案：在handlers的配置里，显式指定encoding="utf8"。这是必须写的参数，不能省略。

5.5 问题五：“ERROR 日志没进 error_file！”——不是配置错了，是 logger 选错了

现象：error_filehandler 配置了level=ERROR，但admin_error.log里还是空的。

真相：error_filehandler 是挂在fastapi_adminlogger 上的，但ERROR级别的日志，可能来自sqlalchemy或uvicorn.error，它们有自己的 logger，没用fastapi_admin的 handler。

正确做法：为sqlalchemy和uvicorn.error也配置error_filehandler，或者，更推荐的做法是：只用一个filehandler，然后在loggers里，把所有你想监控的 logger 的level都设为ERROR，并把它们的handlers都指向file。这样，所有 ERROR 日志都汇聚到一个文件，方便统一告警。

5.6 问题六：“日志里的时间是 UTC，不是北京时间！”——不是服务器时区错了，是 Python 的锅

现象：日志里的asctime是2024-06-15 06:22:38，但服务器时间是 `14:22:3