分步骤指南撰写

标准分步骤指南：新功能上线、代码合并与紧急回退

一、目的与适用范围
- 目的：确保新功能上线过程可控、可追溯、可回退，降低业务与技术风险。
- 适用范围：涉及应用服务、后端接口、前端、数据库、配置与基础设施的变更；覆盖预检、审批、灰度、发布、验证与回退的全流程。
- 参与角色：研发（开发、架构）、QA、发布经理/变更经理、SRE/运维、产品/业务方、安全与合规。

二、术语与原则
- 灰度/金丝雀发布：将新版本逐步暴露给少量实例/用户/区域，依据指标放量或终止。
- 回退/回滚：将系统恢复至变更前可用状态（可通过关停特性开关、回滚镜像/包、回滚配置、回滚数据库变更等方式实现）。
- 关键原则：
  - 一次变更只做一类风险可控的改动，保持可观测、可回退。
  - 所有变更必须具备明确的回退方案和触发条件。
  - 数据库变更遵循向后兼容与“扩展-迁移-收缩（expand-migrate-contract）”策略。
  - 在业务低峰与批准的变更窗口内操作，保持沟通同步。

三、前置检查（必备质量门）
1) 代码与分支
- 变更集中在功能分支；禁止直接向主分支提交。
- 与主分支同步最新基线，解决冲突并通过本地构建。
- 遵循代码规范检查（静态扫描、lint）无阻断级问题。

2) 测试与质量
- 单元测试覆盖核心逻辑，新增代码行覆盖率达到团队阈值（如≥80%，视团队标准为准）。
- 集成/契约测试通过；关键对外接口有契约或Mock验证。
- 回归测试覆盖受影响模块；无阻塞缺陷（Severity 1/2）。
- 性能基准对比无显著退化（如P95延迟、吞吐、CPU/内存）。
- 安全扫描通过（依赖漏洞、SAST/DAST），无高危未处置项。

3) 架构与兼容性
- 向后兼容：接口和消息格式加字段不删字段；老客户端可正常工作。
- 数据库变更设计有双读/双写或后台迁移方案；禁止在同一版本中做破坏性删除。
- 依赖版本与系统约束（JDK/Node/OS等）满足目标环境。

4) 运维与发布准备
- 构建产物唯一、可追踪（版本号/Commit SHA），存入制品库。
- 部署参数、配置、密钥已准备并纳入配置管理；敏感信息不入仓。
- 监控与日志：为新功能/新端点配置指标、日志、告警规则（错误率、延迟、CPU、OOM、饱和度等）。
- 健康检查/存活探针/就绪探针实现并本地验证。
- 预设熔断/限流策略，避免放量时冲击核心依赖。

5) 文档与沟通
- 变更说明（变更目的、影响范围、风险等级、发布与回退计划、负责人、时窗）。
- 运维Runbook（发布步骤、验证步骤、回退步骤、联系方式）。
- 用户影响与客服预案（如有外显变更），必要时准备公告与FAQ。

四、审批流程
1) 风险评估与分级
- 依据影响范围、数据风险、可回退性、业务峰谷期评估为低/中/高。
- 高风险需架构/安全/变更委员会（CAB）联合审批。

2) PR与变更单审批
- PR需至少两名代码所有者评审通过，CI全绿，无未解讨论。
- 变更单包含：版本信息、依赖项、拓扑影响、灰度策略、回退方案、验证清单、值守安排。
- 变更窗口与冻结策略确认（如大促前冻结）。

五、代码合并（主干或发布分支）
1) 分支策略
- 主干开发（Trunk-based）或GitFlow均可；发布需基于发布分支/Tag。
- 合并策略：建议Squash或Rebase保持线性历史；禁止强推主分支。

2) 合并步骤
- 将功能分支变更合并入发布分支，解决冲突并重跑全量CI。
- 打版本Tag（遵循语义化版本，如MAJOR.MINOR.PATCH），生成发布说明。
- 锁定制品（不可变版本），禁止合并后修改同一版本内容。

六、灰度发布（金丝雀）
1) 策略与范围
- 维度：实例/节点、区域/机房、用户分群（内测、员工、少量真实用户）。
- 起始流量：1%-5%实例或小分区；分阶段：1% → 5% → 10% → 25% → 50% → 100%。
- 使用特性开关控制新功能显隐，确保可随时关闭。

2) 执行步骤
- 部署至灰度环境/小规模生产实例，启用只读或最小写入路径（如可行）。
- 启动观察期（例如15-30分钟/阶段，或覆盖关键业务周期）。
- 监控关键SLO/SLA与守门指标：
  - 技术：错误率、P95/P99延迟、失败请求数、CPU/内存、重启次数、队列长度、GC、依赖服务错误。
  - 业务：下单成功率、转化率、活跃度、退款率异常。
- 阈值示例（按团队SLO设定）：5xx错误率不高于基线+0.1%，P95延迟不超过基线+10%，依赖错误不升高。
- 指标达标则放量至下一阶段；不达标立即暂停放量并执行回退或关闭特性开关。

3) 自动化保护
- 设置自动回退触发器（阈值+观测窗口+冷却时间）。
- 发布平台需支持一键停止/回滚与实时开关切换。

七、正式发布（全面放量）
1) 部署策略
- 推荐滚动发布或蓝绿/影子发布；对无状态服务优先滚动，状态ful服务评估连接耗尽与会话迁移。
- 数据库变更分步执行：先扩展（加列/加索引）→ 应用读写兼容逻辑上线 → 数据迁移任务 → 收缩（删除旧字段/路径）在后续版本执行。
- 确保配置与密钥按环境加载正确，启用就绪探针以防流量进入未就绪实例。

2) 执行要点
- 在批准的变更窗口内操作，相关方在场值守（研发+SRE+QA）。
- 灰度阶段通过后，逐步扩大到全量；过程保持监控面板与日志聚合实时查看。
- 如需短暂停机（极少数场景），提前公告与倒计时。

八、发布后验证（生产验收）
1) 技术验证
- 自动化Smoke测试通过（核心路径：登录、下单、支付、查询等）。
- 健康检查全部绿；告警无新增或不超过阈值。
- 日志无大量新错误类别；异常堆栈为预期内。

2) 业务验证
- 关键KPI在观察窗口内回归基线区间；AB对照无显著负面差异。
- 功能验收用例完成，产品与业务确认通过。

3) 关闭动作
- 更新变更单为已完成，保存监控截图与指标对比。
- 更新用户/运维文档，记录版本特性与已知问题。

九、紧急回退（故障处置）
1) 触发条件（任一满足立即评估，超出阈值立即回退）
- 大面积5xx/错误率飙升、核心接口超时、容量耗尽。
- 关键业务KPI异常（下单/支付/登录失败率明显上升）。
- 安全事件或数据一致性风险。
- 无法在设定RTO内修复或风险不可控。

2) 回退类型与优先级
- 首选：关闭特性开关（即时，低风险）。
- 快速：回滚配置（恢复上一版本配置/阈值/路由）。
- 应用回滚：回退至上一个已知稳定版本的镜像/包。
- 数据库回退：
  - 优先设计为“前滚修复”（热修复或补丁）以避免数据丢失。
  - 如必须回退，确保有备份/快照，评估数据回放/补偿方案。
  - 严禁在无备份与验证情况下执行破坏性回退。

3) 回退步骤
- 立即冻结进一步放量或部署，广播故障与回退决定（频道：发布群/事件频道）。
- 执行已预演的回退Runbook（脚本化、一键化优先）。
- 验证：
  - 技术指标回归基线；错误与延迟恢复。
  - 业务核心路径恢复；无新告警。
- 记录事件时间线、影响范围与临时缓解措施。
- 根据需要发布对外公告与客服口径。

4) 回退后的善后
- 启动事后复盘（Postmortem），在约定时限内产出报告（无责文化）。
- 问题分类：根因、促发因素、探测缺口、流程缺口。
- 行动项：测试补齐、监控告警优化、发布策略调整、文档与Runbook更新。

十、记录与合规
- 变更记录：版本、时间、批准人、操作人、步骤、结果、回退与验证证据。
- 审计要求：保留构建产物、日志、审批与事故记录，满足合规与可追溯性。
- 指标沉淀：发布成功率、平均恢复时间（MTTR）、变更失败率、交付频率等，用于持续改进。

附：简要检查清单（可转化为表单/自动化门禁）
- 代码与测试：CI全绿；覆盖率达标；安全与依赖扫描无高危；契约/集成测试通过。
- 发布准备：制品可追踪；配置与密钥就绪；监控与告警到位；Runbook与变更单完整。
- 审批：风险分级完成；相关角色签署；变更窗口确认。
- 灰度：特性开关可控；放量计划与阈值明确；自动回退触发配置完成。
- 正式发布：部署策略选择正确；数据库迁移分步；值守到位。
- 验证：Smoke用例通过；技术与业务指标达标；文档更新。
- 回退：触发条件明确；一键回退可用；备份与恢复演练通过；复盘计划安排。

说明
- 本指南为通用规范，需结合贵司工具链（CI/CD平台、监控与A/B平台、工单与审批系统）映射为具体流程与自动化规则。
- 高风险变更需提前演练回退；数据库与状态ful系统需重点预案与双活/只读策略评估。

分步骤指南：微服务网关的安装与基础配置，并集成用户认证模块（基于 Traefik + OAuth2 Proxy + 任意 OIDC 身份提供商）

目标与适用范围
- 目标：在通用主机环境使用 Docker Compose 搭建微服务网关，完成基础路由、上游服务注册、健康检查与 TLS 可选配置，并以 OpenID Connect（OIDC）为基础，集成用户认证模块，实现对后端服务的统一登录拦截与身份透传。
- 对象：熟悉 Linux 命令行、Docker/Compose 基础的工程师。
- 选型说明：
  - 网关：Traefik v2（开源、轻量、支持 ForwardAuth 中间件，适合与 OAuth2 Proxy 组合实现 OIDC 登录）。
  - 认证模块：OAuth2 Proxy（开源，支持 OIDC，常与 Traefik/NGINX 等网关集成）。
  - 身份提供商（IdP）：任一 OIDC 兼容实现（如 Keycloak、Auth0、Okta、Azure AD、Google 等）。

第1章 架构与工作流概述
- 组件与职责
  - Traefik：作为微服务网关，负责 L7 路由、反向代理、转发至上游、插入中间件（ForwardAuth、错误处理）。
  - OAuth2 Proxy：负责与 OIDC 身份提供商交互（登录、回调、会话管理），向网关提供“是否已登录”的判定接口，并在认证通过时回传用户标识头部。
  - 身份提供商（IdP）：授权服务器，颁发 ID Token/Access Token，提供 OIDC 发现与 JWK 验签能力。
- 请求流程（浏览器为例）
  1) 用户访问网关公开域名（如 http://app.localhost）。
  2) Traefik 对该路由附加 ForwardAuth，中间件请求 OAuth2 Proxy 的 /auth 接口进行认证判定。
  3) 未登录时，/auth 返回 401；Traefik 错误处理中间件将 401 转发至 OAuth2 Proxy 的 /oauth2/start，触发 302 重定向至 IdP 登录页。
  4) 登录成功后，IdP 回调到 /oauth2/callback，OAuth2 Proxy 建立会话 Cookie，再次访问时 /auth 返回 202（已认证）。
  5) Traefik 放行至上游服务，并可透传 X-Auth-Request-Email 等用户信息头部。

第2章 前置条件
- 软件与环境
  - Docker ≥ 20.x，Docker Compose v2（compose 命令可用）
  - 一个可用的 OIDC 应用配置（从 IdP 管理台创建），需具备：
    - 客户端 ID、客户端密钥（Client ID/Secret）
    - 发行者地址（Issuer URL，例如 https://<idp>/realms/<realm>）
    - 回调地址（Redirect URI），形如：http://app.localhost/oauth2/callback
- 域名与网络
  - 开发环境可使用 app.localhost（系统解析到 127.0.0.1）
  - 暴露端口：80（可选 443）
- 机密与安全
  - 生成 32 字节随机 Cookie Secret（Base64 编码）。示例：
    - Linux/macOS：head -c 32 /dev/urandom | base64

第3章 安装网关（Traefik）与演示上游服务
步骤1：创建工作目录与网络
- mkdir -p ~/micro-gateway && cd ~/micro-gateway
- docker network create web

步骤2：编写 docker-compose.yml
- 将以下内容保存为 docker-compose.yml。请替换占位符：
  - OIDC_ISSUER_URL：OIDC 发行者地址（末尾保留斜杠或按 IdP 指南配置）
  - OIDC_CLIENT_ID、OIDC_CLIENT_SECRET：IdP 发放
  - OAUTH2_PROXY_COOKIE_SECRET：前述生成的 Base64 机密

version: "3.8"
services:
  traefik:
    image: traefik:v2.11
    command:
      - --providers.docker=true
      - --providers.docker.exposedbydefault=false
      - --entrypoints.web.address=:80
      - --api.dashboard=true
      # 开发环境可启用不安全 Dashboard 便于观察（生产禁用）：
      # - --api.insecure=true
    ports:
      - "80:80"
      # 开发环境观察 Dashboard 可启用： - "8080:8080"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
    networks:
      - web

  # 演示上游服务（回显请求），可替换为你的微服务
  whoami:
    image: traefik/whoami:v1.10
    networks:
      - web
    labels:
      - traefik.enable=true
      # 路由规则：以 Host 头部匹配
      - traefik.http.routers.app.rule=Host(`app.localhost`)
      - traefik.http.routers.app.entrypoints=web
      # 绑定认证与错误重定向中间件（在下方定义）
      - traefik.http.routers.app.middlewares=auth,auth-redirect
      - traefik.http.services.app.loadbalancer.server.port=80

      # ForwardAuth 中间件，指向 oauth2-proxy 的 /auth
      - traefik.http.middlewares.auth.forwardauth.address=http://oauth2-proxy:4180/auth
      - traefik.http.middlewares.auth.forwardauth.trustForwardHeader=true
      # 将认证后的用户信息透传到上游
      - traefik.http.middlewares.auth.forwardauth.authResponseHeaders=X-Auth-Request-User,X-Auth-Request-Email,Authorization

      # 错误处理中间件（401/403 -> 触发登录）
      - traefik.http.middlewares.auth-redirect.errors.status=401-403
      - traefik.http.middlewares.auth-redirect.errors.service=oauth2@docker
      - traefik.http.middlewares.auth-redirect.errors.query=/oauth2/start?rd=%2F

  # OAuth2 Proxy 实例（OIDC）
  oauth2-proxy:
    image: quay.io/oauth2-proxy/oauth2-proxy:v7.6.0
    networks:
      - web
    environment:
      - OAUTH2_PROXY_PROVIDER=oidc
      - OAUTH2_PROXY_OIDC_ISSUER_URL=${OIDC_ISSUER_URL}
      - OAUTH2_PROXY_CLIENT_ID=${OIDC_CLIENT_ID}
      - OAUTH2_PROXY_CLIENT_SECRET=${OIDC_CLIENT_SECRET}
      - OAUTH2_PROXY_COOKIE_SECRET=${OAUTH2_PROXY_COOKIE_SECRET}
      - OAUTH2_PROXY_REDIRECT_URL=http://app.localhost/oauth2/callback
      - OAUTH2_PROXY_EMAIL_DOMAINS=*
      - OAUTH2_PROXY_REVERSE_PROXY=true
      - OAUTH2_PROXY_SET_AUTHORIZATION_HEADER=true
      - OAUTH2_PROXY_PASS_AUTHORIZATION_HEADER=true
      - OAUTH2_PROXY_SKIP_PROVIDER_BUTTON=true
      - OAUTH2_PROXY_UPSTREAM=file:///dev/null
      # 开发环境为 HTTP，生产请改为 true 并使用 HTTPS
      - OAUTH2_PROXY_COOKIE_SECURE=false
      # 可选：限制群组或域，结合 IdP 的 claims 使用
      # - OAUTH2_PROXY_ALLOWED_GROUPS=group-a,group-b
      # - OAUTH2_PROXY_OIDC_GROUPS_CLAIM=groups
    labels:
      - traefik.enable=true
      # 暴露 OAuth2 Proxy 的路由（用于 /oauth2/start 与 /oauth2/callback）
      - traefik.http.routers.oauth2.rule=PathPrefix(`/oauth2`)
      - traefik.http.routers.oauth2.entrypoints=web
      - traefik.http.services.oauth2.loadbalancer.server.port=4180

networks:
  web:
    external: true

步骤3：准备环境变量文件（可选）
- 在同目录创建 .env 文件，填入：
OIDC_ISSUER_URL=https://your-idp.example.com/realms/demo
OIDC_CLIENT_ID=your-client-id
OIDC_CLIENT_SECRET=your-client-secret
OAUTH2_PROXY_COOKIE_SECRET=base64-32bytes-secret

步骤4：启动
- docker compose up -d
- 验证容器状态：docker compose ps
- 本地访问：http://app.localhost
  - 预期：跳转登录（经 /oauth2/start -> IdP 登录页）

第4章 网关基础配置说明
- 路由与服务
  - 以 Host 头匹配路由（Host(`app.localhost`)），指向服务 app。
  - 通过 labels 指定上游服务端口（traefik.http.services.<name>.loadbalancer.server.port）。
- 中间件
  - ForwardAuth：将认证判定外包给 OAuth2 Proxy 的 /auth。
  - Errors：捕获 401/403，转而请求 OAuth2 Proxy 的 /oauth2/start（该端点会返回 302 跳转 IdP）。
- 健康检查与高可用（可选）
  - 基于容器平台健康检查（Docker HEALTHCHECK、Kubernetes readiness）与 Traefik 负载均衡策略结合。
- TLS/HTTPS（生产建议）
  - 可在 Traefik 中启用 websecure entrypoint、证书解析器（Let’s Encrypt），并将路由 entrypoints 从 web 切换到 websecure，设置 HSTS 与安全头。

第5章 集成用户认证模块（OIDC）流程
步骤1：在 IdP 创建 OIDC 应用
- 配置授权类型：Authorization Code（含 PKCE 由 OAuth2 Proxy 代管）
- 回调地址（Redirect URI）：http://app.localhost/oauth2/callback
- 允许的注销/白名单域：localhost 或你的真实域名
- 记录 Issuer、Client ID、Client Secret

步骤2：配置 OAuth2 Proxy
- 使用上文 docker-compose.yml 环境变量或命令行参数完成 OIDC 关联。
- 关键项：
  - OIDC_ISSUER_URL：精确填写 IdP 的发行者地址（可通过 .well-known/openid-configuration 验证）。
  - OAUTH2_PROXY_COOKIE_SECRET：Base64 编码的 32 字节机密，保证会话 Cookie 安全。
  - REDIRECT_URL：与 IdP 应用配置一致。

步骤3：在 Traefik 中启用 ForwardAuth 与错误重定向
- 已在 whoami 中通过 labels 配置：
  - middlewares=auth,auth-redirect
  - auth -> forwardauth.address=http://oauth2-proxy:4180/auth
  - auth-redirect -> errors.status=401-403 -> oauth2@docker /oauth2/start
- 将这些中间件重用到你的业务服务（替换 whoami 为其他服务时，复用相关 labels）。

步骤4：用户信息透传与后端鉴权
- 通过 forwardauth.authResponseHeaders 将用户标识头透传，例如：
  - X-Auth-Request-Email、X-Auth-Request-User、Authorization（如需）
- 后端服务可读取这些头部执行细粒度鉴权（角色、权限映射可在 IdP claims 或网关二次中间件实现）。

步骤5：验证登录流程
- 未登录访问 http://app.localhost -> 跳至 IdP 登录
- 登录后回到 http://app.localhost，whoami 将显示请求头；检查是否包含 X-Auth-Request-Email。
- 使用 curl 验证跳转链路（观察 302）：
  - curl -I http://app.localhost

第6章 验证与排错
- 常见问题与定位
  - 400 invalid redirect_uri：检查 IdP 应用的 Redirect URI 是否与 OAUTH2_PROXY_REDIRECT_URL 完全一致（协议、主机、路径）。
  - 403/401 循环或无法登录：
    - 检查 cookie 域/安全属性（开发环境 cookie_secure=false；生产须启用 HTTPS 与 cookie_secure=true）。
    - 检查时钟同步（容器与宿主时间差会导致 Token 验证失败）。
    - 检查 OIDC_ISSUER_URL 是否准确（应能访问到 {issuer}/.well-known/openid-configuration）。
  - 无法触发登录页：确认 errors 中间件已绑定路由，且 service=oauth2@docker 指向存在的 oauth2-proxy 服务，query=/oauth2/start 正确。
  - 502/404：检查 Docker 网络是否为同一 network（web），服务名称解析是否正确（oauth2-proxy:4180）。

第7章 生产化要点（概要）
- 强制 HTTPS，配置 HSTS、安全响应头（Content-Security-Policy、X-Frame-Options 等）。
- 将 OAuth2 Proxy Cookie 设为 Secure、SameSite=Lax 或 Strict，按业务需要调整。
- 缓存与限流中间件：对高频接口实施速率限制与后端保护。
- 日志与可观测性：开启 Traefik 访问日志；将网关与 OAuth2 Proxy 日志采集到集中平台。
- 灰度与回滚：为关键中间件（认证、重定向）变更预留灰度发布能力。

章节检查清单

检查清单A：环境与前置
- [ ] 已安装 Docker 与 Compose，并可执行 docker compose。
- [ ] 预创建 Docker 网络：web。
- [ ] IdP 中创建了 OIDC 应用，拿到 Issuer、Client ID、Client Secret。
- [ ] 配置 Redirect URI 为 http://app.localhost/oauth2/callback。
- [ ] 生成了 32 字节 Base64 的 Cookie Secret。

检查清单B：网关安装与基础配置
- [ ] Traefik 已启动并监听 80 端口。
- [ ] 上游服务通过 labels 正确暴露（服务端口、路由规则）。
- [ ] 中间件加载正常（auth、auth-redirect 可在日志中看到生效）。
- [ ] 可选：TLS 已配置（生产环境必须启用）。

检查清单C：认证集成
- [ ] OAuth2 Proxy 能访问到 Issuer 的 .well-known/openid-configuration。
- [ ] OAUTH2_PROXY_REDIRECT_URL 与 IdP 配置一致。
- [ ] ForwardAuth 指向 http://oauth2-proxy:4180/auth，并已设置 authResponseHeaders。
- [ ] Errors 中间件已将 401/403 跳转至 /oauth2/start。
- [ ] 登录后可在上游服务看到 X-Auth-Request-Email 或自定义头部。

检查清单D：安全与合规
- [ ] 生产启用 HTTPS 与安全 Cookie（Secure=true，合理的 SameSite）。
- [ ] 令牌与会话机密安全管理（不写入仓库，使用密钥管理服务或机密管理）。
- [ ] 网关与认证日志接入集中审计与告警。
- [ ] 对敏感路径配置额外的访问控制（白名单、基于组/角色的策略）。

附录：关键点释义与替换建议
- 替换演示服务：将 whoami 替换为你的微服务容器，并复用 middlewares=auth,auth-redirect。
- 迁移到 HTTPS：
  - 为 Traefik 增加 entryPoints.websecure=:443、证书解析器（Let’s Encrypt 或自管证书），更新路由 entrypoints=websecure。
  - 将 OAUTH2_PROXY_REDIRECT_URL、IdP 回调地址改为 https。
  - 设置 OAUTH2_PROXY_COOKIE_SECURE=true。
- 非浏览器客户端（API 调用）：
  - 若需要机器到机器认证，建议在网关增加专用路由走 Token 验证（例如使用 oauth2-proxy 的 Bearer Token 验证或在网关侧引入 JWT 验证中间件），与浏览器登录流区分。

至此，你已获得一套可运行的微服务网关安装与基础配置方案，并完成了基于 OIDC 的用户认证模块集成。该方案以开源组件为主，兼顾开发环境可用性与生产环境可扩展性。根据你的实际业务，可逐步接入更多中间件（限流、熔断、重试）与更完善的访问控制策略。

标准作业流程（SOP）：生产环境搭建、监控告警设置、常见故障处置与回滚

一、范围与目标
- 目的：提供在生产环境中可执行、可复用、可审计的标准流程，覆盖环境搭建、监控告警、故障处置与变更回滚，确保稳定性、可观测性与可追踪性。
- 适用对象：平台/运维工程师、后端工程师、SRE、值班与事故响应人员。
- 不在范围：具体供应商或产品的安装细节（可在本 SOP 基础上补充厂商操作手册）。

二、角色与职责
- 变更发起人（Owner）：提出需求、提供验收标准、编写/更新变更文档。
- 执行人（Executor）：按SOP执行落地，记录操作与证据。
- 审批人（Approver）：变更评审与放行。
- 值班工程师（On-call）：告警响应、初步处置与升级。
- 事故指挥（Incident Commander）：重大故障统一调度、决策与沟通。
- 记录员（Scribe）：记录时间线、关键决策与证据。
- 安全负责人（Security）：访问、密钥、安全基线与合规。

三、通用前置条件（适用于文档各部分）
- 变更管理与审批：变更单、回滚方案、风险评估与同意（CAB/审批流）。
- 访问与审计：最小权限（RBAC）、MFA、堡垒机/跳板机，命令审计与会话录制。
- 基线合规：时间同步（NTP）、时区统一、系统安全基线（CIS 等标准）、补丁策略。
- 配置与密钥管理：集中化配置（分环境分密级）、密钥托管（KMS/HSM/Vault）、密钥轮换策略。
- 版本与镜像：不可变镜像/包管理，版本可溯源（SBOM）、镜像签名与策略控制（如策略引擎）。
- 数据保护：备份策略与验证（RPO/RTO）、恢复演练记录、数据加密（静态/传输）。
- 可观测性植入：指标/日志/追踪埋点及上下文（如TraceID）贯通。
- 灰度能力：金丝雀/蓝绿/特性开关具备且可控，支持快速回切。
- 验收标准：SLO/性能基线/功能清单明确，具备自动化验证脚本。

四、SOP 1：生产环境搭建

A. 前置条件
- 已完成容量规划与可用性目标：QPS/吞吐、峰值与增长、SLO（可用性、延迟、错误率）、容灾等级（RPO/RTO）。
- 网络规划与命名规范：VPC/子网/路由/防火墙、安全组、私有与公有出口策略。
- 依赖清单与拓扑：外部服务、数据库、缓存、消息中间件、对象存储、第三方API。
- IaC 模板评审通过（例如使用 Terraform/Ansible 等）；CI/CD 流水线可用且在预生产验证通过。

B. 步骤
1. 基础设施与网络
   - 创建隔离的生产网络边界（VPC/子网/防火墙规则），启用出入站访问白名单。
   - 配置负载均衡、WAF、DDoS 防护、TLS 证书与自动更新。
   - 建立出站代理与依赖服务的私网/专线连接，限制直连公网。

2. 计算与运行时
   - 部署计算集群（VM/Kubernetes/容器服务），启用自动扩缩容与节点污点/亲和调度。
   - 运行时基线：只读根文件系统、最小镜像、非root运行、资源配额与限制、健康探针（liveness/readiness/startup）。

3. 数据层
   - 部署高可用数据库/缓存/消息队列与跨可用区复制。
   - 创建数据库账户分离（只读/读写/管理），启用连接池与超时。
   - 配置自动备份与周期性恢复演练；开启审计与慢查询。

4. 配置与密钥
   - 使用集中配置服务（按环境/应用/版本分层管理），支持灰度与回滚。
   - 密钥采用专用密管服务，应用只获取所需作用域与TTL，启用密钥轮换和吊销。

5. CI/CD 与变更控制
   - 建立从源码到生产的签名链与制品库；启用合并前检查、静态扫描、安全扫描、许可证合规。
   - 配置分阶段发布（预发→金丝雀→全量），发布窗口与变更冻结期明确。
   - 引入自动化回滚钩子（失败阈值触发回滚）。

6. 可观测性
   - 指标：系统（CPU/内存/磁盘/网络）、服务（延迟p95/p99、成功率、吞吐、队列积压）、业务自定义指标。
   - 日志：结构化、集中采集、索引策略与保留周期。
   - 追踪：分布式追踪与上下文传播，采样率与隐私策略。
   - 仪表盘：面向SRE/开发/业务的层级仪表盘与单页概览。

7. 安全与合规
   - RBAC、网络策略、镜像与制品签名策略、CVE 漏洞基线与例外管理。
   - 敏感数据加密与脱敏，日志隐私保护；供应商与第三方访问控制。

8. 演练与文档
   - 进行故障注入或演练：节点故障、依赖超时、流量突增、区域故障切换。
   - 完成运维手册、Runbook、架构图与应急联系列表，纳入知识库。

C. 风险提示
- 未经充分容量与性能验证的上线可能导致连锁故障。
- 缺少最小权限与审计可能造成合规与安全风险。
- 数据备份未做恢复演练等于无备份。

D. 结果验证
- 通过自动化验收：健康检查通过率≥99.9%，关键接口p95 延迟与错误率达SLO。
- 灰度发布期间错误率无显著上升，核心业务链路功能正确。
- 观测性链路闭环：指标、日志、追踪均可查询到跨组件调用。
- 备份可在沙箱环境成功恢复并通过一致性校验。

五、SOP 2：监控与告警设置

A. 前置条件
- 已定义SLO与错误预算，明确服务边界与依赖清单。
- 指标、日志、追踪埋点完成，采集代理/Sidecar/SDK 部署成功。

B. 指标体系与采集
- 系统层：CPU使用率、内存可用、磁盘IOPS/延迟、网络丢包/重传。
- 服务层（四黄金指标）：延迟（p50/p95/p99）、吞吐、错误率、饱和度（线程/连接/队列）。
- 资源利用与容量：实例数、HPA 目标、连接池使用率、队列积压、缓存命中率。
- 业务自定义：下单成功率、支付成功率、库存扣减失败率等。
- 依赖健康：下游API可用性、超时/重试次数、熔断触发率。

C. 日志与追踪
- 统一日志格式与字段（时间、级别、TraceID、Tenant、关键标签）。
- 日志采集与索引分级（热/温/冷），保留周期与脱敏策略。
- 追踪采样策略（关键路径100%，非关键按采样率）。

D. 仪表盘与可视化
- 建立服务总览、依赖拓扑、容量与SLO仪表盘。
- 为告警提供“故障三板斧”仪表盘：近期变更、依赖健康、资源瓶颈快速对比。

E. 告警策略与路由
- 严重级别定义：
  - P1（致命）：影响核心业务或大规模用户；触发电话/IM 持续告警；响应≤5分钟。
  - P2（高）：部分功能受影响；响应≤15分钟。
  - P3（中）：非核心降级或异常趋势；工作时间内处理。
- 告警规则示例（应根据基线与历史校准）：
  - 错误率：5分钟内错误率>2%（P2）、>5%（P1）。
  - 延迟：p95 超出SLO阈值且持续10分钟。
  - 饱和：CPU>85% 且持续15分钟；连接池使用率>90%。
  - 可用性：健康实例数低于期望的80%。
  - 依赖：下游超时比例>3%，重试/熔断持续触发。
- 噪声治理：去重、静默窗口、维护窗口、抑制链（依赖故障抑制上游告警风暴）。
- 路由与升级：按服务/团队/时区/轮班路由；未响应自动升级到上级与IC。

F. 风险提示
- 阈值设置不当导致告警风暴或漏报。
- 未分级路由导致响应延迟。
- 过度采集与高基数标签导致时序库膨胀。

G. 结果验证
- 告警演练：注入故障触发预期级别，验证路由、通知与Runbook链接。
- 噪声基线：告警恢复比≥80%，单事件去重率合理，无长期“红灯常亮”。
- 可见性：从告警一键跳转到相关仪表盘、日志与Trace，MTTI 明显下降。

六、SOP 3：常见故障处置

A. 前置条件
- 值班排班、联络方式与升级路径可用；War-room 通道预置。
- 每类故障有对应Runbook与诊断脚本；最近变更记录可查。

B. 事件响应流程（通用）
1. 触发与分级：收到告警→确认告警有效性→按影响范围分级（P1/P2/P3）。
2. 组建响应：指派IC、Scribe，召集相关服务Owner；建立沟通频道。
3. 止损优先：
   - 启用流量限流/熔断/降级。
   - 将流量回切至稳定版本或减少金丝雀比例。
   - 扩容实例或提升资源配额（若容量不足）。
4. 诊断路径（外到内）：
   - 用户侧：合规模块、入口网关、域名/TLS、错误比例与地域分布。
   - 资源侧：CPU/内存/磁盘/网络、连接池/队列饱和。
   - 应用侧：实例健康探针、线程池、GC、异常堆栈、最近变更。
   - 依赖侧：数据库/缓存/消息/外部API的延迟与错误。
5. 变更回溯：检查过去2–4小时的发布、配置、扩缩容、证书轮换与Schema变更。
6. 升级与协作：超出团队能力或影响扩大时，升级到平台/数据库/网络/安全团队。
7. 恢复与监控：缓解后持续观察关键SLO 30–60分钟；防止反弹。
8. 复盘与记录：产出时间线、根因、影响、度量（MTTA/MTTR）、改进项与负责人。

C. 常见故障场景与处置要点
- CPU/内存/GC 压力：
  - 识别：CPU>85% 或频繁FGC，内存接近上限。
  - 缓解：临时扩容、降低并发、启用缓存/降级；优化JVM参数或限流。
  - 证据：火焰图/堆/线程Dump、热点接口与索引。
- 连接池/队列耗尽：
  - 识别：等待时间长、超时上升、积压增长。
  - 缓解：增加池大小（保守）、短期扩容、优化超时与重试（避免雪崩）。
  - 检查：下游限速/熔断阈值、慢查询。
- 磁盘/文件句柄耗尽：
  - 识别：写失败、日志丢失、系统告警。
  - 缓解：清理日志/索引、提升inode/句柄上限；紧急扩容磁盘。
  - 防范：日志轮转策略、冷热分层。
- 网络/证书问题：
  - 识别：握手失败、重传/丢包、证书过期。
  - 缓解：切换备用证书、降级到健康区域、启用备用链路。
  - 防范：证书到期告警、出入口限速与QoS。
- 数据库性能与锁等待：
  - 识别：慢查询、锁等待、复制延迟。
  - 缓解：加索引、读写分离、热点表分片、临时禁用重负载任务。
  - 防范：变更前执行计划评审与基准测试。
- 第三方依赖故障：
  - 识别：下游超时/错误率上升。
  - 缓解：熔断、降级到缓存/兜底、调整超时与退避重试。
  - 防范：就地缓存与替代供应商预案。
- 发布导致功能性错误：
  - 识别：仅新版本实例异常、错误集中在新代码路径。
  - 缓解：降低金丝雀比例或快速回滚。
  - 验证：回滚后错误率恢复，追踪显示旧版本路径正常。

D. 风险提示
- 盲目扩容或放大超时/重试可能引发雪崩。
- 未经评审的热修或紧急变更可能引入更大风险。
- 信息不对称导致重复操作与冲突，必须保持单一指挥与通道。

E. 关闭与验证
- SLO 恢复并稳定至少30分钟。
- 根因得到佐证（日志/Trace/指标/配置变更），临时措施与长期修复有明确Owner与期限。
- 文档与Runbook已更新；必要时向业务方发布事后通告。

七、SOP 4：回滚

A. 前置条件
- 回滚包或旧版本制品可用且经过预生产验证。
- 数据/配置备份完备，具备一键回切脚本；访问与审批已放行。
- 明确回滚触发阈值与决策人（IC/系统Owner）。

B. 回滚触发条件（满足任一）
- 超出SLO阈值并持续超过观察窗口（如10–15分钟）。
- 核心功能错误或数据错误可被复现且与新变更强相关。
- 发布/配置变更后健康实例数不足或探针失败率高。
- 业务影响达到或逼近P1。

C. 回滚策略
- 应用回滚：按发布环（金丝雀→10%→50%→100%）逆向回切，保留固定健康比例。
- 配置回滚：使用版本化配置服务；原子切换，避免部份实例不一致。
- 数据库回滚：
  - 优先采用可逆“扩展/收缩（expand/contract）”策略，确保向后兼容。
  - Schema 变更与代码解耦：先上兼容Schema，再上代码；回滚时先回代码，再收缩Schema。
  - 数据迁移采用双写/影子表与校验，必要时仅回滚读路径。
- 流量回切：蓝绿切换或将流量权重回切到旧版本，必要时启用维护页。

D. 回滚步骤
1. 决策与冻结：宣布回滚，冻结非必要变更；记录开始时间与影响范围。
2. 数据与配置快照：确认最近备份可用；导出关键配置/特性开关状态。
3. 执行回滚：
   - 应用：按环次逐步回切，观察指标（错误率/延迟/实例健康）。
   - 配置：原子回滚，触发动态刷新；验证一致性。
   - 数据：停止不可逆迁移进程；按预案执行回退或切换只读模式。
4. 验证与解冻：
   - 自动化与手工回归关键用例，检查指标与日志；确认数据完整性。
   - 分阶段解除冻结，保留加强监控窗口（30–60分钟）。
5. 文档与通告：更新变更单状态与回滚报告，向干系人同步。

E. 风险提示
- 数据不可逆更改（删除列/变更语义）可能导致无法完全回滚，需事先采用可逆设计。
- 配置与代码版本错配会引发隐藏故障，必须校验版本矩阵。
- 金丝雀过小可能掩盖问题；过大则扩大影响，需根据业务流量调整。

F. 结果验证
- 关键SLO恢复并稳定；错误率、延迟与资源占用回到基线±10%内。
- 业务关键路径通过回归；追踪显示旧版本路径无异常。
- 数据一致性校验通过（抽样比对、计数校验、哈希校验）。
- 关闭变更单并创建后续修复/改进任务。

八、检查清单（可打印/执行前后勾选）

A. 生产环境搭建检查清单
- [ ] VPC/子网/安全组/路由就绪并审计通过
- [ ] 负载均衡/WAF/TLS 配置完成并自动续期
- [ ] 计算/运行时基线（探针、配额、只读FS、非root）生效
- [ ] 数据库/缓存/消息队列高可用与备份/恢复演练通过
- [ ] 配置中心与密钥管理上线，权限最小化
- [ ] CI/CD、分阶段发布与自动回滚测试通过
- [ ] 指标/日志/追踪采集与仪表盘上线
- [ ] 性能与容量压测通过，SLO/错误预算已定义
- [ ] 安全基线与漏洞扫描无阻塞项
- [ ] Runbook/架构图/应急通讯录归档

B. 监控与告警检查清单
- [ ] 四黄金指标与关键业务指标可见
- [ ] 告警阈值分级合理，具抑制与静默策略
- [ ] 告警路由与升级链路演练通过
- [ ] 告警到仪表盘/日志/Trace 跳转链路可用
- [ ] 存储与索引容量评估通过，成本受控

C. 故障处置检查清单
- [ ] 值班表、IC、Scribe 指派明确
- [ ] 最近变更清单与回滚包可用
- [ ] 止损措施（限流/熔断/降级）可一键启用
- [ ] 跨团队升级机制可用且已演练
- [ ] 复盘模板与知识库可访问

D. 回滚检查清单
- [ ] 回滚触发条件满足并获得批准
- [ ] 旧版本制品与配置版本验证通过
- [ ] 数据/配置快照完成
- [ ] 分阶段回切与监控方案明确
- [ ] 回滚后验证与解冻标准明确

九、度量与持续改进
- 关键度量：变更失败率、平均探测时间（MTTI）、平均响应时间（MTTA）、平均恢复时间（MTTR）、告警噪声率、错误预算消耗率。
- 节奏：每次重大变更后与每月进行一次演练与复盘，持续优化阈值、Runbook 与自动化脚本。

以上SOP可作为组织级模板。建议结合具体技术栈与合规要求补充细化的工具与命令级操作手册，并通过演练迭代。