docker-compose部署Django时runserver命令未执行如何解决

• 监听地址配置错误：runserver绑定127.0.0.1属于容器本地环回地址，仅容器内部可访问，外部端口映射无法触达；同时部分场景下绑定异常会导致进程静默退出，无日志输出。
• Python输出缓冲未关闭：默认Python会对标准输出/错误做缓冲，容器非交互运行时缓冲不会主动刷新，导致启动日志被吞，看起来像命令未执行。
• 特权端口权限不足：80属于1024以下的系统保留端口，普通用户运行进程时无绑定权限，命令会直接静默失败。
• 容器前台进程缺失：如果run.sh执行完启动命令后没有把Django进程放在前台维持运行，脚本执行完成后容器会直接退出，服务自然无法启动。

1. 修改run.sh中的启动命令，替换为以下内容：

exec python3 -u manage.py runserver 0.0.0.0:8000

参数说明：

• exec：用Django进程替换当前shell进程，保证Django作为容器1号前台进程运行，避免脚本执行完容器退出
• -u：关闭Python输出缓冲，所有日志直接打印到控制台
• 0.0.0.0：监听容器所有网卡，支持外部端口映射访问
• 8000：使用非特权端口，避免普通用户权限不足问题

2. 调整docker-compose.yml的端口映射配置，对应修改为：

ports:
  - "80:8000"

将宿主机80端口流量转发到容器内的8000端口，不需要容器内部绑定80端口。

• Django自带的runserver仅适用于本地开发调试，性能、安全性都不符合生产要求，生产环境请替换为Gunicorn、uWSGI等WSGI服务器部署。
• 容器内运行的服务必须以前台方式启动，不要在启动命令后加&放到后台，否则容器会因为前台无存活进程自动退出。
• 确需在容器内使用80等特权端口的，可以在Dockerfile中切换为root用户运行，或者给Python二进制添加端口绑定权限：RUN setcap 'cap_net_bind_service=+ep' /usr/bin/python3。
• 无输出排查时可以先执行docker exec -it 容器ID /bin/bash进入容器，手动执行启动命令查看报错，快速定位问题。

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