健康检查与监控

概述

生产环境的健康检查与监控是保障服务可用性的关键环节。本文介绍 FastAPI 应用的健康检查端点、监控指标采集、日志聚合方案。

监控体系层次

1. 应用层：健康检查端点、业务指标
2. 系统层：CPU/内存/磁盘/网络
3. 中间件：MySQL/Redis 连接状态
4. 日志：集中式日志收集与分析

健康检查端点

FastAPI 内置健康检查路由，可用于负载均衡器或容器编排的探针配置：

# 基础健康检查
GET /api/v1/health

# 响应示例
{
    "code": 0,
    "data": {
        "status": "healthy",
        "version": "1.0.0",
        "uptime": 3600
    },
    "msg": "操作成功",
    "ok": true
}

Docker 健康检查

在 Dockerfile 中配置 HEALTHCHECK：

HEALTHCHECK --interval=30s --timeout=10s --retries=3 \
 CMD curl -f http://localhost:8031/api/v1/health || exit 1

监控指标

应用指标

指标	说明	采集方式
请求总量	API 调用次数	Nginx access log / 应用中间件
响应时间	P50/P95/P99 延迟	应用中间件 / APM
错误率	5xx 响应占比	Nginx error log / 应用日志
活跃连接数	当前并发请求	Uvicorn stats

系统指标

指标	说明	告警阈值
CPU 使用率	进程 CPU 占用	> 80%
内存使用率	进程内存占用	> 85%
磁盘使用率	磁盘空间占用	> 90%
网络流量	入站/出站带宽	根据带宽设定

中间件指标

指标	说明	告警阈值
MySQL 连接数	活跃/空闲连接	> max_connections * 0.8
MySQL 慢查询	执行时间 > 1s 的查询	> 10/min
Redis 内存使用	Redis 内存占用	> maxmemory * 0.8
Redis 连接数	活跃客户端连接	> maxclients * 0.8

日志聚合

应用日志格式

项目使用 Python logging 模块输出结构化日志：

2026-09-05 10:30:15 [INFO] core.app: Application startup complete
2026-09-05 10:30:16 [WARNING] middleware.rate_limit: Rate limit exceeded for 192.168.1.100
2026-09-05 10:30:17 [ERROR] modules.auth.service: Login failed for user admin

ELK 方案

Elasticsearch + Logstash + Kibana 集中日志收集：

# Filebeat 配置示例
filebeat.inputs:
  - type: log
    enabled: true
    paths:
      - /data/apps/logs/*.log
    fields:
      app: djangoadmin
    multiline.pattern: '^\d{4}-\d{2}-\d{2}'
    multiline.negate: true
    multiline.match: after

output.elasticsearch:
  hosts: ["http://elasticsearch:9200"]
  index: "djangoadmin-%{+yyyy.MM.dd}"

Loki 方案

轻量级日志聚合（配合 Grafana）：

# docker-compose.yml 添加 Loki 和 Grafana
services:
  loki:
    image: grafana/loki:latest
    ports:
      - "3100:8001"

  promtail:
    image: grafana/promtail:latest
    volumes:
      - /data/apps/logs:/var/log/app
      - ./promtail-config.yml:/etc/promtail/config.yml

  grafana:
    image: grafana/grafana:latest
    ports:
      - "3000:3000"

Loki 优势

相比 ELK，Loki 更轻量——不索引日志内容，仅索引标签，存储成本低，适合中小规模部署。

告警配置

常用告警规则

# Prometheus AlertManager 规则示例
groups:
  - name: djangoadmin
    rules:
      - alert: HighErrorRate
        expr: rate(http_requests_total{status=~"5.."}[5m]) > 0.1
        for: 5m
        labels:
          severity: critical
        annotations:
          summary: "错误率超过10%"

      - alert: HighResponseTime
        expr: histogram_quantile(0.95, rate(http_request_duration_seconds_bucket[5m])) > 2
        for: 5m
        labels:
          severity: warning
        annotations:
          summary: "P95响应时间超过2秒"

总结

健康检查与监控是生产环境的基础设施：通过健康检查端点实现负载均衡探针，通过系统/应用/中间件指标全面掌握服务状态，通过 ELK 或 Loki 实现日志集中分析。建议中小项目优先采用 Loki+Grafana 轻量方案，大型项目使用 ELK 全家桶。