模多多教育版

Appearance

01_Docker 快速启动手册 ​

适用于 Windows (Docker Desktop)、macOS、Linux

1. 安装前置 ​

  1. 安装 Docker Desktop (含 Compose V2)
  2. Windows ➜ 启用 WSL 2 或 Hyper-V，确保 CPU 虚拟化已开启
  3. 终端验证
bash
docker version
docker compose version

2. 准备环境变量 .env ​

项目根目录创建 .env：

bash
DATABASE_URL=postgresql+asyncpg://moduoduo:moduoduo@postgres:5432/moduoduo
SECRET_KEY=ReplaceThisWithRandom
ACCESS_TOKEN_EXPIRE_MINUTES=1440
ALLOW_ORIGINS=*
# 可选：启用 Redis 缓存（读多写少：课程详情/手册快照/元数据）
REDIS_URL=redis://redis:6379/0

3. 首次启动 / 构建 ​

bash
docker compose up --build -d   # -d 后台运行

容器一览：

服务端口描述
postgres55432PostgreSQL 17
redis6379Redis 7
backend8000FastAPI 应用
pgadmin5050pgAdmin 4 Web UI

默认账号 & 连接信息 ​

组件用途Host/URL端口用户名密码其他
PostgreSQL应用 / 本地客户端连接localhost55432moduoduomoduoduo默认数据库 moduoduo
PostgreSQL服务间连接（容器内部）<容器 IP>5432moduoduomoduoduo先执行 docker inspect -f '{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}' moduoduo-edu-mvp-postgres-1 (云服务器里是moduoduo-edu-backend-postgres-1) 获取 IP，再作为 Host 填写
pgAdmin 4Web 管理界面登录http://localhost:505080admin@example.commoduoduo首次启动自动创建账号

4. 初始化数据库 ​

bash
docker compose exec backend alembic upgrade head

5. 开发热更新 ​

bash
# 停掉后台 backend
docker compose stop backend
# 前台热加载
docker compose run --service-ports backend \
  uvicorn app.main:app --reload --host 0.0.0.0

6. 常见命令 ​

场景命令
查看日志docker compose logs -f backend
重新构建镜像docker compose build backend
重启/启动已存在容器（Docker Desktop 重启后）docker compose up -d
停止并删除docker compose down -v
清理悬挂镜像/层docker builder prune -af

7. 常见错误速查 ​

报错解决方案
.env not found在根目录创建 .env 文件
version is obsolete删除 docker-compose.yml 顶部 version: 字段，或忽略
No matching distribution更新 requirements.txt 中问题包版本
SettingsError ALLOW_ORIGINS确保 .env 中 ALLOW_ORIGINS 正确，如 * 或多域名逗号分隔
open //./pipe/dockerDesktopLinuxEngine: The system cannot find the file specifiedWindows 上的 Docker 引擎未启动。解决：启动 Docker Desktop 并等待状态为 Running；docker version 应显示 Server 信息；在 Docker Desktop 设置中启用 WSL2 引擎（Use the WSL 2 based engine），必要时开启 Windows 功能 WSL/Virtual Machine Platform 并重启。

完成后访问：