前言在生产环境中完善的日志系统是排查问题、性能优化的关键。本文将详细介绍如何为 FastAPI Uvicorn 项目从零搭建一套完整的日志系统包括访问日志记录每个 HTTP 请求应用日志记录应用运行状态性能日志记录接口响应时间自动识别慢查询最终效果logs/ ├── access.log # API 访问日志 ├── app.log # 应用运行日志 └── performance.log # 性能监控日志自动识别慢查询一、核心架构设计1.1 日志分离原则不同类型的日志应该分开存储便于快速定位问题针对性分析避免干扰1.2 技术选型Uvicorn 内置日志处理访问日志Python logging 模块统一日志管理RotatingFileHandler自动日志轮转防止文件过大FastAPI 中间件性能监控二、实现步骤2.1 创建日志配置模块创建logging_config.py 日志配置模块 功能 - 配置三种日志访问日志、应用日志、性能日志 - 支持自动轮转单文件最大 10MB保留 5 个历史文件 - 双输出模式控制台 文件 import logging import os from logging.handlers import RotatingFileHandler def setup_logging(): 配置应用日志系统 # 创建 logs 目录 log_dir logs if not os.path.exists(log_dir): os.makedirs(log_dir) print(f[LOGGING] Created log directory: {log_dir}) # 日志格式定义 # 默认格式时间 - 来源 - 级别 - 消息 default_formatter logging.Formatter( fmt%(asctime)s - %(name)s - %(levelname)s - %(message)s, datefmt%Y-%m-%d %H:%M:%S ) # 访问日志格式更简洁 access_formatter logging.Formatter( fmt%(asctime)s - %(message)s, datefmt%Y-%m-%d %H:%M:%S ) # 性能日志格式专注于性能指标 performance_formatter logging.Formatter( fmt%(asctime)s - %(message)s, datefmt%Y-%m-%d %H:%M:%S ) # 应用日志处理器 # 文件处理器 app_file_handler RotatingFileHandler( filenameos.path.join(log_dir, app.log), maxBytes10 * 1024 * 1024, # 10 MB backupCount5, encodingutf-8 ) app_file_handler.setFormatter(default_formatter) app_file_handler.setLevel(logging.INFO) # 控制台处理器 console_handler logging.StreamHandler() console_handler.setFormatter(default_formatter) console_handler.setLevel(logging.INFO) # 访问日志处理器 access_file_handler RotatingFileHandler( filenameos.path.join(log_dir, access.log), maxBytes10 * 1024 * 1024, backupCount5, encodingutf-8 ) access_file_handler.setFormatter(access_formatter) access_file_handler.setLevel(logging.INFO) access_console_handler logging.StreamHandler() access_console_handler.setFormatter(access_formatter) access_console_handler.setLevel(logging.INFO) # 性能日志处理器 performance_file_handler RotatingFileHandler( filenameos.path.join(log_dir, performance.log), maxBytes10 * 1024 * 1024, backupCount5, encodingutf-8 ) performance_file_handler.setFormatter(performance_formatter) performance_file_handler.setLevel(logging.INFO) # 配置日志记录器 # Uvicorn 主日志 uvicorn_logger logging.getLogger(uvicorn) uvicorn_logger.handlers.clear() uvicorn_logger.addHandler(app_file_handler) uvicorn_logger.addHandler(console_handler) uvicorn_logger.setLevel(logging.INFO) uvicorn_logger.propagate False # Uvicorn 错误日志 uvicorn_error_logger logging.getLogger(uvicorn.error) uvicorn_error_logger.handlers.clear() uvicorn_error_logger.addHandler(app_file_handler) uvicorn_error_logger.addHandler(console_handler) uvicorn_error_logger.setLevel(logging.INFO) uvicorn_error_logger.propagate False # Uvicorn 访问日志 access_logger logging.getLogger(uvicorn.access) access_logger.handlers.clear() access_logger.addHandler(access_file_handler) access_logger.addHandler(access_console_handler) access_logger.setLevel(logging.INFO) access_logger.propagate False # 性能日志记录器 performance_logger logging.getLogger(performance) performance_logger.handlers.clear() performance_logger.addHandler(performance_file_handler) # 默认不输出到控制台避免干扰 # performance_logger.addHandler(performance_console_handler) performance_logger.setLevel(logging.INFO) performance_logger.propagate False # 根日志记录器 root_logger logging.getLogger() root_logger.handlers.clear() root_logger.addHandler(app_file_handler) root_logger.addHandler(console_handler) root_logger.setLevel(logging.INFO) print([LOGGING] Log system configured successfully!) print(f[LOGGING] Application logs: {os.path.abspath(os.path.join(log_dir, app.log))}) print(f[LOGGING] Access logs: {os.path.abspath(os.path.join(log_dir, access.log))}) print(f[LOGGING] Performance logs: {os.path.abspath(os.path.join(log_dir, performance.log))}) def get_logger(name: str) - logging.Logger: 获取日志记录器 使用示例 from logging_config import get_logger logger get_logger(__name__) logger.info(This is an info message) return logging.getLogger(name)2.2 在应用中集成日志系统修改app.pyimport os import sys import time import logging import asyncio from contextlib import asynccontextmanager from dotenv import load_dotenv from fastapi import FastAPI, Request from logging_config import setup_logging, get_logger # 日志系统初始化 # 在加载环境变量之前初始化日志系统 setup_logging() # 环境变量加载 env_mode os.getenv(ENV, development) env_file f.env.{env_mode} # 创建应用日志记录器 logger get_logger(__name__) if os.path.exists(env_file): load_dotenv(env_file) print(f[ENV] Loaded environment from: {env_file}) logger.info(fLoaded environment from: {env_file}) else: print(f[WARN] {env_file} not found, using default values) logger.warning(f{env_file} not found, using default values) # FastAPI 应用实例 asynccontextmanager async def lifespan(_app: FastAPI): 应用生命周期管理 # 启动 logger.info(FastAPI application startup initiated) print([INFO] FastAPI Server Started Successfully!) logger.info(FastAPI server started successfully) yield # 关闭 logger.info(FastAPI application shutdown initiated) logger.info(Application shutdown completed) app FastAPI( titleFastAPI Backend Service, description基于 FastAPI 的后端服务支持热重载开发, version0.1.0, lifespanlifespan, ) # 注册路由... # app.include_router(...)2.3 添加性能监控中间件继续在app.py中添加# 性能监控中间件 performance_logger logging.getLogger(performance) # 测试模式从环境变量读取 SLOW_MODE os.getenv(SLOW_MODE, false).lower() true SLOW_DELAY float(os.getenv(SLOW_DELAY, 1.0)) if SLOW_MODE: print(f[TEST MODE] WARNING: SLOW MODE ENABLED: All requests will be delayed by {SLOW_DELAY}s) logger.warning(fSLOW MODE ENABLED: All requests will be delayed by {SLOW_DELAY}s) app.middleware(http) async def log_request_performance(request: Request, call_next): 性能监控中间件 功能 - 记录每个 API 请求的响应时间 - 自动识别慢查询响应时间 1 秒 - 记录到单独的性能日志文件 # 记录请求开始时间 start_time time.time() # 测试模式模拟慢查询 if SLOW_MODE: await asyncio.sleep(SLOW_DELAY) # 处理请求 response await call_next(request) # 计算响应时间 duration time.time() - start_time # 获取请求信息 method request.method url_path request.url.path status_code response.status_code # 判断是否为慢查询响应时间 1 秒 if duration 1.0: # 慢查询记录为 WARNING 级别 performance_logger.warning( fSLOW REQUEST: {method} {url_path} - {status_code} - {duration:.3f}s ) else: # 正常请求记录为 INFO 级别 performance_logger.info( f{method} {url_path} - {status_code} - {duration:.3f}s ) # 将响应时间添加到响应头 response.headers[X-Response-Time] f{duration:.3f}s return response2.4 在 .gitignore 中忽略日志文件# 日志文件 logs/ *.log三、使用示例3.1 在代码中记录日志from logging_config import get_logger logger get_logger(__name__) app.get(/api/users) async def get_users(): logger.info(正在获取用户列表) try: users await fetch_users() logger.info(f成功获取 {len(users)} 个用户) return users except Exception as e: logger.error(f获取用户列表失败: {str(e)}, exc_infoTrue) raise3.2 查看日志实时查看应用日志# PowerShell Get-Content logs\app.log -Wait -Tail 50 # Linux/Mac tail -f logs/app.log查看性能日志tail -f logs/performance.log只查看慢查询# PowerShell Select-String -Path logs\performance.log -Pattern SLOW REQUEST # Linux/Mac grep SLOW REQUEST logs/performance.log四、日志输出示例4.1 应用日志 (app.log)2026-03-03 14:30:10 - __main__ - INFO - Loaded environment from: .env.development 2026-03-03 14:30:11 - __main__ - INFO - FastAPI application startup initiated 2026-03-03 14:30:12 - __main__ - INFO - FastAPI server started successfully 2026-03-03 14:30:15 - api.users - INFO - 正在获取用户列表 2026-03-03 14:30:16 - api.users - INFO - 成功获取 125 个用户4.2 访问日志 (access.log)2026-03-03 14:30:15 - 127.0.0.1:52548 - GET /api/users HTTP/1.1 200 OK 2026-03-03 14:30:20 - 127.0.0.1:52548 - POST /api/login HTTP/1.1 201 Created 2026-03-03 14:30:25 - 127.0.0.1:52548 - GET /docs HTTP/1.1 200 OK4.3 性能日志 (performance.log)2026-03-03 14:30:15 - GET /api/users - 200 - 0.123s 2026-03-03 14:30:20 - POST /api/login - 201 - 0.045s 2026-03-03 14:30:25 - GET /api/products - 200 - 0.089s 2026-03-03 14:30:30 - SLOW REQUEST: GET /api/dashboard - 200 - 2.345s五、性能监控测试5.1 慢查询测试模式为了方便测试性能监控功能可以使用环境变量开启慢查询模拟# 方式 1临时设置环境变量 SLOW_MODEtrue SLOW_DELAY3.0 uvicorn app:app --reload # 方式 2在 .env 文件中配置 SLOW_MODEtrue SLOW_DELAY3.05.2 创建测试脚本创建start_slow_mode.bat(Windows):echo off echo echo 慢查询测试模式启动 echo set SLOW_MODEtrue set SLOW_DELAY2.0 poetry run uvicorn app:app --reload --host 0.0.0.0 --port 50005.3 测试效果启动慢查询测试模式后# 使用 curl 测试 curl http://localhost:5000/docs # 查看响应时间应该 2 秒 curl -w \nResponse time: %{time_total}s\n http://localhost:5000/docs查看性能日志2026-03-03 16:00:10 - SLOW REQUEST: GET /docs - 200 - 2.015s 2026-03-03 16:00:12 - SLOW REQUEST: GET /api/users - 200 - 2.123s六、生产环境优化6.1 调整日志级别生产环境建议只记录 WARNING 以上级别# 在 logging_config.py 中 uvicorn_logger.setLevel(logging.WARNING) access_logger.setLevel(logging.WARNING)6.2 禁用控制台输出生产环境只保留文件输出# 注释掉控制台处理器 # uvicorn_logger.addHandler(console_handler) # access_logger.addHandler(access_console_handler)6.3 调整日志轮转策略根据实际情况调整文件大小和保留数量app_file_handler RotatingFileHandler( filenameos.path.join(log_dir, app.log), maxBytes50 * 1024 * 1024, # 50 MB backupCount10, # 保留 10 个历史文件 encodingutf-8 )6.4 定期清理日志虽然有自动轮转但建议定期清理过期日志# Linux crontab 示例 # 每周日凌晨 2 点删除 30 天前的日志 0 2 * * 0 find /path/to/logs -name *.log.* -mtime 30 -delete七、性能分析实战7.1 统计某个接口的平均响应时间grep /api/users logs/performance.log | \ awk -F - {print $NF} | \ awk -Fs {sum$1; count} END {print Average:, sum/count s}7.2 找出最慢的 10 个请求grep -E [0-9]\.[0-9]s$ logs/performance.log | \ sort -t - -k4 -rn | \ head -107.3 统计慢查询数量# PowerShell (Select-String -Path logs\performance.log -Pattern SLOW REQUEST).Count # Linux/Mac grep -c SLOW REQUEST logs/performance.log八、核心特性总结8.1 自动轮转单个日志文件最大 10MB超过限制自动创建新文件app.log.1, app.log.2...最多保留 5 个历史文件旧文件自动删除8.2 日志分离访问日志所有 HTTP 请求应用日志应用运行状态性能日志接口响应时间8.3 性能监控自动记录所有接口响应时间自动识别慢查询 1 秒响应头添加X-Response-Time支持测试模式模拟慢查询8.4 双输出模式控制台实时查看开发调试文件永久保存生产环境九、最佳实践9.1 合理使用日志级别logger.debug(调试信息) # 开发阶段使用 logger.info(一般信息) # 重要的业务流程 logger.warning(警告信息) # 可能的问题 logger.error(错误信息) # 错误和异常 logger.critical(严重错误) # 致命错误9.2 记录有用的信息# ✅ 好的日志 logger.info(fUser {user_id} logged in from {ip_address}) # ❌ 不好的日志 logger.info(User logged in) # 缺少关键信息9.3 不要记录敏感信息# ❌ 危险 logger.info(fUser login: {username}, password: {password}) # ✅ 安全 logger.info(fUser {user_id} login successful)9.4 使用异常日志try: risky_operation() except Exception: # 自动记录完整的异常堆栈 logger.exception(Operation failed)十、常见问题Q1: 为什么看不到 DEBUG 级别的日志A: 默认日志级别是 INFO。要查看 DEBUG 日志需要在logging_config.py中修改uvicorn_logger.setLevel(logging.DEBUG)Q2: 日志文件太大怎么办A: 日志系统已配置自动轮转会自动管理文件大小。你也可以手动删除旧的日志文件。Q3: 如何完全关闭某类日志A: 在logging_config.py中注释掉对应的处理器# performance_logger.addHandler(performance_file_handler)Q4: Windows 下中文乱码怎么办A: 日志文件已配置 UTF-8 编码。如果查看时乱码确保使用支持 UTF-8 的编辑器如 VS Code。十一、总结本文实现了一个完整的 FastAPI 日志系统包括✅三种日志分离访问日志、应用日志、性能日志✅自动日志轮转防止文件过大✅性能监控自动识别慢查询✅测试模式方便测试慢查询场景✅双输出模式控制台 文件✅生产就绪可直接用于生产环境核心代码仅需两个文件logging_config.py日志配置约 150 行app.py集成日志和性能监控约 50 行完整代码已在实际项目中测试通过可以直接使用。参考资源Python logging 官方文档Uvicorn 官方文档FastAPI 中间件文档RotatingFileHandler 文档作者Claude发布时间2026-03-03项目地址GitHub