Docker单机部署指南：快速实现Django项目的容器化运行

2025年11月1日 互联网

一、引言：为何选择Docker部署Django？

在单机环境下开发Django项目时，开发者常面临环境配置复杂、依赖管理混乱等问题。Docker作为一种轻量级容器化技术，能够将应用及其依赖环境打包成独立的容器，实现”一次构建，到处运行”的便利性。通过Docker部署Django项目，可以：

  1. 隔离开发环境，避免依赖冲突
  2. 简化部署流程，提升交付效率
  3. 方便跨平台迁移，保持环境一致性
  4. 快速扩展服务，支持横向扩容

二、环境准备：安装Docker基础组件

1. 安装Docker引擎

在Linux系统（以Ubuntu为例）上安装Docker：

  1. # 更新软件包索引
  2. sudo apt-get update
  4. # 安装依赖包
  5. sudo apt-get install apt-transport-https ca-certificates curl gnupg-agent software-properties-common
  7. # 添加Docker官方GPG密钥
  8. curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo apt-key add -
  10. # 添加Docker APT仓库
  11. sudo add-apt-repository "deb [arch=amd64] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable"
  13. # 安装Docker CE
  14. sudo apt-get update
  15. sudo apt-get install docker-ce docker-ce-cli containerd.io
  17. # 验证安装
  18. sudo docker run hello-world

2. 配置Docker用户组

为避免每次使用docker命令都需要sudo权限，将当前用户加入docker组：

  1. sudo usermod -aG docker $USER
  2. newgrp docker  # 立即生效

三、Django项目准备：基础结构搭建

1. 创建Django项目

  1. mkdir django_docker_demo
  2. cd django_docker_demo
  3. python3 -m venv venv
  4. source venv/bin/activate
  5. pip install django
  6. django-admin startproject myproject
  7. cd myproject

2. 创建测试应用

  1. python manage.py startapp myapp

3. 配置基本设置

修改myproject/settings.py，确保允许所有主机访问：

  1. ALLOWED_HOSTS = ['*']

四、Dockerfile编写：构建Django镜像

在项目根目录创建Dockerfile文件：

  1. # 使用官方Python基础镜像
  2. FROM python:3.9-slim
  4. # 设置环境变量
  5. ENV PYTHONDONTWRITEBYTECODE 1
  6. ENV PYTHONUNBUFFERED 1
  8. # 创建工作目录
  9. WORKDIR /app
  11. # 安装系统依赖
  12. RUN apt-get update && apt-get install -y --no-install-recommends \
  13.     netcat \
  14.     && rm -rf /var/lib/apt/lists/*
  16. # 复制依赖文件并安装
  17. COPY requirements.txt .
  18. RUN pip install --no-cache-dir -r requirements.txt
  20. # 复制项目文件
  21. COPY . .
  23. # 暴露端口
  24. EXPOSE 8000
  26. # 定义启动命令
  27. CMD ["sh", "-c", "python manage.py migrate && python manage.py runserver 0.0.0.0:8000"]

关键点说明：

  1. 基础镜像选择：使用python:3.9-slim既保证功能完整又减少镜像体积
  2. 环境变量设置：
    • PYTHONDONTWRITEBYTECODE：禁止生成.pyc文件
    • PYTHONUNBUFFERED：使Python输出直接发送到终端而不缓冲
  3. 依赖管理：先复制requirements.txt单独安装依赖，利用Docker层缓存机制提高构建效率
  4. 工作目录：所有操作在/app目录下进行，保持容器内文件结构清晰

五、构建与运行Django容器

1. 创建requirements.txt

  1. pip freeze > requirements.txt

2. 构建Docker镜像

  1. docker build -t django-app .

3. 运行容器

  1. docker run -d -p 8000:8000 --name mydjango django-app

4. 验证运行

访问http://localhost:8000，应看到Django欢迎页面

六、进阶配置：优化Docker部署

1. 使用docker-compose管理多容器

创建docker-compose.yml文件：

  1. version: '3.8'
  3. services:
  4.   web:
  5.     build: .
  6.     command: sh -c "python manage.py migrate && python manage.py runserver 0.0.0.0:8000"
  7.     volumes:
  8.       - .:/app
  9.     ports:
  10.       - "8000:8000"
  11.     environment:
  12.       - DEBUG=1

启动服务：

  1. docker-compose up -d

2. 分离生产环境配置

创建.env.prod文件：

  1. DEBUG=0
  2. SECRET_KEY=your-secret-key
  3. ALLOWED_HOSTS=.example.com

修改docker-compose.yml：

  1. environment:
  2.   - DEBUG=${DEBUG}
  3.   - SECRET_KEY=${SECRET_KEY}
  4.   - ALLOWED_HOSTS=${ALLOWED_HOSTS}

3. 使用Nginx作为反向代理

添加nginx服务到docker-compose.yml：

  1. nginx:
  2.   image: nginx:alpine
  3.   ports:
  4.     - "80:80"
  5.   volumes:
  6.     - ./nginx/default.conf:/etc/nginx/conf.d/default.conf
  7.   depends_on:
  8.     - web

创建nginx/default.conf：

  1. server {
  2.     listen 80;
  3.     server_name localhost;
  5.     location / {
  6.         proxy_pass http://web:8000;
  7.         proxy_set_header Host $host;
  8.         proxy_set_header X-Real-IP $remote_addr;
  9.         proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
  10.     }
  12.     location /static/ {
  13.         alias /app/static/;
  14.     }
  15. }

七、常见问题解决方案

1. 静态文件加载失败

解决方案：

  1. 确保settings.py中配置了正确的STATIC_URL和STATIC_ROOT
  2. 运行python manage.py collectstatic收集静态文件
  3. 在Nginx配置中添加静态文件服务规则

2. 数据库连接问题

解决方案：

  1. 使用环境变量配置数据库连接：

    1. DATABASES = {
    2.  'default': {
    3.      'ENGINE': 'django.db.backends.postgresql',
    4.      'NAME': os.getenv('DB_NAME', 'postgres'),
    5.      'USER': os.getenv('DB_USER', 'postgres'),
    6.      'PASSWORD': os.getenv('DB_PASSWORD', 'postgres'),
    7.      'HOST': os.getenv('DB_HOST', 'db'),
    8.      'PORT': os.getenv('DB_PORT', '5432'),
    9.  }
    10. }

  2. 在docker-compose.yml中添加数据库服务：
    ```yaml
    db:
    image: postgres:13
    environment:

    • POSTGRES_DB=mydatabase
    • POSTGRES_USER=myuser
    • POSTGRES_PASSWORD=mypassword
      volumes:
    • postgres_data:/var/lib/postgresql/data

volumes:
postgres_data:

  2. ## 3. 容器启动顺序问题
  3. 解决方案：使用`depends_on`和健康检查确保服务就绪：
  4. ```yaml
  5. web:
  6.   depends_on:
  7.     db:
  8.       condition: service_healthy
  10. db:
  11.   healthcheck:
  12.     test: ["CMD-SHELL", "pg_isready -U postgres"]
  13.     interval: 5s
  14.     timeout: 5s
  15.     retries: 5

八、最佳实践建议

  1. 多阶段构建：减少最终镜像体积
    ```dockerfile

    构建阶段

    FROM python:3.9 as builder
    WORKDIR /app
    COPY requirements.txt .
    RUN pip install —user -r requirements.txt

运行阶段

FROM python:3.9-slim
WORKDIR /app
COPY —from=builder /root/.local /root/.local
COPY . .
ENV PATH=/root/.local/bin:$PATH
CMD [“gunicorn”, “—bind”, “0.0.0.0:8000”, “myproject.wsgi”]

  2. 2. **使用.dockerignore文件**：排除不必要的文件

.git
pycache/
.pyc
.pyo
*.pyd
.env
venv/

  2. 3. **日志管理**：集中收集容器日志
  3. ```yaml
  4. services:
  5.   web:
  6.     logging:
  7.       driver: "json-file"
  8.       options:
  9.         max-size: "10m"
  10.         max-file: "3"
  1. 安全加固：
    • 使用非root用户运行容器
    • 定期更新基础镜像
    • 限制容器资源使用

九、总结与展望

通过Docker部署Django项目，开发者可以获得：

  1. 一致的开发环境，减少”在我机器上能运行”的问题
  2. 简化的部署流程，提高交付效率
  3. 更好的资源隔离，提升系统稳定性
  4. 方便的扩展能力，支持快速扩容

未来发展方向：

  1. 结合Kubernetes实现更高级的编排管理
  2. 引入CI/CD流水线实现自动化部署
  3. 探索服务网格技术提升微服务管理能力
  4. 采用无服务器架构进一步简化运维

通过本文介绍的完整流程，开发者可以在单机环境下快速搭建起生产级的Django容器化部署方案，为后续的云原生迁移和规模化部署打下坚实基础。

最新文章