开发调试常用命令速查

以下命令均假设在 项目根目录 执行 (E:\Desktop\模多多教育版\moduoduo-edu-mvp)，并已安装 Docker Desktop / Docker Compose。

1. Docker 镜像 & 容器

场景	命令	说明
停止并删除所有容器 + 匿名卷	`docker compose down -v`	清掉数据库卷、Redis 数据等，从零开始。
仅停止 backend	`docker compose stop backend`	Postgres/Redis 保留运行。
删除 backend 容器	`docker compose rm -f backend`	删除已停止的 backend 容器。
删除 backend 镜像	`docker rmi $(docker images -q moduoduo-edu-mvp-backend)`	重新 build 前手动清理旧镜像。
删除 dangling 镜像	`docker image prune -f`	清理无 tag 镜像，释放磁盘。
删除全部卷	`docker volume prune -f`	删除全部孤立卷，清理数据。

操作	命令
再次打开 Docker Desktop 后快速启动所有服务	`docker compose up -d`
完整重建 backend 镜像（无缓存）	`docker compose build --no-cache backend`
重建并启动 backend	`docker compose up -d --build backend`
一次性重建所有服务	`docker compose up -d --build`

-d 代表后台运行（detached）。如需查看日志，可用 docker compose logs -f backend。

场景	命令
运行最新迁移	`docker compose exec backend alembic upgrade head`
生成新迁移 (例)	`docker compose exec backend alembic revision --autogenerate -m "add course table"`

场景	命令
在容器内运行 pytest	`docker compose exec -e PYTHONPATH=/app backend pytest -q`
仅运行某个文件	`docker compose exec -e PYTHONPATH=/app backend pytest tests/test_auth.py`
带 coverage	`docker compose exec -e PYTHONPATH=/app backend pytest --cov=app`

如果在 docker-compose.yml 中为 backend 设置 environment: PYTHONPATH=/app，则可省去 -e PYTHONPATH=/app。

操作	命令
进入 backend Bash	`docker compose exec -it backend bash`
进入 postgres psql (socket)	`docker compose exec postgres psql -U moduoduo`
测试 TCP 连接	`docker compose exec postgres bash -c 'PGPASSWORD=moduoduo psql -h postgres -U moduoduo -d moduoduo -c "SELECT 1"'`

场景	命令
实时查看 backend 日志	`docker compose logs -f backend`
过滤 ERROR	`docker compose logs backend
拉取 Prometheus 指标	打开 `http://localhost:8000/metrics`

密码认证失败：

bash

# socket 方式重设密码
docker compose exec -it postgres psql -U moduoduo -c "ALTER USER moduoduo WITH PASSWORD 'moduoduo';"

基础镜像拉取超时：

bash

docker pull python:3.11-slim          # 重试或换镜像 tag
# 或配置镜像加速器 (Docker Desktop Settings > Registries)

如果有新的常用命令，直接编辑此文件 DEV_COMMANDS.md 追加即可。