使用Docker运行Django应用时出现runserver参数未识别错误

核心错误原因 #

报错 manage.py runserver: error: unrecognized arguments: python manage.py runserver 是因为Dockerfile的ENTRYPOINT与docker-compose.yml的command命令冲突：
Dockerfile中已经通过ENTRYPOINT ["python", "manage.py", "runserver", "0.0.0.0:8000"]指定了完整启动命令，而docker-compose.yml的command字段又追加了python manage.py runserver，最终执行的命令变成：

python manage.py runserver 0.0.0.0:8000 python manage.py runserver

runserver 将后面的字符串识别为无效参数，导致报错。

另外，Dockerfile中多个CMD指令只有最后一个会生效，所以makemigrations和migrate命令从未执行，这也是潜在问题。

修复步骤 #

方案一：使用启动脚本统一处理迁移与服务启动 #

1. 创建启动脚本 entrypoint.sh，添加数据库就绪检测（解决depends_on不等待数据库就绪的问题）：

#!/bin/sh
# 等待PostgreSQL数据库就绪
while ! pg_isready -h db -U postgres; do
  echo "等待数据库启动..."
  sleep 2
done

# 执行迁移命令
python manage.py makemigrations
python manage.py migrate

# 启动Django服务
exec python manage.py runserver 0.0.0.0:8000

给脚本添加执行权限：

chmod +x entrypoint.sh

2. 修改Dockerfile，安装数据库检测工具并配置脚本为入口：

# syntax=docker/dockerfile:1
FROM python:3
ENV PYTHONDONTWRITEBYTECODE=1
ENV PYTHONUNBUFFERED=1
WORKDIR /code

# 安装PostgreSQL客户端（用于检测数据库状态）
RUN apt-get update && apt-get install -y postgresql-client && rm -rf /var/lib/apt/lists/*

# 安装Python依赖
COPY requirements.txt /code/
RUN pip3 install -r requirements.txt

# 复制项目文件与启动脚本
COPY . /code/
COPY entrypoint.sh /code/

# 设置启动脚本为入口
ENTRYPOINT ["/code/entrypoint.sh"]

3. 修改docker-compose.yml，移除冲突的command字段：

version: "3.9"

services:
  db:
    image: postgres:alpine
    volumes:
      - ./data/db:/var/lib/postgresql/data
    environment:
      - POSTGRES_DB=gitlabdumptables
      - POSTGRES_USER=postgres
      - POSTGRES_PASSWORD=postgres
  web:
    build: .
    volumes:
      - .:/code
    ports:
      - "8000:8000"
    environment:
      - POSTGRES_NAME=gitlabdumptables
      - POSTGRES_USER=postgres
      - POSTGRES_PASSWORD=postgres
    depends_on:
      - db

方案二：直接在Dockerfile中合并命令（无需脚本） #

如果不需要数据库就绪检测，可以简化配置：
修改Dockerfile，用sh -c合并迁移与启动命令，移除ENTRYPOINT：

# syntax=docker/dockerfile:1
FROM python:3
ENV PYTHONDONTWRITEBYTECODE=1
ENV PYTHONUNBUFFERED=1
WORKDIR /code

COPY requirements.txt /code/
RUN pip3 install -r requirements.txt
COPY . /code/

# 合并执行迁移与启动命令
CMD ["sh", "-c", "python manage.py makemigrations && python manage.py migrate && python manage.py runserver 0.0.0.0:8000"]

同时删除docker-compose.yml中web服务的command字段。

验证修复 #

执行以下命令启动服务：

docker-compose up --build

服务启动后，访问http://localhost:8000即可打开应用。

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