跳到主要内容

第 2 课：用 Dockerfile 构建 FastAPI 镜像

FASTAPI × DOCKER · 第二阶段
适合 Docker 初学者

第 1 课我们运行了别人准备好的 Nginx 镜像。本课开始自己制作镜像：把一个 FastAPI 应用、Python 环境和依赖打包起来，再启动成容器。

本课完成标准​

完成后，你应该能够：

  • 读懂 Dockerfile 的基本指令；
  • 成功构建 FastAPI 镜像；
  • 启动 FastAPI 容器；
  • 打开 /health 和 /docs；
  • 查看容器状态和日志；
  • 解释电脑端口与容器端口的区别。

1. 先回顾第 1 课​

第 1 课中：

  • 镜像像“应用安装包”；
  • 容器像“已经打开运行的应用”。

本课的流程：

Dockerfile（制作说明）
        ↓ docker build
镜像（FastAPI 应用包）
        ↓ docker run
容器（正在运行的 FastAPI）

Dockerfile 不是镜像，也不是容器，它更像一张菜谱，告诉 Docker 如何制作镜像。

本课只记 5 个动作：

  1. 选择 Python 环境；
  2. 设置工作目录；
  3. 复制文件；
  4. 安装依赖；
  5. 启动 FastAPI。

2. 准备一个最小 FastAPI 项目​

真实的 student-management-api 会在第 11 课接入。本课先准备练习项目：

fastapi-docker-demo/
├── app/
│   ├── __init__.py
│   └── main.py
└── requirements.txt

app/main.py​

from fastapi import FastAPI

app = FastAPI(
    title="Docker FastAPI Demo",
    version="1.0.0",
)

@app.get("/health")
def health():
    return {"status": "ok"}

@app.get("/")
def home():
    return {"message": "Hello from FastAPI"}

/health 是健康检查接口。它不访问数据库，只回答“应用进程是否能响应请求”。

app/init.py​

# 留空即可

requirements.txt​

fastapi[standard]

容器会自己安装依赖，不要把本机的 venv 目录复制进 Docker。

3. 编写 Dockerfile​

在项目根目录新建文件，文件名必须是 Dockerfile，不要有 .txt 后缀：

FROM python:3.12-slim

WORKDIR /code

COPY requirements.txt ./
RUN pip install --no-cache-dir -r requirements.txt

COPY ./app ./app

EXPOSE 8000

CMD ["fastapi", "run", "app/main.py", "--host", "0.0.0.0", "--port", "8000"]

4. 逐行理解 Dockerfile​

指令白话解释
FROM选择已经包含 Python 的基础镜像
WORKDIR设置容器内部的工作目录
COPY把本机文件复制到镜像
RUN制作镜像时执行安装命令
EXPOSE说明应用习惯使用的端口
CMD容器启动时执行的默认命令

FastAPI 官方也使用官方 Python 镜像和自定义 Dockerfile：FastAPI 官方容器部署文档。

5. 为什么使用 0.0.0.0？​

容器内部有自己的网络环境。如果程序只监听容器内部的 127.0.0.1，Docker 从容器外部可能无法访问它。

电脑 127.0.0.1:8000
          ↓
容器内部 0.0.0.0:8000

0.0.0.0 表示在容器的所有网络接口上监听。它不等于直接暴露公网，是否能从电脑访问还要看端口发布配置。

6. 构建镜像​

进入 Dockerfile 所在目录：

cd fastapi-docker-demo

构建：

docker build -t fastapi-demo:lesson2 .

命令含义：

  • docker build：按照 Dockerfile 制作镜像；
  • -t fastapi-demo:lesson2：镜像名为 fastapi-demo，标签为 lesson2；
  • 最后的点：使用当前目录作为构建上下文。

查看镜像：

docker images

应该能看到 fastapi-demo 和 lesson2。

第一次构建需要下载 Python 镜像和依赖，等待较长是正常的。

7. 启动容器​

docker run -d \
  --name fastapi-demo-running \
  -p 127.0.0.1:8000:8000 \
  fastapi-demo:lesson2

Windows PowerShell 可以使用一行：

docker run -d --name fastapi-demo-running -p 127.0.0.1:8000:8000 fastapi-demo:lesson2

参数说明：

  • -d：后台运行；
  • --name：给容器起名字；
  • -p 127.0.0.1:8000:8000：电脑 8000 连接到容器 8000，只允许本机访问；
  • fastapi-demo:lesson2：要启动的镜像名和标签。

8. 浏览器验证​

打开：

http://127.0.0.1:8000/health

应该看到：

{"status":"ok"}

再打开：

http://127.0.0.1:8000/docs

看到 Swagger UI 页面，说明 FastAPI 已经成功运行。

命令行检查：

macOS/Linux：

curl http://127.0.0.1:8000/health

Windows PowerShell：

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

9. 查看状态和日志​

docker ps
docker logs fastapi-demo-running

如果容器不在运行列表中：

docker ps -a
docker logs fastapi-demo-running

日志是排查启动失败最重要的证据。

10. 停止、删除容器和镜像​

docker stop fastapi-demo-running
docker rm fastapi-demo-running

如果要删除本课镜像：

docker rmi fastapi-demo:lesson2

初学时不要执行 docker system prune，它可能删除其他项目正在使用的内容。

11. 常见错误​

找不到 Dockerfile​

macOS/Linux 执行：

ls

Windows PowerShell 执行：

Get-ChildItem

确认当前目录中有 Dockerfile，并且不是 Dockerfile.txt。

电脑端口被占用​

换电脑端口：

docker run -d --name fastapi-demo-running-2 -p 127.0.0.1:18000:8000 fastapi-demo:lesson2

访问 http://127.0.0.1:18000/health。

左边的电脑端口可以修改，右边的容器端口仍然是 8000。

容器启动后立即退出​

docker ps -a
docker logs fastapi-demo-running

常见原因是入口路径错误、依赖安装失败、Python 导入失败或 COPY 路径错误。

浏览器显示 404​

本课只定义了 / 和 /health。访问其他路径返回 404，可能只是应用的正常响应。

12. 本课自测​

问题 1：Dockerfile 最像什么？​

  • A. 制作镜像的菜谱
  • B. 正在运行的容器
  • C. 阿里云安全组

正确答案：A。

问题 2：-p 127.0.0.1:8000:8000 中左边的 8000 是什么？​

  • A. 电脑端口
  • B. 镜像版本号
  • C. Python 版本

正确答案：A。

本课通关证据​

请保留并发送：

docker images
docker ps
docker logs fastapi-demo-running
curl.exe -i http://127.0.0.1:8000/health

如果你能解释 Dockerfile 中的 FROM、COPY、RUN、CMD，并能打开 /health 和 /docs，第 2 课就完成了。

下一课：第 3 课：验证容器——端口、日志和健康检查

官方资料​

遇到任何问题都可以继续问我。请注明 macOS、Windows，还是服务器环境，并贴完整命令和输出。

课程推荐

想系统学习这门课程？

你已阅读完本文。需要更完整的知识体系，可以继续了解「Vibe Coding 实战课程」。

查看课程详情