Docker化Django构建：如何仅执行一次createsuperuser命令

所有方案的核心逻辑是以持久化存储的数据库内容作为判断依据，而非容器本地文件（容器重建会丢失本地标记，这也是普通首次启动方案不生效的根本原因），实现真正的幂等执行，不管容器重启、重建多少次都不会重复执行创建逻辑。

方案1：自定义幂等的初始化命令（推荐，可复用性强） #

1. 在任意一个你的Django业务app下，新建目录结构management/commands/，在里面创建init_superuser.py文件，代码如下：

from django.core.management.base import BaseCommand
from django.contrib.auth import get_user_model
import os


class Command(BaseCommand):
    help = "幂等创建超级用户，已存在则直接跳过"

    def handle(self, *args, **kwargs):
        User = get_user_model()
        username = os.getenv("DJANGO_SUPERUSER_USERNAME")
        email = os.getenv("DJANGO_SUPERUSER_EMAIL", "")
        password = os.getenv("DJANGO_SUPERUSER_PASSWORD")

        # 未配置账号密码则直接跳过
        if not (username and password):
            self.stdout.write(self.style.WARNING("未配置超级用户环境变量，跳过初始化"))
            return

        # 检测到对应超级用户已存在则跳过
        if User.objects.filter(username=username, is_superuser=True).exists():
            self.stdout.write(self.style.SUCCESS(f"超级用户{username}已存在，跳过创建"))
            return

        User.objects.create_superuser(username=username, email=email, password=password)
        self.stdout.write(self.style.SUCCESS(f"超级用户{username}创建成功"))

2. 在你docker-compose调用的启动脚本中，按顺序执行命令即可：

#!/bin/bash
# 等待数据库就绪（数据库与app同属compose集群时建议加这步）
while ! python manage.py check --database default; do
  echo "等待数据库连接..."
  sleep 1
done

# 执行数据库迁移
python manage.py migrate --noinput

# 执行幂等的超级用户初始化
python manage.py init_superuser

# 启动Django服务
exec gunicorn 你的项目名.wsgi:application --bind 0.0.0.0:8000

方案2：启动脚本内嵌判断逻辑（无额外文件，轻量） #

不想新增自定义命令文件的话，直接把判断逻辑写在启动脚本里，通过Django shell执行即可：

#!/bin/bash
# 等待数据库就绪
while ! python manage.py check --database default; do
  echo "等待数据库连接..."
  sleep 1
done

# 执行迁移
python manage.py migrate --noinput

# 幂等创建超级用户
python manage.py shell -c "
from django.contrib.auth import get_user_model
import os
User = get_user_model()
username = os.getenv('DJANGO_SUPERUSER_USERNAME')
pwd = os.getenv('DJANGO_SUPERUSER_PASSWORD')
email = os.getenv('DJANGO_SUPERUSER_EMAIL', '')
if username and pwd and not User.objects.filter(username=username, is_superuser=True).exists():
    User.objects.create_superuser(username, email, pwd)
    print('超级用户创建完成')
else:
    print('超级用户已存在，跳过创建')
"

# 启动服务
exec gunicorn 你的项目名.wsgi:application --bind 0.0.0.0:8000

避坑说明 #

• 不要把createsuperuser写在Dockerfile的构建步骤里：构建阶段数据库服务未启动、网络不通，必然执行失败。
• 不要用容器内本地标记文件（比如/initialized之类的flag）判断是否首次启动：CI/CD重建容器时容器文件系统会重置，标记会丢失，每次启动都会触发创建逻辑。
• 不要直接裸跑官方的createsuperuser命令：Django 4+版本下该命令不做幂等判断，用户存在时直接抛出UNIQUE constraint failed异常，会中断容器启动流程。
• 超级用户的账号、密码全部通过环境变量注入，不要硬编码在代码/脚本里，只要你的数据库volume不删除，无论容器重建多少次、配置怎么更新，初始化逻辑只会在第一次部署（数据库为空）时执行一次。

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