ECC 部署模式实战指南：发布策略、Docker 多阶段构建与 CI/CD、健康检查、回滚及生产就绪检查清单

本文基于 ECC 仓库的部署模式技能文档（SKILL.md，主目录下的 skills/deployment-patterns/SKILL.md 为其同源副本），系统讲解生产环境部署的完整方法论：滚动/蓝绿/金丝雀三种发布策略的取舍、Node.js/Go/Python 三语言的多阶段 Dockerfile 写法、标准 CI/CD 管道、健康检查端点与 Kubernetes 探针、基于环境变量与 Zod 的配置校验、回滚策略，以及发布前的生产就绪检查清单。读完后，你可以为一套 Web 应用搭建可复制的部署基础设施，并用 ECC 仓库自身的 Dockerfile 与 GitHub Actions 工作流作为参照实现来核对每个实践点。

一、何时启用部署模式

该技能在以下场景中激活（引自 SKILL.md 的 "When to Activate" 一节）：

• 搭建 CI/CD 流水线
• 为应用做 Docker 容器化
• 规划部署策略（蓝绿、金丝雀、滚动）
• 实现健康检查与就绪探针
• 准备一次生产发布
• 配置环境相关的设置

文末 "When to Use This Skill" 一节还补充了第七个场景：排障部署问题（troubleshooting deployment issues）。以下各节按"策略选型 → 容器化 → 流水线 → 健康检查 → 环境配置 → 回滚 → 就绪清单"的顺序展开，这正是从代码合并到生产上线的完整链路。

二、部署策略选型

2.1 滚动部署（默认策略）

滚动部署逐台替换实例——发布期间新旧版本同时运行。原文给出的三实例示意：

Instance 1: v1 → v2  (update first)
Instance 2: v1        (still running v1)
Instance 3: v1        (still running v1)

Instance 1: v2
Instance 2: v1 → v2  (update second)
Instance 3: v1

Instance 1: v2
Instance 2: v2
Instance 3: v1 → v2  (update last)

• 优点：零停机、灰度推进
• 缺点：两个版本同时运行——要求变更向后兼容
• 适用：标准部署、向后兼容的变更

滚动是 Kubernetes 的默认更新方式，也是成本最低的选项。它的核心约束是"新老实例必须能同时对外提供正确服务"，因此 API 契约、数据格式必须向后兼容。

2.2 蓝绿部署

运行两套完全相同的环境，流量原子切换：

Blue  (v1) ← traffic
Green (v2)   idle, running new version

# After verification:
Blue  (v1)   idle (becomes standby)
Green (v2) ← traffic

• 优点：秒级回滚（切回蓝环境）、切换干净
• 缺点：部署期间需要 2 倍基础设施
• 适用：关键服务、对故障零容忍的场景

2.3 金丝雀部署

先将小比例流量导到新版本：

v1: 95% of traffic
v2:  5% of traffic  (canary)

# If metrics look good:
v1: 50% of traffic
v2: 50% of traffic

# Final:
v2: 100% of traffic

• 优点：全量铺开前用真实流量暴露问题
• 缺点：需要流量分割基础设施与完善的监控
• 适用：高流量服务、高风险变更、特性开关场景

三种策略的本质差异在于"风险暴露面积"：滚动是逐步暴露，蓝绿是验证后一次性暴露（但可瞬时撤回），金丝雀是持续小面积暴露并按指标扩量。选型时应结合基础设施成本（蓝绿需双倍容量）与监控成熟度（金丝雀依赖指标驱动的决策）。

三、Docker 多阶段构建实战

原文为三套主流技术栈各给出一份可直接使用的多阶段 Dockerfile。以下逐一继承原文并补充关键指令的意图说明。

3.1 Node.js 多阶段 Dockerfile

# Stage 1: Install dependencies
FROM node:22-alpine AS deps
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci --production=false

# Stage 2: Build
FROM node:22-alpine AS builder
WORKDIR /app
COPY --from=deps /app/node_modules ./node_modules
COPY . .
RUN npm run build
RUN npm prune --production

# Stage 3: Production image
FROM node:22-alpine AS runner
WORKDIR /app

RUN addgroup -g 1001 -S appgroup && adduser -S appuser -u 1001
USER appuser

COPY --from=builder --chown=appuser:appgroup /app/node_modules ./node_modules
COPY --from=builder --chown=appuser:appgroup /app/dist ./dist
COPY --from=builder --chown=appuser:appgroup /app/package.json ./

ENV NODE_ENV=production
EXPOSE 3000

HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
  CMD wget --no-verbose --tries=1 --spider http://localhost:3000/health || exit 1

CMD ["node", "dist/server.js"]

要点解读：

• deps 阶段只拷贝 package.json/package-lock.json 并执行 npm ci，利用层缓存让依赖安装与源码变更解耦——源码改动不会触发重新安装依赖；
• builder 阶段执行构建后 npm prune --production 剥离开发依赖，最终镜像只携带生产 node_modules；
• runner 阶段创建非 root 用户（UID 1001），并在拷贝时显式 --chown，保证容器内进程不以 root 运行；
• HEALTHCHECK 使用 wget --spider（HEAD 语义、不落盘）探测 /health，--start-period=5s 给冷启动留出缓冲，--retries=3 避免单次抖动即标记不健康。

3.2 Go 多阶段 Dockerfile

FROM golang:1.22-alpine AS builder
WORKDIR /app
COPY go.mod go.sum ./
RUN go mod download
COPY . .
RUN CGO_ENABLED=0 GOOS=linux go build -ldflags="-s -w" -o /server ./cmd/server

FROM alpine:3.19 AS runner
RUN apk --no-cache add ca-certificates
RUN adduser -D -u 1001 appuser
USER appuser

COPY --from=builder /server /server

EXPOSE 8080
HEALTHCHECK --interval=30s --timeout=3s CMD wget -qO- http://localhost:8080/health || exit 1
CMD ["/server"]

要点解读：

• CGO_ENABLED=0 产出纯静态二进制，可跑在最小化的 alpine:3.19 上，无需 glibc；
• -ldflags="-s -w" 去掉符号表与 DWARF 调试信息，进一步压缩体积；
• 先 COPY go.mod go.sum 再 go mod download，同样是依赖层与代码层分离的缓存优化；
• runner 阶段只 apk --no-cache add ca-certificates（TLS 校验所需），镜像面积极小，攻击面同步收敛。

3.3 Python/Django 多阶段 Dockerfile

FROM python:3.12-slim AS builder
WORKDIR /app
RUN pip install --no-cache-dir uv
COPY requirements.txt .
RUN uv pip install --system --no-cache -r requirements.txt

FROM python:3.12-slim AS runner
WORKDIR /app

RUN useradd -r -u 1001 appuser
USER appuser

COPY --from=builder /usr/local/lib/python3.12/site-packages /usr/local/lib/python3.12/site-packages
COPY --from=builder /usr/local/bin /usr/local/bin
COPY . .

ENV PYTHONUNBUFFERED=1
EXPOSE 8000

HEALTHCHECK --interval=30s --timeout=3s CMD python -c "import urllib.request; urllib.request.urlopen('http://localhost:8000/health/')" || exit 1
CMD ["gunicorn", "config.wsgi:application", "--bind", "0.0.0.0:8000", "--workers", "4"]

要点解读：

• builder 阶段用 uv 替代 pip 做依赖安装（速度快、缓存友好），--system 把包装进基础镜像的系统 Python 环境，runner 阶段只需整体拷贝 site-packages 与 /usr/local/bin（gunicorn 等入口）；
• PYTHONUNBUFFERED=1 保证日志实时刷出，避免容器日志采集出现延迟/缺行；
• 健康检查直接用 python -c + urllib 发起 HTTP 请求，不依赖镜像内的 curl/wget；
• gunicorn --workers 4 是示例值，生产应按 CPU 核数与并发模型调整。

3.4 Docker 最佳实践清单

原文以 GOOD/BAD 对照给出 7 条实践，完整继承：

# GOOD practices
- Use specific version tags (node:22-alpine, not node:latest)
- Multi-stage builds to minimize image size
- Run as non-root user
- Copy dependency files first (layer caching)
- Use .dockerignore to exclude node_modules, .git, tests
- Add HEALTHCHECK instruction
- Set resource limits in docker-compose or k8s

# BAD practices
- Running as root
- Using :latest tags
- Copying entire repo in one COPY layer
- Installing dev dependencies in production image
- Storing secrets in image (use env vars or secrets manager)

3.5 仓库佐证：ECC 自身 Dockerfile 如何落地这些实践

ECC 仓库的 docker/plugin-setup/Dockerfile 是上述实践的"加强版"参照，可以逐条对照：

• 比固定 tag 更严：按 digest 钉死镜像。该 Dockerfile 前两行用 ARG NODE_IMAGE=node:22-bookworm-slim@sha256:6c74...（见 Dockerfile#L1-L2）——即通过内容摘要而非 tag 引用基础镜像，从根本上杜绝 tag 被移动/重打导致的构建不可复现；
• 多阶段隔离运行时：FROM ${NODE_IMAGE} AS node-runtime 后以第二个 FROM ${OS_IMAGE} 起新阶段，仅 COPY --from=node-runtime /usr/local/ /usr/local/（Dockerfile#L4-L18）把 Node 运行时拷入 Debian/Ubuntu 基座，实现跨发行版的同一套测试镜像；
• 非 root 运行：USER 1000:1000（Dockerfile#L42），并且用 getent passwd 1000 断言该用户存在，把"以非特权用户运行"从约定变成构建期硬校验；
• 版本钉死 + 缓存清理：全局安装的 @anthropic-ai/claude-code@2.1.220 等包全部显式版本号，随后 npm cache clean --force 清理层内缓存（Dockerfile#L23-L31）。

配套的 docker/plugin-setup/compose.yaml 则展示了"设置资源限制与运行约束"这条实践的具体形态。其 x-real-cli 锚点（compose.yaml#L5-L16）对容器做了完整加固：

network_mode: none        # 默认完全断网
read_only: true           # 根文件系统只读
pids_limit: 256           # 限制进程数，防 fork 炸弹
cap_drop: [ALL]           # 丢弃全部 Linux capabilities
security_opt:
  - no-new-privileges:true
tmpfs:
  - /tmp:rw,...,size=2g    # 仅挂载受限 tmpfs 作可写区

real-cli 服务复用该锚点并在 compose.yaml#L62-L72 中通过 build.args 把带 digest 的 NODE_IMAGE 传入 Dockerfile，同时 real-cli-ubuntu 服务（compose.yaml#L81-L91）用 Ubuntu 24.04 基座构建同构镜像——这正是"部署策略"一节的跨环境一致性思路在测试侧的应用。

四、CI/CD 管道搭建

4.1 标准 GitHub Actions 管道

原文给出的三阶段（test → build → deploy）标准管道完整继承：

name: CI/CD

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
          cache: npm
      - run: npm ci
      - run: npm run lint
      - run: npm run typecheck
      - run: npm test -- --coverage
      - uses: actions/upload-artifact@v4
        if: always()
        with:
          name: coverage
          path: coverage/

  build:
    needs: test
    runs-on: ubuntu-latest
    if: github.ref == 'refs/heads/main'
    steps:
      - uses: actions/checkout@v4
      - uses: docker/setup-buildx-action@v3
      - uses: docker/login-action@v3
        with:
          registry: ghcr.io
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}
      - uses: docker/build-push-action@v5
        with:
          push: true
          tags: ghcr.io/${{ github.repository }}:${{ github.sha }}
          cache-from: type=gha
          cache-to: type=gha,mode=max

  deploy:
    needs: build
    runs-on: ubuntu-latest
    if: github.ref == 'refs/heads/main'
    environment: production
    steps:
      - name: Deploy to production
        run: |
          # Platform-specific deployment command
          # Railway: railway up
          # Vercel: vercel --prod
          # K8s: kubectl set image deployment/app app=ghcr.io/${{ github.repository }}:${{ github.sha }}
          echo "Deploying ${{ github.sha }}"

结构要点：

• test 先行：lint → typecheck → 带覆盖率的测试，覆盖率产物用 if: always() 上传，失败也能回看；
• build 与 deploy 均限定 main 分支，且经 needs 形成严格依赖链；镜像以 commit SHA 打 tag（${{ github.sha }}），保证制品与代码提交一一对应——这也是后文"瞬时回滚"的前提；
• deploy 使用 environment: production：GitHub Actions 的环境级保护（如审批人、等待窗口）在此生效；
• 末尾注释给出三种平台（Railway / Vercel / K8s）的部署命令形态，按实际托管替换即可。

4.2 管道阶段划分

原文的两条流水线阶段链：

PR opened:
  lint → typecheck → unit tests → integration tests → preview deploy

Merged to main:
  lint → typecheck → unit tests → integration tests → build image → deploy staging → smoke tests → deploy production

PR 阶段止步于预览部署（低成本快速反馈）；主干阶段多了"镜像构建 → 预生产部署 → 冒烟测试 → 生产部署"，smoke tests 是生产上线前的最后一道门禁。

4.3 仓库佐证：ECC 自身的 CI 与发布工作流

ECC 仓库的 .github/workflows/ci.yml 可看作上述标准管道的工程化加强，其中几处做法值得对照学习：

• 矩阵化测试：test 作业在 os × node × 包管理器 三维矩阵上跑（ubuntu/windows/macos × Node 18/20/22 × npm/pnpm/yarn/bun，并用 exclude 排除 bun-on-Windows，见 ci.yml#L25-L34），测试入口是 tests/run-all.js；
• Action 按完整 commit SHA 钉版本，如 actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0（ci.yml#L38），并配 persist-credentials: false，防止第三方 action 拿到推送凭据——这是对 4.1 示例中 @v4 这类 tag 引用更进一步的供应链加固；
• 最小权限与去重：工作流顶层 permissions: contents: read 与 concurrency（同 ref 取消旧运行，见 ci.yml#L10-L17）；
• 组件校验门禁：validate 作业依次执行 agents/hooks/commands/skills/安装清单/workflow 安全/rules/目录计数/命令注册表等 10 项校验（ci.yml#L179-L240）；
• 安全扫描作为一等作业：security 作业运行 npm audit signatures 与 npm audit --omit=dev --audit-level=high（生产依赖 high 级漏洞即阻断），再跑供应链 IOC 扫描（ci.yml#L289-L297），对应生产就绪清单中"Dependencies scanned for CVEs"一项；
• 失败取证：矩阵测试失败时上传 tests/ 目录制品（ci.yml#L101-L109），coverage 作业与 4.1 示例一致地 if: always() 上传覆盖率报告（ci.yml#L321-L326）。

发布侧，.github/workflows/release.yml 展示了"发布即部署"的守门细节，与"回滚策略"一节呼应：

• 要求发布提交恰好等于 origin/main（release.yml#L30-L38），杜绝从游离分支打 tag 发布；
• tag 格式校验（vX.Y.Z 或预发布格式，release.yml#L55-L60）与 package.json 版本和 tag 一致性校验（release.yml#L64-L74）；
• 发布前同样执行供应链 IOC 扫描（release.yml#L49-L50）。

从这套结构看，ECC 的主干流程正是 4.2 中"Merged to main"阶段链的变体：PR 触发 CI，tag 触发发布校验与打包。

五、健康检查

5.1 健康检查端点

原文给出"简单 + 详细"两级端点：

// Simple health check
app.get("/health", (req, res) => {
  res.status(200).json({ status: "ok" });
});

// Detailed health check (for internal monitoring)
app.get("/health/detailed", async (req, res) => {
  const checks = {
    database: await checkDatabase(),
    redis: await checkRedis(),
    externalApi: await checkExternalApi(),
  };

  const allHealthy = Object.values(checks).every(c => c.status === "ok");

  res.status(allHealthy ? 200 : 503).json({
    status: allHealthy ? "ok" : "degraded",
    timestamp: new Date().toISOString(),
    version: process.env.APP_VERSION || "unknown",
    uptime: process.uptime(),
    checks,
  });
});

async function checkDatabase(): Promise<HealthCheck> {
  try {
    await db.query("SELECT 1");
    return { status: "ok", latency_ms: 2 };
  } catch (err) {
    return { status: "error", message: "Database unreachable" };
  }
}

设计意图：

• /health（liveness 用）：无依赖、恒定 200，回答"进程是否活着"。探针不应依赖数据库等外部组件，否则 DB 抖动会连带重启实例、放大故障；
• /health/detailed（内部监控用）：逐项探测数据库、Redis、外部 API，任一失败返回 503 且 status 为 "degraded"，并附带版本、uptime 与逐项检查明细，供告警与排障使用；
• 单项检查以 try/catch 兜底，探测函数本身不允许抛穿到框架层。

5.2 Kubernetes 三探针

livenessProbe:
  httpGet:
    path: /health
    port: 3000
  initialDelaySeconds: 10
  periodSeconds: 30
  failureThreshold: 3

readinessProbe:
  httpGet:
    path: /health
    port: 3000
  initialDelaySeconds: 5
  periodSeconds: 10
  failureThreshold: 2

startupProbe:
  httpGet:
    path: /health
    port: 3000
  initialDelaySeconds: 0
  periodSeconds: 5
  failureThreshold: 30    # 30 * 5s = 150s max startup time

三者分工：

• startupProbe：启动期唯一生效的探针，failureThreshold: 30 × periodSeconds: 5 = 150s 给慢启动应用留出上限窗口；启动成功后让位给另两个探针；
• readinessProbe：决定实例是否接收流量。失败只摘流量、不重启——与 5.1 中"liveness 探针不打外部依赖"的原则一致；
• livenessProbe：失败触发容器重启，周期更长（30s）、容忍更多连续失败（3 次），避免误杀。

六、环境配置：十二要素与启动期校验

6.1 十二要素应用模式

配置全部走环境变量、绝不入代码：

# All config via environment variables — never in code
DATABASE_URL=postgres://user:pass@host:5432/db
REDIS_URL=redis://host:6379/0
API_KEY=${API_KEY}           # injected by secrets manager
LOG_LEVEL=info
PORT=3000

# Environment-specific behavior
NODE_ENV=production          # or staging, development
APP_ENV=production           # explicit app environment

要点：连接串统一为 URL 形态（DATABASE_URL/REDIS_URL），密钥由 secrets manager 注入而非写死，NODE_ENV 与显式的 APP_ENV 区分运行时状态与应用环境语义。

6.2 启动期配置校验（fail fast）

import { z } from "zod";

const envSchema = z.object({
  NODE_ENV: z.enum(["development", "staging", "production"]),
  PORT: z.coerce.number().default(3000),
  DATABASE_URL: z.string().url(),
  REDIS_URL: z.string().url(),
  JWT_SECRET: z.string().min(32),
  LOG_LEVEL: z.enum(["debug", "info", "warn", "error"]).default("info"),
});

// Validate at startup — fail fast if config is wrong
export const env = envSchema.parse(process.env);

要点：

• 进程启动时一次性 parse：配置缺失或非法（如 JWT_SECRET 少于 32 字符、DATABASE_URL 不是合法 URL）立即崩溃，把"配置错误"消灭在部署阶段而非运行时随机报错——这与 3.1 节 Dockerfile 中 HEALTHCHECK 的配合是：配置错误会导致容器反复重启并被编排系统暴露出来；
• 有合理缺省的值（PORT 默认 3000、LOG_LEVEL 默认 info）用 .default()，没有缺省的（密钥、连接串）强制显式提供。

七、回滚策略

7.1 瞬时回滚命令

# Docker/Kubernetes: point to previous image
kubectl rollout undo deployment/app

# Vercel: promote previous deployment
vercel rollback

# Railway: redeploy previous commit
railway up --commit <previous-sha>

# Database: rollback migration (if reversible)
npx prisma migrate resolve --rolled-back <migration-name>

命令成立的前提在 4.1 节已经埋下：镜像按 SHA 打 tag 且旧 tag 保留，rollout undo 才能找到上一个镜像。数据库回滚单独列出是因为它是回滚中最容易出错的环节——只有可逆迁移才能安全回退，且 Prisma 场景下需要 migrate resolve --rolled-back 把迁移状态对齐。

7.2 回滚检查清单

• [ ] 上一个镜像/制品可用且已打 tag
• [ ] 数据库迁移向后兼容（无破坏性变更）
• [ ] 特性开关可在不重新部署的情况下关闭新功能
• [ ] 已为错误率飙升配置监控告警
• [ ] 回滚已在 staging 演练过再上生产

其中"迁移向后兼容"是滚动/蓝绿策略的共同前提：新旧版本实例会共存，drop column 这类破坏性变更会使旧版本实例报错。

八、生产就绪检查清单

原文 "Production Readiness Checklist" 按五个维度给出发布门禁，完整继承。任何一项不满足，发布都应被推迟。

8.1 应用

• [ ] 全部测试通过（单元、集成、E2E）
• [ ] 代码与配置文件中无硬编码密钥
• [ ] 错误处理覆盖所有边界情况
• [ ] 日志为结构化（JSON）且不包含 PII
• [ ] 健康检查端点返回有意义的状态

8.2 基础设施

• [ ] Docker 镜像可复现构建（版本钉死）
• [ ] 环境变量已文档化并在启动时校验
• [ ] 已设置资源限制（CPU、内存）
• [ ] 已配置水平扩缩容（最小/最大实例数）
• [ ] 所有端点启用 SSL/TLS

对照仓库：第 1、2 项分别对应 3.5 节的 digest 钉死（Dockerfile#L1-L2）与 6.2 节的启动期 Zod 校验；第 3 项对应 compose.yaml#L9 的 pids_limit 与 tmpfs 尺寸约束等资源限制形态。

8.3 监控

• [ ] 导出应用指标（请求速率、延迟、错误）
• [ ] 为错误率超阈值配置告警
• [ ] 日志聚合已就位（结构化日志、可检索）
• [ ] 健康端点有可用性监控

8.4 安全

• [ ] 依赖已扫描 CVE
• [ ] CORS 仅配置允许的源
• [ ] 公共端点启用限流
• [ ] 认证与授权已验证
• [ ] 安全响应头已设置（CSP、HSTS、X-Frame-Options）

ECC 的 CI 将其中第一项工程化为 ci.yml#L289-L297 的 security 作业（audit + IOC 扫描），且同样的 IOC 扫描在 release.yml#L49-L50 发布前复跑一遍，形成"CI 与发布双门禁"。

8.5 运维

• [ ] 回滚方案已文档化并演练过
• [ ] 数据库迁移已在生产规模数据上测试
• [ ] 常见故障场景有 Runbook
• [ ] 值班轮转与升级路径已定义

九、小结

本文以 ECC 的部署模式技能文档为主线，完整继承了其发布策略、Docker 多阶段构建、CI/CD 管道、健康检查、环境配置、回滚与生产就绪检查清单的全部实操内容，并结合仓库内真实实现做了纵深印证：docker/plugin-setup/Dockerfile 展示了 digest 级镜像钉死与非 root 硬校验，docker/plugin-setup/compose.yaml 展示了断网、只读文件系统、capability 全丢弃等运行加固，.github/workflows/ci.yml 与 .github/workflows/release.yml 展示了矩阵测试、SHA 钉版本的 Action、供应链扫描与发布守门。这套文档给出的是"应然"模板，仓库自身实现是"实然"参照——两者对照使用，即可把部署基础设施从原则落到可执行配置。