Windows环境Django4.2.3使用QueueHandler等日志组件报错求助

问题根源 #

1. QueueListener 误用为 Handler：你的配置错误地将 queue_listener 添加到了日志记录器的 handlers 列表中。QueueListener 本质是一个独立线程，用于消费 QueueHandler 推送的日志队列，并非标准日志 Handler。将其作为 Handler 注册会导致文件句柄被多个线程/上下文持有，在 Windows 下触发文件占用的权限错误。
2. Django 版本差异：Django 4.2.x 对日志系统的线程初始化逻辑做了调整，使得原本在 4.0.4 中未暴露的资源竞争问题显现。

修复步骤 #

1. 修正日志配置，移除错误的 Handler 引用 #

修改 settings.py 中的 LOGGING 配置，将所有日志记录器 handlers 列表里的 queue_listener 移除：

LOGGING = {
    'version': 1,
    'disable_existing_loggers': True,
    'formatters': {
        'console': {
            'format': console_fmt
        },
    },
    'handlers': {
        'console': {
            'class': 'logging.StreamHandler',
            'level': 'INFO',
            'formatter': 'console',
        },
        'queue_handler': {
            'class': 'logging.handlers.QueueHandler',
            'level': 'DEBUG',
            'queue': LOGS_QUE,
        },
        # 保留 queue_listener 的配置，但仅用于初始化，不添加到任何 logger 的 handlers
        'queue_listener': {
            '()': CustQueueListener,
            'cust_level': logging.DEBUG,
            'queue': LOGS_QUE,
            'handlers': [file_handler,],
        }
    },
    'loggers': {
        '': {
            'level': 'DEBUG',
            'handlers': ['console', 'queue_handler'],  # 移除 queue_listener
            "propagate": False,
        },
        'django': {
            "handlers": ["console", 'queue_handler'],
            "propagate": False,
        },
        'django.server': {
            'level': 'DEBUG',
            'handlers': ['console', 'queue_handler'],  # 移除 queue_listener
            "propagate": False,
        },
        'django.db.backends': {
            'level': 'DEBUG',
            'handlers': ['console', 'queue_handler'],  # 移除 queue_listener
            "propagate": False,
        }
    },
}

2. 单独启动 QueueListener 线程 #

在 Django 启动时初始化并启动 QueueListener，确保只有一个线程操作日志文件。推荐在你的主应用的 apps.py 中实现：

from django.apps import AppConfig
import logging
import atexit
from django.conf import settings

class MainAppConfig(AppConfig):
    default_auto_field = 'django.db.models.BigAutoField'
    name = '你的主应用名称'

    def ready(self):
        # 从配置中初始化 QueueListener
        listener_config = settings.LOGGING['handlers']['queue_listener']
        queue_listener = listener_config['()'](
            cust_level=listener_config['cust_level'],
            queue=listener_config['queue'],
            handlers=listener_config['handlers'],
            respect_handler_level=listener_config.get('respect_handler_level', False)
        )
        # 启动监听线程
        queue_listener.start()
        # 注册退出钩子，确保 Django 关闭时停止监听线程
        atexit.register(queue_listener.stop)

3. 验证配置 #

启动 Django 服务后，生成足够多的日志触发轮转，此时文件占用问题应该会消失，日志文件能正常重命名为 q_debug.log.1 等备份文件。

额外优化（可选） #

如果仍遇到 Windows 文件锁问题，可以改用 ConcurrentRotatingFileHandler（需安装 concurrent-log-handler 包），它专门针对多线程/多进程场景优化了文件轮转逻辑：

pip install concurrent-log-handler

然后替换 RotatingFileHandler：

from concurrent_log_handler import ConcurrentRotatingFileHandler

file_handler = ConcurrentRotatingFileHandler(
    f'{str(LOGS_DIR)}/q_debug.log',
    maxBytes=5000,
    backupCount=9,
    encoding='UTF8'
)

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