Docker环境下Django上传文件至S3超时致Gunicorn进程退出求助

将应用从Heroku迁移至Azure App Services的Docker环境后，所有上传文件至S3的操作均超时，导致Gunicorn worker退出。启用Boto3调试日志后，上传操作卡在任务提交阶段，最终抛出SystemExit: 1错误。

环境依赖 #

Django==3.2.25
boto3==1.35.9
botocore==1.35.9
s3transfer==0.10.2
django-storages==1.14.4

配置信息 #

DEFAULT_FILE_STORAGE = 'project.utils.storage.HashedFilenameMediaS3Boto3Storage'

注：自定义存储类为8年前实现的哈希文件名存储类

错误栈 #

Traceback (most recent call last):
  File "/usr/local/lib/python3.12/site-packages/s3transfer/tasks.py", line 269, in _main
    self._submit(transfer_future=transfer_future, **kwargs)
  File "/usr/local/lib/python3.12/site-packages/s3transfer/upload.py", line 597, in _submit
    self._submit_upload_request(
  File "/usr/local/lib/python3.12/site-packages/s3transfer/upload.py", line 632, in _submit_upload_request
    self._transfer_coordinator.submit(
  File "/usr/local/lib/python3.12/site-packages/s3transfer/futures.py", line 323, in submit
    future = executor.submit(task, tag=tag)
             ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/usr/local/lib/python3.12/site-packages/s3transfer/futures.py", line 474, in submit
    future = ExecutorFuture(self._executor.submit(task))
                            ^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/usr/local/lib/python3.12/concurrent/futures/thread.py", line 165, in submit
    with self._shutdown_lock, _global_shutdown_lock:
  File "/usr/local/lib/python3.12/site-packages/gunicorn/workers/base.py", line 204, in handle_abort
    sys.exit(1)
SystemExit: 1

1. Azure网络出站限制导致S3连接超时 #

• 原因：Azure App Services默认网络配置可能存在出站流量限制，或未正确配置VNet/防火墙规则，无法建立稳定的S3连接，上传任务超时触发Gunicorn终止。
• 解决：
  • 检查Azure App Services的出站规则，确保允许访问目标S3区域的IP段或域名。
  • 启用Azure App Services的VNet集成，通过虚拟网络路由流量到S3，规避公共网络限制。
  • 在容器内执行curl https://<你的S3桶名>.s3.<区域>.amazonaws.com，验证网络连通性。

2. Gunicorn线程模型与s3transfer线程池冲突 #

• 原因：s3transfer默认用线程池处理上传，而Gunicorn的sync worker模式可能存在线程安全问题，或worker超时配置过短，导致线程提交任务时触发锁冲突，触发handle_abort退出。
• 解决：
  • 修改Gunicorn启动参数，延长worker超时时间：添加--timeout 300（根据文件大小调整）。
  • 切换Gunicorn worker类型为gthread或gevent：启动命令添加--worker-class gthread --threads 4。
  • 禁用s3transfer线程池，改用同步上传：在Django配置中添加AWS_S3_TRANSFER_CONFIG = {'use_threads': False}。

3. 旧自定义存储类与新依赖不兼容 #

• 原因：8年前的自定义存储类可能依赖旧版boto3/django-storages的API，当前新版本依赖的接口已变更，导致上传逻辑阻塞。
• 解决：
  • 检查自定义存储类代码，对比当前boto3文档确认API兼容性，重点查看上传逻辑的底层调用。
  • 临时替换为官方存储类storages.backends.s3boto3.S3Boto3Storage，测试是否能正常上传，排除自定义类问题。
  • 逐步更新自定义类代码，适配新版本依赖的参数传递、回调逻辑。

4. Python版本与依赖兼容性问题 #

• 原因：当前使用Python 3.12，但Django 3.2.25官方仅支持到Python 3.10，可能存在解释器层面的线程锁或兼容性问题，导致线程池提交任务异常。
• 解决：
  • 将Python版本降级到3.10，重新构建Docker镜像测试。
  • 升级Django到支持Python 3.12的版本（如Django 4.2+），注意处理版本升级带来的其他兼容问题。

5. S3权限或配置错误 #

• 原因：迁移后未正确配置S3访问密钥、区域、桶权限，导致请求被拒绝或挂起，触发超时。
• 解决：
  • 验证容器内的AWS_ACCESS_KEY_ID、AWS_SECRET_ACCESS_KEY、AWS_S3_REGION_NAME环境变量是否正确。
  • 在容器内编写简单Python脚本，直接调用boto3的upload_file方法测试上传，排除Django存储类的干扰。
  • 检查S3桶的CORS策略和ACL，确保允许Azure环境的IP或IAM用户执行上传操作。

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