4. 自愈剧本设计原则：幂等性、可观测性、安全熔断、回滚机制与灰度策略

自愈剧本是 Runbook 联动自动化的核心执行单元。一个生产级自愈剧本必须同时满足五项设计原则，否则在真实故障场景中可能引发二次事故或状态混乱。本章从工程实践角度逐一拆解这些原则的实现要点。

4.1 幂等性：重复执行不产生副作用

幂等性是自愈剧本的基石。当网络抖动、调度器重试或人工干预导致同一剧本被多次触发时，每次执行的结果必须一致，且不会对系统状态造成额外影响。

# 幂等重启示例（伪代码）
def restart_service_if_needed(service_name):
    status = get_service_status(service_name)
    if status == 'running':
        log('Service already running, skip restart')
        return True
    elif status == 'stopped':
        execute('systemctl start ' + service_name)
        return True
    else:
        raise NonIdempotentState('Unexpected status: ' + status)

4.2 可观测性：自愈过程全链路透明

自愈剧本不能成为“黑盒”。运维人员需要实时了解：剧本是否被触发、当前执行到哪一步、每一步的结果是什么、失败原因是什么。可观测性设计应覆盖三个维度：日志、指标、事件。

• 结构化日志：每个步骤输出 JSON 格式日志，包含剧本 ID、触发告警 ID、执行节点、耗时、结果码。
• 关键指标：暴露 Prometheus 指标，如 runbook_execution_total（执行次数）、runbook_duration_seconds（执行耗时）、runbook_success_rate（成功率）。
• 事件通知：剧本开始、成功、失败、熔断时，向统一事件总线发送结构化事件，供下游系统消费。

4.3 安全熔断：防止自愈引发二次故障

自愈剧本本身可能成为故障放大器。当修复操作失败、执行超时、或触发频率过高时，必须立即熔断，避免对系统造成更大破坏。

# 熔断器实现示例
class CircuitBreaker:
    def __init__(self, failure_threshold=3, timeout_seconds=300):
        self.failure_count = 0
        self.failure_threshold = failure_threshold
        self.timeout_seconds = timeout_seconds
        self.is_open = False

    def call(self, func, *args, **kwargs):
        if self.is_open:
            raise CircuitBreakerOpenError('熔断器已打开，拒绝执行')
        try:
            result = func(*args, **kwargs)
            self.failure_count = 0
            return result
        except Exception as e:
            self.failure_count += 1
            if self.failure_count >= self.failure_threshold:
                self.is_open = True
                alert_operator('熔断器触发，请立即介入')
            raise

4.4 回滚机制：可逆的自愈操作

任何自愈操作都必须设计对应的回滚步骤。回滚不是简单的“撤销”，而是将系统恢复到执行前的已知安全状态。

• 快照前置：在修改配置、重启服务、变更资源前，先记录当前状态（配置文件备份、容器镜像版本、实例数量）。
• 回滚脚本：每个修复步骤配套一个回滚步骤，形成“正向-回滚”配对。
• 原子回滚：如果剧本包含多个步骤，任一步骤失败时，应回滚所有已成功执行的步骤。
• 回滚验证：回滚完成后，验证系统是否恢复到原始状态，而非仅执行命令。

步骤1: 备份 /etc/nginx/nginx.conf → /backup/nginx.conf.20250101
步骤2: 修改 nginx 配置
步骤3: 重载 nginx
步骤4: 验证配置生效
回滚: 将 /backup/nginx.conf.20250101 复制回 /etc/nginx/nginx.conf，重载 nginx

4.5 灰度策略：逐步放量降低风险

自愈剧本不应在全量环境同时生效。灰度策略确保新剧本先在低风险区域验证，确认无误后再扩大执行范围。

4.6 五项原则联动检查表

在编写自愈剧本时，建议使用以下检查表逐项验证，确保剧本达到生产级质量。