📚 课程目录第4章同步窗口核心参数解析

4. 同步窗口核心参数解析

同步窗口的治理能力最终通过 spec.syncPolicy 下的三个核心参数落地。理解这三个参数的组合逻辑，是精准控制同步行为的前提。本章逐一拆解 syncOptions、selfHeal 和 prune 的作用机制与配置陷阱。

4.1 spec.syncPolicy.syncOptions：同步行为修饰器

syncOptions 是一个字符串列表，用于微调 Argo CD 在同步过程中的具体行为。它不决定“是否同步”，而是决定“如何同步”。

选项名称	作用说明	典型场景
`Validate=false`	跳过服务端资源校验（如 CRD 版本检查）	集群中已存在自定义资源，但缺少完整 CRD 定义时
`CreateNamespace=true`	自动创建目标命名空间（如果不存在）	新环境首次部署，避免手动创建 namespace
`PruneLast=true`	先应用资源，最后再执行删除操作	需要确保新资源就绪后再移除旧资源，降低停机风险
`RespectIgnoreDifferences=true`	同步时忽略 `ignoreDifferences` 中定义的字段差异	避免因集群自动注入的字段（如 `kubectl.kubernetes.io/last-applied-configuration`）触发不必要的同步
`ApplyOutOfSyncOnly=true`	仅同步状态为 OutOfSync 的资源	大规模集群中减少同步负载，提升效率

最佳实践：在同步窗口内，建议始终开启 CreateNamespace=true 和 ApplyOutOfSyncOnly=true，前者减少人工干预，后者降低窗口内的同步压力。

4.2 spec.syncPolicy.automated.selfHeal：自动修复机制

selfHeal 控制 Argo CD 是否自动将集群中偏离期望状态的资源“拉回”到 Git 仓库中的定义。当 selfHeal: true 时，任何手动修改（如 kubectl edit 或直接修改 Deployment 副本数）都会被自动覆盖。

风险提示：在同步窗口关闭期间，如果 selfHeal: true 且集群状态发生偏离，Argo CD 会立即触发修复，这可能导致窗口外意外同步。建议在窗口外将 selfHeal 设置为 false，或结合 syncWindows 的 deny 规则阻止非窗口期的自动同步。

# 示例：开启 selfHeal 的 Application 配置片段
spec:
  syncPolicy:
    automated:
      prune: true
      selfHeal: true
    syncOptions:
      - CreateNamespace=true
      - ApplyOutOfSyncOnly=true

4.3 spec.syncPolicy.automated.prune：自动清理策略

prune 决定 Argo CD 是否删除集群中存在于 Git 仓库中已移除的资源。当 prune: true 时，删除 Git 中的资源定义，Argo CD 会自动删除集群中对应的实际资源。

prune 值	行为	风险等级
`false`	仅应用新增或变更，不删除任何资源	低
`true`	同步时自动删除 Git 中已移除的资源	高

  治理建议：在同步窗口内，建议将 prune 设置为 true 以保持集群与 Git 完全一致；在窗口外，务必设置为 false，防止意外删除生产资源。结合 PruneLast=true 可以进一步降低删除操作对运行中服务的影响。

4.4 三参数协同关系图

下图展示了 syncOptions、selfHeal 和 prune 在同步窗口内的协同工作流程：

4.5 参数组合与窗口策略对照表

在实际治理中，不同窗口阶段需要不同的参数组合。下表总结了推荐配置：

窗口阶段	selfHeal	prune	推荐 syncOptions	说明
窗口开启（允许同步）	true	true	CreateNamespace=true, ApplyOutOfSyncOnly=true, PruneLast=true	全量自动同步，保持集群与 Git 严格一致
窗口关闭（禁止同步）	false	false	无特殊要求	禁止任何自动变更，防止意外覆盖或删除
窗口关闭（仅允许手动同步）	false	false	Validate=false（如需绕过校验）	保留手动触发能力，但禁止自动修复和清理

关键结论：同步窗口治理的核心不在于单一参数，而在于 syncOptions、selfHeal 和 prune 的协同配置。窗口开启时三者配合实现全自动治理，窗口关闭时三者关闭确保安全。任何参数的误配都可能导致窗口外意外同步或资源丢失。