@umacloud/knowledge 1.0.1

package/cloud-native/04-antipatterns/container-antipatterns.md

@@ -0,0 +1,660 @@
+---
+title: 容器反模式库
+version: 1.0.0
+last_updated: 2025-03-20
+owner: platform-team
+tags: [container, docker, antipatterns, best-practices]
+status: production
+domain: cloud-native
+difficulty: intermediate
+quality_score: 70
+---
+
+# 开发：Excellent（11964948@qq.com）
+# 功能：容器常见反模式识别与修正
+# 作用：帮助团队避免容器化常见错误
+# 创建时间：2025-03-20
+# 最后修改：2025-03-20
+
+## 反模式分类
+
+- **P0** - 严重问题，必须立即修复
+- **P1** - 重要问题，应尽快修复
+- **P2** - 建议改进，可计划修复
+
+---
+
+## 1. 镜像构建反模式
+
+### 1.1 使用 latest 标签 [P0]
+
+**反模式描述**：镜像使用 latest 标签，版本不可追溯。
+
+```dockerfile
+# [FAIL] 反模式
+FROM node:latest
+```
+
+**问题影响**：
+- 版本不可预测
+- 构建结果不一致
+- 无法回滚到特定版本
+- 生产环境风险
+
+**正确实践**：
+
+```dockerfile
+# [DONE] 正确做法
+FROM node:20.11-alpine3.19@sha256:abc123...
+```
+
+### 1.2 镜像过大 [P1]
+
+**反模式描述**：镜像包含不必要的工具和包。
+
+```dockerfile
+# [FAIL] 反模式
+FROM ubuntu:latest
+RUN apt-get update && apt-get install -y \
+    curl wget vim git build-essential python3 nodejs
+```
+
+**问题影响**：
+- 拉取时间长
+- 存储成本高
+- 攻击面大
+- 启动慢
+
+**正确实践**：
+
+```dockerfile
+# [DONE] 正确做法
+FROM python:3.11-slim-bookworm
+# 或使用 alpine
+FROM python:3.11-alpine
+# 或使用 distroless
+FROM gcr.io/distroless/python3-debian12
+```
+
+### 1.3 未清理缓存 [P1]
+
+**反模式描述**：安装后未清理包管理器缓存。
+
+```dockerfile
+# [FAIL] 反模式
+RUN apt-get update && apt-get install -y python3
+RUN pip install -r requirements.txt
+# 未清理缓存
+```
+
+**正确实践**：
+
+```dockerfile
+# [DONE] 正确做法
+RUN apt-get update && \
+    apt-get install -y --no-install-recommends python3 && \
+    apt-get clean && \
+    rm -rf /var/lib/apt/lists/*
+
+RUN pip install --no-cache-dir -r requirements.txt
+```
+
+### 1.4 多个 RUN 指令 [P2]
+
+**反模式描述**：每个命令单独一层，增加镜像大小。
+
+```dockerfile
+# [FAIL] 反模式
+RUN apt-get update
+RUN apt-get install -y python3
+RUN apt-get install -y pip
+RUN pip install -r requirements.txt
+```
+
+**正确实践**：
+
+```dockerfile
+# [DONE] 正确做法
+RUN apt-get update && \
+    apt-get install -y --no-install-recommends python3 python3-pip && \
+    pip install --no-cache-dir -r requirements.txt && \
+    apt-get clean && \
+    rm -rf /var/lib/apt/lists/*
+```
+
+---
+
+## 2. 安全反模式
+
+### 2.1 以 root 运行 [P0]
+
+**反模式描述**：容器默认以 root 用户运行。
+
+```dockerfile
+# [FAIL] 反模式
+FROM python:3.11-slim
+WORKDIR /app
+COPY . .
+CMD ["python", "app.py"]
+# 默认以 root 运行
+```
+
+**问题影响**：
+- 安全风险
+- 权限过大
+- 容器逃逸风险
+
+**正确实践**：
+
+```dockerfile
+# [DONE] 正确做法
+FROM python:3.11-slim
+RUN groupadd -r appgroup && useradd -r -g appgroup appuser
+WORKDIR /app
+COPY --chown=appuser:appgroup . .
+USER appuser
+CMD ["python", "app.py"]
+```
+
+### 2.2 硬编码密钥 [P0]
+
+**反模式描述**：敏感信息硬编码在镜像中。
+
+```dockerfile
+# [FAIL] 反模式
+ENV DATABASE_PASSWORD="plaintext_password"
+ENV API_KEY="secret_key_123"
+RUN echo "password=secret" > /app/config
+```
+
+**问题影响**：
+- 密钥泄露
+- 无法更换密钥
+- 安全审计失败
+
+**正确实践**：
+
+```dockerfile
+# [DONE] 正确做法
+# 镜像中不包含敏感信息
+# 运行时通过环境变量或 Secret 注入
+ENV DATABASE_PASSWORD=""
+# Kubernetes 中：
+# env:
+# - name: DATABASE_PASSWORD
+#   valueFrom:
+#     secretKeyRef:
+#       name: db-credentials
+#       key: password
+```
+
+### 2.3 暴露不必要的端口 [P1]
+
+**反模式描述**：暴露所有端口。
+
+```dockerfile
+# [FAIL] 反模式
+EXPOSE 80 443 8080 3000 5432 6379
+```
+
+**正确实践**：
+
+```dockerfile
+# [DONE] 正确做法
+EXPOSE 8080
+```
+
+### 2.4 使用 ADD 而非 COPY [P2]
+
+**反模式描述**：不必要的 ADD 增加安全风险。
+
+```dockerfile
+# [FAIL] 反模式
+ADD http://example.com/file.tar.gz /tmp/
+ADD archive.tar.gz /app/
+```
+
+**问题影响**：
+- 自动解压可能导致意外行为
+- 远程文件下载风险
+
+**正确实践**：
+
+```dockerfile
+# [DONE] 正确做法
+# 使用 COPY 复制本地文件
+COPY archive.tar.gz /app/
+RUN tar -xzf /app/archive.tar.gz -C /app && rm /app/archive.tar.gz
+```
+
+---
+
+## 3. 运行时反模式
+
+### 3.1 单进程容器运行多服务 [P0]
+
+**反模式描述**：一个容器运行多个服务。
+
+```dockerfile
+# [FAIL] 反模式
+CMD nginx && php-fpm && mysql
+```
+
+**问题影响**：
+- 进程管理困难
+- 资源隔离失效
+- 日志混乱
+- 扩缩容困难
+
+**正确实践**：
+
+```dockerfile
+# [DONE] 正确做法
+# 每个服务独立容器
+# Nginx 容器
+FROM nginx:alpine
+CMD ["nginx", "-g", "daemon off;"]
+
+# PHP-FPM 容器
+FROM php:8.2-fpm-alpine
+CMD ["php-fpm"]
+
+# 使用 Kubernetes Pod 或 Docker Compose 编排
+```
+
+### 3.2 阻塞式启动脚本 [P1]
+
+**反模式描述**：使用复杂的启动脚本。
+
+```bash
+# [FAIL] 反模式
+#!/bin/bash
+echo "Starting..."
+sleep 10
+./start.sh
+tail -f /var/log/app.log
+```
+
+**正确实践**：
+
+```dockerfile
+# [DONE] 正确做法
+# 直接运行应用进程
+CMD ["python", "app.py"]
+# 或使用 entrypoint 处理信号
+ENTRYPOINT ["./entrypoint.sh"]
+CMD ["python", "app.py"]
+```
+
+```bash
+# entrypoint.sh
+#!/bin/sh
+set -e
+# 初始化操作
+exec "$@"  # 使用 exec 传递信号
+```
+
+### 3.3 忽略信号处理 [P1]
+
+**反模式描述**：应用不处理 SIGTERM 信号。
+
+```dockerfile
+# [FAIL] 反模式
+CMD python app.py &  # 后台运行
+```
+
+**问题影响**：
+- 优雅终止失败
+- 强制杀死导致数据丢失
+- 更新中断
+
+**正确实践**：
+
+```dockerfile
+# [DONE] 正确做法
+# 前台运行，正确处理信号
+CMD ["python", "app.py"]
+# 或使用 exec
+CMD ["sh", "-c", "exec python app.py"]
+```
+
+---
+
+## 4. 数据管理反模式
+
+### 4.1 数据存储在容器内 [P0]
+
+**反模式描述**：持久化数据存储在容器内部。
+
+```dockerfile
+# [FAIL] 反模式
+VOLUME /data
+# 数据在容器删除时丢失
+```
+
+**问题影响**：
+- 容器删除数据丢失
+- 无法备份
+- 无法共享
+
+**正确实践**：
+
+```yaml
+# [DONE] 正确做法
+# Kubernetes 中使用 PVC
+apiVersion: v1
+kind: Pod
+spec:
+  containers:
+  - name: app
+    volumeMounts:
+    - name: data
+      mountPath: /data
+  volumes:
+  - name: data
+    persistentVolumeClaim:
+      claimName: app-pvc
+```
+
+### 4.2 写入容器文件系统 [P1]
+
+**反模式描述**：应用写入容器文件系统。
+
+```dockerfile
+# [FAIL] 反模式
+# 应用写入 /app/data/
+# 每次重启数据丢失
+```
+
+**正确实践**：
+
+```yaml
+# [DONE] 正确做法
+# 挂载 emptyDir 或 PVC
+volumeMounts:
+- name: app-data
+  mountPath: /app/data
+volumes:
+- name: app-data
+  emptyDir: {}
+```
+
+---
+
+## 5. 网络反模式
+
+### 5.1 host 网络模式 [P0]
+
+**反模式描述**：使用 host 网络模式。
+
+```yaml
+# [FAIL] 反模式
+docker run --net host myapp
+```
+
+**问题影响**：
+- 端口冲突
+- 网络隔离失效
+- 安全风险
+
+**正确实践**：
+
+```yaml
+# [DONE] 正确做法
+docker run -p 8080:8080 myapp
+# Kubernetes
+apiVersion: v1
+kind: Pod
+spec:
+  hostNetwork: false
+  containers:
+  - name: app
+    ports:
+    - containerPort: 8080
+```
+
+### 5.2 特权端口 [P1]
+
+**反模式描述**：容器尝试绑定特权端口。
+
+```dockerfile
+# [FAIL] 反模式
+EXPOSE 80
+# 非 root 无法绑定
+```
+
+**正确实践**：
+
+```dockerfile
+# [DONE] 正确做法
+EXPOSE 8080
+# 或使用 Kubernetes service 映射
+```
+
+---
+
+## 6. 资源管理反模式
+
+### 6.1 无资源限制 [P0]
+
+**反模式描述**：容器无资源限制。
+
+```yaml
+# [FAIL] 反模式
+docker run myapp
+# 无 CPU/内存限制
+```
+
+**问题影响**：
+- 资源耗尽
+- OOMKilled
+- 影响其他容器
+
+**正确实践**：
+
+```yaml
+# [DONE] 正确做法
+docker run --memory=1g --cpus=2 myapp
+# Kubernetes
+resources:
+  requests:
+    cpu: "500m"
+    memory: "512Mi"
+  limits:
+    cpu: "2000m"
+    memory: "1Gi"
+```
+
+### 6.2 内存限制过低 [P1]
+
+**反模式描述**：内存限制低于实际需求。
+
+```yaml
+# [FAIL] 反模式
+resources:
+  limits:
+    memory: "64Mi"  # 太小
+```
+
+**正确实践**：
+
+```yaml
+# [DONE] 正确做法
+# 根据实际使用设置
+resources:
+  limits:
+    memory: "1Gi"
+# 基于监控数据调整
+```
+
+---
+
+## 7. 日志管理反模式
+
+### 7.1 日志写入文件 [P1]
+
+**反模式描述**：应用日志写入文件。
+
+```python
+# [FAIL] 反模式
+with open('/var/log/app.log', 'a') as f:
+    f.write(log_message)
+```
+
+**问题影响**：
+- 日志采集困难
+- 磁盘空间耗尽
+- 无法集中管理
+
+**正确实践**：
+
+```python
+# [DONE] 正确做法
+import logging
+import sys
+
+logger = logging.getLogger()
+logger.addHandler(logging.StreamHandler(sys.stdout))
+logger.info("Application started")
+```
+
+### 7.2 日志格式不规范 [P2]
+
+**反模式描述**：日志格式不统一。
+
+```python
+# [FAIL] 反模式
+print(f"Error: {error}")
+print(f"User {user_id} logged in")
+```
+
+**正确实践**：
+
+```python
+# [DONE] 正确做法
+import logging
+import json
+
+logger = logging.getLogger()
+
+# 结构化日志
+log_data = {
+    "level": "INFO",
+    "message": "User logged in",
+    "user_id": user_id,
+    "timestamp": datetime.utcnow().isoformat()
+}
+logger.info(json.dumps(log_data))
+```
+
+---
+
+## 8. 健康检查反模式
+
+### 8.1 无健康检查 [P1]
+
+**反模式描述**：容器无健康检查。
+
+```dockerfile
+# [FAIL] 反模式
+# 无 HEALTHCHECK
+```
+
+**问题影响**：
+- 死锁无法检测
+- 流量发送到不健康容器
+
+**正确实践**：
+
+```dockerfile
+# [DONE] 正确做法
+HEALTHCHECK --interval=30s --timeout=3s --start-period=10s --retries=3 \
+    CMD curl -f http://localhost:8080/health || exit 1
+```
+
+### 8.2 健康检查过于简单 [P2]
+
+**反模式描述**：健康检查不验证依赖。
+
+```dockerfile
+# [FAIL] 反模式
+HEALTHCHECK CMD echo "healthy"
+```
+
+**正确实践**：
+
+```dockerfile
+# [DONE] 正确做法
+HEALTHCHECK --interval=30s --timeout=3s \
+    CMD curl -f http://localhost:8080/health/ready || exit 1
+# /health/ready 检查数据库连接等
+```
+
+---
+
+## 9. 依赖管理反模式
+
+### 9.1 依赖未锁定 [P1]
+
+**反模式描述**：未使用 lock 文件。
+
+```dockerfile
+# [FAIL] 反模式
+RUN pip install flask
+RUN npm install express
+# 无版本锁定
+```
+
+**问题影响**：
+- 构建不一致
+- 依赖冲突
+- 安全漏洞
+
+**正确实践**：
+
+```dockerfile
+# [DONE] 正确做法
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+# 或使用 lock 文件
+COPY Pipfile Pipfile.lock .
+RUN pip install pipenv && pipenv install --system
+```
+
+### 9.2 开发依赖进入生产 [P1]
+
+**反模式描述**：生产镜像包含开发依赖。
+
+```dockerfile
+# [FAIL] 反模式
+COPY package.json .
+RUN npm install  # 包含 devDependencies
+```
+
+**正确实践**：
+
+```dockerfile
+# [DONE] 正确做法
+# 多阶段构建
+FROM node:20 AS builder
+WORKDIR /app
+COPY package*.json ./
+RUN npm ci
+
+FROM node:20-alpine
+WORKDIR /app
+COPY --from=builder /app/node_modules ./node_modules
+COPY . .
+RUN npm prune --production
+CMD ["node", "app.js"]
+```
+
+---
+
+## 参考资料
+
+- [Docker 最佳实践](https://docs.docker.com/develop/develop-images/dockerfile_best-practices/)
+- [CIS Docker Benchmark](https://www.cisecurity.org/benchmark/docker)
+- [OWASP Docker Security](https://cheatsheetseries.owasp.org/cheatsheets/Docker_Security_Cheat_Sheet.html)
+- [Docker 反模式](https://docs.docker.com/develop/dev-best-practices/)