Docker 多阶段构建与非特权运行时实践：以 FastAPI 微服务为例

在将 Python Web 应用（如 FastAPI 服务）打包为容器镜像时，如果直接在单一阶段中执行依赖安装与镜像打包，往往会将包管理器缓存（如 pip 缓存、wheel 构建残留）留在最终镜像层中，同时默认以 root 身份运行容器进程也会带来安全隐患。本文以 FastAPI + Uvicorn 微服务为例，介绍如何通过 Docker 多阶段构建（Multi-Stage Build）实现构建阶段与运行阶段分离，并配置非特权运行用户。

一、单阶段构建的常见问题

1. 构建缓存与工具冗余：在单阶段构建中，即使只安装纯 Python 依赖，pip 升级及构建过程中的中间产物也容易残留在镜像历史层中；若涉及 C 扩展包，编译工具链更会大幅增加镜像体积。
2. 默认特权运行风险：未显式指定 USER 指令时，容器内应用默认以 root（UID 0）身份启动。一旦应用层出现漏洞，容易导致特权扩散。
3. 依赖路径管理混乱：直接全局安装或使用 --user 安装依赖，在切换非 root 用户时常会遇到路径权限不足或环境变量找不到可执行文件的问题。

二、工程结构与完整示例

推荐采用标准的 /opt/venv 独立虚拟环境方案，将所有依赖集中安装在固定路径，便于在多阶段构建中直接跨阶段复制。

1. 依赖配置文件 (requirements.txt)

fastapi>=0.100.0,<1.0.0
uvicorn>=0.23.0,<1.0.0

2. 服务端代码 (src/main.py)

import os
from fastapi import FastAPI
import uvicorn

app = FastAPI(title="Minimal FastAPI Service")

@app.get("/health")
def health_check():
    return {"status": "healthy", "service": "fastapi-microservice"}

if __name__ == "__main__":
    port = int(os.environ.get("PORT", 8080))
    uvicorn.run(app, host="0.0.0.0", port=port)

3. 多阶段构建文件 (Dockerfile)

由于 FastAPI 与基础 Uvicorn 均提供预编译的纯 Python Wheel 包，无需在构建阶段额外安装 gcc 等系统编译器，从而保持构建过程轻量高效：

FROM python:3.11-slim AS builder
WORKDIR /build
RUN python -m venv /opt/venv
ENV PATH="/opt/venv/bin:$PATH"
COPY requirements.txt .
RUN pip install --no-cache-dir --upgrade pip && \
    pip install --no-cache-dir -r requirements.txt

FROM python:3.11-slim AS runner
WORKDIR /app
RUN groupadd -r appgroup && useradd -r -g appgroup -s /sbin/nologin appuser
COPY --from=builder /opt/venv /opt/venv
COPY --chown=appuser:appgroup ./src /app/src
ENV PATH="/opt/venv/bin:$PATH" \
    PYTHONDONTWRITEBYTECODE=1 \
    PYTHONUNBUFFERED=1
USER appuser
EXPOSE 8080
CMD ["python", "src/main.py"]

三、本地构建与验证步骤

在包含上述文件的项目根目录下，可通过以下命令完成镜像构建与行为验证：

# 1. 构建容器镜像
docker build -t fastapi-demo:1.0.0 .
# 2. 启动后台容器并映射端口
docker run -d --name test-fastapi -p 8080:8080 fastapi-demo:1.0.0
# 3. 请求健康检查接口
curl -s http://localhost:8080/health
# 预期返回：{"status":"healthy","service":"fastapi-microservice"}
# 4. 检查容器内进程运行身份
docker exec test-fastapi whoami
# 预期返回：appuser
# 5. 测试完成后清理容器
docker rm -f test-fastapi

四、关键设计要点总结

1. 构建阶段与运行阶段分离：通过 COPY --from=builder /opt/venv /opt/venv，运行阶段直接复用已安装完毕的虚拟环境目录，无需在运行镜像中保留 pip 缓存或构建中间层。
2. 落实最小特权原则：通过创建无登录 Shell 的系统账号 appuser 并声明 USER appuser，有助于落实最小特权原则，降低容器进程默认以 root 身份运行所带来的特权扩散风险。
3. 环境一致性：将 ENV PATH=“/opt/venv/bin:$PATH” 同时声明在构建与运行阶段，确保 python 与 uvicorn 等命令始终指向虚拟环境中的确定版本。