# 部署与运维最佳实践

本指南旨在建立标准化的部署与运维体系，覆盖从环境规划、容器编排到上线策略及日常监控的全生命周期管理，确保系统的稳定性、可观测性与持续迭代能力。

基础部署与监控基线见 `docs/13-ops-deployment.md`，本文侧重可落地的最佳实践与治理细节。

## 1. 部署架构与环境规划

为保障开发效率与生产稳定性，采用分层环境架构，并基于 Kubernetes 进行统一编排。

### 1.1 环境分层策略

| 环境 | 标识 | 用途 | 配置策略 |
| --- | --- | --- | --- |
| 生产环境 | PROD | 面向最终用户，高可用保障 | 严格隔离，配置加密，多副本 |
| 预发环境 | STAGING | 上线前的模拟演练，数据脱敏 | 1:1 仿真生产配置与网络 |
| 测试环境 | TEST/QA | 功能测试与集成测试 | 快速迭代，资源配额限制 |

### 1.2 容器编排与基础设施

- 配置与密钥管理
  - ConfigMap：分离应用配置，禁止硬编码。
  - Secret：敏感数据(API Token, DB Password)必须加密存储。
  - 版本化：配置变更需随代码一同提交至 Git(GitOps)。
- 网络与存储
  - Ingress：统一流量入口，配置 TLS 证书。
  - Service Mesh：用于复杂的微服务间通信与治理。
  - PVC/PV：状态数据(如日志、DB)必须挂载持久化存储。

## 2. 上线策略与版本管理

采用分阶段发布策略以最小化风险，并结合 API 进行自动化版本记录。

### 2.1 发布模式对比

| 策略 | 原理 | 适用场景 | 回滚速度 |
| --- | --- | --- | --- |
| 滚动发布 | 逐批替换 Pod (K8s Default) | 常规迭代，资源有限 | 中(需逐批回退) |
| 蓝绿发布 | 新旧版本并存，流量切换 | 重大版本升级，资源充足 | 快(切回旧路由) |
| 灰度发布(Canary) | 引入少量流量至新版本验证 | 高风险功能，依赖真实流量验证 | 快(切断灰度流量) |

### 2.2 灰度发布流程

1) 基准部署：部署 Canary 版本，初始流量权重设为 0%。
2) 流量切分：调整 Ingress/Service Mesh 权重至 5%，观察 Error Rate。
3) 逐步放量：若指标正常，按 20% -> 50% -> 100% 逐步提升。
4) 快速回滚：若触发告警，立即将 Canary 权重置零并下线。

### 2.3 迭代版本记录

发布后的迭代登记统一走知识库文档系统接口：
- 接口与鉴权：`docs/18-docs-rest-api.md`
- 迭代记录模板：`docs/21-iteration-template.md`

## 3. 监控与日志实践

建立多维度的可观测性体系，确保在故障发生前及时预警。

### 3.1 关键监控指标

| 维度 | 指标名称 | 定义与阈值 |
| --- | --- | --- |
| 可用性 | 采集成功率 / 失败率 | 请求 HTTP 5xx 比例 < 0.1% |
| 性能 | 延迟(Latency) | P95 < 200ms, P99 < 500ms |
| 数据质量 | 重复率 / 覆盖率 | 数据处理任务的幂等性与完整性校验 |
| 资源 | 容量与成本 | CPU/Mem 使用率 < 70%，闲置资源回收 |

### 3.2 日志与告警策略

- 日志结构化：应用日志必须输出为 JSON 格式，并包含 trace_id 以便全链路追踪。高并发服务建议开启动态采样。

```json
{"level":"ERROR","trace_id":"x-123","msg":"DB timeout"}
```

- 告警分级与抑制
  - P0：核心业务中断(如无法支付)，SLA 响应 < 5min。
  - P1：非核心功能受损，SLA 响应 < 30min。
  - 抑制机制：配置告警分组与静默，避免风暴。

## 4. 运维日常与持续改进

运维不仅是救火，更是通过制度化流程提升系统韧性。

- 变更管理：所有生产变更遵循 Change Request 流程，明确操作步骤、回滚方案及审批记录。
- SLA 报告：每月输出 SLA 报告，统计可用性(如 99.9%)与 MTTR(平均修复时间)。
- 事故复盘：P1 以上故障必须进行无责复盘(Post-mortem)，产出改进项并跟进闭环。

## 5. 关联文档

- `docs/13-ops-deployment.md`：运维与部署基线
- `docs/29-security-compliance-cost.md`：安全合规与成本/容灾策略