10分钟上线生产级Docker+Django应用：从0到部署的工业化实践
项目地址: https://gitcode.com/gh_mirrors/do/docker-django-example 读完你将获得
- 用Docker Compose搭建包含PostgreSQL+Redis+Celery的完整Django生态
- 掌握.env环境配置与run脚本自动化运维的核心技巧
- 解决"开发-测试-生产"环境一致性难题的最佳实践
- 前端资源(esbuild+Tailwind)与后端服务的无缝集成方案
- 一键生成安全密钥、数据库迁移、代码质量检查的自动化流程
为什么Dockerized Django如此重要？
传统Django开发中，你是否遇到过这些痛点：
- "在我电脑上能运行"的环境依赖地狱
- 生产服务器配置与开发环境不一致导致的诡异bug
- 手动执行数据库迁移时的操作失误
- 前端资源构建与后端服务部署的割裂
本教程基于GitHub加速计划的docker-django-example项目，通过10个步骤带你构建生产就绪的Django应用容器化方案。该方案已在数十个企业级项目中验证，包含Docker最佳实践与Django生态系统的深度整合。
技术架构全景图
环境准备与项目初始化
1. 基础环境要求
- Docker Engine 20.10+ 与 Docker Compose v2.20.2+
- Git 版本控制工具
- 网络连接(拉取镜像与依赖)
2. 项目克隆与目录结构解析
git clone https://gitcode.com/gh_mirrors/do/docker-django-example hellodjango
cd hellodjango
核心目录结构说明：
| 路径 | 作用 | 关键文件 |
|---|---|---|
| /src | Django应用根目录 | manage.py, settings.py |
| /src/config | 项目配置中心 | urls.py, wsgi.py, celery.py |
| /assets | 前端资源工作区 | package.json, tailwind.config.js |
| /public | 静态文件输出目录 | CSS/JS/图片资源 |
| /bin | 自动化脚本 | rename-project, docker-entrypoint |
环境配置与密钥管理
3. 环境变量配置(.env)
cp .env.example .env
核心配置项说明：
# 安全配置
SECRET_KEY=your-secure-key-here # 执行./run secret生成
DEBUG=false # 生产环境必须为false
# 数据库配置
POSTGRES_USER=hello
POSTGRES_PASSWORD=secure-password
POSTGRES_DB=hello
# 网络配置
DOCKER_WEB_PORT_FORWARD=8000 # 端口映射
ALLOWED_HOSTS=example.com,www.example.com
# 资源限制
DOCKER_POSTGRES_MEMORY=512m # 防止容器过度消耗资源
DOCKER_WEB_MEMORY=1g
⚠️ 安全警告：.env文件包含敏感信息，已在.gitignore中配置，永远不要提交到版本库
4. 自动化运维脚本(run)详解
run脚本是项目的"多功能工具"，执行./run查看所有可用命令：
1 cmd
2 manage
3 lint:dockerfile
4 lint:shell
5 lint
6 format:shell
7 format
8 quality
9 secret
10 shell
11 psql
12 redis-cli
13 deps:install
14 uv
15 uv:outdated
16 yarn
17 yarn:outdated
18 yarn:build:js
19 yarn:build:css
20 clean
21 ci:install-deps
22 ci:test
23 help
常用命令速查：
| 命令 | 作用 |
|---|---|
./run secret | 生成Django安全密钥 |
./run manage migrate | 执行数据库迁移 |
./run quality | 全面代码质量检查 |
./run psql | 连接PostgreSQL数据库 |
./run deps:install | 安装所有依赖 |
容器化构建与服务启动
5. Docker多阶段构建解析(Dockerfile)
项目采用三阶段构建策略，确保生产镜像最小化：
关键优化点：
- 使用uv代替pip，依赖安装速度提升10倍
- 多阶段构建剔除构建工具，生产镜像体积减少70%
- 非root用户运行，遵循最小权限原则
- 内置健康检查与优雅关闭机制
6. 服务编排与启动(compose.yaml)
services:
postgres:
image: "postgres:17.5-bookworm"
environment:
POSTGRES_USER: "${POSTGRES_USER}"
POSTGRES_PASSWORD: "${POSTGRES_PASSWORD}"
volumes:
- "postgres:/var/lib/postgresql/data"
redis:
image: "redis:8.0.2-bookworm"
volumes:
- "redis:/data"
web:
<<: *default-app
ports:
- "${DOCKER_WEB_PORT_FORWARD:-127.0.0.1:8000}:${PORT:-8000}"
depends_on:
postgres:
condition: "service_started"
required: false # 支持无数据库启动开发
worker:
<<: *default-app
command: celery -A config worker -l "${CELERY_LOG_LEVEL:-info}"
首次启动命令：
# 构建并启动所有服务
docker compose up --build
# 新终端执行数据库迁移
./run manage migrate
# 创建超级用户
./run manage createsuperuser
服务启动后访问 http://localhost:8000 查看应用，http://localhost:8000/admin 进入管理后台。
开发工作流与质量保障
7. 代码质量自动化
# 执行全面代码质量检查
./run quality
# 单独执行代码格式化
./run format
# 单独执行代码 linting
./run lint
质量检查包含：
- Python代码：ruff(替代flake8+black+isort)
- Shell脚本：shellcheck
- Dockerfile：hadolint
- 前端资源：esbuild编译检查
8. 测试策略与CI集成
# 运行测试套件
./run manage test
# 查看测试覆盖率
./run manage test --coverage
CI/CD流程配置(.github/workflows/ci.yml)：
- 代码检出与环境准备
- 构建Docker镜像
- 启动依赖服务(PostgreSQL/Redis)
- 执行数据库迁移
- 运行代码质量检查与测试
- 生成测试报告
项目定制与生产部署
9. 项目重命名自动化
使用内置脚本快速定制项目名称：
bin/rename-project myapp MyApp
该脚本自动完成：
- 项目名称的全局替换
- Python包结构调整
- Docker相关配置更新
- 初始化新的Git仓库
10. 生产环境部署清单
基础部署步骤：
-
环境准备
# 生产服务器安装Docker与Docker Compose curl -fsSL https://get.docker.com -o get-docker.sh sudo sh get-docker.sh sudo usermod -aG docker $USER -
安全配置
# .env生产环境关键配置 DEBUG=false ALLOWED_HOSTS=yourdomain.com,www.yourdomain.com DOCKER_WEB_PORT_FORWARD=127.0.0.1:8000 # 仅本地监听 -
Nginx反向代理
server { listen 80; server_name yourdomain.com www.yourdomain.com; location /static/ { alias /path/to/your/app/public_collected/; expires 30d; } location / { proxy_pass http://localhost:8000; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; } } -
启动与监控
# 后台启动服务 docker compose up -d # 查看日志 docker compose logs -f # 设置自动启动 sudo systemctl enable docker
生产环境优化项：
| 优化点 | 配置方法 | 收益 |
|---|---|---|
| 数据库备份 | ./run psql_dump | 防止数据丢失 |
| SSL证书 | Let's Encrypt + Certbot | 加密传输 |
| 资源限制 | compose.yaml中设置cpus/memory | 防止资源耗尽 |
| 日志轮转 | Docker日志驱动配置 | 控制磁盘占用 |
| 健康检查 | compose.yaml healthcheck配置 | 自动恢复故障服务 |
高级特性与最佳实践
Django配置优化
# src/config/settings.py 关键配置
# 生产环境安全设置
SECURE_SSL_REDIRECT = not DEBUG
SESSION_COOKIE_SECURE = not DEBUG
CSRF_COOKIE_SECURE = not DEBUG
# 静态文件优化
STATICFILES_STORAGE = "whitenoise.storage.CompressedManifestStaticFilesStorage"
# 缓存配置
CACHES = {
"default": {
"BACKEND": "django.core.cache.backends.redis.RedisCache",
"LOCATION": os.getenv("REDIS_URL", "redis://redis:6379/0"),
}
}
# Celery异步任务
CELERY_BROKER_URL = os.getenv("REDIS_URL", "redis://redis:6379/0")
CELERY_RESULT_BACKEND = CELERY_BROKER_URL
前端资源工作流
# 开发模式(自动监听变化)
docker compose --profile assets up
# 生产构建
./run yarn build
前端技术栈整合：
- TailwindCSS：原子化CSS框架
- esbuild：极速JS打包工具
- Heroicons：SVG图标库
- 自定义主题配置：assets/tailwind.config.js
问题排查与性能调优
常见问题解决
| 问题 | 解决方案 |
|---|---|
| 端口冲突 | 修改.env中的DOCKER_WEB_PORT_FORWARD |
| 权限错误 | 调整.env中的UID/GID与宿主匹配 |
| 数据库连接失败 | 检查POSTGRES_*环境变量配置 |
| 静态文件404 | 执行./run manage collectstatic |
| Celery任务不执行 | 确认Redis服务正常运行 |
性能优化方向
-
数据库优化
- 添加适当索引
- 配置连接池
- 定期VACUUM分析
-
缓存策略
- 实现模板片段缓存
- 添加Redis缓存层
- 配置浏览器缓存策略
-
应用服务器调优
# src/config/gunicorn.py workers = 4 # 建议设置为 (2 x CPU核心数 + 1) threads = 2 timeout = 120
总结与扩展学习
通过本教程，你已掌握使用Docker容器化Django应用的完整流程，包括开发环境搭建、代码质量保障、测试策略与生产部署。这个方案解决了传统开发模式中的环境一致性、部署复杂性和运维效率问题。
进阶学习路径：
-
Docker深度实践
- 多阶段构建优化
- 镜像安全扫描
- Docker Swarm/Kubernetes编排
-
Django性能优化
- 数据库查询优化
- 异步视图与ASGI
- GraphQL API实现
-
监控与可观测性
- Prometheus指标收集
- Grafana可视化
- ELK日志分析
项目源码持续更新，可通过git pull获取最新最佳实践。遇到问题可提交issue或参与社区讨论。
附录：常用命令速查表
| 功能 | 命令 |
|---|---|
| 启动所有服务 | docker compose up |
| 构建镜像 | docker compose build |
| 数据库迁移 | ./run manage migrate |
| 创建超级用户 | ./run manage createsuperuser |
| 执行Celery任务 | ./run shell "from app.tasks import mytask; mytask.delay()" |
| 查看日志 | docker compose logs -f |
| 停止服务 | docker compose down |
| 清理静态文件 | ./run clean |
| 依赖更新 | ./run deps:install |
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
