开发环境部署
本文档描述如何使用 Docker Compose 在本地运行项目的开发环境。
内容涵盖环境配置、初始化步骤、访问入口以及常用命令。
前置条件
- Docker Engine 和 Docker Compose v2
- 推荐使用 Linux 主机；Windows/macOS 用户建议使用 Docker Desktop 以获得更好的体验
- 确保 3000 和 8000 端口未被占用
服务列表
开发用的 Docker Compose 文件（docker-compose.yml）包含以下服务：
| 服务 | 说明 |
|---|---|
db | PostgreSQL 18 数据库 |
redis | Redis 7 — Celery 消息代理、结果后端及 Django 缓存 |
backend | Django runserver（热重载） |
celery-worker | Celery worker（并发数=2，热重载） |
celery-beat | Celery beat 调度器（DatabaseScheduler，调度数据存储在 PostgreSQL 中） |
frontend | Vite 开发服务器 |
vitepress | 文档服务器（VitePress） |
快速开始
配置环境变量
在项目根目录下创建 .env 文件。开发环境至少包含以下内容：
text
POSTGRES_PASSWORD=password
DJANGO_DEBUG=true
SM2_PUBLIC_KEY=your_sm2_public_key
SM2_PRIVATE_KEY=your_sm2_private_key其余变量在开发环境下均有默认值。如需覆盖数据库名称、微信密钥、对象存储、构建镜像源等配置，请参阅环境变量。
TIP
.env 文件会由 Docker Compose 自动加载。请不要将 .env 提交到版本控制中（将其添加到 .gitignore）。
初始化系统
bash
# 构建并启动所有服务
docker compose up --build -d
# 执行数据库迁移
docker compose exec backend python manage.py migrate
# 创建管理员账户
docker compose exec backend python manage.py createsuperuser访问入口
| 服务 | URL |
|---|---|
| 前端 | http://localhost:3000 |
| 后端 API | http://localhost:8000/api/v1/ |
| 管理后台 | http://localhost:8000/django-admin/ |
开发环境与生产环境对比
| 配置项 | docker-compose.yml | docker-compose.prod.yml |
|---|---|---|
| 用途 | 开发 | 生产 |
| 前端服务 | Vite 开发服务器 | Nginx 静态托管 |
| 后端服务 | runserver | Gunicorn |
| Celery worker | 并发数=2 | 并发数=4 |
| Redis | 无持久化 | 启用 AOF 持久化 |
| 端口 | 3000、8000 | 80 或 443（启用 TLS 时） |
常用命令
bash
# 停止并移除容器（默认保留数据卷）
docker compose down
# 重启所有服务
docker compose restart
# 查看后端日志（实时跟踪）
docker compose logs -f backend
# 进入后端容器的 Shell
docker compose exec backend bash
# 重建并重启单个服务（以后端为例）
docker compose up --build -d backend
# 查看容器状态
docker compose ps重置环境（移除数据卷）
使用以下命令清除持久化数据（如数据库数据卷）并从头重新创建所有内容。
WARNING
此操作将删除 Docker 数据卷中的所有本地开发数据。
bash
docker compose down -v
docker compose up --build -d常见问题排查
如果前端无法连接后端，请确认后端容器运行正常，且 API 基础 URL 为
http://localhost:8000。如果
docker compose up因端口冲突失败，请修改docker-compose.yml中的端口映射，或停止占用端口的进程。当数据库迁移失败时，请先查看后端日志：
bashdocker compose logs -f backend