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

FASTAPI × DOCKER · 第二阶段

容器显示“正在运行”，不代表应用一定正常。本课建立固定检查顺序：先看容器状态，再看日志，再测 HTTP，最后判断端口。

本课完成标准

• 确认容器是否仍在运行；
• 查看 FastAPI 启动日志；
• 访问 /health；
• 理解 HTTP 200、404、500；
• 理解电脑端口和容器端口；
• 按证据排查“网页打不开”。

---

1. 为什么要验证？

第 2 课执行 docker run 后，终端没有报错，不代表所有事情都成功了。

可能出现：

• 容器已经启动，但应用进程随后退出；
• 应用正常，但电脑端口没有正确映射；
• 端口映射正常，但访问了不存在的 URL；
• 应用返回错误，需要从日志中查找原因。

排查流程：

容器状态
    ↓
应用日志
    ↓
HTTP 请求
    ↓
端口映射

2. 准备本课容器

如果第 2 课的容器已经删除，请重新构建并启动：

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

如果容器已经存在，不要重复执行相同的 --name 参数。

先执行：

docker ps

看到 fastapi-demo-running 和 Up，才能继续。

3. 第一步：查看容器状态

只看正在运行的容器：

docker ps

重点观察：

列	含义	观察内容
STATUS	容器状态	是否有 Up
PORTS	端口映射	是否有 127.0.0.1:8000 转发
NAMES	容器名称	后续日志命令使用
IMAGE	使用的镜像	是否是 lesson2 镜像

查看所有容器，包括已停止的容器：

docker ps -a

如果容器不在 docker ps、但出现在 docker ps -a，说明它启动后已经退出。

4. 第二步：查看应用日志

docker logs fastapi-demo-running

正常启动时通常能看到：

Uvicorn running on http://0.0.0.0:8000
Application startup complete

持续查看新日志：

docker logs -f fastapi-demo-running

按 Ctrl+C 只退出日志查看，不会停止容器。

只看最后 100 行：

docker logs --tail=100 fastapi-demo-running

不要只复制日志最后一行。真正的错误原因可能在上方，例如导入失败、路径错误或依赖缺失。

5. 第三步：访问健康检查接口

本课项目定义了 /health：

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

macOS/Linux：

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

Windows PowerShell：

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

正常响应：

HTTP/1.1 200 OK
content-type: application/json

{"status":"ok"}

HTTP 状态码：

状态码	白话含义	处理方式
200	请求成功	健康检查通过
404	路径不存在	检查 URL 是否写成 /health
500	应用内部错误	查看 docker logs
连接失败	没有建立 HTTP 连接	先查容器和端口

6. 第四步：理解端口映射

第 2 课使用：

-p 127.0.0.1:8000:8000

结构是：

-p [电脑地址:电脑端口]:[容器端口]

对应关系：

电脑 127.0.0.1:8000
          ↓
容器 0.0.0.0:8000

两边端口可以不同：

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

此时访问电脑的 18000，Docker 会转发到容器的 8000：

http://127.0.0.1:18000/health

参考：Docker 官方端口发布文档。

7. 用一张表定位问题

现象	先执行	最可能原因
docker ps 没有容器	docker ps -a	容器已经退出
容器 Exited	docker logs 容器名	启动、导入或依赖错误
容器 Up，浏览器失败	docker ps	端口映射或访问端口错误
返回 404	检查 URL	路径不存在
返回 500	docker logs	应用内部异常
port already in use	换左边电脑端口	电脑端口已占用

8. 查看容器内部信息

docker exec -it fastapi-demo-running sh

进入后执行：

pwd
ls
ls app
exit

exit 只退出容器内部命令行，不会停止容器。

如果镜像没有 bash，使用 sh 更兼容。不要在容器内部直接修改代码，重新构建镜像后临时修改会消失。

9. 停止和清理练习

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

如果创建了备用容器，也按名称清理：

docker ps -a
docker rm fastapi-demo-18000

不要使用会影响其他项目的全局清理命令。

10. 一分钟自测

问题 1

容器显示 Exited，第一条有价值的命令是什么？

• A. docker logs 容器名
• B. 重新安装操作系统
• C. 删除所有镜像

正确答案：A。

问题 2

访问 /health 返回 404，最应该先检查什么？

• A. URL 路径是否写对
• B. 立刻修改数据库
• C. 关闭 Docker Desktop

正确答案：A。

本课通关证据

请保留并发送：

docker ps
docker ps -a
docker logs --tail=100 fastapi-demo-running
curl.exe -i http://127.0.0.1:8000/health

如果你能按照“状态 → 日志 → HTTP → 端口”的顺序排查问题，第 3 课就完成了。

下一课：第 4 课：用 Docker Compose 管理 FastAPI

遇到错误时，请注明 macOS、Windows 还是服务器环境，并贴完整命令和完整输出。不要只发“打不开”。