Flask API 生产级 Docker 化：从环境一致性到容器健壮性

1. 项目概述：为什么一个简单的 Flask API 值得被认真 Docker 化

你手头有个跑在本地的 Flask API，几行代码就能返回图片主色调，测试起来飞快，flask run一敲，浏览器里http://localhost:5000/analyze?url=https://example.com/photo.jpg就出结果。这时候有人问：“这玩意儿能上生产吗？”你可能下意识回答“当然可以”，但真要交到运维手里、部署到另一台服务器、或者交给客户做二次集成时，问题就来了——对方机器上没装 Python 3.9？Pillow 版本太老解不开 WebP？requirements.txt里那个opencv-python-headless在 Alpine Linux 上编译失败？甚至只是pip install -r requirements.txt跑了二十分钟还卡在building wheel for numpy？这些不是假设，是我去年帮三个不同团队迁移 API 时踩过的坑，平均每个项目多花了 1.5 天在环境对齐上。

Docker 化不是给简历镀金的装饰项，它是把“我的代码能在我的电脑跑”这个模糊承诺，变成“这段逻辑在任何符合标准的 Linux 环境里，启动即用、行为一致”的硬性契约。它解决的从来不是“能不能跑”，而是“能不能被别人零理解成本地复现、交付、监控和扩缩容”。尤其对 API 这类无状态服务，容器化后，你交付的不再是一堆.py文件和一份写满“请先执行…”的 README，而是一个自包含的、带完整运行时的、可校验哈希值的镜像文件。客户拿到my-flask-api:1.2.0，docker run -p 8000:5000 my-flask-api:1.2.0之后，端口监听、日志输出、健康检查路径，全部按你预设的方式工作，中间没有“我这边环境不一样”的灰色地带。这背后是三层确定性：操作系统层（基础镜像）、语言运行时层（Python 版本与包）、应用逻辑层（你的代码与配置）。我把这三者像三明治一样压紧，再用 Dockerfile 这张“食谱”精确描述每一步操作，最终产出的镜像，就是我在开发机上调试通过的那个“确定性副本”。它不依赖宿主机的 Python 安装路径，不关心目标服务器有没有virtualenv，甚至不需要对方懂 Python——只要他有 Docker 引擎，就能运行。这才是现代 API 交付的起点，而不是终点。

2. 整体设计与思路拆解：从“能跑”到“生产就绪”的四步跃迁

很多人以为 Dockerize 就是写个FROM python:3.9-slim、COPY . /app、CMD ["python", "app.py"]，然后docker build一把梭。这确实能让 API “跑起来”，但离“生产可用”差了至少四个关键维度：资源可控性、进程健壮性、日志可观测性、以及安全基线。我见过太多团队用这种“裸奔式”镜像上线后，API 在高并发下内存暴涨到 2GB，把整台 4GB 的云服务器拖垮；也见过因为没设置--restart=unless-stopped，容器崩溃后服务静默下线两小时没人发现；更常见的是日志全打在 stdout，但没配 logrotate，三个月后/var/lib/docker/containers/xxx/xxx-json.log占满磁盘。所以我的设计不是“最小可行”，而是“最小生产可行”（Minimum Production-Viable），它必须一次性覆盖这四个维度。

2.1 为什么选python:3.9-slim-bullseye而非alpine？

基础镜像选择是第一个分水岭。python:3.9-alpine镜像体积小（约 50MB），很诱人，但它用的是 musl libc，而很多 Python 科学计算包（如numpy、Pillow）的预编译 wheel 默认针对 glibc。直接pip install很可能触发源码编译，导致构建时间暴增（从 30 秒拉长到 8 分钟），且 Alpine 的apk包管理器和主流 Linux 发行版的apt不兼容，后续调试strace或gdb会非常痛苦。我实测过，在alpine上安装Pillow，即使加了--no-cache-dir和--find-links https://download.pytorch.org/whl/torch_stable.html，依然有 37% 的概率因编译器缺失失败。而python:3.9-slim-bullseye（基于 Debian 11）体积约 120MB，虽大一点，但它是 glibc 环境，所有 PyPI 上的主流 wheel 都能直接安装，构建稳定在 45 秒内。更重要的是，它的用户态工具链（curl、ps、netstat）和线上服务器高度一致，排查网络连接、进程状态时，命令和输出格式完全一样，省去大量环境适配认知成本。这不是为体积妥协，而是为构建稳定性和运维一致性主动选择的合理冗余。

2.2 为什么用 Gunicorn 而非原生 Flask 开发服务器？

Flask 自带的Werkzeug服务器仅用于开发调试，它单线程、无超时控制、不支持优雅关闭，生产环境直连等于裸奔。Gunicorn 是经过十年以上生产验证的 WSGI 服务器，它提供进程模型（prefork）、请求超时（--timeout 30）、优雅重启（--graceful-timeout 30）、以及最重要的——worker 进程隔离。当某个请求因图片解析卡死（比如遇到一个 200MB 的 TIFF 文件），Gunicorn 能在超时后强制杀死该 worker，其他 worker 继续处理新请求，避免整个 API 因单个坏请求雪崩。我在压测中对比过：纯 Flask 服务器在 50 并发下，一个慢请求会让后续所有请求排队等待，P99 延迟飙升至 12 秒；而 Gunicorn 配置--workers 4 --worker-class sync --timeout 30后，P99 稳定在 320ms，且错误率低于 0.1%。这不是过度设计，而是把“单点故障”从“整个进程挂掉”降级为“单个 worker 暂时不可用”，这是 API 可用性的底线。

2.3 为什么坚持多阶段构建（Multi-stage Build）？

Dockerfile 里常见的反模式是：RUN pip install -r requirements.txt和COPY . /app写在同一层，导致每次改一行代码，Docker 都要重新下载并安装所有 Python 包。一个 20 行的requirements.txt，pip install步骤平均耗时 22 秒，如果每天改 10 次代码，光构建就浪费近 4 分钟。多阶段构建把构建环境和运行环境彻底分离：第一阶段（builder）用完整的python:3.9镜像，安装编译工具（build-essential）、Python 头文件（python3.9-dev）和所有依赖；第二阶段（final）只从第一阶段COPY --from=builder /usr/local/lib/python3.9/site-packages /usr/local/lib/python3.9/site-packages，把编译好的包拷贝过来。这样，requirements.txt不变时，builder阶段的 layer 完全复用，final镜像构建只需 3 秒。我统计过，一个中等复杂度的 Flask API（含numpy、Pillow、requests），多阶段构建让 CI/CD 流水线平均提速 68%，且最终镜像体积比单阶段小 40%——因为build-essential等编译工具根本不会打进生产镜像。

2.4 为什么健康检查（HEALTHCHECK）必须独立于业务逻辑？

Docker 的HEALTHCHECK指令常被误用为“调用/health接口”。但/health通常会检查数据库连接、缓存状态等外部依赖，一旦 Redis 挂了，/health返回 503，Docker 就认为容器不健康，触发重启。这会导致“Redis 故障 → API 容器反复重启 → 加剧 Redis 负载 → 故障扩大”的死亡螺旋。正确的做法是：HEALTHCHECK只检查容器自身是否存活，不碰任何外部服务。我在app.py里加了一个专用的/healthz端点，它只返回{"status": "ok"}，不查 DB、不读文件、不发 HTTP 请求，纯粹是“进程还在呼吸”的信号。Dockerfile 中写HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 CMD curl -f http://localhost:5000/healthz || exit 1。这样，即使 Redis 全挂，API 容器依然健康，Kubernetes 或 Docker Swarm 会继续将流量路由给它，而业务层的/health接口则由前端网关或监控系统单独调用，实现故障隔离。这是把“容器生命周期管理”和“业务健康状态”解耦的关键设计。

3. 核心细节解析与实操要点：从代码结构到 Dockerfile 的每一处深意

一个真正可靠的 Dockerized Flask API，其价值不仅在于能否运行，更在于它如何应对真实世界的混乱：突然的 SIGTERM 信号、磁盘空间告警、日志爆炸、依赖包版本漂移。这些细节藏在代码组织、配置方式和 Dockerfile 指令的每一个选择里。下面我逐层拆解，告诉你为什么这么写，以及不这么写的代价。

3.1 应用代码结构：为什么app.py必须只负责“胶水”，而逻辑全在api/目录？

新手常把所有代码塞进一个app.py：路由定义、图片解析、颜色提取、异常处理全混在一起。这在 Docker 里会引发两个致命问题：一是无法热重载（--reload在容器里失效），二是import错误难以定位。我坚持采用分层结构：

/my-flask-api ├── app.py # 仅创建 Flask 实例、注册蓝图、配置日志 ├── api/ │ ├── __init__.py # 空文件，声明包 │ ├── routes.py # 所有 @app.route() 装饰器在此 │ └── services.py # 主色调提取等核心业务逻辑 ├── requirements.txt └── Dockerfile

app.py的核心只有三件事：初始化Flask(__name__)、调用app.register_blueprint(api_bp, url_prefix='/api')、配置app.config.from_object(Config)。所有业务逻辑（如services.extract_dominant_colors()）严格放在api/services.py。这样做的好处是：当routes.py修改时，Gunicorn 的 worker 进程能通过--reload捕获文件变化并优雅重启，而app.py本身几乎不变，避免了因Flask()初始化多次导致的全局状态污染。更重要的是，单元测试可以from api.services import extract_dominant_colors独立测试，无需启动整个 Flask 应用，测试速度提升 5 倍。我曾重构一个 300 行的单文件 API，拆分后，CI 测试时间从 2.1 分钟降到 24 秒，且docker build缓存命中率从 40% 提升到 92%——因为api/services.py改动频率远低于app.py，Docker 复用COPY ./api ./api这一层的次数大大增加。

3.2 配置管理：为什么Config类必须区分DevelopmentConfig和ProductionConfig，且SECRET_KEY绝不能硬编码？

Flask 的配置看似简单，但在容器环境下极易翻车。最典型的错误是：app.config['SECRET_KEY'] = 'dev-key'。这在开发时没问题，但镜像一旦推送到公共仓库，SECRET_KEY就成了明文泄露，攻击者可伪造 session cookie。正确做法是：Config基类定义通用配置，子类覆盖敏感项，并通过环境变量注入。

# config.py import os class Config: # 所有环境共用的配置 JSON_SORT_KEYS = False MAX_CONTENT_LENGTH = 16 * 1024 * 1024 # 16MB 图片上传限制 class ProductionConfig(Config): # 生产环境特有配置 DEBUG = False SECRET_KEY = os.environ.get('SECRET_KEY') or None # 必须由外部提供 # 关闭 Flask 的自动重载 USE_RELOADER = False class DevelopmentConfig(Config): DEBUG = True SECRET_KEY = 'dev-secret-change-in-prod'

Dockerfile 中不写ENV SECRET_KEY，而是在docker run时用-e SECRET_KEY=your-real-key-here注入。这样，镜像本身不携带任何密钥，符合“镜像不可变”原则。同时，MAX_CONTENT_LENGTH设为 16MB 是经过测算的：小于 16MB 的图片，Pillow 解析内存占用通常 < 100MB；超过此值，内存峰值可能突破 500MB，触发 OOM Killer。这个数字不是拍脑袋，而是我用memory_profiler对 1000 张不同尺寸 JPG/PNG/WebP 图片实测后取的 P95 值。

3.3 Dockerfile 指令精解：为什么COPY必须分两次，且USER指令不可或缺？

一个被严重低估的 Dockerfile 最佳实践是：分层 COPY，精准控制缓存。错误写法：

# ❌ 危险！一次 COPY 所有，任何文件改动都使 pip install 失效 COPY . /app WORKDIR /app RUN pip install -r requirements.txt

正确写法：

# ✅ 分层 COPY：先拷依赖文件，再拷代码 COPY requirements.txt . RUN pip install --no-cache-dir -r requirements.txt # 仅在依赖安装后才拷代码，确保 pip layer 高度复用 COPY api/ ./api/ COPY app.py config.py ./

这样，只要requirements.txt不变，pip install这一层永远从缓存加载，无论你改了 100 行services.py还是 1000 行routes.py。实测显示，这种写法让docker build在 CI 环境下平均提速 3.2 倍。

另一个关键指令是USER。默认容器以 root 用户运行，这违反最小权限原则。一旦 Flask 应用存在 RCE 漏洞（比如用户可控的eval()），攻击者就能直接获得宿主机 root 权限。我在Dockerfile结尾添加：

# 创建非特权用户 RUN adduser --disabled-password --gecos '' appuser USER appuser WORKDIR /home/appuser

所有后续指令（包括CMD）都以appuser身份执行。adduser命令比useradd更安全，它会自动创建家目录、设置合理的 umask。WORKDIR /home/appuser确保所有文件操作都在用户目录下，避免权限混乱。这个改动让容器的 CVE 漏洞利用难度指数级上升——攻击者即使突破应用层，也只能在/home/appuser目录下活动，无法写入/etc或/usr/local。

3.4 日志与错误处理：为什么logging.basicConfig()必须禁用，而gunicorn.conf.py是日志中枢？

Flask 默认的日志输出到stderr，但在容器里，stderr会被 Docker 拦截并写入 JSON 日志文件（/var/lib/docker/containers/xxx/xxx-json.log）。如果应用自己再用logging.basicConfig()配置文件输出，就会造成日志重复、时间戳错乱、甚至磁盘爆满。正确策略是：应用层只输出结构化日志到 stdout/stderr，日志收集由外部统一处理。

因此，app.py中必须删除所有logging.basicConfig()调用，改为：

import logging # 使用 Gunicorn 的 logger，避免重复初始化 gunicorn_logger = logging.getLogger('gunicorn.error') app.logger.handlers = gunicorn_logger.handlers app.logger.setLevel(gunicorn_logger.level)

所有日志（app.logger.info()、app.logger.error()）都会流向 Gunicorn 的日志管道。真正的日志配置在gunicorn.conf.py：

# gunicorn.conf.py import os loglevel = 'info' accesslog = '-' # 输出到 stdout，供 Docker 拦截 errorlog = '-' # 输出到 stderr，供 Docker 拦截 capture_output = True # 捕获 Flask print() 输出

accesslog = '-'是关键——它告诉 Gunicorn 把访问日志（谁在什么时候调用了哪个接口）直接打印到 stdout，Docker 会将其作为结构化日志的一部分收集。这样，你用docker logs -f my-api看到的，是混合了访问日志（127.0.0.1 - - [20/Jul/2023:10:23:45 +0000] "GET /api/analyze?url=... HTTP/1.1" 200 123）和错误日志（ERROR in app: Failed to process image: OSError(123)）的完整流，无需在容器内tail -f多个文件。这极大简化了故障排查——一个docker logs命令，就能还原整个请求生命周期。

4. 实操过程与核心环节实现：从零开始构建、测试、优化的完整流水线

现在我们把前面所有设计落地为可执行的步骤。这不是教科书式的“复制粘贴”，而是我每天在终端里实际敲的命令、遇到的真实报错、以及当场解决的方案。我会带你走完从初始化项目到发布镜像的全流程，每一步都附带“为什么这么做”和“不这么做会怎样”。

4.1 初始化项目与依赖管理：requirements.txt的生成必须带--hash

第一步不是写代码，而是建立可复现的依赖基线。很多人用pip freeze > requirements.txt，但这会把所有间接依赖（如urllib3、chardet）也写进去，导致pip install时版本冲突。正确流程是：

# 1. 创建干净的虚拟环境（避免污染全局 pip） python3.9 -m venv venv source venv/bin/activate # 2. 只安装明确需要的包（不装 flask，因为 gunicorn 会带） pip install "gunicorn==21.2.0" "Pillow==9.5.0" "requests==2.31.0" # 3. 生成带哈希的 requirements.txt（关键！） pip install pip-tools pip-compile --generate-hashes --output-file=requirements.txt pyproject.toml

pip-compile会解析pyproject.toml（需先创建，内容见下文），生成requirements.txt，其中每行都带--hash=sha256:xxx。例如：

Pillow==9.5.0 \ --hash=sha256:abc123... \ --hash=sha256:def456...

这样，pip install -r requirements.txt会校验每个 wheel 的 SHA256，确保下载的包未被篡改。我曾因 CDN 被劫持，下载到恶意修改的requests包，它会在后台偷偷发送数据到境外 IP，而带哈希的安装直接报错Hashes do not match，阻止了漏洞利用。pyproject.toml内容极简：

[build-system] requires = ["setuptools>=45", "wheel"] build-backend = "setuptools.build_meta" [project] dependencies = [ "gunicorn==21.2.0", "Pillow==9.5.0", "requests==2.31.0", ]

它只声明直接依赖，pip-compile会自动解析并锁定所有传递依赖（如Pillow依赖的libjpeg、libpng），生成的requirements.txt有 127 行，但全部可审计、可复现。

4.2 编写核心业务逻辑：services.py中的图片解析必须设超时与内存限制

services.py是整个 API 的心脏，也是最容易出问题的地方。用户传来的 URL 可能指向一个 500MB 的 RAW 文件，或一个返回 302 重定向链的恶意站点。我们必须在代码层设防：

import requests from PIL import Image import io import logging def extract_dominant_colors(image_url: str, max_size: int = 1024) -> list: try: # 1. 下载图片，带超时和大小限制 response = requests.get( image_url, timeout=(3.05, 27), # connect: 3.05s, read: 27s (总超时30s) stream=True, headers={'User-Agent': 'MyFlaskAPI/1.0'} ) response.raise_for_status() # 2. 检查 Content-Length，防止下载超大文件 content_length = int(response.headers.get('content-length', 0)) if content_length > 16 * 1024 * 1024: # 16MB raise ValueError(f"Image too large: {content_length} bytes") # 3. 用 io.BytesIO 流式读取，避免内存爆炸 image_bytes = io.BytesIO() for chunk in response.iter_content(chunk_size=8192): image_bytes.write(chunk) # 实时检查已读大小 if image_bytes.getbuffer().nbytes > 16 * 1024 * 1024: raise ValueError("Downloaded image exceeds 16MB limit") # 4. Pillow 解析，带尺寸限制 image = Image.open(image_bytes) # 缩放到最大边 1024px，大幅降低内存占用 image.thumbnail((max_size, max_size), Image.Resampling.LANCZOS) # 5. 提取主色（简化版，实际用 KMeans） colors = image.convert('RGB').getcolors(maxcolors=1000) if not colors: raise ValueError("Cannot extract colors from image") # 按像素数排序，取前3 dominant = sorted(colors, key=lambda x: x[0], reverse=True)[:3] return [{"color": f"#{r:02x}{g:02x}{b:02x}", "count": count} for count, (r, g, b) in dominant] except requests.exceptions.Timeout: raise TimeoutError("Image download timed out") except requests.exceptions.RequestException as e: raise ValueError(f"Failed to fetch image: {e}") except Exception as e: logging.exception("Error processing image") raise ValueError(f"Invalid image format: {e}")

这里的关键防御点：timeout=(3.05, 27)遵循 AWS 的 3-27 规则 ，避免连接池阻塞；iter_content流式下载 + 实时字节计数，确保内存不超 16MB；image.thumbnail()将大图压缩，使 Pillow 解析内存从 GB 级降到 MB 级。我用一张 8000x6000 的 TIFF 测试，未压缩时 Pillow 占用 1.2GB 内存，加thumbnail后仅 45MB。

4.3 构建与本地测试：docker build的参数和docker run的黄金组合

构建镜像不是docker build -t my-api .就完事。生产级构建必须加参数：

# 构建时指定平台（避免 Apple Silicon 机器构建的镜像在 x86 服务器上运行失败） docker build --platform linux/amd64 -t my-flask-api:1.0.0 . # 构建时启用 BuildKit（更快、更安全的构建引擎） DOCKER_BUILDKIT=1 docker build --platform linux/amd64 -t my-flask-api:1.0.0 . # 构建时跳过测试（CI/CD 中常用） docker build --build-arg SKIP_TESTS=true -t my-flask-api:1.0.0 .

--platform linux/amd64是必须的，否则 M1/M2 Mac 构建的镜像，glibc版本可能与 x86 服务器不兼容，导致ImportError: cannot open shared object file: No such file or directory。BuildKit 则让多阶段构建更高效，且支持--secret传递敏感信息（如私有 PyPI token），避免密钥硬编码。

本地测试要模拟生产环境：

# 1. 运行容器，映射端口，注入密钥，启用健康检查 docker run -d \ --name my-api-test \ -p 8000:5000 \ -e SECRET_KEY=super-secret-key-for-testing \ --restart=unless-stopped \ --memory=512m --memory-swap=512m \ # 限制内存，防 OOM --cpus=1.0 \ my-flask-api:1.0.0 # 2. 等待健康检查通过（最多等 30 秒） until docker inspect my-api-test | jq -r '.[0].State.Health.Status' | grep -q "healthy"; do echo "Waiting for health check..." sleep 2 done # 3. 发送测试请求（用真实图片 URL） curl -v "http://localhost:8000/api/analyze?url=https://httpbin.org/image/jpeg" # 4. 查看实时日志 docker logs -f my-api-test

--memory=512m是关键——它告诉 Docker，这个容器最多用 512MB 内存，超了就 OOM Kill。这比让容器吃光服务器内存更可控。--restart=unless-stopped确保容器崩溃后自动恢复，这是生产服务的底线。curl -v的-v参数显示详细 HTTP 交互，方便确认状态码、响应头（如Content-Type: application/json）是否正确。

4.4 镜像优化与安全扫描：docker scout和trivy是上线前的最后防线

构建完的镜像不能直接上线，必须经过两道扫描：

# 1. 用 docker scout 检查基础镜像漏洞（免费，集成 Docker Hub） docker scout cves my-flask-api:1.0.0 # 2. 用 trivy 扫描 Python 依赖漏洞（开源，更细粒度） trivy image --severity CRITICAL,HIGH my-flask-api:1.0.0

docker scout会报告python:3.9-slim-bullseye基础镜像中的已知 CVE，如CVE-2023-29383（OpenSSL 漏洞）。如果报告 HIGH 或 CRITICAL 级别漏洞，必须升级基础镜像（如切到python:3.9-slim-bookworm）。trivy则深入到 Python 包层，例如它曾发现Pillow<9.5.0存在CVE-2023-27500（拒绝服务漏洞），提示我必须将Pillow锁定到9.5.0。扫描不是形式主义，而是把“未知风险”转化为“已知风险清单”。我要求所有上线镜像，trivy扫描结果必须为0 CRITICAL, 0 HIGH，否则 CI 流水线直接失败。这规则让团队在两周内修复了 17 个潜在高危漏洞，其中 3 个已在公开 PoC 中被利用。

5. 常见问题与排查技巧实录：那些文档里不会写的“血泪教训”

再完美的设计，也会在真实环境中撞墙。以下是我在过去三年 Dockerizing 数十个 Flask API 时，记录下来的高频问题、根因分析和一招制敌的解决方案。它们不是理论，而是我在凌晨三点盯着docker logs时，亲手验证过的救命技巧。

5.1 问题：容器启动后立即退出，docker logs显示OSError: [Errno 98] Address already in use

现象：docker run -p 8000:5000 my-api后，docker ps看不到容器，docker ps -a显示状态为Exited (1)，日志末尾是Address already in use。

根因：Gunicorn 默认绑定0.0.0.0:5000，但容器内5000端口被其他进程（如残留的python app.py）占用。更隐蔽的情况是：app.py里写了if __name__ == '__main__': app.run(host='0.0.0.0', port=5000)，而 Gunicorn 启动时又 fork 出多个 worker，每个 worker 都试图绑定5000端口，导致冲突。

解决方案：在app.py顶部加守护判断：

# app.py 开头 import os if os.environ.get('RUNNING_IN_CONTAINER') == 'true': # 容器内，禁止执行 app.run() pass else: # 本地开发时才运行 if __name__ == '__main__': app.run(host='0.0.0.0', port=5000)

并在Dockerfile的CMD中设置环境变量：

CMD ["gunicorn", "--bind", "0.0.0.0:5000", "--workers", "4", "--timeout", "30", "--graceful-timeout", "30", "app:app"] # 注意：这里没有设置 RUNNING_IN_CONTAINER，因为 CMD 是在容器内执行的

但更彻底的方案是：永远不要在app.py里写app.run()。把它移到一个单独的dev-server.py：

# dev-server.py from app import app if __name__ == '__main__': app.run(host='0.0.0.0', port=5000, debug=True)

Dockerfile的CMD只调用 Gunicorn，dev-server.py仅供本地python dev-server.py使用。这样，代码路径彻底分离，永不冲突。

5.2 问题：API 响应缓慢，docker stats显示 CPU 100%，但top里看不到 Python 进程

现象：curl请求耗时 10+ 秒，docker stats my-api显示 CPU 持续 100%，但进入容器docker exec -it my-api bash后，top命令显示 Python 进程 CPU 占用仅 5%，大部分时间在sleep。

根因：这是典型的 I/O 等待（IOWAIT）伪装成 CPU 占用。Gunicorn worker 在等待 Pillow 解析图片，而 Pillow 的Image.open()是同步阻塞调用，会把整个 worker 线程卡住。4 个 worker 全部卡在 I/O，新请求只能排队，docker stats的 CPU 统计把 IOWAIT 算作了 CPU 时间。

解决方案：用gunicorn的--worker-class gevent替换sync：

CMD ["gunicorn", "--bind", "0.0.0.0:5000", "--workers", "4", "--worker-class", "gevent", "--timeout", "30", "app:app"]

gevent是基于协程的异步 worker，它能让一个 worker 同时处理多个 I/O 密集型请求。当一个请求在等待图片下载时，gevent会自动切换到另一个请求，CPU 利用率立刻从 100% 降到 35%，P99 延迟从 12 秒降到 450ms。但注意：gevent要求所有依赖库都是协程友好的，requests不是，所以必须换成gevent兼容的requests-gevent或直接用urllib3。我在services.py中改用：

import urllib3 http = urllib3.PoolManager(timeout=urllib3.Timeout(connect=3.05, read=27)) response = http.request('GET', image_url, preload_content=False)

preload_content=False让urllib3返回流式响应，配合gevent的monkey.patch_all()，实现真正的异步 I/O。

5.3 问题：docker build在 CI 中随机失败，报错Connection refused或ReadTimeout

现象：本地docker build百分百成功，但 Jenkins/GitLab CI 中，pip install步骤偶尔失败，错误是Connection refused to pypi.org或ReadTimeout on https://pypi.org/simple/pillow/。

根因：CI 服务器通常位于企业内网，出口 IP 被 PyPI 限流。PyPI 对同一 IP 的请求频率有限制，CI 服务器集群的多个节点共享一个出口 IP，导致请求被429 Too Many Requests。

解决方案：在Dockerfile中配置 pip 镜像源和重试：

# 在 RUN pip install 前，配置 pip RUN pip config set global.index-url https://pypi.t