第 4 课：用 Docker Compose 管理 FastAPI

第二阶段 · 本地管理 FastAPI · 面向 macOS 和 Windows 的 Docker 初学者

本课完成标准

你能够：

• 解释 Dockerfile、镜像、容器和 Compose 的关系；
• 写出一个 compose.yaml；
• 使用 docker compose up -d --build 启动 FastAPI；
• 使用 ps、logs 检查服务；
• 区分 restart、stop、start 和 down。

1. Compose 是什么？

把几个名词先分开：

名词	小白解释	本课中的角色
Dockerfile	制作镜像的说明书	告诉 Docker 如何准备 FastAPI
镜像	可以启动应用的“安装包”	例如 fastapi-demo:lesson2
容器	镜像启动后正在运行的实例	真正提供 HTTP 服务
Compose	管理一个或多个容器的配置文件和命令	统一启动、停止和查看服务

可以把流程记成：

compose.yaml（服务配置文件）
        ↓ docker compose up
FastAPI 容器（正在运行的服务）

Compose 不会取代 Docker Engine。它只是让我们更方便地告诉 Docker：“要运行什么、映射哪个端口、是否自动重启”。

2. 创建 compose.yaml

进入第 2 课的练习项目 fastapi-docker-demo 根目录，新建文件。文件名建议使用官方推荐的 compose.yaml，不要写成 compose.yaml.txt。

services:
  api:
    build: .
    container_name: fastapi-demo-compose
    ports:
      - "127.0.0.1:8000:8000"
    restart: unless-stopped

逐行理解：

配置	白话含义
services	要管理的服务集合；现在只有一个 API 服务。
api	服务名称，后面用 docker compose logs api 指定它。
build: .	使用当前目录的 Dockerfile 构建镜像。
container_name	给容器一个容易阅读的名字。
127.0.0.1:8000:8000	只允许本机访问；电脑端口 8000 转到容器端口 8000。
restart: unless-stopped	程序异常退出时自动重启；手动停止后不要自动启动。

**生产环境提醒：**本课把端口绑定到 127.0.0.1，表示只给本机测试。以后在 ECS 上由 Nginx 对外提供 80/443 端口，不要直接把 FastAPI 的 8000 暴露到公网。

3. 启动前先检查配置

docker compose config

这个命令会读取并展开 Compose 配置。如果 YAML 缩进错误、字段拼写错误，通常会在这里先发现。YAML 对缩进敏感，使用两个空格，不要随意混用 Tab。

4. 构建并后台启动

docker compose up -d --build

拆开看：

• up：创建并启动服务；
• -d：后台运行，终端可以继续输入命令；
• --build：启动前重新构建镜像，确保 Dockerfile 或代码变更生效。

第一次运行可能需要下载基础镜像和 Python 依赖，请等待命令结束。看到容器创建并启动后，继续检查：

docker compose ps

服务状态应为 Up。然后打开 http://127.0.0.1:8000/docs，或执行健康检查：

macOS / Linux Terminal：

curl -i http://127.0.0.1:8000/health

Windows PowerShell：

curl.exe -i http://127.0.0.1:8000/health

正常情况下会返回 HTTP 200。

5. 查看日志：logs 和 logs -f

docker compose logs api
docker compose logs --tail=100 api
docker compose logs -f api

api 是 Compose 文件中的服务名，不是必须写容器名。-f 表示持续跟踪日志；按 Ctrl+C 只退出查看，不会停止服务。

排错时建议按这个顺序：

1. docker compose ps：确认服务是否仍然运行；
2. docker compose logs api：如果状态不是 Up，查看退出原因；
3. 再访问 /health：确认 HTTP 层是否正常。

6. 修改代码后如何生效？

本课的镜像把代码复制进镜像，因此修改本机代码不会自动改变已经运行的容器。用下面命令重新构建并替换服务：

docker compose up -d --build

如果只想重启而不重新构建：

docker compose restart api

区别是：restart 只重新启动旧容器；up -d --build 会把新的代码和依赖重新做进镜像。

7. 停止、启动和清理

# 停止并移除本项目创建的容器和网络
docker compose down

# 重新启动已经存在的服务
docker compose start

# 停止服务但保留容器
docker compose stop

down 不会删除 Docker 镜像，也不会删除源代码。它只清理本 Compose 项目创建的容器和网络。初学阶段不要使用会影响其他项目的全局删除命令。

8. Compose 常见问题

现象	先执行	可能原因
YAML parse error	docker compose config	缩进或冒号格式错误
port is already allocated	docker ps	电脑的 8000 端口已被占用
服务状态 Exited	docker compose logs api	应用启动命令、依赖或导入错误
代码修改没变化	docker compose up -d --build	没有重新构建镜像
Ctrl+C 后服务停止	检查是否使用了 -d	没有后台启动时，Ctrl+C 会结束前台进程

9. 一分钟自测

问题 1：哪个命令会在后台构建并启动 Compose 服务？

• A. docker compose up -d --build
• B. docker compose logs -f
• C. docker compose config

问题 2：修改代码后，为什么通常要加 --build？

• A. 让新的代码重新进入镜像
• B. 把端口改成 443
• C. 删除 Git 仓库

答案：1A，2A。

本课通关证据

请执行并保留输出：

docker compose config
docker compose up -d --build
docker compose ps
docker compose logs --tail=100 api

健康检查：

# macOS/Linux
curl -i http://127.0.0.1:8000/health

# Windows
curl.exe -i http://127.0.0.1:8000/health

完成标准：docker compose ps 显示服务运行中，健康检查返回 HTTP 200，并且你能解释 down、stop、restart 的区别。

如果命令报错，请把操作系统、完整命令和完整错误输出发给老师。下一阶段会把这些本地操作迁移到阿里云 ECS 和宝塔面板。

参考：Docker Compose 官方文档。

---

← 第 3 课：验证容器 · 第 5 课：创建 ECS 与安全组 →