Docker Compose环境下Django应用使用Gunicorn时日志阻塞问题排查

碰到过类似的日志阻塞坑，结合你的配置情况，给你几个可行的解决方案：

1. 优先切换为Docker友好的日志输出（推荐） #

Docker容器环境下，不建议用FileHandler写本地文件日志——一来多进程的Gunicorn会引发文件写入竞争，二来容器内的日志文件不好收集和管理，还容易因为权限或缓冲导致阻塞。

修改你的LOGGING配置，把文件输出换成直接输出到控制台（让Docker日志驱动捕获）：

import os
import sys
from pathlib import Path

BASE_DIR = Path(__file__).resolve().parent.parent
LOGGING_DIR = os.path.join(BASE_DIR, 'logs')
# 确保日志目录存在
os.makedirs(LOGGING_DIR, exist_ok=True)

DEBUG = True

LOGGING = {
    'version': 1,
    'disable_existing_loggers': False,
    'formatters': {
        'verbose': {
            'format': '%(levelname)s %(asctime)s %(module)s %(process)d %(thread)d %(message)s'
        },
        'simple': {
            'format': '%(levelname)s %(message)s'
        }
    },
    'handlers': {
        'console': {
            'class': 'logging.StreamHandler',
            'formatter': 'verbose',
            # 直接指向stdout，避免缓冲堆积
            'stream': 'ext://sys.stdout'
        }
    },
    'root': {
        'handlers': ['console'],
        'level': 'DEBUG' if DEBUG else 'INFO'
    },
    'loggers': {
        'django': {
            'handlers': ['console'],
            'level': os.getenv('DJANGO_LOG_LEVEL', 'INFO'),
            'propagate': False,
        },
    }
}

同时启动Gunicorn时，确保它的日志也输出到控制台：

gunicorn --bind 0.0.0.0:8000 --workers 4 --access-logfile - --error-logfile - your_project.wsgi:application

（--access-logfile -和--error-logfile -表示把访问日志和错误日志输出到stdout/stderr）

2. 处理多进程日志竞争问题（如果一定要用文件日志） #

如果必须把日志写入容器内的文件，要解决Gunicorn多进程写入冲突的问题，推荐用QueueHandler+QueueListener的组合：

import logging
import logging.handlers
from queue import Queue
import os
from pathlib import Path

BASE_DIR = Path(__file__).resolve().parent.parent
LOGGING_DIR = os.path.join(BASE_DIR, 'logs')
os.makedirs(LOGGING_DIR, exist_ok=True)

DEBUG = True

# 初始化日志队列，用于多进程日志转发
log_queue = Queue(-1)

LOGGING = {
    'version': 1,
    'disable_existing_loggers': False,
    'formatters': {
        'verbose': {
            'format': '%(levelname)s %(asctime)s %(module)s %(process)d %(thread)d %(message)s'
        }
    },
    'handlers': {
        'queue': {
            'class': 'logging.handlers.QueueHandler',
            'queue': log_queue,
        },
        'file': {
            'level': 'DEBUG',
            'class': 'logging.FileHandler',
            'filename': os.path.join(LOGGING_DIR, 'django.log'),
            'formatter': 'verbose',
            'encoding': 'utf-8',
            # 启用行缓冲，减少阻塞概率
            'buffering': 1
        }
    },
    'root': {
        'handlers': ['queue'],
        'level': 'DEBUG'
    },
}

# 启动队列监听器，单独进程处理日志写入（避免多进程直接写文件）
listener = logging.handlers.QueueListener(log_queue, LOGGING['handlers']['file'])
listener.start()

这样每个Gunicorn worker进程的日志都会发送到队列，由单独的监听器进程写入文件，避免多进程直接写文件导致的阻塞和日志混乱。

3. 调整Debug模式与日志级别 #

如果是生产环境部署，强烈建议把DEBUG = False——DEBUG模式下Django会输出大量调试日志，不仅影响性能，还会加重日志缓冲的压力。同时可以根据环境调整日志级别，比如生产环境用INFO级别，减少日志输出量。

4. 检查Docker Compose的日志配置 #

确保你的docker-compose.yml里没有限制日志的缓冲大小，比如可以添加日志驱动配置：

services:
  web:
    build: .
    command: gunicorn --bind 0.0.0.0:8000 --workers 4 --access-logfile - --error-logfile - your_project.wsgi:application
    logging:
      driver: "json-file"
      options:
        max-size: "10m"
        max-file: "3"

这会限制单个日志文件大小，避免日志文件过大导致的阻塞问题。

内容的提问来源于stack exchange，提问作者shartshooter