使用 Docker 本地开发 Cookiecutter Django 项目完整指南【免费下载链接】cookiecutter-djangoCookiecutter Django is a framework for jumpstarting production-ready Django projects quickly.项目地址: https://gitcode.com/GitHub_Trending/co/cookiecutter-django本文是 Cookiecutter Django 官方文档「Getting Up and Running Locally With Docker」的深度扩展版。它以docker-compose.local.yml为核心的本地开发工作流为主线覆盖从环境准备、镜像构建、依赖锁定、容器启动、管理命令执行到环境变量配置、Celery 任务调试、前端热更新与本地 HTTPS 的完整实战路径。读完本文你将掌握一套可直接复制执行的 Docker 本地开发命令集并理解其背后的 Compose 配置与源码实现。前置条件Prerequisites在开始之前请确保你的开发机上已安装以下工具Docker尚未安装请参考官方安装文档https://docs.docker.com/install/Docker Compose安装指南见官方文档https://docs.docker.com/compose/install/Pre-commit用于提交前自动检查安装说明见https://pre-commit.com/#installCookiecutter用于从模板生成项目见其官方 GitHub 仓库。如果你刚接触 Docker请注意一个容易踩坑的细节Docker 会在系统层面缓存镜像与资源。当你在本地用相同项目名反复生成项目时某些缓存内容例如 Postgres 数据卷可能会“残留”并重新出现引发类似 Postgres 认证失败的问题可参考本文档开头的docker-postgres-auth-failed说明。遇到这类问题优先清理同名 volume 后再重建。生成新项目Before Getting Started使用以下命令从模板生成一个全新的 Cookiecutter Django 项目cookiecutter gh:cookiecutter/cookiecutter-django在交互式向导中务必关注与 Docker 相关的选项use_docker选择y才会生成docker-compose.local.yml、docker-compose.production.yml、compose/目录与justfileuse_celery选择y会额外生成 redis、celeryworker、celerybeat、flower 等服务frontend_pipeline选择Gulp或Webpack会生成node服务用于静态资源构建与热更新mail_catcher选择Mailpit或Mailtrap Local会生成对应的邮件捕获服务。模板的生成后钩子hooks/post_gen_project.py会根据这些选项自动裁剪文件例如当use_docker为n时会执行remove_docker_files()删除全部 Docker 相关文件当use_celery为n时会执行remove_celery_files()与remove_celery_compose_dirs()清理 Celery 入口与 Compose 目录。因此下面所有命令都假定你在生成时选择了use_dockery。构建镜像与锁定依赖Build the Stack首次构建镜像在项目根目录执行首次构建会比较耗时请耐心等待docker compose -f docker-compose.local.yml build如果你想尽量贴近生产环境做验证可以把docker-compose.local.yml换成docker-compose.production.yml——本指南中的所有命令都遵循这一规则需要切换环境时直接替换 Compose 文件即可。本地镜像的构建细节可以参考 compose/local/django/Dockerfile它基于ghcr.io/astral-sh/uv:python3.14-bookworm-slim在构建阶段用uv sync --no-install-project先装入依赖层以获得缓存随后拷贝代码执行完整uv sync并挂载entrypoint与start脚本。注意 Dockerfile 中的注释提醒虚拟环境被刻意放置在/app/.venv因为$APP_HOME会被 Compose 的 bind mount 覆盖——这解释了为什么docker-compose.local.yml中需要- /app/.venv这个匿名卷来保护容器内的虚拟环境不被宿主目录冲掉。生成依赖锁文件构建产物有一个关键限制Docker 在构建期间无法向宿主系统写入文件因此uv.lock锁文件必须在容器内生成。执行docker compose -f docker-compose.local.yml run --rm django uv lock这对可复现构建至关重要锁文件确保容器内外安装的依赖版本完全一致。一般情况下当你通过uv add package_name添加包时锁文件会自动更新无需手动执行上述命令。完成锁定后建议再构建一次镜像以确保一切就绪docker compose -f docker-compose.local.yml build初始化 Git 与 pre-commit在第一次git commit之前请在宿主机全局安装 pre-commit然后初始化仓库并安装钩子git init pre-commit install跳过这一步会导致大量本可避免的 CI 与 Linter 报错模板在项目生成时默认带有.pre-commit-config.yaml钩子配置。启动本地开发栈Run the Stack启动 Django 与 PostgreSQL在项目根目录打开终端执行docker compose -f docker-compose.local.yml up首次启动会拉取/构建镜像、初始化数据库耗时较长之后再次启动会非常快。该命令会同时拉起 Django 与 PostgreSQL如果启用了 Celery还会拉起 redis 与 worker 等。不想每次手敲-f参数可以设置环境变量COMPOSE_FILEexport COMPOSE_FILEdocker-compose.local.yml docker compose up需要后台detached运行时docker compose up -d从 docker-compose.local.yml 的源码可以看到本地栈的服务拓扑django服务依赖postgres以及可选的redis/mailpit/mailtrap-local通过env_file读取./.envs/.local/.django与./.envs/.local/.postgres均标记为required: false文件缺失时不会报错并将宿主目录以.:/app:z挂载进容器实现代码热同步。启动文档服务上述命令不会启动 docs 服务。单独运行文档服务docker compose -f docker-compose.docs.yml up如果希望文档服务与本地主栈同时运行例如边改代码边看文档docker compose -f docker-compose.local.yml -f docker-compose.docs.yml updocs 服务定义在 docker-compose.docs.yml 中它把docs/、config/与项目目录挂载进容器并执行make livehtml见 compose/local/docs/start在9000端口提供带自动重载的 Sphinx 文档预览。访问地址启动成功后若你在生成项目时选择了Webpack 或 Gulp作为前端流水线请访问http://localhost:3000由node服务代理见下文“Webpack/Gulp”一节否则访问http://localhost:8000Django 服务直接暴露的端口。在容器内执行管理命令Execute Management Commands任何要在容器内运行的 shell 命令都通过docker compose ... run --rm完成例如docker compose -f docker-compose.local.yml run --rm django python manage.py migrate docker compose -f docker-compose.local.yml run --rm django python manage.py createsuperuser其中django是 Compose 文件中的目标服务名即 docker-compose.local.yml 中的django服务。注意docker exec无法用于运行 Django 管理命令——因为容器进程是由/start脚本启动的见 compose/local/django/start其内部会自动执行python manage.py migrate再启动服务器exec进容器直接跑manage.py会绕过 Compose 服务的环境与挂载上下文导致行为异常。值得一提的源码细节compose/local/django/start 中容器每次启动都会先自动执行python manage.py migrate再根据是否启用异步use_async选择uvicorn config.asgi:application --host 0.0.0.0 --reload --reload-include *.html或python manage.py runserver_plus 0.0.0.0:8000。可选指定 Docker 开发服务器 IP当DEBUGTrue时Django 默认只信任[localhost, 127.0.0.1, [::1]]这三个主机。使用 virtualenv 裸机开发时这通常够用但在 Docker 场景下你需要把宿主开发机的 IP 加入 config/settings/local.py 的INTERNAL_IPS用于 django-debug-toolbar或ALLOWED_HOSTS若该变量存在。该文件默认值为ALLOWED_HOSTS [localhost, 0.0.0.0, 127.0.0.1] INTERNAL_IPS [127.0.0.1, 10.0.2.2]同时当USE_DOCKERyes时local.py会通过socket.gethostbyname_ex动态把容器的网关 IP即*.1网段追加进INTERNAL_IPS并尝试解析node服务容器 IP 一并加入——这就是 debug-toolbar 在 Docker 下开箱即用的原因。配置环境变量Configuring the Environment整个栈的行为由位于envs/目录下的一组环境变量envs驱动。以docker-compose.local.yml中的postgres服务为例节选postgres: build: context: . dockerfile: ./compose/production/postgres/Dockerfile volumes: - local_postgres_data:/var/lib/postgresql/data - local_postgres_data_backups:/backups env_file: - ./.envs/.local/.postgres这里最关键的字段是env_file指向的./.envs/.local/.postgres。模板为你生成的 env 目录结构如下.envs ├── .local │ ├── .django │ └── .postgres └── .production ├── .django └── .postgres约定规则对于环境e中的任意服务sI只要该服务需要配置就存在一个.envs/.e/.sI服务配置文件“某个环境”的判断标准是项目根目录存在对应的someenv.ymlCompose 文件例如docker-compose.local.yml对应.local。以.envs/.local/.postgres为例# PostgreSQL # ------------------------------------------------------------------------------ POSTGRES_HOSTpostgres POSTGRES_DByour project slug POSTGRES_USERXgOWtQtJecsAbaIyslwGvFvPawftNaqO POSTGRES_PASSWORDjSljDz4whHuwO3aJIgVBrqEml5Ycbghorep4uVJ4xjDYQu0LfuTZdctj7y0YcCLu其中POSTGRES_DB、POSTGRES_USER、POSTGRES_PASSWORD三个变量均由模板在生成时自动产生POSTGRES_HOSTpostgres对应 Compose 网络中的服务名。django服务容器的 envs 也遵循同样的约定见.envs/.local/.django。这些随机凭据的生成逻辑位于 hooks/post_gen_project.pygenerate_random_string()使用random.SystemRandom()生成密码学安全的随机串POSTGRES_PASSWORD默认 64 位长、含大小写字母与数字DJANGO_SECRET_KEY同样为 64 位随机串DJANGO_ADMIN_URL则是 32 位随机串加/后缀。如果系统缺少安全随机源钩子会打印警告并提醒你手动设置。将生产 envs 合并为单个.env当你需要把.envs/.production/*合并到一个文件时运行python merge_production_dotenvs_in_dotenv.py该脚本merge_production_dotenvs_in_dotenv.py会把.envs/.production/.django与.envs/.production/.postgres按顺序拼接写入项目根目录的.env方便在非 Compose 环境下一次性注入全部生产变量。注意模板钩子会把.envs/*加入.gitignore除非你选择keep_local_envs_in_vcsy因此这些凭据不会入库。实用技巧Tips Tricks激活 Docker Machine如果你使用 Docker Machine 管理多台开发机可以用eval切换目标机器使后续所有命令都作用于指定机器例如dev1eval $(docker-machine env dev1)添加第三方 Python 包不要在容器里直接uv add package_name——容器是临时的该改动不会持久化新容器启动后库就丢了。正确做法是修改pyproject.toml运行时依赖加入[project].dependencies开发依赖加入[tool.uv].dev-dependencies写法形如package_namepackage_version。改完后需要重建镜像并重启容器docker compose -f docker-compose.local.yml build docker compose -f docker-compose.local.yml up调试Debuggingipdb 断点如果你在代码里写了import ipdb; ipdb.set_trace()直接up起来的服务无法进入交互调试。需要显式分配服务端口并以前台方式运行docker compose -f docker-compose.local.yml run --rm --service-ports django--service-ports会把服务声明的端口8000:8000映射到宿主机否则run默认不发布端口。django-debug-toolbar要让它正常工作需在 config/settings/local.py 的INTERNAL_IPS中指定你的 Docker Machine IP上文“指定开发服务器 IP”一节已说明本地 Docker 场景通常会自动追加网关 IP无需手动配置。查看容器日志与进程docker-compose.local.yml中每个服务都声明了container_name命名规则是project_slug_local_service可配合 Docker 命令排查docker logs project_slug_local_celeryworker docker top project_slug_local_celeryworker注意容器名是依据你的 project slug 动态生成的例如 slug 为my_awesome_project时worker 容器名就是my_awesome_project_local_celeryworker。邮件捕获Mail Catcher本地开发时与其真实投递邮件不如用本地 SMTP 捕获服务查看项目发出的邮件例如django-allauth发送的注册验证邮件。具体选型取决于生成项目时mail_catcher的选项。Mailpit生成时选择mail_catcherMailpit确保project_slug_local_mailpit容器已启动对应 docker-compose.local.yml 中的mailpit服务映射端口8025:8025浏览器打开http://127.0.0.1:8025。Mailtrap Local生成时选择mail_catcherMailtrap Local确保project_slug_local_mailtrap容器已启动对应mailtrap-local服务映射端口3550:3550数据挂载于 tmpfs浏览器打开http://127.0.0.1:3550。容器内的邮件投递目标同样在 config/settings/local.py 中配置Mailpit 场景下EMAIL_HOST默认为mailpit、端口1025Mailtrap Local 场景下EMAIL_HOST默认为mailtrap-local、端口3535——注意这些主机名就是 Compose 服务名容器网络内可直接解析。本地开发中的 Celery 任务不使用 Dockerbare metal时模板默认将 Celery 任务设为Eager 模式CELERY_TASK_ALWAYS_EAGER True见 config/settings/local.py 中use_docker n分支任务直接在请求线程内同步执行无需完整消息队列栈。而使用 Docker 时模板会默认启用任务调度器redis broker worker。如果希望在开发期间让任务在主线程同步执行便于测试或配合 django-debug-toolbar 做性能剖析在 config/settings/local.py 中设置CELERY_TASK_ALWAYS_EAGER TrueCelery Flower 监控面板Flower 是 Celery 分布式任务队列的“实时监控与 Web 管理”工具。使用前提生成项目时use_dockery生成项目时use_celeryy。默认情况下本地与生产环境的 Compose 配置docker-compose.local.yml与docker-compose.production.yml都包含flower服务本地映射端口5555:5555。出于安全考虑Flower 要求客户端提供认证凭据即对应环境的.envs/.local/.django与.envs/.production/.django中的CELERY_FLOWER_USER与CELERY_FLOWER_PASSWORD环境变量同样由 hooks/post_gen_project.py 在生成时随机填充。打开localhost:5555即可查看监控面板。使用 Webpack 或 Gulp 前端流水线如果你选择了 Gulp 或 Webpack项目自带Sass 编译与live reloading修改 Sass/JS 源文件后任务运行器会自动重建 CSS/JS 资源并在浏览器中热刷新无需手动刷新页面。栈中有一个专门的node服务负责构建静态资源、监听文件变化并把请求代理到 Django 应用同时在响应中注入 live reload 脚本。要让这一切正常运转必须通过 node 服务的端口访问应用默认是http://localhost:3000对应 docker-compose.local.yml 中node服务的3000:3000端口映射命令为npm run dev。用 Just 简化 Docker 命令项目根目录附带了 justfile把高频 Docker 命令封装成了简洁的just子命令。先按官方文档安装 Justhttps://just.systems/man/en/packages.html然后即可使用命令作用just build使用本地 Compose 文件构建 Python 镜像just up以 detached 模式启动容器并清理孤儿容器just down停止正在运行的容器just prune停止并删除容器及其卷可传服务名参数只清理单个容器just logs查看容器日志可传服务名参数查看指定服务just manage command在容器内运行 Django 管理命令如migrate、createsuperuser、shell从源码看justfile开头即export COMPOSE_FILE : docker-compose.local.yml所以这些命令无需-f参数just manage实际执行docker compose run --rm django python ./manage.py ...此外还提供了just pytest用于在容器内运行测试。警告目前 Just 不能可靠地处理/转发信号给子进程。按 CTRLC或发送 SIGTERM/SIGINT/SIGHUP时可能只会中断 Just 本身而不会中断其子进程。详见 Just 的 GitHub issue #2473。在使用前请知悉此限制。可选本地开发启用 HTTPS当你需要接入 Facebook 等 OAuth 提供商的社交登录时这些平台通常要求回调 URL 必须是 HTTPS。下面是两种本地 HTTPS 方案。方案一Nginx参考外部教程“how to add HTTPS using Nginx”为本地 Docker 环境添加 HTTPS该教程同时介绍了如何在需要时从media目录提供用户上传文件。方案二Webpack mkcert如果你使用 Webpack首先安装 mkcert——一个“极简设计”的本地 TLS 证书生成工具无需掌握繁琐的证书知识支持任意主机名/IP包括 localhost兼容 macOS、Linux、Windows以及 Firefox、Chrome、Java甚至可通过少量手动步骤在移动设备上使用。配置步骤生成证书并放置将证书放入项目根目录的certs文件夹。假设本地主机名注册为my-dev-env.local则证书文件应为my-dev-env.local.crt与my-dev-env.local.key。在docker-compose.local.yml中添加nginx-proxy反向代理服务作为独立 service避免干扰生产环境专属的traefik配置nginx-proxy: image: jwilder/nginx-proxy:alpine container_name: nginx-proxy ports: - 80:80 - 443:443 volumes: - /var/run/docker.sock:/tmp/docker.sock:ro - ./certs:/etc/nginx/certs restart: always depends_on: - node environment: - VIRTUAL_HOSTmy-dev-env.local - VIRTUAL_PORT3000在 config/settings/local.py 中放行新域名ALLOWED_HOSTS [localhost, 0.0.0.0, 127.0.0.1, my-dev-env.local]修改webpack/dev.config.js的devServer配置注意:0写法client: { webSocketURL: auto://0.0.0.0:0/ws, // note the :0 after 0.0.0.0 },重建 Docker 应用docker compose -f docker-compose.local.yml up -d --build在浏览器地址栏访问https://my-dev-env.local。小结本文以 Cookiecutter Django 的docker-compose.local.yml本地开发栈为主线串起了从cookiecutter生成项目、docker compose build构建镜像、容器内uv lock锁定依赖、docker compose up启动服务到管理命令、envs 约定、Celery/Flower、Webpack 热更新、HTTPS 配置的完整链路。结合 docker-compose.local.yml、compose/local/django/start、config/settings/local.py、hooks/post_gen_project.py 与 justfile 等源码你可以随时深入验证每一个命令与配置的真实行为。生产环境部署的更多细节可继续阅读仓库中docs/3-deployment/下的部署文档。【免费下载链接】cookiecutter-djangoCookiecutter Django is a framework for jumpstarting production-ready Django projects quickly.项目地址: https://gitcode.com/GitHub_Trending/co/cookiecutter-django创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考