观澜涉川 · 札记

在 Istio Gateway 中保留客户端传入的 X-Request-ID

Thu, 22 Oct 2026 00:00:00 GMT

客户端发送了 X-Request-ID，服务端收到的却是另一个值。为什么 Istio Gateway 要改写它？

本文由 DeepSeek V4.1 Flash 1017 完成搜索和分析。

原因并不复杂：Istio Gateway 改写 X-Request-ID 不是 bug，而是 Envoy 在信任边界上的默认行为。preserve_external_request_id 能解决“整值替换”，但解决不了“UUID 第 13 个十六进制位被改写”。如果要求字节级不变，还需要调整 request_id_extension；如果只是要业务链路关联，更稳妥的做法是单独使用一个 correlation header，而不是和 Envoy 的 X-Request-ID 语义硬碰硬。

现象：是谁改了 X-Request-ID

Istio 的 ingress gateway 本质上是一个 Envoy。X-Request-ID 由 Envoy 的 HTTP Connection Manager（HCM）管理，Envoy 文档对它的定义是：

The x-request-id header is used by Envoy to uniquely identify a request as well as perform stable access logging and tracing. Envoy will generate an x-request-id header for all external origin requests (the header is sanitized). It will also generate an x-request-id header for internal requests that do not already have one.

—— Envoy HTTP header manipulation: x-request-id

HTTP header 名称大小写不敏感（RFC 9110 §5.1），X-Request-ID、X-Request-Id 和 x-request-id 是同一个字段；HTTP/2 在构造消息时要求字段名转为小写（RFC 9113 §8.2）。本文正文统一写作 X-Request-ID，Envoy 文档和配置示例中则常见小写 x-request-id。

这段话里有两个关键词：external origin request 和 sanitized。也就是说，对于来自外部客户端的请求，Envoy 默认不信任客户端带来的 X-Request-ID，会重新生成一个；对于 mesh 内部的请求，如果已经有值，则保留。具体行为可以归纳为四种：

请求情况	Envoy 默认行为
没有 `X-Request-ID`	生成新的 UUID
有 `X-Request-ID`，非 edge 请求	保留原值
有 `X-Request-ID`，edge 请求，`preserve_external_request_id=false`	替换为新 UUID
有 `X-Request-ID`，edge 请求，`preserve_external_request_id=true`	保留原值

这张表只描述 preserve_external_request_id 本身；如果 pack_trace_reason 保持默认的 true，36 字符的 UUID 还可能被改写第 13 个十六进制位，见后文。

这里的 edge 指 Envoy 术语中的 edge request：外部客户端进入受信任网络的第一跳代理，通常是 ingress gateway；它不是“边缘计算”的 edge，也不特指某个 CDN 节点。相对于这个 Envoy，后续 mesh 内部的请求都算内部请求。

这里的“edge 请求”由 use_remote_address 和地址判断共同决定。Istio 的 gateway HCM 使用 use_remote_address: true，所以从公网或集群外来的请求会被当作 edge 请求，于是就会出现“客户端明明传了 ID，服务端却收到另一个”的现象。

为什么 Istio 1.25 之后更容易遇到

在 Envoy 1.33 之前，RFC 1918 私网地址默认被视为 internal。很多请求经过云负载均衡器或另一层代理后，源地址是 10.x、192.168.x 这类私网地址，Envoy 会把它当成内部请求，于是 X-Request-ID 被保留。看起来“一直都没问题”。

Envoy 1.33 改了这个默认值：

http: RFC1918 addresses are no longer considered to be internal addresses by default. This addresses a security issue for Envoy’s in multi-tenant mesh environments. Please explicitly set internal_address_config to retain the prior behavior.

—— Envoy 1.33 release notes

Istio 1.25 开始带 Envoy 1.33，因此升级后，同样的私网来源会被重新判定为 edge 请求，X-Request-ID 就开始被替换了。Istio 的 issue #57938 里记录了这个升级前后的差异，维护者的解释也是这个原因。

所以，如果是在升级 Istio 之后才发现这个问题，很可能不是 Istio 单独改了逻辑，而是 Envoy 上游的安全默认值变了。

Envoy 为什么要这样做

从“客户端认为 ID 应该端到端不变”的角度看，这个行为确实反直觉；但从网关的信任边界看，它是合理的：

外部 ID 不可信。客户端可以伪造、复用、构造超长值，甚至用 ID 影响采样。网关作为 edge，负责签发一个可信的 ID。
需要稳定的采样和日志关联。Envoy 的默认 UUID 扩展会把 trace sampling 决策编码进 UUID 的第 13 个十六进制位（即 UUID 第三组的第一个字符）。如果直接信任外部 ID，外部就可以携带一个“已采样”的标记进来。
信任边界重启是行业惯例。W3C Trace Context 规范明确允许 front gate 重启 trace，用于消除 DoS 攻击面；Envoy 对 X-Request-ID 的处理是同一类思路。

Envoy 的模型是：edge 负责签发，mesh 内部负责传播。如果诉求是“客户端是可信的，希望端到端保持”，这是另一种同样合理的模型，但需要显式打开开关。

方案：用 EnvoyFilter 保留 X-Request-ID

解决方式并不复杂：给 gateway 的 HCM 打一个 MERGE patch，把 preserve_external_request_id 设为 true：

apiVersion: networking.istio.io/v1alpha3
kind: EnvoyFilter
metadata:
  name: gateway-preserve-request-id
  namespace: "<gateway-namespace>"
spec:
  workloadSelector:
    labels:
      gateway.networking.k8s.io/gateway-name: "<gateway-name>"
  configPatches:
    - applyTo: NETWORK_FILTER
      match:
        context: GATEWAY
        listener:
          filterChain:
            filter:
              name: envoy.filters.network.http_connection_manager
      patch:
        operation: MERGE
        value:
          typed_config:
            "@type": type.googleapis.com/envoy.extensions.filters.network.http_connection_manager.v3.HttpConnectionManager
            preserve_external_request_id: true

这段配置有几个关键点：

context: GATEWAY 限定只改 gateway，不影响 sidecar。
applyTo: NETWORK_FILTER + filter.name: envoy.filters.network.http_connection_manager 精确匹配到 HCM。
MERGE 只加字段，不替换整个 HCM，风险最小。
workloadSelector 用的 gateway.networking.k8s.io/gateway-name 是 Istio Gateway controller 自动加到 Deployment、Service、Pod 等资源上的 well-known label，用来选自动创建的 Gateway 没问题；如果是手工部署的 gateway，需要自己确保 pod 上有这个 label。Istio 1.24 起移除了旧的 istio.io/gateway-name，新版本统一用这个 label。

有一个容易忽略的细节：EnvoyFilter 是 namespace 级的。workloadSelector 只会匹配同一 namespace 的 pod；如果 Gateway 在 istio-system，EnvoyFilter 也要放在 istio-system，或者放到 Istio 的 root namespace 并接受它作用于所有匹配 workload。

如果 Istio 版本在 1.22 及以上，也可以用 targetRefs 替代 workloadSelector，直接指向 Gateway API 的 Gateway，避免依赖生成的 label：

spec:
  targetRefs:
    - group: gateway.networking.k8s.io
      kind: Gateway
      name: "<gateway-name>"

targetRefs 和 workloadSelector 只能二选一。

验证时，先看 gateway 的 config dump 里有没有生效：

istioctl proxy-config listener <gateway-pod> -n <namespace> -o json \
  | jq '.. | objects | select(has("preserveExternalRequestId")) | {preserveExternalRequestId, requestIdExtension}'

没有任何输出，说明 patch 没匹配到目标 HCM。然后用几种不同格式的 ID 各打一次（UUID4、UUIDv7 形状、32 位十六进制），对比服务端看到的原始值；只测 UUID4 很容易漏掉第 13 个十六进制位的问题。

关键坑：打开 preserve 后，第 13 个十六进制位仍可能变化

这是最容易漏掉的一点。preserve_external_request_id: true 确实阻止了 Envoy 把整个值换掉，但 Envoy 的 UUID 请求 ID 扩展还有一个 pack_trace_reason，默认是 true。当请求是 edge、选择保留外部 ID、且 pack_trace_reason 为 true 时，对于 36 字符的 UUID，Envoy 会把第 13 个十六进制位写成 4，用来清除外部 ID 里的 trace sampling 标记。这一步和是否启用 tracing 无关，只要 pack_trace_reason 为 true 就会执行。

Envoy 的 tracing 文档也明确提醒了这一点：

The default implementation will modify the request ID UUID4 to pack the final trace reason into the UUID. … However, trace reason packing may break externally generated request IDs that must be maintained. The pack_trace_reason field can be used to disable this behavior at the expense of also disabling stable trace reason propagation and associated features.

—— Envoy tracing overview

具体表现取决于 ID 的格式：

客户端发送的 ID	只加 `preserve_external_request_id`	再加 `pack_trace_reason: false`
标准 UUID4，例如 `11111111-1111-4111-8111-111111111111`	不变（该位置本来就是 `4`）	不变
UUIDv7 形状，例如 `11111111-1111-7111-8111-111111111111`	第 13 个十六进制位从 `7` 变成 `4`	不变
被 Envoy 标记过采样的 UUID，例如 `11111111-1111-9111-8111-111111111111`	第 13 个十六进制位被清回 `4`	不变
32 位十六进制、ULID 等非 36 字符 ID	不变（长度不是 36，Envoy 不会改写）	不变
任意 36 字符字符串	第 13 个十六进制位被写成 `4`	不变

这解释了一个常见现象：用 UUID4 测试时看起来“完全保留”，换成 UUIDv7 或某些客户端生成的 ID 后，第 13 个十六进制位就变了。如果验证时只用了 UUID4，可能刚好没有暴露这个问题。

如果要求字节级一致，把 request_id_extension 一起补上（仍是 HCM typed_config 的子字段）：

            preserve_external_request_id: true
            request_id_extension:
              typed_config:
                "@type": type.googleapis.com/envoy.extensions.request_id.uuid.v3.UuidRequestIdConfig
                pack_trace_reason: false
                use_request_id_for_trace_sampling: false

注意，UuidRequestIdConfig 必须嵌在 HCM 的 request_id_extension 字段里，不能把 UuidRequestIdConfig 单独作为一个 NETWORK_FILTER patch；它不是网络过滤器，类型对不上，不会得到预期的效果。

这两个开关的代价要讲清楚：

pack_trace_reason: false 能保证 ID 字节级一致，但 Envoy 文档说，依赖 X-Request-ID 的稳定 trace/access log 采样会失效，只剩随机采样。
use_request_id_for_trace_sampling: false 让 Envoy 不再用 X-Request-ID 做采样决策，适合链路上存在非 Envoy 代理、或者不希望客户端 ID 影响采样的场景。

如果不需要字节级一致，只保留 preserve_external_request_id 也完全可以接受：第 13 个十六进制位的清理本质上是 Envoy 在拒绝信任外部采样标记，是一个安全特性，不是 bug。

这样做的副作用

副作用	说明	建议
客户端可伪造	任何外部客户端都能指定 ID。如果下游拿它做鉴权、审计、限流或幂等，风险很高	只从可信上游保留；校验格式和长度；不要用于安全决策
影响采样	`use_request_id_for_trace_sampling` 默认 true，客户端可以用 ID 影响是否采样；复用同一个 ID 还会让日志和采样关联失真	不需要时设为 false，或保留 Envoy 默认的 trace reason 清理
第 13 个十六进制位被改写	`pack_trace_reason` 默认 true，36 字符 ID 的固定位置会被写成 `4`	要字节级一致就关掉，并接受稳定采样失效
日志注入/噪音	客户端提供的值通常会进入访问日志；超长值会污染日志	限制字符集和长度；使用结构化日志并转义
EnvoyFilter 维护成本	依赖 Envoy 内部字段和 type URL，Istio 升级后可能失效	升级后复查 config dump；保持 patch 最小
作用域是 HCM	选中 gateway 的所有 HTTP listener/filter chain 都会生效，不能按 host 区分	如果多个 Gateway 共享一个 deployment，确认影响范围
响应不回显	默认不会把生成的 ID 放到响应头	需要时加 `always_set_request_id_in_response: true`
用内部地址配置绕过	把 LB 网段设为 internal 也能“保留”，但会改变 `x-envoy-*` 头的信任逻辑	不要这么做；用 `preserve_external_request_id` 更精准

特别要提醒的是幂等。Istio issue #57938 中记录了一个案例：网关改写 X-Request-ID 后，幂等逻辑失效，产生了重复交易。但 X-Request-ID 本身不是为幂等设计的：客户端提供的值不保证唯一，也不保证可信，可以重放同一个值。如果业务需要重试去重，应该用独立的 Idempotency-Key，而不是复用请求 ID。

另外，不建议用“把负载均衡器网段配置成 internal”来解决这个问题。那会同时改变 Envoy 对 x-envoy-* 头的信任判断，扩大攻击面；Istio 的 #53402 讨论的就是这个信任收紧。这里只需要保留一个 header，不应该顺手把信任边界也改掉。

X-Request-ID、X-Correlation-ID 和其他跟踪字段

这几个 header 经常被混用，但语义并不一样：

字段	语义	是否标准	谁生成	典型用途
`X-Request-ID`	标识一次 HTTP 请求；在信任边界可能被重置	事实标准，不是 RFC	edge/gateway 或客户端	访问日志、单次请求排障
`X-Correlation-ID`	标识一笔业务事务，可能跨多个请求和服务	事实标准，不是 RFC	第一次交互处	跨服务日志关联、客服排障
`traceparent` / `tracestate`	分布式 trace 的上下文	W3C 标准	链路起点或各跳	分布式追踪
`b3` / `x-b3-*`	Zipkin 的 trace 上下文	事实标准	链路起点或各跳	Zipkin/Jaeger 生态
`x-amzn-trace-id`	AWS X-Ray/ALB 的 trace 上下文	AWS 专有	ALB 或上游	AWS 内追踪
`x-cloud-trace-context`	GCP 旧版 trace 上下文	GCP 专有，旧版	GCP 负载均衡/服务	GCP 追踪，现已建议用 `traceparent`
`x-ms-request-id` / `x-ms-client-request-id`	Azure 的服务端请求 ID / 客户端请求 ID	Azure 专有	服务端 / 客户端	Azure 排障、重试去重
`Idempotency-Key`	标识一次可重试的操作	IETF 草案（已过期）	客户端	重试幂等

业界的做法大致可以分成几类：

1. Edge 签发，内部传播（Envoy/Istio 的模型）

网关负责给外部请求分配 ID，内部服务只负责传播。好处是 ID 可信、唯一、可稳定采样；代价是客户端无法自己指定端到端 ID。这是 Envoy 的默认模型，也是很多 API gateway 的默认模型。

2. 有则保留，无则生成（ingress-nginx、Kong 的模型）

ingress-nginx 的模板里有一个很典型的 map：

map $http_x_request_id $req_id {
    default   $http_x_request_id;
    ""        $request_id;
}

客户端带了 X-Request-ID 就原样传给上游，没带才用 nginx 的 $request_id 生成。Kong 的 correlation-id 插件也是类似策略：如果请求里已经有同名 header，就尊重它，不覆盖。

这类做法对客户端友好，但前提是网关信任客户端，或者至少对值做了校验。

3. 分层 ID（AWS ALB、Azure 的模型）

AWS ALB 的处理很值得借鉴：如果请求里已经有 X-Amzn-Trace-Id 的 Root 字段，ALB 保留 Root，再插入一个 Self 字段；没有才生成新的 Root。这样既保留了调用方的 trace 起点，又加上了当前负载均衡器的信息。

Azure 的部分协议也区分 x-ms-client-request-id（客户端提供）和 x-ms-request-id（服务端生成），并可以通过 x-ms-return-client-request-id 决定是否回显客户端 ID。与其覆盖，不如把“客户端 ID”和“服务端 ID”分开。

4. 标准追踪上下文（W3C traceparent）

真正的分布式追踪不应该依赖 X-Request-ID。W3C Trace Context 定义了 traceparent 和 tracestate，把 trace ID、parent span ID、采样标记标准化；Google Cloud 也明确建议优先使用 traceparent，x-cloud-trace-context 只作为兼容保留。

W3C 规范还明确允许 front gate “restart trace”，用于消除 DoS 攻击面。这再次说明：在信任边界重启追踪上下文是正当设计，不是实现错误。

5. 业务 correlation ID

Microsoft 的工程手册对 Correlation ID 的定义是：在第一次交互时分配，传播到所有下游组件，所有组件在日志里使用同一个 ID。它建议优先使用 OpenTelemetry 的 TraceId；如果不用 OTel，就用一个自定义 header（常见的就是 X-Correlation-ID）。

这类 ID 的语义是“业务事务”，不是“单次 HTTP 请求”，所以通常应该跨网关保留，而不是每跳重置。但它同样不是标准，值需要校验，也不能用于安全决策。

6. 命名规范

RFC 6648 从 2012 年起就不建议再给自定义 header 加 X- 前缀了。现实中 X-Request-ID、X-Correlation-ID 已经大量存在，不可能一夜改掉；但新设计的系统应该优先用标准名（如 traceparent），或者至少把 header 的语义、生成方、是否透传写进接口契约，而不是靠猜。

实践建议

把“请求 ID”“关联 ID”“trace ID”“幂等键”分开，是最稳妥的做法：

场景	建议
公网客户端，需要排障	让 gateway 生成 `X-Request-ID`，必要时打开 `always_set_request_id_in_response`，通过响应头返回给客户端；客户端记录这个 ID
可信上游（CDN、另一层网关）已有 ID	用 `preserve_external_request_id` 保留，并在网关或应用入口校验字符集和长度
需要跨服务业务关联	单独使用 `X-Correlation-ID`，在第一次交互处生成，网关只做校验和透传
分布式追踪	使用 `traceparent`/`tracestate`，不要把 `X-Request-ID` 当 trace ID
重试幂等	使用 `Idempotency-Key`，服务端做去重存储，不要复用 `X-Request-ID`
多厂商/多语言	统一到 W3C trace context + 一个自定义 correlation header，并写进契约

如果要在网关或应用入口校验，可以先用一个保守的白名单，例如 ^[A-Za-z0-9._:-]{1,128}$，并拒绝多个同名 header；具体规则取决于 ID 的生成方式。

回到开头的方案：方向正确，可以用。如果只关心“服务端能拿到客户端传的那个 ID”，并且客户端 ID 是标准 UUID4（第三组首位为 4）或非 36 字符，现有配置就够了；如果要求字节级一致，补上 request_id_extension；如果目标是长期可维护的端到端关联，建议把 X-Request-ID 留给网关/Envoy，用一个独立的 X-Correlation-ID 承载业务语义。

一句话总结：不要和 Envoy 的 X-Request-ID 语义硬碰硬。要么显式接管它（preserve_external_request_id，必要时关闭 trace packing），要么换一个不承载 Envoy 内部语义的 header。

参考

让 HAProxy 和 Caddy 之后的应用拿到客户端 IP

Tue, 20 Oct 2026 00:00:00 GMT

假定部署结构如下：

客户端 → HAProxy → Caddy → 应用
HAProxy 用 mode tcp 转发 443
Caddy 持有证书并终止 TLS
应用只监听回环

这种结构下，应用默认只能看到 Caddy 的地址（127.0.0.1）。要拿到真实的客户端 IP，需要把地址分两跳传下去：

HAProxy 通过 PROXY protocol 把源地址带到 Caddy；
Caddy 把它写进 X-Forwarded-For；
应用读取这个头。

图：客户端 IP 的两跳传递

地址如何走过两跳

跳	传递方式	作用
客户端 → HAProxy	TLS	HAProxy 在 TCP 层看到客户端源地址
HAProxy → Caddy	PROXY protocol	TLS 透传时把源地址带给 Caddy
Caddy → 应用	X-Forwarded-For	应用从 HTTP 头读取真实 IP

HAProxy 工作在 mode tcp，只看得到 TCP 字节和 TLS ClientHello 里的 SNI，读不到 HTTP，因此无法添加 X-Forwarded-For。Caddy 终止 TLS 后能看到 HTTP，但它默认不采信上游送来的 XFF（文档）：

For these X-Forwarded-* headers, by default, the proxy will ignore their values from incoming requests, to prevent spoofing.

所以分工是：PROXY protocol 补上 HAProxy 这一跳，XFF 负责 Caddy 到应用这一跳。

配置 HAProxy

在 frontend 上绑定 443，在指向 Caddy 的 backend 上加 send-proxy-v2：

frontend fe_https
    mode tcp
    bind *:443
    default_backend be_caddy

backend be_caddy
    mode tcp
    option tcplog
    server caddy 127.0.0.1:8453 send-proxy-v2

send-proxy-v2 只加在 backend 的 server 行上。它会让 HAProxy 在每条连接的开头、TLS 握手之前，写入一段包含客户端源地址的 PROXY v2 头。

配置 Caddy

在 Caddyfile 最上面的 global options 里启用 proxy_protocol listener wrapper，并把它放在 tls 之前：

{
	servers {
		listener_wrappers {
			proxy_protocol {
				allow 127.0.0.1/32
			}
			tls
		}
	}
}

app.example.com:8453 {
	reverse_proxy 127.0.0.1:9000
}

几个关键点：

proxy_protocol 必须在 tls 之前。它在 TLS 握手之前读取明文前缀，顺序反了就解析不到。
allow 指定可信来源。127.0.0.1/32 表示只采用同机 HAProxy 送来的 PROXY 头；如果 HAProxy 改用 ::1 连接，这里要写 ::1/128。
fallback_policy 默认是 ignore。不在 allow 列表里的来源，连接照收，但 PROXY 头里的地址会被丢弃。因此 allow 不能省略，也不要把默认策略改成 use，否则任何人都能伪造来源地址。
servers 块只对 Caddyfile 中实际存在的站点生效，所以上面保留下面的站点块；改完配置后 reload。
reverse_proxy 默认会向上游写 X-Forwarded-For、X-Forwarded-Proto 和 X-Forwarded-Host，不需要额外的 header_up。其中 X-Forwarded-Proto 取自 Caddy 收到的请求协议（这里是 https），X-Forwarded-Host 取自请求的 Host；这三个头都由 Caddy 生成，不是从 HAProxy 透传的。如果站点块里手写了 header_up X-Forwarded-For ...，它会覆盖默认行为，应当删掉。

这里不需要配置 trusted_proxies。它控制的是是否采信上游通过 HTTP 头送来的地址，而不是是否生成这些头。proxy_protocol 已经在 TCP 层把连接对端换成了真实客户端，Caddy 直接以这个地址为准；没有 trusted_proxies 时，入站的头会被忽略并重新生成，正是这条链路想要的结果。

配置应用

应用读取 X-Forwarded-For，取最右边一条。以 Rust 为例：

use std::net::IpAddr;

fn client_ip(xff: &str) -> Option<IpAddr> {
    xff.rsplit(',').next()?.trim().parse().ok()
}

这条链路上，Caddy 会忽略入站请求里的 XFF，按自己看到的客户端地址重写这个头，所以右起第一条就是真实客户端；最左边那条是调用方自己写的，永远不可信。

如果应用需要还原原始协议或 Host（例如生成绝对 URL），可以同时读取 X-Forwarded-Proto 和 X-Forwarded-Host。

如果应用读的是 TCP 对端（例如 axum 的 ConnectInfo），代理之后只能拿到 Caddy 的地址（这里是 127.0.0.1），必须改成读 XFF。

验证配置

下面用 203.0.113.7 作为示例地址；它属于 RFC 5737 保留的文档专用网段，不会与真实主机冲突。

① 应用层——跳过 Caddy，直接打应用，注入一条 XFF：

curl -s -H 'X-Forwarded-For: 203.0.113.7' http://127.0.0.1:9000/api/v1/ip/addresses/self
# {"ip":"203.0.113.7"}  → 应用读取 XFF 正确
# {"ip":"127.0.0.1"}    → 应用读的是 ConnectInfo

② Caddy 层——跳过 HAProxy，自己发一个 PROXY 头（curl --haproxy-clientip 需要 curl ≥ 8.2，旧版可用这段 Python）：

import socket, ssl
s = socket.create_connection(("127.0.0.1", 8453))
s.sendall(b"PROXY TCP4 203.0.113.7 127.0.0.1 40000 8453\r\n")
c = ssl.create_default_context().wrap_socket(s, server_hostname="app.example.com")
c.sendall(b"GET /api/v1/ip/addresses/self HTTP/1.1\r\nHost: app.example.com\r\nConnection: close\r\n\r\n")
print(c.recv(4096).decode(errors="replace").split("\r\n\r\n")[-1])

这里发的是 PROXY v1 头，Caddy 的 wrapper 同时支持 v1 和 v2。

输出	含义
`203.0.113.7`	Caddy 已采用，应用也读取正确；再确认 HAProxy 配置并 reload
`127.0.0.1`	Caddy 解析了头但没采用，检查 `allow` / `fallback_policy`
报错 / 挂住	`listener_wrappers` 没生效，检查顺序和 reload

③ 端到端——从公网访问：

curl -s https://app.example.com/api/v1/ip/addresses/self   # 应是真实公网 IP

注意事项

不要信任 XFF 的最左端。那是调用方自己填的，只有最右侧、由可信代理写入的地址才可信。
Caddy 默认不记录访问日志，只记错误和警告。需要观察 Caddy 看到的客户端时，可以临时加一个响应头，验完记得删掉：
```
header X-Caddy-Saw {remote_host}
```

参考

企业环境下的 Certbot 实战：用 Azure Key Vault 托管私钥签发 SSL 证书

Fri, 16 Oct 2026 00:00:00 GMT

在单机场景里，用 Certbot 申请 Let’s Encrypt 证书可以很省事：它自己生成私钥、完成域名验证、保存证书，几乎不需要人工介入。代价是它默认了一件事——运行 Certbot 的那台机器，就是最终使用这张证书的机器。

域名前面挂了 CDN 或别的反向代理时，还有一层额外的限制：HTTP-01 校验到不了运行 Certbot 的机器，只能改用 DNS-01，在域名的 DNS 里写一条 _acme-challenge 记录来证明所有权。DNS-01 顺带也更好拿通配符证书，只是要配上 DNS 服务商的插件或自己写的 hook，否则 --manual 会停下来等你手工加记录。

到了企业环境，前面那个“同一台机器”的默认就不成立了：CI/CD 的运行器、审计人员、甚至别的团队都可能接触到那台机器；私钥一旦落在构建机的磁盘上，就可能进入构建缓存、日志、镜像层或者备份，而它恰恰是整个 TLS 信任链里最不能泄露的东西。

本文给出一套可以在企业里落地的 Azure 方案：域名用 DNS-01 挑战验证，私钥由 Azure Key Vault 生成并保管，Certbot 只负责让 Let’s Encrypt 用这份私钥对应的 CSR 签出一张证书，签名完成后再把证书合并回 Key Vault——整个签发过程中，私钥从不离开 Key Vault。

为什么不干脆用云厂商的托管证书？因为托管证书的私钥拿不到手。以 Azure Front Door 为例，它的托管证书由 DigiCert 签发后存放在 Front Door 自己的 Key Vault 里，你既看不到私钥，也没法把它用到别处；一旦需要通配符，或者同一张证书要同时挂在 Front Door 和源站上，就只能自带证书（BYOC），而 BYOC 要求证书来自你自己的 Key Vault。AWS 的 ACM、GCP 的 Certificate Manager 也提供类似的托管证书，各有自带证书的做法，思路相通，但产品与限制不同，本文不展开。

目标与设计

密钥生成与签名分离

先说清楚一个容易混淆的点：我们不用的是 Certbot 生成的私钥，而不是“Certbot 创建的证书”。证书必须由权威 CA 签发，Certbot 在这里的角色是 ACME 客户端，负责完成域名验证并取回签名结果。真正要剥夺的是 Certbot 生成和保存私钥的权力。

要做到这一点，需要把“生成密钥对”和“请求签名”两件事拆开：

Key Vault 生成密钥对和 CSR。私钥创建在 Key Vault 内部，外部只拿到 CSR（Certificate Signing Request，证书签名请求，里面只有公钥和域名信息，没有私钥）。
Certbot 拿着 CSR 去让 Let’s Encrypt 签名。Certbot 通过 DNS-01 挑战证明域名所有权，但签名的是我们给它的 CSR，所以它自始至终看不到私钥。
把签名后的证书链合并回 Key Vault 并保存。Key Vault 把它和自己保管的那把私钥配对，完成证书创建并存进库中，供消费端引用。

这正是 Key Vault 的“外部签名证书”能力：只要证书策略里的签发者是 Unknown，Key Vault 就停在“待处理（pending）”状态，等我们把外部 CA 签好的证书合并进来。

三方角色

整条链路涉及三方：

Azure Key Vault：生成并保管私钥，出具 CSR；收到签名证书后与库内私钥配对，把它保存为证书。
签发作业（CI/CD 或定时任务）：运行 Certbot，只持有 CSR 和签名结果，读不到私钥。
Let’s Encrypt：通过 DNS-01 挑战验证域名所有权，对 CSR 签名。

消费端与 exportable

“私钥不离开 Key Vault”这句话有一个前提，就是证书策略里的 exportable 必须为 false。这是整个方案里最容易踩的坑：

exportable: false 时，私钥只是 Key Vault 里的一个密钥对象，即使把它对应的 secret 取出来，内容里也不包含私钥。这才是真正的“私钥不出库”。
exportable: true 时，任何拿到 secrets/get 权限的人都能把私钥（连同 PFX）导出走，所谓“不离开 Key Vault”就名存实亡了。

代价是：不可导出的私钥，任何需要私钥材料来完成 TLS 握手的消费端都用不上——Key Vault 把密钥锁在库里，服务拿不到密钥本身，也就没法在自己这边终止 TLS。所以 exportable: false 换来的是“密码学意义上的私钥不出库”，代价是适用面很窄：它基本只能用于把 Key Vault 当签名引擎的场景（比如 mTLS 客户端证书、代码签名），而不是普通的 HTTPS 服务端证书。

一个具体的例子：这张证书只给 Application Gateway 用。 很多人以为这样就能设成不可导出，其实不行——官方文档写得很明确：“Key Vault certificates must have an exportable private key in order for the Application Gateway to be able to use them.” Application Gateway 是用自己的托管标识，在运行时去 Key Vault 里 Get 证书的 secret，把私钥装进监听器，所以私钥材料确实从 Key Vault 交到了 Application Gateway 手上。App Service 从 Key Vault 导入证书、Front Door 通过 Get 取用证书，也都属于这一类——它们都需要私钥。

所以要分清两种“不离开 Key Vault”：

密码学意义：exportable: false，私钥永远出不了库；代价是消费端只能用 Key Vault 做密钥操作，普通的 TLS 终止做不到。
运营意义：exportable: true，但私钥由消费端（Application Gateway、Front Door、App Service）用托管标识在运行时直接从 Key Vault 取用，运维和签发流水线从不经手 PFX，也不把它落到别处。这才是大多数企业场景里真实可得的收益。

消费方式	exportable	说明
TLS 终止类服务（Application Gateway、Front Door、App Service）	`true`	需要私钥材料，由服务用托管标识从 Key Vault 取用
需要证书文件的主机 / 容器 / Nginx / IIS	`true`	私钥落到该主机，需另行防护
只用 Key Vault 做签名 / 解密（如 mTLS 客户端证书）	`false`	私钥真正不出库
合规要求密钥托管在 HSM	用 Managed HSM	密钥天然不可导出

要注意，签发环节和 exportable 无关：无论设成哪个值，CSR 都由 Key Vault 生成，私钥都不经过 Certbot 和签发流水线；exportable 只决定消费端能不能拿到私钥材料。即便设成 true，也比“在构建机上生成私钥”安全得多——私钥由 Key Vault 生成，签发作业只有证书权限、拿不到 secrets/get（见下文的最小权限设计），连它自己签出来的私钥都读不到。

准备工作

签发作业的身份

执行这套流程需要一个 Azure 身份。它至少要做三件事：在 Key Vault 里创建/合并证书、在 DNS 里增删 TXT 记录、以及（首次运行时）注册 ACME 账户。

推荐用 用户分配的托管标识（UAI），或 GitHub Actions / Azure DevOps 的 OIDC 联合凭据。两者都能避免在流水线里存放长期的服务主体密码：

运行在 Azure 计算资源上（VM、Container Apps、AKS）：用 UAI，az login --identity --username <client-id>。
运行在 GitHub Actions / Azure DevOps：用工作负载联合身份，az login 时使用 federated token，不落盘任何密码。

最小权限

认证和授权是两回事。这里的关键是给这个身份刚好够用的权限——但“刚好够用”不是把权限压到最小，而是在安全和运维成本之间取一个平衡点。下面按“够用”和“更严”两档来看。

Key Vault 侧：内置角色 Key Vault Certificates Officer 已经贴近需要——它的 data actions 只有 certificatecas/*、certificates/*、certificatecontacts/write，不包含 secrets/*，即便签发作业被攻破，它也读不到私钥的私密部分（读私钥要走 secret 接口，需要 secrets/get）。日常直接用它就是合理的：签发流程和“读取私钥”本来就是两套权限。

如果还想再收一点，可以自定义一个只保留证书读、创建、更新的角色——内置角色除了这些，还包含删除、清除、备份、管理联系人等：

{
  "Name": "Key Vault Certificate Issuer",
  "Description": "仅供外部 CA 证书的创建与合并使用",
  "Actions": [],
  "DataActions": [
    "Microsoft.KeyVault/vaults/certificates/read",
    "Microsoft.KeyVault/vaults/certificates/create/action",
    "Microsoft.KeyVault/vaults/certificates/update/action",
    "Microsoft.KeyVault/vaults/certificates/delete"
  ],
  "NotDataActions": [],
  "AssignableScopes": ["/subscriptions/<SUBSCRIPTION_ID>"]
}

DNS 侧：这里才是真正要权衡的地方，有三档，宽松程度递减、运维成本递增：

DNS Zone Contributor（最省事，也最宽）：它能管理整个区的所有记录类型，等于把域名解析交了出去。签发身份一旦出问题，影响面最大。
只写 TXT 的自定义角色（折中）：DNS-01 只在一个名字下增删 TXT，所以可以只给 dnsZones/TXT/*：

{
  "Name": "ACME DNS TXT Contributor",
  "Description": "仅供 ACME DNS-01 挑战增删 TXT 记录",
  "Actions": [
    "Microsoft.Network/dnsZones/read",
    "Microsoft.Network/dnsZones/TXT/read",
    "Microsoft.Network/dnsZones/TXT/write",
    "Microsoft.Network/dnsZones/TXT/delete"
  ],
  "NotActions": [],
  "DataActions": [],
  "NotDataActions": [],
  "AssignableScopes": ["/subscriptions/<SUBSCRIPTION_ID>"]
}

但要注意 TXT 记录本身也很敏感：SPF、DMARC、DKIM、站点验证令牌都是 TXT。拿到主区的 TXT 写权限，就可能在邮件安全上做手脚。

把 _acme-challenge 委派到独立的挑战区（最严）：在主区里为每个要签发的域名放一条 CNAME，指向一个单独的挑战区，只给这个身份写那个区的权限。这样它连主区的记录都碰不到——这条思路也符合 Let’s Encrypt 官方“使用更细粒度的凭据、在独立服务器上做验证”的建议。

第 3 档的代价是每条 CNAME 只覆盖一个主机名：子域名越多，主区里的 CNAME 就越多。有两点可以让它划算起来：

改用通配符证书：签 *.example.com 时，DNS-01 只用 _acme-challenge.example.com 一个名字，一条 CNAME 就够，与子域名的数量无关。
用 IaC 管理这些 CNAME：写进 Pulumi / Terraform，新增子域名时随资源一起创建，而不是手工维护。

所以它算不上过度设计（over-engineering），关键看取舍：子域名不多、或者能上通配符，第 3 档很划算；子域名成百上千、又只能逐个签发，第 2 档更实际。

别忘了 CAA 记录：如果域名的 DNS 里配置了 CAA，需要确认它允许 letsencrypt.org 签发，否则请求会被拒绝。

网络与审计

企业环境的 Key Vault 通常应该关闭公网访问，用 Private Endpoint 走 Azure 私有链接，只允许签发作业所在的网络访问。同时：

打开 软删除（soft-delete）与清除保护（purge protection），避免误删导致私钥永久丢失。
把 Key Vault 的诊断日志送到 Log Analytics，记录每一次证书的创建与合并，作为审计证据。
订阅 Event Grid 的 Microsoft.KeyVault.CertificateNearExpiry、Microsoft.KeyVault.CertificateExpired、Microsoft.KeyVault.CertificateNewVersionCreated 事件，用它们做到期提醒和新版本通知。

ACME 账户

先澄清一个常见的误解：即使加上 --register-unsafely-without-email（也就是常说的“匿名”注册），Certbot 仍然会在 Let’s Encrypt 注册一个 ACME 账户——ACME 协议本身就要求有账户，不存在真正匿名的签发。这个参数只是不提供邮箱联系方式，代价是收不到到期和吊销通知。

账户对应的是一对密钥，默认放在 --config-dir/accounts/ 下，它是一份敏感凭据，能以你的账户身份申请和吊销证书。所以：

不要每次运行都重新注册一个账户——否则既浪费 Let’s Encrypt 的注册额度（每个 IP 每 3 小时最多 10 个新账户），又丢掉了账户连续性。
用一个持久化的 --config-dir 保存账户，不要每次运行都删掉整个目录；生产环境里放在受控的持久卷上，并像对待密钥一样保护它。
邮箱是可选填的，但建议提供（--email），这样能收到到期和吊销通知。

在 GitHub Actions 这类临时运行器上怎么办？ GitHub 托管的 runner 是临时的，没有持久卷，“持久化 --config-dir”就落不了地。思路是把账户存到运行器之外，每次运行再取回来：

一次性注册好账户，把 --config-dir/accounts/ 整个目录打包（tar + base64）。
把它存进 GitHub Actions secret，或者存进 Azure Key Vault。
每次 job 开始时解压回 --config-dir，Certbot 就会复用它，不再注册新账户。

用 GitHub secret 最省事（账户目录只有几 KB，远小于 secret 的大小上限）：

- name: Restore ACME account
  run: |
    mkdir -p "${STATE_DIR}/config"
    printf '%s' "${{ secrets.ACME_ACCOUNT }}" \
      | base64 -d | tar xzf - -C "${STATE_DIR}/config"

首次注册和导出可以放在一次性 job 或本地做：tar czf - -C "${STATE_DIR}/config" accounts | base64，再把输出写进 secret。

有一个细节：workflow 默认没有写 secret 的权限（GITHUB_TOKEN 不能改 secret），所以如果希望 CI 能自动把新账户存回去，用 Key Vault 更顺——但别破坏前面“签发身份读不到私钥”的设计：把这个 ACME 账户密钥放进独立的 vault，或给它按 secret 作用域的角色分配，只授予这一条 secret 的 get。

另外，不要用 actions/cache 存账户：cache 不是给敏感数据用的（GitHub 本身也不建议往里面放密钥），而且随时可能被清理。

工具与 DNS 验证方式

pip install certbot

Certbot 自带的 --manual 模式，配合 --manual-auth-hook / --manual-cleanup-hook 就能完成 DNS-01 挑战，不需要额外的插件。本文用这种方式：验证逻辑拿 Azure CLI 自己写，不引入第三方依赖——在需要审计、追求依赖最小化的场合，这比省下来的那点代码更重要。

代价是两个 hook 要自己负责两件事：在 _acme-challenge 下增删 TXT 记录，以及等待 DNS 传播（--manual 不会替你等）。

如果不在意第三方依赖，也有现成的 certbot-dns-azure 插件，它内部同样是通过 Azure API 增删记录，并且会自己等待传播：

pip install certbot-dns-azure

它支持托管标识、工作负载身份、CLI 凭据等多种认证方式，都不用把密码写进配置。两种方式二选一即可，下文用前者（manual hook）。

完整实操

下面用一个目标域名 app.example.com 走一遍。命令本身都不长，关键在每一步的意图；理解了流程，再按自己的环境把变量填好即可。

创建 pending 证书（CSR）

用一份证书策略在 Key Vault 里创建证书，签发者设为 Unknown，表示“由外部 CA 签名”。Key Vault 会生成密钥对，并返回一个 CSR——注意它是 base64 编码的 DER、没有 PEM 头，需要自己补上 -----BEGIN CERTIFICATE REQUEST----- / -----END CERTIFICATE REQUEST----- 再落成 .pem 文件。

策略里几个要点：

keyProperties.exportable：私钥是否可导出（前文讨论过的取舍）；
keyType / keySize：RSA 或 EC 及其长度；
reuseKey: false：每次续期生成新密钥，满足密钥轮换；
subject 与 subjectAlternativeNames.dnsNames：把域名放进 SAN（现代 TLS 客户端只看 SAN，不看 CN）；
validityInMonths：只是信息性的，真正的有效期由 CA 决定。

一份最小的策略文件（policy.json）长这样，把域名和 exportable 按需要改即可：

{
  "issuerParameters": { "name": "Unknown" },
  "keyProperties": {
    "exportable": false,
    "keyType": "RSA",
    "keySize": 2048,
    "reuseKey": false
  },
  "secretProperties": { "contentType": "application/x-pkcs12" },
  "x509CertificateProperties": {
    "subject": "CN=app.example.com",
    "subjectAlternativeNames": { "dnsNames": ["app.example.com"] },
    "keyUsage": ["digitalSignature", "keyEncipherment"],
    "validityInMonths": 3
  }
}

用它创建证书并取回 CSR：

az keyvault certificate create \
  --vault-name "${KEY_VAULT_NAME}" \
  --name "${KEY_VAULT_CERT_NAME}" \
  --policy @policy.json \
  --query csr -o tsv

如果这个证书名上还留着上次没走完的 pending 操作，az keyvault certificate pending show 能看出来；要么先排查，要么清掉再重来：

# 查看遗留的 pending 操作
az keyvault certificate pending show \
  --vault-name "${KEY_VAULT_NAME}" \
  --name "${KEY_VAULT_CERT_NAME}"

# 排查后确认可以丢弃，再删除
az keyvault certificate pending delete \
  --vault-name "${KEY_VAULT_NAME}" \
  --name "${KEY_VAULT_CERT_NAME}"

用 Certbot 对 CSR 签名

把 CSR 交给 Certbot。域名来自 CSR，所以不要再传 -d；Certbot 全程看不到私钥：

certbot certonly \
  --non-interactive --agree-tos \
  --email "${ACME_EMAIL}" \
  --staging \
  --csr request.csr.pem \
  --manual --preferred-challenges dns \
  --manual-auth-hook ./azure-auth.sh \
  --manual-cleanup-hook ./azure-cleanup.sh \
  --cert-path cert.pem \
  --chain-path chain.pem \
  --fullchain-path fullchain.pem \
  --config-dir ./letsencrypt/config \
  --work-dir ./letsencrypt/work \
  --logs-dir ./letsencrypt/logs

上面的命令带 --staging，也就是 --test-cert 的别名：它切到 Let’s Encrypt 的测试环境，签发的证书不受信任、只用于跑通流程，也不会消耗生产额度。对应地，证书名要带 -staging 后缀（见「Staging 环境与速率限制」）。确认流程无误后，去掉 --staging 再签发生产证书。

不想提供邮箱就把它换成 --register-unsafely-without-email（原因见「ACME 账户」一节）。--config-dir 指向一个持久化目录来保存 ACME 账户；--manual-auth-hook / --manual-cleanup-hook 指到下面写的 DNS 脚本。

合并证书回 Key Vault

Certbot 产出的 fullchain.pem 顺序是“叶子在前、中间证书在后、不含根”。把它合并进上一步的 pending 证书：

az keyvault certificate pending merge \
  --vault-name "${KEY_VAULT_NAME}" \
  --name "${KEY_VAULT_CERT_NAME}" \
  --file fullchain.pem

Key Vault 会把它和自己保管的私钥配对，完成证书创建。

校验

合并后要确认“库里这张证书”和“刚签发的结果”是同一张：用 az keyvault certificate show 取回指纹，和本地 openssl x509 -fingerprint -sha1 算出的对比，不一致就说明配错了。

MERGED=$(az keyvault certificate show \
  --vault-name "${KEY_VAULT_NAME}" --name "${KEY_VAULT_CERT_NAME}" \
  --query x509ThumbprintHex -o tsv)
LEAF=$(openssl x509 -in fullchain.pem -noout -fingerprint -sha1 | cut -d= -f2 | tr -d ':')
[ "${MERGED^^}" = "${LEAF^^}" ] || { echo "指纹不一致"; exit 1; }

DNS 验证 hook

--manual 模式下，Certbot 会为每个待验证的域名调用一次 auth hook、验证后再调用 cleanup hook，并通过环境变量 CERTBOT_DOMAIN（正在验证的域名）与 CERTBOT_VALIDATION（要写进 TXT 的值）传参。本文用两个小脚本承接——./azure-auth.sh 负责写入，./azure-cleanup.sh 负责清理。

./azure-auth.sh：验证前写入 TXT 并等待传播。 它先把域名换算成相对 DNS 区域的记录名（app.example.com → _acme-challenge.app，apex 则是 _acme-challenge），核心就是一条 az 命令：

az network dns record-set txt add-record \
  --resource-group "${DNS_RESOURCE_GROUP}" --zone-name "${DNS_ZONE_NAME}" \
  --record-set-name "${RECORD_NAME}" --value "${CERTBOT_VALIDATION}" -o none

写完还要轮询公共递归 DNS 等待生效——--manual 不会替你等传播。

./azure-cleanup.sh：验证后只删自己写入的值。 用 --value 精确删除很重要：apex 和通配符（example.com 与 *.example.com）会共用同一个 _acme-challenge，删整条会把别的挑战值一起删掉。

az network dns record-set txt remove-record \
  --resource-group "${DNS_RESOURCE_GROUP}" --zone-name "${DNS_ZONE_NAME}" \
  --record-set-name "${RECORD_NAME}" --value "${CERTBOT_VALIDATION}" -o none

两个脚本的完整写法（含环境变量校验、记录名换算、for 轮询等待）如下：

#!/usr/bin/env bash
# azure-auth.sh —— 写入 _acme-challenge 的 TXT 并等待传播
set -euo pipefail

: "${CERTBOT_DOMAIN:?Certbot 注入}"
: "${CERTBOT_VALIDATION:?Certbot 注入}"
: "${DNS_ZONE_NAME:?}"
: "${DNS_RESOURCE_GROUP:?}"

# 记录名相对区域：app.example.com -> _acme-challenge.app
if [ "${CERTBOT_DOMAIN}" = "${DNS_ZONE_NAME}" ]; then
  RECORD_NAME="_acme-challenge"
else
  RECORD_NAME="_acme-challenge.${CERTBOT_DOMAIN%.${DNS_ZONE_NAME}}"
fi

az network dns record-set txt add-record \
  --resource-group "${DNS_RESOURCE_GROUP}" --zone-name "${DNS_ZONE_NAME}" \
  --record-set-name "${RECORD_NAME}" --value "${CERTBOT_VALIDATION}" -o none

# --manual 不会替你等传播，这里轮询公共递归 DNS（dig 来自 dnsutils / bind-utils）
for _ in $(seq 1 30); do
  if dig +short TXT "${RECORD_NAME}.${DNS_ZONE_NAME}" @8.8.8.8 \
       | grep -qF "${CERTBOT_VALIDATION}"; then
    exit 0
  fi
  sleep 10
done
echo "ERROR: TXT 记录 ${RECORD_NAME}.${DNS_ZONE_NAME} 未生效" >&2
exit 1

cleanup hook 只删自己写入的值：

#!/usr/bin/env bash
# azure-cleanup.sh —— 只删除本次写入的那个 TXT 值
set -euo pipefail

: "${CERTBOT_DOMAIN:?}"
: "${CERTBOT_VALIDATION:?}"
: "${DNS_ZONE_NAME:?}"
: "${DNS_RESOURCE_GROUP:?}"

if [ "${CERTBOT_DOMAIN}" = "${DNS_ZONE_NAME}" ]; then
  RECORD_NAME="_acme-challenge"
else
  RECORD_NAME="_acme-challenge.${CERTBOT_DOMAIN%.${DNS_ZONE_NAME}}"
fi

# apex 与通配符会共用同一个 _acme-challenge，删整条会误伤，所以只删自己写的值
az network dns record-set txt remove-record \
  --resource-group "${DNS_RESOURCE_GROUP}" --zone-name "${DNS_ZONE_NAME}" \
  --record-set-name "${RECORD_NAME}" --value "${CERTBOT_VALIDATION}" -o none || true

关于 cleanup 的一个坑：Certbot 会在验证之后调用 cleanup hook，但如果 certbot 进程在调用它之前就异常退出（崩溃、被 kill，或中途某一步报错），这个 hook 可能不会执行，TXT 记录就留在 DNS 里了。好在残留的 TXT 记录本身无害——下次验证会写入新值，Let’s Encrypt 只匹配本次的预期值。如果在意整洁，可以再挂一个定时任务巡检并清理陈旧的 _acme-challenge 记录。

工程细节

staging 隔离：用 staging 时把证书名加上 -staging 后缀并做强制校验，避免不受信任的测试证书被合并进生产证书的版本。
并发保护：用 flock 对同一个证书加锁，避免两次运行同时操作。
幂等：签发前先检查有没有遗留的 pending 操作；auth hook 用“追加”而非“覆盖”的方式写 TXT。
自校验：合并后按第 4 步比对指纹，失败就报错，别让它悄悄过去。

运行顺序

先设置环境变量（目标域名、Key Vault 名称与证书名、DNS 区域与资源组），然后先打开 staging 跑一遍完整流程；确认无误后，再切回生产证书名跑一遍。另外，不要每次运行都重新注册 ACME 账户，账户的持久化见「ACME 账户」一节。

Staging 环境与速率限制

Let’s Encrypt 的证书签发有速率限制，调试阶段最容易撞上的几条是：

相同标识符集（exact set of identifiers）：每 7 天最多 5 张。反复用同一组域名申请，第 6 次就会被拒。这是全局限制，所有账户的请求都计入，而且吊销证书并不会返还额度。
同一注册域名：每 7 天最多 50 张，同样是全局限制。
每账户新订单：每 3 小时最多 300 个。

这几条限制设计得很不友好的一点，恰好戳中本方案：每次调用 az keyvault certificate create 都会开启一个新的订单。如果合并失败、又反复重试，额度会很快被吃掉。所以正确的姿势是：

用 staging 环境把整条链路跑通。staging 的额度比生产高得多（相同标识符集每周约 30000 张），签出来的证书不受信任，只能用于测试。
staging 的证书必须用一个带 -staging 后缀的独立证书名，并在流程里强制校验，否则一旦有人把它合并进生产证书，线上 TLS 立刻失效。
生产环境只在 staging 演练通过、且确实到达续期窗口时才运行。

还有两个容易忽略的点：

--csr 模式拿不到 ARI 豁免。 正常模式下，支持 ACME Renewal Info（ARI）的客户端续期可以豁免全部速率限制；但 --csr 只能配合 certonly 子命令使用，谈不上由 Certbot 管理的续期谱系，所以这份优惠用不上。这也是为什么续期必须自己调度、并且要珍惜额度。
公信证书会进入证书透明度（CT）日志。 签发的域名会被公开记录，内部敏感主机名不适合用公信证书。

自动化续期

--csr 模式不能用 certbot renew，Key Vault 对非合作 CA（Let’s Encrypt 不是 Key Vault 的内置合作 CA）也不提供自动续期。所以必须自己写调度逻辑。

具体做法是“先判断、再签发”：先用 az keyvault certificate show 读出证书的到期时间，算出剩余天数；只有剩余低于阈值时才真正走一遍签发流程，否则直接跳过。这样既不会空跑，也避免无谓地消耗 Let’s Encrypt 的额度。

# 读出到期时间，再自行换算剩余天数
az keyvault certificate show \
  --vault-name "${KEY_VAULT_NAME}" \
  --name "${KEY_VAULT_CERT_NAME}" \
  --query attributes.expires -o tsv

注意，--csr 模式下 Key Vault 策略里的 validityInMonths 只是信息性的，真正的有效期由 CA 决定。而且这个有效期正在变短：Let’s Encrypt 目前默认签发 90 天，但已明确会在 2028 年 2 月前缩短到 45 天；6 天有效期的短命证书（160 小时）也已可用（选用 ACME 的 shortlived 证书配置即可）。更大的背景是行业规则——CA/Browser Forum 的 SC-081 把公开 TLS 证书的最长有效期从 398 天逐步压到 200 天（2026-03-15）、100 天（2027-03-15）、47 天（2029-03-15）。变短的动因之一是安全：压缩误签与密钥泄露的有效窗口；但它同时“倒逼自动化”——有效期只有几十天时，任何手工续期都不可靠。

对本文方案来说，这意味着续期要比过去更频繁、更可靠：

续期必须做成定时任务并接入监控（cron、systemd timer、GitHub Actions 的 schedule、Azure DevOps 的 scheduled pipeline 都可以），每天或每周检查一次。
--csr 模式拿不到 ARI 续期豁免（见上文），额度更经不起浪费，“只在到期窗口内签发”这个判断不能省。
不要把阈值写死成 RENEW_BEFORE_DAYS=30，按有效期比例来设更稳，例如剩余不足 1/3 就续期；证书变短时窗口会自动跟着变短。

调度之外，还要做监控，否则“续期失败”可能直到证书过期才被发现：

续期任务失败要告警（流水线失败通知，或写入监控系统）。
订阅 Key Vault 的 CertificateNearExpiry / CertificateExpired 事件作为第二道保险。
签发作业的日志（Certbot 的 --logs-dir）应被采集，用于审计与排障。

故障排查

合并后证书与私钥不匹配？ 合并时的 fullchain.pem 必须来自同一个 CSR 对应的签名结果，且叶子证书在前、中间证书在后、不要带根证书。上文第 4 步的指纹校验就是为了拦住这种错配。

验证一直失败（DNS-01）？ 确认 _acme-challenge.<域名> 的 TXT 记录确实被创建、并且能被公网递归 DNS 解析到。本文的 auth hook 会轮询公共递归 DNS 等待传播，但前提是签发作业能访问公共解析——如果所在网络启用了私有 DNS 区域，它可能查不到刚刚写入的记录。别忘了 CAA 记录。

卡在 pending 状态？ 说明证书已创建但始终没有合并。脚本默认会直接报错而不是悄悄删掉，就是为了让这种异常可见。排查后确认可以丢弃时，再用 DELETE_PENDING=true 重跑。

撞上速率限制？ 看错误信息里的 Retry-After，按提示时间等待即可，没有提前重置的办法。开发测试请改用 staging；生产环境要避免“每次部署都重新签发”，只按到期窗口续期。

安全清单

项目	做法
私钥保管	默认 `exportable: false`；TLS 终止类消费端需 `true`，由服务用托管标识取用；合规场景用 Managed HSM
密钥轮换	`reuseKey: false`，每次续期生成新密钥
签发身份	UAI 或 OIDC 联合凭据，不用长期密钥
Key Vault 权限	只给证书相关角色，不含 `secrets/*`
DNS 权限	自建只写 TXT 的角色，或用 CNAME 委派到独立挑战区
网络	Private Endpoint + 关闭公网访问
数据保护	开启软删除与清除保护
审计监控	诊断日志入 Log Analytics，订阅证书事件
ACME 账户	用持久化的 `--config-dir` 保存；邮箱可选但建议填
测试隔离	staging 用 `-staging` 后缀的独立证书名
到期与续期	自带调度 + 失败告警，不依赖 Key Vault 自动续期

小结

企业环境里最值钱、也最容易在自动化流程中被忽视的东西，是私钥。把私钥的生成与保管交给 Azure Key Vault、让 Certbot 退回到“ACME 客户端”的本分，再用最小权限和 staging 演练把整条链路管起来，就能在保留 Let’s Encrypt 免费与自动化的同时，满足企业最基本的安全与审计要求。剩下的取舍——私钥到底能不能导出、证书落在哪里——取决于谁来消费它，这需要在动手之前就想清楚。

参考

Azure Front Door 配置路由指南

Mon, 12 Oct 2026 00:00:00 GMT

Azure Front Door 的 Standard/Premium 里，一条能对外服务的路由，背后是几个资源按顺序拼起来的：自定义域名、源组与源、路由，必要时再加 WAF（Web Application Firewall，Web 应用防火墙）。顺序错了，或者某个字段理解偏了，就会出现「域名配好了却打不开」「健康探针一直 Unhealthy」之类的问题。

本文按实际配置顺序把整条链路走一遍，希望能让刚接触 Front Door 的人照着做就能跑通。文中说的 Front Door 均指 Standard/Premium（classic 版本正在退役）。

Azure 上的几个入口服务

Azure 上有几个容易混淆的流量入口服务，定位差别很大：

服务	工作层次	范围	典型用途
Azure Front Door	L7（HTTP/HTTPS）	全局（location 就是 Global，接入点遍布各地）	全球入口：加速、缓存、TLS 卸载、WAF
Application Gateway	L7（HTTP/HTTPS）	区域（部署在某个区域 / VNet 里）	区域内的 L7 负载均衡，可带 WAF
Azure Load Balancer	L4（TCP/UDP）	区域	四层负载均衡
Azure Traffic Manager	DNS	全局	基于 DNS 的流量调度

关键区别在范围：Front Door 是全局服务（它的 location 就叫 Global），用户就近接入边缘节点；Application Gateway 是区域服务，部署在具体的 VNet 里。所以两者定位不同，也常常配合使用——Front Door 放最外层做全球入口，Application Gateway 放在区域内的入口。（顺带一提，Azure CDN from Microsoft (classic) 正在退役，其缓存能力已并入 Front Door。）

先认识几个资源

资源	作用
Profile	Front Door 本体，也是日志、安全策略的作用域
Endpoint	每个 endpoint 都有一个默认域名 `xxx.z01.azurefd.net`
Custom domain	对外的自定义域名（含通配符）
Origin group / Origin	源组和源，即后端服务
Route	把自定义域名和源组连起来
Rule set / Rule	规则集与规则：匹配条件 + 动作，挂在路由上（URL 重写、改请求/响应头、缓存覆盖等）
Security policy	把自定义域名和 WAF policy 连起来

依赖关系上，通常是：先把域名建好并验证，再建源组和源，然后建路由把两者连起来，最后按需挂规则集、接 WAF。

第 1 步：创建自定义域名

Front Door 支持三种自定义域名：

类型	示例	典型用途
子域名	`www.contoso.com`	最常见
顶级域名（apex）	`contoso.com`	裸域名
通配符	`*.contoso.com`	多租户 / SaaS，一个通配符覆盖所有一级子域名

通配符最省事：配好一条路由，customer1.contoso.com、customer2.contoso.com 这类一级子域名就都被覆盖了。新增租户时，只要在 DNS 里加一条 CNAME 指过来即可——完全不用碰 Front Door，也不用逐个签发证书。换句话说，以后新增域名只动 DNS，不动 Front Door。

关于域名，有一点要特别提醒：一个自定义域名同一时间只能关联一个 endpoint。不同 profile 可以用同一个域名的不同子域名，但不能用同一个完整域名。

这一点比较坑，值得展开说：它意味着把一个已经上线的域名从 profile A 挪到 profile B，只能先把它从 A 删掉、再加到 B，这中间必然有中断，因为 Front Door 不支持在 B 里先把同一个域名配好。官方给的两条「无中断」路子是——临时把流量切到源站或另一个 CDN 做中转，或者走 tier 升级（classic → Standard/Premium、Standard → Premium）。再叠加下面要说的配置传播时间，这个窗口会比预想的更长，迁移前记得留够维护窗口。同样的坑在从 Azure CDN 迁过来时也会遇到，可参考《迁移 Azure CDN (Classic) 到 Azure Front Door》。

第 2 步：用 _dnsauth 的 TXT 记录验证所有权

域名所有权验证是必须做的。默认用 _dnsauth 的 TXT 记录完成，这也是选择 Azure 托管证书时的固定方式；如果自带证书（BYOC）且证书的 CN/SAN 与域名匹配，所有权会自动通过，就不需要再加 TXT（不匹配时仍然要加）。

添加域名时，Front Door 会给出一个验证令牌（validation token），需要在 DNS 里建一条 TXT 记录来证明域名归属。

TXT 记录名的规律是 _dnsauth. 加上去掉开头 *. 的域名，最终以门户给出的记录名为准：

自定义域名	TXT 记录名（FQDN）
`www.contoso.com`	`_dnsauth.www.contoso.com`
`contoso.com`（apex）	`_dnsauth.contoso.com`
`*.contoso.com`	`_dnsauth.contoso.com`

记录值就是门户上显示的 token。验证状态会经历 Submitting → Pending → Approved，通常几分钟内完成。如果一直不通过，检查记录名和值是否完全一致、TTL 是否过大；验证用的 TXT 记录有一定时效，失败时可以重新生成一个。

验证通过后，就可以给域名启用 HTTPS 了，两种方式：

Azure 托管证书：免费，Front Door 负责签发和部署，推荐。选择它时，所有权继续用上面的 TXT 记录验证。
自带证书（BYOC）：证书放在 Key Vault，记得给 Front Door 的托管标识授予 Key Vault 的读取权限。

托管证书会自动轮换，但轮换时是否需要重新验证域名所有权，取决于 Azure 当前的最新策略，不同域名类型可能不同：

域名类型	是否支持托管证书
子域名	支持
apex（顶级域名）	支持
通配符	支持

无论哪种域名，轮换时都有可能进入 Pending revalidation，此时需要重新生成并更新 _dnsauth 的 TXT 记录。保险的做法是关注域名的验证状态，看到 Pending revalidation 就及时处理，别等到证书到期。

最后，还要把域名的 CNAME 指向 Front Door 的 endpoint 域名，流量才会过来。apex 域名不支持 CNAME，需要用 Azure DNS 的 alias 记录，或提供商的 CNAME flattening。

第 3 步：创建源组和源

先分清 SNI、Host 和 X-Forwarded-Host

这是最容易踩坑的地方。Front Door 到源之间，有三个不同的概念：

名称	出现在哪	由谁决定
SNI	TLS 握手	源的 Host name
Host 头	HTTP 请求	源的 Origin host header；留空则透传客户端请求的原始 Host
X-Forwarded-Host	HTTP 请求	Front Door 自动添加，值 = 客户端请求的原始 Host（会覆盖已有值）

要点：

Front Door 与源建立 TLS 连接时，SNI 用的是源的 Host name，而不是客户端请求的域名。
转发给源的 Host 头由 Origin host header 决定；把它留空，Front Door 就会把客户端请求的原始 Host 透传下去，这就是所谓的 Host 名保留。
无论 Host 头是什么，源都能从 X-Forwarded-Host 拿到客户端最初请求的域名。

由此有个常见结论：如果源要求 Host 头与证书一致（比如 App Service、Blob Storage），就把 Origin host header 设成源主机名；如果源依赖原始域名做路由，就把它留空。

还有一个开关：证书主体名称校验（Certificate subject name validation），默认开启。开启时，源返回的证书的 CN/SAN 必须匹配源的 Host name，否则连接会被拒绝。启用 Private Link 时这个校验是必须的。

当 SNI 与 Host 不同时

有时候需要让 SNI 与 Host 是两回事：用 A 域名（源主机名）和源的证书建立 TLS，再用 B 域名（面向用户的域名）做路由。这时源必须同时接受两者——用 SNI 选证书，用 Host（或 X-Forwarded-Host）匹配路由。

这在 SaaS 场景里很常见：租户带着自己的域名（B）接进来，证书由 Front Door 统一管理，源站则用内部域名（A）和内部证书接住 Front Door 的 TLS，再靠 Host 头把请求分给对应的租户。

Kubernetes 的 Gateway API 是个典型例子。默认它要求 TLS 的 SNI 与 HTTP 的 Host 一致，或至少有交集，否则返回 404。解决办法是在 Gateway 上不设置 hostname、只配置 TLS 证书，把域名匹配交给 HTTPRoute 的 hostnames。这样一来，即使 Front Door 用源的 Host name 作为 SNI 建连、而 Host 头是另一个域名，也能正常路由。具体可参考《在 K8s Gateway API 中为多个 Hostname 使用单个证书》和《将 Ingress NGINX 迁移到 Azure Kubernetes Service 上的 Gateway API》。

配好后，可以在本地直接验证源是否接受 SNI 与 Host 不一致：

# 用一个 SNI 建 TLS，检查证书是否匹配源的 Host name
openssl s_client -connect <origin-host>:443 -servername <origin-host-name>

# TLS 用源的 Host name，但 HTTP Host 用另一个域名
curl -sv --resolve <origin-host-name>:443:<origin-ip> -H "Host: <public-domain>" https://<origin-host-name>/

注意，这种「容忍 SNI 与 Host 不一致」是 Front Door 对源的要求；换成 Front Door 自己做入口，情况就反过来了。Front Door 有域名前置（domain fronting）防护：请求的 SNI 与 Host 不匹配时会被拒绝，返回 421 Misdirected Request，日志里 Error Info 记为 SSLMismatchedSNI；只有两个域名同属一个订阅、且都配置在路由里时才放行。

这也解释了一个实际限制：Front Door 不能套 Front Door。官方 FAQ 明确说，把一个 Front Door profile/endpoint 放在另一个后面会共用同一批边缘 POP，导致路由冲突和性能问题，所以不要把多个 Front Door 串起来。

源在私有网络里：用 Private Link

如果源在内网 VNet 里，Front Door「看不到」它，可以让源通过 Private Link Service 暴露出来，Front Door 侧作为一个 private endpoint 接入。几个要点：

启用 Private Link 后，Host name 用于 SNI，要与服务端证书匹配；Origin host header 只用于 HTTP 请求头。
必须开启证书主体名称校验。
需要在源侧 Private Link Service 里 approve 这个 private endpoint connection（也可以配置自动 approve）。
同一个源组里不能混用公有源和私有源。

源组的其他设置

健康探针（协议、路径、间隔）：HTTPS 探针同样用源的 Host name 建连，所以源的证书必须匹配它，否则探针会报 Unhealthy。
负载均衡：按延迟或按样本。
优先级（Priority）与权重（Weight）：用于主备或多活。
会话保持（Session affinity）：见下。

会话保持（Session affinity）

同一个域名、应用在多个源上做分布式部署时，Front Door 默认会把同一客户端的不同请求分发到不同源。对无状态应用没问题，但对有状态应用（本机 session、内存缓存、要求固定实例的鉴权令牌等）就会出问题。开启源组级的 Session affinity 后，Front Door 会给客户端下发会话 cookie（ASLBSA 和 ASLBSACORS），后续请求据此回到同一个源。

几个容易踩的点：

它在源组级别开启（Standard/Premium），作用于与该源组关联的域名。
它是尽力而为，不是硬绑定。Front Door 先按延迟筛出候选源（最佳 RTT + 延迟灵敏度窗口），再从候选里优先选 cookie 指向的那个。如果固定的源不健康，或掉出延迟窗口，请求仍会被切走。延迟灵敏度越大越稳，但不是硬绑定。
只有在不可缓存的响应上才会建立会话 cookie：响应要带 Cache-Control: no-store（注意 no-cache 不算），或是带未过期 Authorization 头、或 302 响应，并且源必须健康。源回可缓存内容时 cookie 不会下发，粘性也就无从谈起。
它是会话 cookie，浏览器关闭即失效；通配符域名下，同一浏览器会话可在子域名之间共享。
它替代不了共享状态。真正需要跨实例共享的 session 或缓存，还是应该放到共享存储里，不要依赖粘性。

源响应超时（Origin response timeout）

Front Door 等待源返回的时间是有上限的。这个值在 profile 的 Overview 页设置（不在源组里），作用于该 profile 的所有 endpoint，可填范围是 16–240 秒，最长 4 分钟。接口偶尔会慢（比如报表生成、长轮询）时，记得先把这个值调大，否则会收到 5xx。

注意 4 分钟就是天花板。真有需要更长时间才返回的请求，Front Door 满足不了，得换个入口放在源前面，可能就要改用 Application Gateway。

第 4 步：创建路由

路由把自定义域名和源组连起来，主要配：

域名：选择一个或多个自定义域名。
路径模式：通常用 /*。注意各条路由之间的路径模式要一致，否则可能出现域名命中了、路径却没命中，客户端直接失败。
转发协议：到源用 HTTP 还是 HTTPS。
缓存、压缩、规则集（Rule set）等。

域名匹配遵循最具体优先：同时存在通配符 *.contoso.com 和具体子域名 image.contoso.com 时，请求 image.contoso.com 会走具体子域名的那条路由。

缓存与压缩

在路由上可以开启缓存，对静态资源（图片、CSS、JS）收益最大；反过来，动态或需要鉴权的接口不要缓存，以免串数据——建议把静态和动态拆成不同路由。

查询字符串缓存行为决定带 ?a=1 的请求算不算同一个缓存对象，有四种：Ignore Query String、Use Query String、Ignore specified query strings、Include specified query strings。
压缩（动态压缩）也在这里开，可以指定要压缩的 content type。
缓存时长优先看源返回的 Cache-Control；源没给时，Front Door 默认随机缓存 1–3 天。private、no-cache、no-store 的响应不会被缓存。
需要按条件覆盖缓存行为或时长时，可以在规则集里做；规则集的缓存配置会覆盖路由的。

规则集（Rule set）：挂在路由上的小逻辑

规则集由「匹配条件 + 动作」组成，建好后要关联到路由才会生效；一个规则集可以关联多条路由。常用动作有：URL 重定向、URL 重写、修改请求头、修改响应头，以及缓存相关的覆盖。

一个典型用法是加安全响应头：新建规则集，动作用「修改响应头（Response header）」、操作选 Append，头名写 Content-Security-Policy、值填策略，再挂到对应的路由上——这样匹配该路由的响应都会带上 CSP。HSTS、X-Frame-Options、CORS 的 Access-Control-Allow-Origin 同理。

注意：Front Door 有一批保留头不能由规则修改，X-Forwarded-Host 等就在其中。

路由数量不是无限的：composite route limit

Front Door 对路由的约束不是「一个 endpoint 最多几条」这么简单，而是按 profile 算一个综合值（composite route metric），上限 5000（完整规则和示例见 Routing limits in Azure Front Door）。算法是：

单条路由：HTTP 域名数 × HTTP 路径数 加上 HTTPS 域名数 × HTTPS 路径数；
如果这条路由通过规则集做了路由覆盖（route override），还要再加 域名数 × 覆盖次数（HTTP、HTTPS 分别算）；
把所有路由的这些值加起来，就是该 profile 的综合值。

几点提醒：

它是按 profile 汇总的；origin group、origin、endpoint 的数量不影响这个值。
域名和路径是相乘的关系，域名一多就很容易撞上限——SaaS 场景尤其要注意。
同时开 HTTP 和 HTTPS，等于把路径算了两遍；接入只留 HTTPS，同样配置的占用能减半。
另外还有一条硬性数量限制：每个 profile 最多 100（Standard）/ 200（Premium）条路由。

真撞上限时，官方建议：把路由拆到多个 profile、多用通配符域名、接入只开 HTTPS。

顺带一提，源的名字建好后无法就地修改；真要改名又不能中断服务，可参考《Azure Front Door 技巧：修改 Origin Name》。

第 5 步：把域名关联到 WAF

WAF 不是直接挂在 Front Door 上，而是通过 security policy 把域名和 WAF policy 关联起来。

作用域与优先级：route 级 > domain 级 > profile 级，命中时用最具体的一层。可以先用 profile 级做基线，再对特定域名或路由叠加。
WAF policy 有 Classic/Standard/Premium 之分，要与 Front Door profile 的 tier 对应。自定义规则两层都能用；托管规则集（默认规则集 DRS、Bot 保护）和 Private Link 只有 Premium 有。
费用要留意：Front Door 的底价 Standard 约 $35/月、Premium 约 $330/月（以官方定价为准，因区域而异）；WAF 和 Private Link 已包含在 Premium 里，Standard 的自定义 WAF 规则也不额外收费。只需要自定义规则就选 Standard，要用托管规则集再上 Premium。
通配符域名可以直接挂 WAF，用一条 policy 覆盖所有子域名。Standard/Premium 下，子域名默认继承通配符域名的 WAF policy；如果某个子域名要用不同的 policy，就显式关联它（具体优先）。
如果不想让某个子域名跑 WAF，可以给它关联一个没有规则的空 policy。

第 6 步：验证配置并切换 DNS

正式切域名前，最好先验证整条链路是否通。此时域名还没指向 Front Door，有两种办法。

可以修改本地 hosts 文件，把域名临时指向 Front Door endpoint 的 IP；更推荐用 curl 的 --connect-to，让 SNI 和 Host 都保持为目标域名，但把连接打到 Front Door 的 endpoint：

# 连接到 endpoint，但 SNI 与 Host 都保持为 www.contoso.com
curl -sv --connect-to www.contoso.com:443:contoso.z01.azurefd.net:443 https://www.contoso.com/health

也可以用 --resolve 指定 endpoint 的 IP：

curl -sv --resolve www.contoso.com:443:<endpoint-ip> https://www.contoso.com/health

-v 会打印 TLS 握手里真正的 SNI、证书的 CN/SAN 以及响应头，方便确认证书是否已为这个域名签发、命中了哪条路由。更完整的说明见《测试已启用 HTTPS 但尚未配置域名的站点》。

其他全局设置与运维

诊断日志

访问日志、健康探针日志、WAF 日志默认都不开，需要在 Front Door profile 的 Diagnostic settings 里显式开启，发送到 Log Analytics、存储账户或 Event Hub：

FrontDoorAccessLog：所有经过 Front Door 的请求。
FrontDoorHealthProbeLog：健康探针的结果。
FrontDoorWebApplicationFirewallLog：被 WAF 规则命中的请求。

排障时的查询示例：

// 访问日志
AzureDiagnostics
| where ResourceProvider == "MICROSOFT.CDN" and Category == "FrontDoorAccessLog"

// 被 WAF 拦截的请求
AzureDiagnostics
| where ResourceProvider == "MICROSOFT.CDN" and Category == "FrontDoorWebApplicationFirewallLog"
| where action_s == "Block"

除了日志，Front Door 还提供指标（包括 WAF 请求计数），可以在 Metrics 里直接看。

清除缓存（Purge cache）

改了内容但 TTL 还没到，可以手动清除（purge）：在 profile 的 Overview 页点 Purge cache，选 endpoint 和域名，然后要么清除全部，要么填具体路径。路径支持单个文件（如 /pictures/strasbourg.png），也支持通配符（如文件夹 /scripts/*、整个 endpoint /*）。

几个注意点：

一次 purge 最多 100 个 URL（域名 + 路径）；更多要分批，且必须等上一批完成再提交，否则会被拒。
purge 大小写不敏感、且忽略查询字符串：清一个 URL 会连带清掉它所有 ?query 变体。
通配符域名不能直接 purge，要指定具体子域名。
purge 是全局操作，在所有 POP 生效最长约 10 分钟。

比起频繁 purge，更好的做法是给静态资源加版本号（每次更新换新 URL），Front Door 下次请求自然就取到新的了。

耐心等待变更生效

Front Door 的配置变更是一次全局操作，改完不会马上生效。按官方 FAQ，单次创建/更新/删除/WAF 操作最长可能要等约 15 分钟，缓存清除约 10 分钟；连续改好几处时，后面的会排队，总时间可能拉到约 30 分钟。自定义 TLS 证书更慢，最长约一小时。

这事也有来历：2025 年 10 月 Front Door 那次多区域故障出在配置传播上，官方随后给传播流水线加了额外的安全阶段和 bake time，传播时间一度被拉长到 45 分钟，之后才逐步压回 15 分钟。

所以，改完配置或切完 DNS，泡杯茶回来再看结果也不迟——别一刷新就怀疑自己配错了。配个东西等半小时，心态要稳。

小结

按顺序走下来其实不复杂：先建域名并用 _dnsauth 的 TXT 记录验证，启用托管证书；再建源组和源，想清楚 SNI、Host 与 X-Forwarded-Host 各自由谁决定；然后用路由把域名和源组连起来；按需用 security policy 接上 WAF；最后别急着切 DNS，先用 curl --connect-to 验证通过再正式切换。日志和 WAF 日志记得打开，排障时会省很多事。

参考资料

在本地运行 Pulumi 管理 GCP 资源

Mon, 12 Oct 2026 00:00:00 GMT

用 CI/CD 流水线部署 GCP 基础设施，是 Cloud Engineering 的正道：比如 GitHub Actions 配合 Workload Identity Federation，把身份、权限、审计都收敛到流水线里，本地不必持有长期凭据。但在学习阶段，或者线上出了故障需要紧急手工修一把时，从本地跑 Pulumi 依然很实用。

麻烦往往出在本地认证上。Pulumi 的 GCP Provider 在没有显式配置时，会回退到 Application Default Credentials（ADC）；而在企业环境里，这条路径经常被组织策略挡住，需要 Google Workspace 或 Cloud 管理员放行。本文记录一个更轻的技巧：复用 gcloud 已经登录的身份，打印一个临时访问令牌并导出成环境变量，就能让本地 Pulumi 直接跑起来。

常规的本地认证方式

Pulumi 的 GCP Provider 支持几种认证方式。本地开发时官方推荐的是先登录 ADC：

gcloud auth application-default login

它会把用户凭据写进 ADC 文件，供 Pulumi 等客户端库读取。另一条路是创建服务账号密钥，再通过 GOOGLE_APPLICATION_CREDENTIALS 指向密钥文件。若没有配置任何凭据，Provider 最后才会回退到 ADC。

在企业环境里，这两条路都可能走不通：

创建服务账号密钥通常被组织策略禁用，例如约束 constraints/iam.disableServiceAccountKeyCreation。
ADC 登录、以及在组织中放行某些认证方式，往往需要管理员操作。

于是就出现了”本地跑 Pulumi 还得找管理员开权限”的尴尬。下面这个技巧绕开了这些步骤：既不创建密钥，也不单独登录 ADC，只是复用 gcloud 已登录的用户身份。

技巧：用 gcloud 的临时访问令牌

前提是本机已经用 gcloud auth login 登录过，并且该账号本身能访问目标项目。

打印访问令牌

gcloud auth print-access-token

它会打印当前 gcloud 活跃账号的 OAuth 2.0 访问令牌。

导出为 Pulumi 读取的环境变量

export GOOGLE_OAUTH_ACCESS_TOKEN="$(gcloud auth print-access-token)"

这里有两个容易混淆的环境变量，值得单独说清楚：

GOOGLE_OAUTH_ACCESS_TOKEN：Pulumi 的 GCP Provider 读取的变量，对应 provider 的 accessToken 配置。
CLOUDSDK_AUTH_ACCESS_TOKEN：gcloud CLI 自身读取的变量。

如果导出的是后者，gcloud 命令会正常使用它，但 Pulumi 依然认不出——这也是我一开始记不清”到底是哪个变量”的原因。

指定项目并执行

export GOOGLE_PROJECT="your-gcp-project-id"
pulumi up

GOOGLE_PROJECT 是 Provider 读取项目的环境变量之一；按其优先级依次还有 GOOGLE_CLOUD_PROJECT、GCLOUD_PROJECT、CLOUDSDK_CORE_PROJECT。当然，也可以在 Pulumi.<stack>.yaml 里用 gcp:project 指定项目。

这样一来，Pulumi 就用自己的用户身份调用 GCP API，不再需要单独配置 ADC 或服务账号密钥。pulumi preview、pulumi refresh、pulumi import 等命令同理，都能直接用这套凭据。

注意事项

令牌有有效期，默认 1 小时。Pulumi 命令要在有效期内跑完；超时就重新执行 gcloud auth print-access-token 并重新导出即可。
Pulumi 不会自动刷新这个令牌，它和 Terraform 的 access_token 一样，只是拿来即用、过期作废。
不要把令牌写进代码或提交到 Git。临时会话用环境变量最省事；若一定要落到 Pulumi 配置里，至少用 pulumi config set --secret。
本文的环境变量技巧适用于 pulumi-gcp（classic）Provider。若你用的是较新的 pulumi-google-native，它不读 GOOGLE_OAUTH_ACCESS_TOKEN，需要把令牌通过 pulumi config set 放进 Provider 配置里。

先提权：用 PAM 临时拿权限

在权限收紧的组织里，日常账号通常没有部署所需的角色，需要先提权。Google Cloud 的 Privileged Access Manager（PAM）提供”按需、限时、可审批”的临时授权，正好适合这种场景。

先搜索自己可以申请的 entitlement：

gcloud pam entitlements search \
  --caller-access-type=grant-requester \
  --location=global \
  --project="your-gcp-project-id"

再发起授权申请，例如申请 1 小时：

gcloud pam grants create \
  --entitlement="ENTITLEMENT_ID" \
  --requested-duration=3600s \
  --justification="emergency hotfix"

如果 entitlement 配置了审批，还需要审批人执行：

gcloud pam grants approve GRANT_NAME --reason="approved"

授权生效后，再用上面的方式打印令牌并运行 Pulumi 命令（例如 pulumi up）。GCP 在每次调用 API 时都会按当前 IAM 角色鉴权，因此 PAM 临时授予的角色会一并生效。

提示：gcloud pam 的部分子命令目前仍处于 beta / alpha，参数可能变化，以本机 gcloud pam --help 为准。

小结

CI/CD 流水线仍是默认路径，Workload Identity Federation 能免去本地长期凭据。
需要在本地临时操作时，用 gcloud auth print-access-token 配合 GOOGLE_OAUTH_ACCESS_TOKEN 最省事，无需 ADC 或服务账号密钥。
权限不够就先用 PAM 做限时提权。
令牌短命、用完即弃；事情处理完，回到流水线。

参考文档

AI 时代的 Cloud Engineering：纪律与修养

Sat, 10 Oct 2026 20:20:20 GMT

写在前面

本文由 AI 执笔，人类立意——生成交给黑盒，把关留给人。 Written by AI, imagined by a human.

软件工程里最老、也最少被遵守的一句忠告，Jeff Atwood 说得最直白：最好的代码，就是没有代码。AI 没让它过时，反而让忽略它变得更贵——它让写代码变快了，却没让“改对了”变简单：未经核实的变更照样打挂集群，嘈杂的 PR 照样耗尽注意力，散落的部落知识照样带来混乱。何况，写代码的人正越来越依赖 AI，也越来越少经历那种把纪律磨成本能的重复；代码生成越来越像黑盒，每一步怎么来的，都难以看清。于是那个老问题又冒了出来：这些老纪律还成立吗？答案是肯定的：它们不但成立，反而更值钱了——生成可以交给黑盒，而黑盒外那几道由人把守的关卡，才守得住质量、压得住混乱，甚至让流程更快。

把经验收拢起来，值得守的习惯大多落在三个地方——版本控制（Git）、基础设施管理（IaC，Pulumi）、应用部署（ArgoCD）。都是些“古法”：不新，不酷，甚至有点老古董；可偏偏是它们，在出事的时候最靠得住。工具和语法从不稀缺，AI 还能现写；稀缺的，是判断和节制。目的不是立规矩，而是让 AI 加速之后的工作流，依然安全、确定、可扩展。

下面不按这三个地方来分——同一条原则，往往同时管着 Git、Pulumi 和 ArgoCD，硬按工具切开反而割裂。所以这里分成三组：四条流程原则，讲变更怎么从成形走到落地；一条设计原则，讲代码与配置怎么组织；外加两条底线，不属于任何单个阶段，却是每条原则都得守的。每条都先讲清它想守住什么，再给能照做的做法。老实说，没有一条是新的。这些原则，说到底都在回答同一个问题：生成变便宜之后，判断与节制该落向哪里——答案或许是，落到一条轨迹上，而不只是一个终态。这也是展开它们之前，需要先摆清楚的前提。

终态是图，轨迹是路

先说一个前提：真实世界里的环境，是有时间维度的——不管它由代码搭建，还是靠手工一步步搭起来。让 AI 一口气把 dev、test、staging、prod 四个环境的配置都生成齐，命名一致、结构齐整，一眼就是“最终形态”；可现实里它从来不是这样长出来的——先在 dev 和 test 里搭起来、验证，再提升到 staging 观察一段时间，确认无事，才轮到 prod。四个环境最终都有这套配置，但它是一级一级攒出来的，不是一次铺满的。

AI 很可能看到的、给出的，都是终态；而工程真正要交付的，却是一条轨迹。前者横着铺开：一句 prompt，就能把终态一次画全，还天然倾向于把能写的都写上；后者竖着走：变更沿一条风险递增的阶梯向上挪，dev → test → staging → prod，每一级都是一次曝光、一轮观察、一次“还能重来”的尝试——所谓“提升”，本质是信心在逐级累积。

这一点在复刻现成的环境时尤其隐蔽：仓库现成、配置现成，一键部署，看上去一步到位。可那套“终态”是从一条轨迹里长出来的，轨迹却几乎无法复制——于是你拿到了结果，却没拿到结果背后的证据。

跳过这条轨迹，等于拿着终态的图去盖生产环境那张“已验收”的章——章是真的，却没人体检过。AI 很可能把终态画得出来，却画不出通往终态的那条路；而判断要不要往上走的依据，全在这条路上。 接下来的四条流程原则，做的正是同一件事：把 AI 折叠掉的那条时间维度重新展开，给“快”重新铺一条能逐级验证、也能逐级回头的轨道。

流程四原则

先看变更本身——从成形到落地，该怎么走。

原则一：小步且可验证

把变更拆小、每步都验证，听起来像常识，作用却很实际：真出问题时，你能一眼看出是哪一小步，也能单独回退，而不必在一坨几百行的改动里大海捞针。

主干开发

先澄清一点：主干开发（Trunk-Based Development）并不等于直接往 main 推代码——对 main 的直接提交是受限制的。

它的意思是：main（旧仓库里可能是 master）是唯一的事实来源，大家用短、快的节奏迭代。

短命特性分支：从 main 切一个分支，完成一个具体的小任务，提 PR，然后尽快合回 main（理想情况下一两天内）。
避开长命分支：特性分支最好别开上几周。它和 main 分离越久，集成越难；如果确实要长期存在，就经常把 main 合并回自己的分支。
从最新的 main 切分支：动手前先 git checkout main && git pull。从陈旧的代码或已存在的特性分支切出去，会把无关的 diff 带进新 PR。
一个任务 = 一个分支 = 一个 PR = 删除：PR 一合并，这个分支的使命就结束了，别再复用。复用会带来“脏状态”（残留的本地提交、旧的 PR 评论历史、跟踪错配）——删掉、从 main 重开，每次都从一张干净的白纸开始。
CODEOWNERS 要求：合入 main 至少需要一位指定 CODEOWNERS 成员批准，且不能是自己。

小而原子的 PR

拆一个大特性，本质上也是一种表达——只不过介质是代码，而不是自然语言。既然是表达，就该让读的人一眼看懂：一个 PR 只讲一件事，讲完就结束。

拆成小的、单一职责的 PR：每个 PR 最好都能独立验证，且合进去不会破坏现网、也不会让系统卡在不一致状态。小而安全的改动，审阅者能更快、更有信心地批准——这是加快评审与合并最有效的办法。
复杂特性早点开 Draft PR：如果特性复杂或有架构影响，在开发早期就开一个 Draft PR，让团队先对高层方案做一次“预评审”，免得临近合并时才发现要推倒重来。
让改动可追踪、可复现：先过流水线再合，能消掉藏在个人脑中的隐性知识，让任何人都能顺着记录追踪、理解，并在各环境复现。

原则二：为审阅者着想

快速获批的关键在发起方的准备。评审需要专注，每一个 PR 请求都是一次上下文切换。发起方把 PR 自审干净、背景写清楚，审阅者就能把精力花在架构和设计上，而不是基础修复或猜意图。

代码评审是反馈，不是评判：它的目的是分享知识、拉齐质量标准、一起发现盲点，而不是针对作者本人。评论尽量具体、建设性，收到反馈也当作一次协作打磨。
先自审，再请人审：AI 工具和代码片段能提速，但它们只是起点。发出去之前快速过一遍——有没有残留的占位符、逻辑对不对、上下文是否自洽——省的是所有人的时间。
让审阅者省点心：作为作者，在 PR 描述里交代改了什么、为什么改、怎么验证的。准备到位，审阅者两三分钟就能看完并批准。
紧急改动走快速通道：对紧急、简单、或只有合并后才能完整验证的改动，在描述里写明背景，审阅者才知道该审到什么深度，周转自然更快。
PR 模板也要守（AI 助手同理）：如果用 AI 工具（如 Claude Code）起草 PR 描述或提 PR，让它遵守仓库的 .github/pull_request_template.md——包括结构、章节标题和 Markdown 格式。AI 生成的描述应当补充团队的标准格式，而不是绕过它，除非有充分理由。

原则三：用环境说话

一句话：别只在自己机器上“感觉没问题”，就让流水线和真实环境来作证。

验证：别只说“本地能跑”

Kent Beck 有句名言：make it work, make it right, make it fast（出处）。这里只取它的前半程：先保证结果正确，再谈代码是否优雅。PR 描述里的“验证”小节，做的就是把验证的过程和结果摆出来，而不只是一句“我本地跑过了”。

给出结果：附上可核实的凭据——流水线运行链接、终端输出，或已创建云资源的截图。
交代过程：说明是在哪个中立环境里验证的（CI 流水线或沙箱），而不是只靠本地，免得上线时踩到意外。
先对齐，再动手：先对齐交付物与验收标准，再动手写代码；一个特性只有真实环境端到端验证通过、并交付了预期价值，才算真正完成。

在 ArgoCD 中做隔离验证

引入新 add-on、修改现有服务，或验证结构性 manifest 变更时，如果直接把代码合进 main，ArgoCD 会立刻把未经核实的变更应用到目标集群（前提是 Application 启用了自动同步 syncPolicy.automated；否则合并后只会显示 OutOfSync，需要人工 sync）。

其实没必要为了“试试能不能跑”就抢着合 main。未验证就合并，换来的往往是试错式的提交噪声、跨多个碎片化 PR 的范围蔓延，以及大段只存在于个人脑子里的隐性知识。

对非平凡的变更，更划算的做法是让每个 PR 或基础设施改动自包含、可验证，在真实环境端到端验证后再合入 main；至于简单的取值更新，走轻量评审、快速合并就够了。

隔离验证的工作流如下：

阶段	`targetRevision`	操作	效果
① 铺路（PR 1）	→ `feature/my-addon-test`	合入 main	ArgoCD 改为从特性分支同步到集群
② 迭代验证	`feature/my-addon-test`	在特性分支上 push、测试	在集群里安全地验证真实行为
③ 恢复（PR 2）	→ `main`	合入 main	回到干净的生产同步

分步说明：

铺好路由（PR 1）：对 main 提一个小 PR，把 ArgoCD Application 定义里的 targetRevision 从 main（或 HEAD）改指向你的特性分支（如 feature/my-addon-test），然后合并。
安全地迭代与验证：直接在特性分支上开发、推送、测试你的 manifest。ArgoCD 会从该分支同步，让你能在集群里完整观察真实行为。
恢复并干净合并（PR 2）：测试通过、准备晋升时，把 targetRevision 改回 main（或 tag / release），再把特性分支的代码合入 main。

注意两点：修改 targetRevision 本身也要等一次 sync 才会生效；如果这个 Application 由 ApplicationSet 或 app-of-apps 管理，该字段可能被上层模板覆盖。

基础设施变更只走流水线

本地用 pulumi preview 看改动没问题。但除非是极端紧急，pulumi up 都该交给流水线，而不是在自己机器上跑。

身份与权限漂移：本地用户和流水线服务主体通常挂着不同的 IAM 角色与权限范围。本地部署容易带来意外失败、权限错配，或云资源归属不当。
状态归属锁（特定项目）：在后端存储账户 ACL 较严的仓库里，本地开发者账户反而权限更高。本地 pulumi up 可能顺手把 state 对象的归属改写成你的个人身份，把自动化的 runner 锁在门外，之后再也更新不了。
审计与可观测：本地的 pulumi preview 和 pulumi up 不留集中、持久的日志。走 CI/CD，每一次部署的日志、执行上下文和 stdout/stderr 才会被永久归档，日后排障、合规、审计都用得上。

竞态：重新 preview。 像 Terraform 这类工具，部署是严格的两阶段（CI 生成 plan 文件，CD 再 apply），以保证 CI 里审过的就是 CD 里应用的。Pulumi 也有对应机制——Update Plans（pulumi preview --save-plan 生成、pulumi up --plan 应用），但它目前仍是实验特性（需 PULUMI_EXPERIMENTAL），未必都已启用。在没有锁定 plan 的情况下，pulumi up 会在部署时重新评估实时代码，所以尤其要留心最终到底会应用什么。

覆盖风险：两位工程师几乎同时从不同特性分支对同一个 stack 执行 pulumi up，或者你的 PR 还没合、另一次部署先完成了，都可能不小心覆盖别人的改动。
中间有任何动静就重跑 preview：如果在初次 pulumi preview 与最终 pulumi up 之间发生过其他流水线运行或部署，值得重新 pulumi preview，重新核对 diff。
尽快合并以免阻塞：为避免竞态、状态冲突或阻塞队友，基础设施 PR 一经批准并验证就尽快合并。

原则四：敬畏生产

生产是唯一一个“改错要道歉、甚至要熬夜”的地方。凡是可能落到它身上的改动，都值得多看一眼。

PR 里附上 preview 运行

IaC 的代码逻辑，并不总能让人看清它对现网云资源的实际影响。一处两行的改动、一个属性的微调，都可能悄悄触发资源的销毁重建（+- replace）。

桥接代码与云的现实：开 PR 时，让 CI 工作流跑一次 pulumi preview，把输出粘贴或链接到 PR 描述里。
把意图摆到台面上：这样审阅者一眼就能看到云侧影响（+ Create、~ Update、+- Replace、- Delete），不必在脑子里推演 Pulumi 会怎么评估代码。

还要留意两类意外的 diff：

意外的更新（~）：preview 里冒出了你并不打算动的属性，停下来查一查。这通常意味着底层状态漂移，或云厂商有未处理的默认属性。
销毁性替换（+-）：数据库、存储桶、静态 IP、有状态服务一旦被替换，就是数据丢失或停机。preview 报出替换时，先确认这个属性是否真的需要重建，或者是否需要显式加 protect: true、ignoreChanges，再往下走。

GitOps 与自动纠偏

对 Kubernetes 应用与 add-on，用 ArgoCD 做严格的 GitOps：Git 仓库是集群状态的唯一事实来源。

别手动改集群：任何在集群里直接做的改动（kubectl edit、kubectl apply，或 UI 覆盖）都会被识别为漂移，并被 ArgoCD 覆盖 / 自动纠偏回 Git 定义的状态。
改环境，先改 Git：想让环境变，就把改动提交到 Git。

自动纠偏有个前提：Application 需要配置 syncPolicy.automated.selfHeal: true。而且漂移检测依赖 refresh，并非实时触发。

及时、增量发布

审批可能要花时间，但合并后就要尽快部署到目标环境。与其把多个 PR 攒成一次大发布，不如一小步一小步地走——小部署爆炸半径小，bug 好定位，好的代码也不会被连累回滚。

设计原则

再看一层：代码与配置该怎么组织。

原则五：用重复换取解耦

DRY 是一种本能，但在跨环境、跨项目的 IaC 里，它常被用过头。判据不该是“两段东西长得像不像”，而是“它们是不是同一份知识、会不会朝同一个方向变”：会一起变，才值得收敛成一份；会各自演化，重复反而更解耦。

真正必须只存一份的，是知识——命名、结构这类所有环境都要一字不差的东西；“哪个环境要建哪些资源”这种会随环境分叉的意图，宁可各写各的。把“看起来一样”的东西过早抽成共享代码，换来的往往是改一处、牵动全环境：独立演化与爆炸半径隔离同时失效。

资源取舍分环境，资源形状一处定义

非生产与生产有差异是常态，处理原则就一条：要建哪些资源，归各环境自己的取舍；资源长什么样，在共享代码里只定义一次——让一处改动尽可能只落在单个环境里。

取舍分环境：要建哪些资源、用什么规格，写在各环境自己的配置里（如 Pulumi.dev.yaml、Pulumi.prod.yaml）——这些本就会随环境演进、各不相同。
形状一处定义：命名、结构、父子关系、通用标签这类必须处处一致的知识，放进共享代码，只写一次。
别拿逻辑分支代替取舍：把 if env == "prod" 塞进共享代码，等于把“该独立演化”的东西焊死在一起——动一处，全局跟着变。

这条取舍的完整论证，见《Duplication over DRY：用重复换取解耦》。

两条底线

最后两条不属于任何单个阶段，而是每条原则都得守住的底线。

原则六：责任在人，不在工具

工具能提速，也会出错，但从不会替你负责——最后一道关，永远是人。

作者负责：审阅者是第二双眼睛，但代码的安全与质量，最终还由作者兜底。
工具提速，不背锅：AI 起草的代码、CI 跑绿的流水线，都只是辅助；它们没覆盖到的边界，仍然要由你判断——绿灯不等于没问题。

原则七：保护密钥

密钥一旦暴露（API key、云凭据、密码、私钥），代价往往比想象中大——不管它落在 main、临时特性分支，还是 AI 的上下文里。这道底线有两半：别提交进 Git，也别让 AI 读到。

安全工具在盯着：Aikido、GitHub Secret Scanning、Trufflehog 这类平台会自动扫描每次 push。密钥一进任何远程分支，立刻被记录并标记。
删分支删不掉密钥：删掉特性分支或 force-push 一个干净提交，都无法把密钥从 GitHub 抹掉。GitHub 会在后端历史里保留陈旧提交一段时间，泄露的值往往还会长期留在 PR 提交历史、时间线日志和审计记录里。
真泄露了怎么办：如果密钥被误提交并推送——哪怕只在短命分支上待了几秒——第一时间通知团队。从 Git 里删掉代码不够，泄露的凭据要立即吊销并轮换。
提前防御（Git Hooks）：可以在本地配上 pre-commit hook（如 git-secrets、detect-secrets），提交前在机器上先扫一遍，把泄露拦在到达 GitHub 之前。
别让 AI 读到密钥（尤其重要）：AI 编码助手（如 Cursor、Claude Code）会把工作区文件、打开的上下文和终端输出送进模型，所以“没提交”并不等于“没泄露”——.env、本地凭据文件，甚至 shell 里 export 的 token，只要落进上下文，就可能被处理或留存。
- 把密钥挡在上下文之外：用工具自己的忽略配置（如 Cursor 的 .cursorignore）把 .env、凭据目录排除出 AI 的可读范围。但它只是尽力而为——官方也承认 LLM 行为难以完全预测，别把它当成唯一防线。
- 别留明文，交给 secret manager：Vault、云 KMS、1Password 之类按需注入，工作区里不落明文。
- 用短时、最小权限凭据：能用 OIDC 换临时 token，就别用长期 key——窗口越短，真出事时代价越小。
- 别把生产密钥贴进 AI 对话：为了“帮忙排障”把密钥粘进聊天框，和提交进 Git 一样危险。

结语

回头看，这些“古法”既不高明，也不时髦，更拦不住 AI 写得比你快。它们守的，其实是一件很朴素的事——让“快”别变成“乱”：黑盒越黑，外面那几道由人把守的关卡就越要紧，而这些关卡得沿着环境一级级抬高，信心才有时间慢慢攒起来。AI 很可能给出的是一张终态的图，工程要补上的，是一条能走、能验、也能回头的路。

参考

主干开发（Trunk-Based Development）— https://trunkbaseddevelopment.com/
GitOps 原则 — https://opengitops.dev/
GitHub · 关于 CODEOWNERS — https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners
Pulumi · pulumi preview — https://www.pulumi.com/docs/iac/cli/commands/pulumi_preview/
Pulumi · Update Plans（实验特性，锁定 preview 与 up）— https://www.pulumi.com/docs/iac/operations/stack-management/update-plans
Pulumi · protect — https://www.pulumi.com/docs/iac/concepts/resources/options/protect/
Pulumi · ignoreChanges — https://www.pulumi.com/docs/iac/concepts/resources/options/ignorechanges/
Argo CD · 自动同步（syncPolicy.automated / selfHeal）— https://argo-cd.readthedocs.io/en/stable/user-guide/auto_sync/
Terraform · plan — https://developer.hashicorp.com/terraform/cli/commands/plan
GitHub · 密钥扫描（secret scanning）— https://docs.github.com/en/code-security/secret-scanning
Cursor · Ignore file（.cursorignore，把密钥挡在 AI 上下文之外）— https://cursor.com/docs/reference/ignore-file
git-secrets — https://github.com/awslabs/git-secrets
detect-secrets — https://github.com/Yelp/detect-secrets
TruffleHog — https://github.com/trufflesecurity/trufflehog
Aikido — https://www.aikido.dev/

Duplication over DRY：用重复换取解耦

Sat, 10 Oct 2026 19:19:19 GMT

写在前面

本文由 AI 执笔，人类立意。
Written by AI, imagined by a human.

过去十几年里，软件架构的审美发生了一次静悄悄却很彻底的转向。曾经 DRY（Don’t Repeat Yourself）几乎是不可挑战的第一原则，代码里但凡出现一点相似，我们的手就痒，非要把它抽出来复用；而在今天的现代软件架构、尤其是微服务架构里，“Duplication over DRY” 正逐渐成为一种共识——宁可容忍一点重复，也不轻易引入一个抽象。

我不打算假装中立。这篇文章就是来给这个立场站台的：我认为，在大多数现代系统里，“重复优先” 是一种更成熟、更诚实的审美。下面我先讲这股共识是怎么形成的、它到底买到了什么、代价又是什么，再把它延伸到 Cloud Engineering：多环境 IaC（基础设施即代码），以及多个 IaC 项目之间的依赖。

为什么”重复优先”会形成共识

一、DRY 的本意被长期误读了。 《The Pragmatic Programmer》里的原始表述是：“Every piece of knowledge must have a single, authoritative representation within a system.” 关键词是 knowledge——它约束的是”知识”的单点，不是”代码文本”的单点。两段长得像的代码，背后未必是同一份知识；强行合并，反而是把两件不同的知识焊死在一起。

二、错误的抽象比重复更贵。 这是这股共识的核心论据，Sandi Metz 把它总结成了一句几乎可以直接贴在墙上的名言：

“Duplication is far cheaper than the wrong abstraction.” —— Sandi Metz

在我看来，这句话之所以成立，是因为两者的成本结构完全不同：重复是局部的、可见的、随时可消除的；而错误的抽象是全局的、隐蔽的、复利式增长的。一旦两个本应独立演化的东西被合并，日后每次需求分叉，你都只能往里塞参数、加开关，最后它变成谁都不敢碰的泥球。我愿意把话再说过头一点：好的抽象难求，烂的抽象难逃。

三、微服务把”独立部署”抬成了黄金法则。 Sam Newman 在《Building Microservices》里把 Independent Deployability（独立部署性） 视为第一原则，并明确提醒：跨服务共享一个库，会把多个服务锁死在同一条发布节奏上——一次改动要让所有消费方一起升级。那等于把分布式系统又收回成”分布式单体”。为了独立部署，宁可容忍一点重复。

同一取舍在分布式架构里还有几个更标准的说法，值得一提：

Data Redundancy / Data Replication（数据冗余 / 数据复制）：订单服务里保存一份客户资料的副本（名称、联系方式等），并随用户服务的事件保持最终一致，这样下单、查单时都不必在运行时回查用户服务——用一点数据的重复，换服务之间的解耦。（注意区分：这里复制的是”用户那份数据”的副本，会随上游更新；如果存的是下单那一刻的联系方式，那其实是订单自己的数据，属于快照、不算这个模式——正如订单的收货电话未必等于用户当前的手机号。）
Share Nothing Architecture（无共享架构）：服务之间宁可各自拥有一整套代码、逻辑甚至数据库，也绝不共享任何资产，以此换取极致的解耦。

相比之下，“A little copying is better than a little dependency.”（Rob Pike, Go Proverbs）——这句话我几乎想印在工位上。

四、服务与团队的边界是真实的。 共享代码一旦跨越团队边界，任何改动都要所有消费方协调；而”各复制一份”把协调成本直接降到零。这背后有 Conway 定律的影子：系统的结构终会映射组织的沟通结构。与其和现实对抗，我更愿意顺着边界切。

五、领域驱动设计（DDD）给了它理论外壳。 在 限界上下文（Bounded Context） 之下，同一个”商品”在仓储系统和销售系统里长得再像，也属于不同上下文，就该是两套模型，而不是共用一个类。这一点我年轻时不信，现在深信。

六、还有一条朴素的经验法则：Rule of Three。 第一次照抄、第二次照抄，等到第三次再考虑抽象——因为到那时你才真正看清”共同点”到底是什么。

重复买到了什么

切断变更耦合：改一处不必改另一处。
切断部署耦合：各自发布、各自回滚，互不阻塞。
局部可读、无间接层：直接看代码就知道发生了什么，不必在层层抽象之间跳来跳去。
缩小爆炸半径：一份坏了，不牵连另一份。
更低的协调成本：跨团队不必为了改一行代码而开会同步。

代价：重复不是免费的

我不想把话说得太满。重复有它真实的账单：

漂移：两份实现会逐渐发散，甚至走向不一致。
成倍维护：缺陷修复、安全补丁、依赖升级，每多一份实现就多一份。
认知负担：面对多份实现，先得回答”哪份才是对的？”
失去单一来源：全局一致性与可追溯性更难保证。

所以真正的问题从来不是”要不要重复”，而是——重复的到底是不是同一份知识。 是知识，就必须单点；只是碰巧长得像的工件，重复往往更划算。既然代价真实存在，就需要纪律与护栏来兜底。

延伸到 Cloud Engineering

前面这套取舍，落到云上的基础设施同样成立——甚至更明显：在 IaC 里，“必须独立演化、独立部署”的边界，被环境天然地切好了。下面我以用 Pulumi 管理基础设施为例，把它拆成两件事来讲（换成 Terraform、CDK 之类，道理完全一样）。

多环境 IaC：资源取舍分环境，资源形状单点

维护 dev / test / staging / prod 多套环境时，我的分工原则很简单——按”要创建哪些资源”和”资源长什么样”这两件事来切：

要创建哪些资源，在每个环境自己的部署栈里定义——需要什么、要不要建，都由这份配置说了算。不同环境可以不一样；就算暂时长得一样，那也是”各自声明”的结果，而不是从一份共享模板派生出来的。
资源长什么样（命名、结构、父子关系、通用标签），放进共享的 Python 代码——这是必须保持一致的知识，所以单点。

示意一下：

# environments/dev.yaml
storage:
  - name: logs
    sku: Standard_LRS

Python 侧读取这份 YAML，按统一命名规范把 name 拼成 stdevlogs...，再创建资源。于是”重复”发生在资源声明层：每个环境各写各的。

为什么这么切？因为这两半的”命运”正好相反——“资源长什么样”必须始终一致，“要创建哪些资源”却会随环境演进分叉。 举个真实的例子：

项目成长期：部署与放行顺序天然是 dev → test → staging → prod，一路验证、一路提升。哪怕四个环境最终的状态非常接近，它们在开发过程中也是在不同的时机被验证和部署的——dev 先上，prod 最后。
维护阶段（开发进入低活跃期）：需求变少，方向反转，我们可能反过来收缩——逐步下线 dev / test，只保留 staging / prod。

也就是说，“哪个环境还有哪些资源”本来就是会变、且各不相同的。把它预先抽成一份共享模板，只会让你不断往模板里打补丁。而命名、结构这类东西，我们希望所有环境一字不差，那正是该收敛到单点的知识。

反过来最容易踩的坑，是把”要创建哪些资源”写进共享代码，比如 if env == "prod": ...。我反对的正是这个：这不是”代码还是配置”的问题，而是把”应该独立演化的东西”当成了”必须保持一致的知识”——结果改一处、牵连全环境，独立演化与爆炸半径隔离同时失效。（如果代码是纯数据驱动的——一套机制配一张”每环境有哪些资源”的表——那还好，本质和 YAML 没区别；真正的坑是逻辑分支。）

有人会说：既然 Python 生成逻辑本来就是共享的，那为什么不把”每个环境要哪些资源”也一并抽象掉，写一份”基础配置”，再由各环境派生？答案还是那句：会分叉的东西，别共享。 四个环境跑在各自的部署栈上，这本来就是常态；该共享的是”资源长什么样”的知识（Python），不是”每个环境要建哪些资源”这份意图。后者一旦抽象，四个环境就又被焊在一起——动一处模板，四个环境一起变。

好处也很直接：dev 里可以随手新建、改配置、跑一段时间验证，稳定后再提升到更高环境；每个环境都是一个能独立折腾的”雪花”，而不是被一份共享模板绑在一起。

多个 IaC 项目之间：把依赖变成显式契约

大型项目往往会被拆成多个 IaC 项目，项目之间必然有依赖。常见做法是用 StackReference / terraform_remote_state / 共享模块，在部署时自动读取上游的输出。它”方便”，却把两个项目的部署时序、状态、生命周期绑在了一起——上游没部署完下游就起不来，上游输出一改名下游就静默炸掉。在我看来，这恰恰是”错误的抽象”在基础设施层的翻版，而且更难排查。

我更偏爱另一种做法：不引入任何运行时/部署时的自动引用，而是手动把上游的稳定标识（资源标识、名字、端点）复制到下游项目里，作为显式输入。

这里要诚实：这并没有消除依赖。资源确实存在，也确实被引用。改变的是依赖的形态——从”隐式、自动、会牵连部署顺序”，变成”显式、单向、可读”。好处随之而来：

独立部署：下游只依赖一个已经落地的值，不需要上游在线。
执行顺序一眼可读：先后关系写在配置里，而不是藏在部署引擎的依赖图里。
爆炸半径可控：一个项目出问题，不会顺着引用链扩散。
边界清晰：这就是限界上下文在基础设施层的翻版。

代价同样存在，所以我会配几条护栏：

尽量让接口稳定：与其复制不透明的资源标识，不如复制稳定命名——此时命名规范本身就是公开契约。
契约校验：持续集成里加一步，检查下游引用的上游值是否存在、是否符合约定。
明确所有权：谁拥有上游，变更时如何通知下游。
只在”变更/部署耦合”确实带来痛苦时重复；否则回到抽象。

一个简单的判断清单

想抽象还是想重复？我会先问自己四个问题：

两边是同一份知识，还是碰巧长得像？（同一份 → 抽象）
它们需要独立演化 / 独立部署吗？（需要 → 重复）
合并之后，需求一旦分叉，会不会在抽象里反复打补丁？（会 → 别合并）
重复带来的漂移风险，有没有可承受的护栏？（没有 → 别轻易重复）

结语

“Duplication over DRY” 之所以在微服务与云架构里逐渐成为共识，是因为大家终于算清了这笔账：重复的成本是局部的、可见的、可控的，而错误抽象的成本是全局的、隐蔽的、复利的。

但它不是教条，而是一种需要勇气的权衡——因为它逆着我们”看到重复就想消除”的直觉。要守住的底线只有一条：知识必须单点。 在这条底线之外，为了独立部署、独立演化、清晰的边界与可读的执行顺序，主动接受一份重复，往往比硬凑一个错误的抽象更便宜，也更好维护。

Duplication is a design decision, not a sin.

参考

The Pragmatic Programmer — DRY（知识的单一权威表示）
Sandi Metz, The Wrong Abstraction (2016)
Rob Pike, Go Proverbs (2015)
Sam Newman, Building Microservices — Independent Deployability
Eric Evans, Domain-Driven Design — Bounded Context

在 2026 年把静态站点从 Zola 迁移到 Astro

Sat, 10 Oct 2026 00:00:00 GMT

2026 年做静态站点，工具大致收敛成了几条清晰的路线。下面先横向看一圈，再聊聊把一次 Zola 站点迁移到 Astro 之后，实际赢下了什么，以及过程中那些具体的坑——代码高亮与语言支持、中文标题锚点、中文标签转拼音，以及 Tailwind 的接入。

横向看：2026 年的四种形态

Hugo、Zola、Eleventy、Astro 基本覆盖了内容站的四种形态：

工具	运行时	内容 / 模板模型	构建速度	定位
Hugo	Go 单二进制	Go 模板	极快	大站、主题生态
Zola	Rust 单二进制	Tera 模板（类 Jinja）	很快	个人站、零依赖
Eleventy	Node	多模板语言可选	中等	JS 生态、极简
Astro	Node + Vite	组件 + islands	中等	内容 + 组件

Hugo 和 Zola 是给内容套模板：单二进制、零依赖、构建飞快，代价是模板语言表达力有限，生态（尤其 Zola）偏薄。Eleventy 是JS 版的 Zola：模板语言随便挑、默认零客户端 JS，但构建更慢、也不自带电池。Astro 则是另一条路——用编程语言去构建内容站点。

再往外还有两条分叉支线：Docusaurus / VitePress / Starlight 偏文档，Next.js / Nuxt / SvelteKit 是应用框架（SSG 只是其中一种输出模式），都不在本文的比较范围内。

从 Zola 到 Astro，赢在哪

1. 内容有了 schema，错误在构建时就暴露

Astro 的内容集合用 Zod 定义 schema：字段类型、是否可选、默认值全部写死在 src/content.config.ts 里。文章少写个引号、tags 写成了字符串，构建直接报错，而不是等到页面上渲染出 undefined。Zola 的 TOML 头是”写啥是啥”，校验全靠自觉。

schema: z.object({
  title: z.string(),
  slug: z.string(),
  date: z.coerce.date(),
  tags: z.array(z.string()).default([]),
})

2. 页面逻辑终于是一门真正的语言

标签聚合、按年归档、分页、取”最近用过的 30 个标签”——在 Zola 里要靠 Tera 的 filter/group_by 拼，在 Astro 里就是普通 TypeScript：getCollection() 拿数组，sort、Map、slice 随便用，逻辑还能抽成 src/utils/*.ts 复用。

3. 组件化，以及能直接借用的生态

页头、侧边栏、文章列表都是可复用的 .astro 组件；代码高亮、RSS、Sitemap 各装一个官方或社区集成即可。需要交互时再用 islands 局部水合，其余部分保持零 JS——这是模板型 SSG 给不了的。

4. 心智模型：从”挑一个主题”到”拥有一个前端项目”

Zola 有一等公民的 theme：config.toml 里 theme = "..."，theme 通常是放在 themes/ 的 git submodule，本质是另一个提供 templates / static / sass 的 Zola 项目，你能用同名文件覆盖它。Astro 没有这套”换装”机制——它是一个你完全拥有的前端项目；社区所谓的 “themes” 其实是整套 starter，clone 下来就是你的代码。好处是彻底掌控、能直接接组件与 npm 生态；代价是升级不再”一键换主题”。

迁移手记

代码高亮与语言支持

Zola 的高亮内置、开箱即用（syntect），主题是 config.toml 里的 highlight_theme（tmTheme）。Astro 默认用 Shiki（VS Code 主题）；如果默认的不够用，可以再叠加 Expressive Code，实现浅色/深色双主题（如 github-light / github-dark 跟随 [data-theme]）、长行自动换行、行标记等需求。

语言支持上不必担心：Shiki 基于 TextMate 语法，覆盖面很广。像 bash、yaml、sql、go、powershell、nginx、kusto、regexp、dotenv、csv、cs 这类常见（以及不少冷门）语言都能直接高亮；真遇到未内置的，再往 Shiki 的 langs 里补即可。

中文标题锚点

Zola 会把中文标题转成拼音锚点，迁移时这个行为不能丢。做法是写一个 rehype 插件，用 unidecode + github-slugger 生成 id，并让它在 Astro 自己的标题 id 收集之前执行——这样目录（TOC）和实际锚点自动保持一致：安装 uv → #an-zhuang-uv。

中文标签 → 拼音 slug

同理，标签和分类也要能变成 URL 安全的路径。做法是抽一个 slug 工具函数，用 unidecode + github-slugger 把中文转成拼音，于是 /tags/画图/ 变成 /tags/hua-tu/；若想保持旧链接不变，可以让它对齐 Zola 原本生成的 slug。

接入 Tailwind

用官方 Vite 插件即可：在 astro.config.mjs 的 vite.plugins 里挂 @tailwindcss/vite，样式入口写一行 @import 'tailwindcss'。深色模式不依赖系统偏好，而是绑定自己控制的 [data-theme]：

@import 'tailwindcss';
@custom-variant dark (&:where([data-theme='dark'], [data-theme='dark'] *));

站内链接

Zola 的 [文字](@/2024/foo.md) 会在构建时校验目标是否存在，且移动文件不改链接。迁到 Astro 后一般改成朴素的绝对路径 [文字](/slug/)——更符合直觉、也更好移植，但代价是失去了构建期的链接校验，需要的话得另加 astro check 或 link checker 补回。

代价

换到 Astro 不是没有成本，得诚实说：

不再是单二进制。Zola / Hugo 一个可执行文件就能构建，Astro 需要 Node 工具链和 node_modules。
构建更慢。这点上 Go / Rust 的 SSG 有天然优势。
依赖会漂移。有 package.json 就有升级、锁版本、偶尔踩坑的日常。
供应链与合规成本，企业里尤其重要。npm 依赖树庞大、CVE 频发；而且构建期恰恰是 CI 密钥所在之处——Shai-Hulud 这类攻击正是靠投毒包的 install 脚本窃取云与代码仓库凭证，所以”只在构建时运行”并不等于安全。更麻烦的是，审计与合规（如 SOC 2 / ISO 27001）通常要求 SBOM 里不存在已知高危 CVE，无论它能否在运行时被利用。相比之下，Zola / Hugo 是单二进制，应用级依赖图几乎为空，维护面小得多。

所以这不是”Astro 全面碾压”，而是需求匹配：只想把 Markdown 铺成一个极简、构建飞快的站点，Zola、Hugo、Eleventy 依然是极佳选择；但当站点开始长出逻辑、组件和交互，Astro 那套”内容 + 组件 + 类型系统”的组合就明显更趁手。

小结

2026 年，静态站点这件事本身没变，变的是我们对它的期待：它不再只是渲染 Markdown，而是一个可以编程、可以复用、可以校验的工程。这次从 Zola 到 Astro 的迁移，真正买到的不是”更炫的框架”，而是把一篇篇内容重新纳入了软件工程该有的约束与实践里。

OpenWrt 二级路由开启 IPv6 中继（Relay）模式：让内网设备拿到公网 IPv6

Tue, 22 Sep 2026 00:00:00 GMT

最近中国联通使用断网逼迫的手段，硬给家里换了一台光猫，之后发现再也无法通过 Tailscale 连接到家里的内网设备了（偶尔可以用过 Relay 的方式建立连接，但是太慢了）。最近 AI模型都降价了，原本可以在外边连回家里，蹬各种 AI 模型来干活，结果被联通的搞坏了。投诉无门，只能自求多福。后来偶尔发现，居然可以用手机通过 4G/5G 网络访问家里的内网设备。经过排查发现，Tailscale 可使用 IPv6 建立 Direct Connection。所以，只要让内网设备拿到公网 IPv6 地址，也许就从外部访问了。遗憾的是，工作电脑在二级路由上，并没有开启 IPv6。最后发现，可以通过在二级路由上开启 IPv6 中继（Relay）模式，让内网设备获取公网 IPv6 地址。

案情梳理：谁偷走了我的 IPv6

先交代一下家里的网络结构，方便各位看官理解这场闹剧：

一级路由（家用路由）：IPv6 设置里的“前缀授权”只有“自动”和“关闭”两个选项，没有“手动指定长度”或“下发至下级”。于是它就从运营商拿到 PD 前缀，自己独吞，绝不往下发。
OpenWrt 二级路由：接在一级路由下面，想要前缀，要不到。
工作电脑：接在二级路由下面，嗷嗷待哺，只有一个 fe80:: 链路本地地址。

换光猫之前，一切岁月静好。换完之后，Tailscale 从大概率可以建立成功的 Direct Connection 退化成 Relay，再退化成直接连不上。排查过程就不细说了，无非是 ping6、traceroute、看日志、骂运营商、再看日志。最终定位到问题：一级路由不下发 IPv6 前缀，导致二级路由无法获取到公网 IPv6，进而内网设备也无法获取公网 IPv6。

解法：让二级路由放弃治疗，改做中继

既然从一级路由那里要不到前缀，那就换个思路：二级路由不做独立的 IPv6 路由器了，改行当快递员，把一级路由的 RA / DHCPv6 / NDP 消息原样透传给内网设备。

这就是 IPv6 中继（Relay）模式。设备拿到的地址直接来自一级路由，网关也指向一级路由，二级路由只在中间当一根透明的管子。

准确地说：IPv4 流量由二级路由做 NAT 转发，IPv6 流量则绕过二级路由的三层路由，由一级路由统一分配地址并担任网关。二级路由在 IPv6 这一层退化成了二层交换机。

配置步骤（LuCI 界面）

配置 LAN 接口：进入“网络” → “接口” → “LAN” → “编辑” → “DHCP 服务器” → “IPv6 设置”，将“路由通告服务（RA-Service）”，“DHCPv6 服务（DHCPv6-Service）”和“NDP 代理（NDP-Proxy）”都设置为“中继模式 (relay mode)”。
配置 WAN6 接口：进入“网络” → “接口” → “WAN6” → “编辑” → “DHCP 服务器” → “IPv6 设置”，保持“忽略此接口”为勾选状态，将“路由通告服务”“DHCPv6 服务”“NDP 代理”都设置为“中继模式”，并勾选“指定的主接口”。

重连客户端

断开 Wi-Fi 重连，或者重启网络接口，或者就是等几秒。别问，问就是玄学。

见证奇迹的时刻

中继配置完成后，先确认你的设备到底有没有拿到公网 IPv6：

ifconfig | grep inet6

成功的话，你会看到类似这样的输出：

inet6 2408:xxxx:xxxx:xxxx:3df1:6840:829a:d770/64 scope global temporary dynamic
       valid_lft 86234sec preferred_lft 14234sec
inet6 2408:xxxx:xxxx:xxxx:8b7a:eda:506c:ce6c/64 scope global dynamic mngtmpaddr noprefixroute
       valid_lft 86234sec preferred_lft 14234sec

重点是：

2408: 开头：说明是联通公网 IPv6 段，不是 fe80:: 链路本地，也不是 fd00:: ULA。
scope global：全球可路由。
temporary dynamic：隐私扩展地址，对外通信用的就是它，会定期更换。
mngtmpaddr：稳定模板地址，系统用它来生成临时地址。
注意 preferred_lft 是首选期，过了之后系统会生成新的临时地址，旧地址逐渐弃用。这就是临时地址会变的原因。

如果只看到 fe80:: 开头的地址，说明中继没生效，回去检查配置。

测试连通性

ping6 -c 3 240c::6666

这是联通公共 DNS。通了就说明 IPv6 出海正常。

再访问 https://test-ipv6.com 看评分。如果不再是 0/10，恭喜，可以从外网直连回家了。

原理简析

中继模式下，二级路由不自己分配地址，而是把一级路由的 RA、DHCPv6、NDP 消息原样转发到 LAN 侧。设备收到的 RA 里，前缀来自一级路由，网关也指向一级路由的链路本地地址。

二级路由的角色从“路由器”退化成了“二层交换机”，只不过它还保留了防火墙和 IPv4 路由的功能。某种意义上，这是一种降级，但在拿不到 PD 前缀的情况下，这是最优雅的解法。

注意事项

中继打破了 NAT 隔离，运营商和一级路由都能看到每台设备的公网 IPv6 地址。介意的话，对不需要外网的设备用 ULA fd00::/8。

不过说实话，在联通硬塞光猫的前提下，你的隐私早就不是你能控制的了。呵呵。

结果：Tailscale 复活

配置完成后，在 4G/5G 网络下，Tailscale 从 Relay 切换回 Direct Connection，延迟从 Relay 时的几百毫秒甚至上千毫秒，降到直连时的几十毫秒以内。AI 模型终于可以顺畅地蹬了，钱包表示压力很大。

一句话总结

OpenWrt 二级路由拿不到 PD 前缀时，把 LAN 和 WAN6 的 RA / DHCPv6 / NDP 全部设为 relay mode，并在 WAN6 勾选“指定的主接口”，即可让内网设备直接获得上游分配的公网 IPv6 地址。

在同一台开发机上隔离多个 Git 账号

Tue, 22 Sep 2026 00:00:00 GMT

同一台开发机上经常会有多个 Git 身份：自己的账号、开源组织的账号，或者不同代码托管平台上的账号。每个身份都有自己的 SSH 密钥，一旦混用，轻则被服务器拒绝，重则把提交推到不该推的账号下。

与其每次手动切换，不如把目录和密钥的对应关系固定下来，让 Git 按路径自动选择。

生成密钥：每个身份一把

先给每套身份生成独立的 Ed25519 密钥，不要复用默认的 id_ed25519：

ssh-keygen -t ed25519 -C "alpha@example.com" -f ~/.ssh/id_ed25519_alpha

-t ed25519：推荐的算法，密钥短、签名快，主流平台都支持
-f：指定输出路径，避免覆盖已有的默认密钥
-C：注释，写清用途，方便在平台上辨认

执行过程中会提示设置 passphrase。建议设置，并把它加入 ssh-agent，免得每次推送都要输入（如果 ssh-agent 尚未运行，先执行 eval "$(ssh-agent -s)"）：

ssh-add ~/.ssh/id_ed25519_alpha

接着收紧权限：

chmod 700 ~/.ssh
chmod 600 ~/.ssh/id_ed25519_alpha
chmod 644 ~/.ssh/id_ed25519_alpha.pub

查看公钥，添加到对应平台或服务器：

cat ~/.ssh/id_ed25519_alpha.pub

私钥（没有 .pub 后缀的那个文件）不要外传，也不要放进同步盘或仓库。另外，同一个公钥不能同时添加到两个 GitHub 账号，每套身份都要单独生成一对。

按目录加载不同配置

前提是不同身份的代码放在不同目录，比如 ~/workspace/alpha/ 和 ~/workspace/beta/。Git 的 includeIf 可以按仓库路径加载不同的配置文件（需要 Git 2.13 及以上）。

在 ~/.gitconfig 末尾加入：

[includeIf "gitdir:~/workspace/alpha/"]
    path = ~/.gitconfig-alpha

然后创建 ~/.gitconfig-alpha：

[core]
    sshCommand = ssh -i ~/.ssh/id_ed25519_alpha -o IdentitiesOnly=yes

两个细节：

gitdir:~/workspace/alpha/ 末尾的 / 不能省，它表示“该目录下的所有仓库”；不带 / 只匹配该路径本身。
IdentitiesOnly=yes 让 SSH 只使用 -i 指定的钥匙，不再把 ssh-agent 里的其他密钥逐个递给服务器。没有它，agent 里恰好有另一把被授权的钥匙时，Git 可能以错误的身份通过认证。

之后这个目录下的仓库自动使用 alpha 的密钥，其他地方不受影响。需要几套身份，就重复几组 includeIf 和对应的配置文件。

只对单个仓库生效

如果不想按目录管理，进入仓库后直接设置局部配置：

git config core.sshCommand "ssh -i ~/.ssh/id_ed25519_alpha -o IdentitiesOnly=yes"

这个值会写进该仓库的 .git/config，优先级高于全局配置。

顺带切换提交身份

SSH 密钥决定“以什么身份连接”，user.name 和 user.email 决定“以什么身份提交”，两者要一起改。在 ~/.gitconfig-alpha 里再加一段：

[user]
    name = Alpha
    email = alpha@example.com

这样该目录下仓库的提交作者也不会串。

验证

在 ~/workspace/alpha/ 下任意仓库里查看配置来源：

git config --show-origin --get core.sshCommand

--show-origin 会显示这条配置来自哪个文件，能确认 includeIf 确实命中了。再验证密钥本身：

ssh -i ~/.ssh/id_ed25519_alpha -o IdentitiesOnly=yes -T git@github.com

这条命令直接调用 ssh，不会读取 Git 的 core.sshCommand，所以要手动带上同样的参数。若要连真实仓库测试：

git ls-remote git@github.com:your-org/your-repo.git

小结

每个身份单独生成一对 Ed25519 密钥，私钥不外传，公钥只加到对应账号。
用 includeIf 按目录加载配置，用 core.sshCommand 指定密钥，并加上 IdentitiesOnly=yes。
密钥之外，别忘了同目录下的 user.name 和 user.email，否则连接身份对了，提交作者还是会串。
临时切换可以只对单个仓库设置 core.sshCommand，不必动全局配置。

参考

远程访问 TP-LINK 路由器管理控制台

Fri, 18 Sep 2026 00:00:00 GMT

TP-LINK 路由器大部分管理操作都可以在手机客户端操作，但某些高级设置，必须连接路由器的局域网才可以修改。如果可以通过远程访问路由器中的某个机器，那么就可以通过这台机器进行相关的高级设置操作。

如果能登录远程的局域网中的 Windows 机器，那很简单，在远程桌面里打开浏览器访问路由器的管理界面即可。对于没有桌面的 Linux 机器而言，可以通过 SSH 登录到这台机器，然后使用命令行工具或者通过端口转发的方式访问路由器的管理界面。

方法一：本地端口转发（失败）

假定路由器的局域网 IP 为 192.168.1.1，期望通过本地的 8888 端口访问路由器的管理界面，可以使用如下命令进行本地端口转发：

ssh -L 8888:192.168.1.1:80 用户名@IP

浏览器访问 http://localhost:8888，会被路由器的强制跳转到 http://tplogin.cn，并返回公网的页面。失败！

方法二：SSH 动态转发 / SOCKS5 代理（成功）

ssh -D 1080 用户名@IP

然后在浏览器中设置 SOCKS5 代理为 localhost:1080（可使用 Chrome 扩展 Zero Omega）。配置好后直接访问 http://192.168.1.1 ，管理页面正常打开。成功！

成功原因：浏览器所有请求都通过 SSH 隧道由远程主机代为发出。路由器前端看到的请求主机名为 192.168.1.1，因此不会触发强制跳转，管理页面可以正常访问。

Tailscale 因 DHCPv6 地址导致无法直连排查记录

Thu, 17 Sep 2026 00:00:00 GMT

在手机上通过 tailscale 访问 Armbian 设备，始终无法建立 Direct Connection。最终定位到根因是 DHCPv6 分配的 /128 地址被内核选为默认源地址，导致 IPv6 回包无法送达。在 Netplan 中添加 ethernets 段并指定 ipv6-address-generation: stable-privacy 后解决。

问题

设备：Armbian ARM 盒子（ab01）
网络管理：Netplan + NetworkManager
问题：从手机访问 ab01 时，Tailscale 连接始终走 DERP 中继（欧洲节点，~450ms），tailscale netcheck 显示 IPv6: no, unavailable in OS
对比：同局域网的 Linux x86桌面电脑（w01）却能正常直连

排查过程

确认 IPv6 地址和路由都正常

$ ip -6 addr show eth0 | grep inet6
    inet6 2408:xxxx:xxxx:xxxx::1001/128 scope global dynamic noprefixroute
    inet6 2408:xxxx:xxxx:xxxx:xxxx:xxxx:xxxx:xxxx/64 scope global dynamic noprefixroute
    inet6 fe80::xxxx:xxxx:xxxx:xxxx/64 scope link noprefixroute

$ ip -6 route show default
default via fe80::xxxx:xxxx:xxxx:xxxx dev eth0 proto ra metric 100 pref medium

设备同时拿到 /128（DHCPv6）和 /64（SLAAC）两个公网地址。路由和防火墙均无异常。

定位到“能发不能收”

先用 nc -6 -u 测试 UDP 发送：

$ nc -6 -u -z -w 3 2400:3200::1 53 && echo "UDP OK" || echo "UDP FAIL"
Connection to 2400:3200::1 53 port [udp/domain] succeeded!
UDP OK

但这只能证明“包发出去了”，不能证明“能收到回包”。UDP 是无连接协议，-z 只是尝试发送，没有握手确认。

于是用一个 Python 脚本做更完整的测试：向 IPv6 的公共 DNS 服务器（2400:3200::1）发送一个 DNS 查询包，然后等待接收服务器返回的结果。如果收到回应，说明 IPv6 收发都正常；如果超时，说明回包进不来。

$ python3 -c "
import socket
s = socket.socket(socket.AF_INET6, socket.SOCK_DGRAM)
s.settimeout(5)
query = b'\x12\x34\x01\x00\x00\x01\x00\x00\x00\x00\x00\x00\x05baidu\x03com\x00\x00\x01\x00\x01'
try:
    s.sendto(query, ('2400:3200::1', 53))
    data, addr = s.recvfrom(512)
    print('收到回应，长度:', len(data))
except Exception as e:
    print('未收到回应:', e)
finally:
    s.close()
"
未收到回应: timed out

结果是超时，定位到问题是“能发不能收”。

找到根因：源地址选错

$ python3 -c "
import socket
s = socket.socket(socket.AF_INET6, socket.SOCK_DGRAM)
s.connect(('2400:3200::1', 53))
print('本地地址:', s.getsockname())
s.close()
"
本地地址: ('2408:xxxx:xxxx:xxxx::1001', 49906, 0, 0)

内核默认选了 /128 的 DHCPv6 地址作为源地址。该地址没有对应的 on-link 路由，回包到达光猫后无法送回设备。

强制绑定 SLAAC 的 /64 地址发送同样的 DNS 查询，立刻收到回应，确认根因。

$ python3 -c "
import socket
s = socket.socket(socket.AF_INET6, socket.SOCK_DGRAM)
s.settimeout(5)
s.bind(('2408:xxxx:xxxx:xxxx:xxxx:xxxx:xxxx:xxxx', 0))
query = b'\x12\x34\x01\x00\x00\x01\x00\x00\x00\x00\x00\x00\x05baidu\x03com\x00\x00\x01\x00\x01'
try:
    s.sendto(query, ('2400:3200::1', 53))
    data, addr = s.recvfrom(512)
    print('收到回应，长度:', len(data))
except Exception as e:
    print('未收到回应:', e)
finally:
    s.close()
"
收到回应，长度: 91

解决方案

确认系统用的是 Netplan：

$ ls /etc/netplan/
00-default-use-network-manager.yaml

原始文件只有：

network:
  version: 2
  renderer: NetworkManager

在文件中添加 ethernets 段，为 eth0 指定 IPv6 配置：

network:
  version: 2
  renderer: NetworkManager
  ethernets:
    eth0:
      dhcp4: true
      dhcp6: false
      accept-ra: true
      ipv6-address-generation: stable-privacy

应用配置：

netplan apply

ipv6-address-generation: stable-privacy 明确告诉 NetworkManager 使用 RFC7217 方式生成 SLAAC 地址的接口标识符。这个参数能被 Netplan 正确识别并翻译给 NetworkManager，从而完整触发 SLAAC 流程，绕过了 accept-ra 翻译丢失的问题。

验证

ip -6 addr show eth0 | grep inet6   # 确认 IPv6 地址存在
tailscale netcheck                   # 确认 IPv6: yes
tailscale ping ab01                 # 确认直连建立

重启设备，再确认一次。

发现

手机流量可以走 IPv6 直连

排查中发现：用手机流量连接 ab01 时，有时能建立 IPv6 直连，有时却走中继。原因是：

手机流量通常有公网 IPv6：4G/5G 网络普遍下发 IPv6 地址，且没有 NAT 转换。如果 ab01 也有可用的公网 IPv6，双方直接通过 IPv6 互通，不需要打洞。
ab01 缺少公网 IPv6 时：手机只能靠 IPv4 打洞。但手机流量的 IPv4 通常处于严格的 CGNAT 后面，打洞成功率低，所以回退到中继。
同局域网内设备表现不同：w01 能直连而 ab01 不能，正是因为 w01 有公网 IPv6，而 ab01 当时没有。

不对称直连是正常现象

Tailscale 的每条连接都是双向独立建立的。两端各自尝试用自己能用的最佳路径去连对方，最终可能形成一条“不对称”的连接路径（一端走 IPv4，另一端走 IPv6）。只要至少一个方向能直连，整体连接就不会走中继。

总结

Tailscale 的 ipv6os=false 不一定代表系统没有 IPv6，也可能是源地址选择错误导致 UDP 回包收不到。排查时重点验证 UDP 的接收能力，而不只是发送。

在 Armbian + Netplan + NetworkManager 环境下，accept-ra: true 可能无法正确触发 SLAAC。在 Netplan 中添加 ethernets 段并指定 ipv6-address-generation: stable-privacy，可以显式引导 NetworkManager 走 SLAAC 流程，是持久有效的解决方案。

释放 Windows 系统上的磁盘空间

Thu, 17 Sep 2026 00:00:00 GMT

不知道从什么时候开始，磁盘空间总是显得不够用。尤其在 Windows 更新之后……

操作步骤

使用 TreeSize Free 分析磁盘，识别大文件。
打开“设置”，进入“系统” - “存储”，点击临时文件，系统会自动开始扫描。可以看到 Installed apps, Temporary files, Other 等选项。进入每一项，查看磁盘占用详情，然后删除。
使用“磁盘清理”（Disk Cleanup）清理系统更新残留:如果刚刚完成过 Windows 大版本更新，系统中可能会留有数 GB 到十余 GB 的旧系统备份。

心得

心得：在 Windows 更新之后，Temporary files 中往往会积累大量的旧系统文件，比如我的遭遇：

Previous Windows Installations - 27.3 GB
Windows upgrade log files - 2.39GB

另外，C:\Windows.old 通常是旧系统的保留目录，它会在 Windows 升级后自动生成，用于保留旧版本系统文件，以便在需要时回退。这个目录有时会占用数 GB 甚至更多的硬盘空间。

修复基于 Debian/Ubuntu 的 Docker 基础镜像中的 CVE 漏洞

Thu, 17 Sep 2026 00:00:00 GMT

使用 python:3.14-slim 或 node:20-slim 等官方镜像时，上游更新可能并不及时，镜像内预装的 Debian/Ubuntu 系统包（如 openssl、glibc）仍可能存在 CVE 漏洞。

解决方案

在 Dockerfile 紧跟 FROM 之后加入以下命令，一键升级系统包并清理缓存：

RUN apt-get update \
    && apt-get upgrade -y \
    && apt-get clean \
    && rm -rf /var/lib/apt/lists/*

要点解析

apt-get upgrade -y：升级系统中所有可升级的软件包，打满系统软件包的最新安全补丁。
rm -rf /var/lib/apt/lists/* + apt-get clean：彻底清理索引与缓存，控制镜像体积。

最佳实践（构建命令）

在 CI/CD 中构建时，建议配合以下参数使用：

docker build --pull --no-cache -t my-app .

--pull：强制拉取最新的基础镜像（确保 upstream 修复也能同步进来）。
--no-cache：跳过本地构建缓存，确保执行最新的 apt-get upgrade。

Windows 上清理 Docker 残留文件的方法

Thu, 17 Sep 2026 00:00:00 GMT

卸载 Docker Desktop 后，如果之前使用过 Windows 容器（Windows Containers），系统常常会在 C 盘残留数 GB 到数十 GB 的容器镜像层文件。这些残留内容通常不能通过常规方式直接删除，因此很容易让磁盘空间被“吞掉”。

1. 核心残留位置

最常见的目录是：

C:\ProgramData\docker\windowsfilter

这也是 Docker 在 Windows 容器模式下生成的历史镜像层和容器文件根目录。

2. 传统清理方式为什么常常失败？

直接使用右键删除、PowerShell Remove-Item 或 CMD rmdir / icacls 时，通常会报错失败，原因主要有三类：

权限不足（Access Denied）：文件所有者常为 SYSTEM 或 TrustedInstaller，普通管理员权限往往无法直接操作。
路径过长（The system cannot find the path specified）：windowsfilter 中的目录层级非常深，容易超过 Windows 默认的 260 字符 MAX_PATH 限制，导致传统清理命令在中途失败。
服务占用：尝试停止 hns / vmcompute 服务来释放锁时，常常受到企业电脑策略、安全软件或权限限制影响，导致无法正常关闭。

3. 终极解决方案：使用 Robocopy 强制清空

Robocopy（Robust File and Folder Copy）是 Windows 自带的强大命令行文件管理工具。它原生支持绕过 260 字符路径限制，并且可以通过“镜像同步”机制直接覆盖目标目录中的内容，绕过部分权限和文件锁问题。

清理步骤（在管理员 CMD 中执行）

无需提前关闭 vmcompute 或 hns 服务，直接在以管理员身份运行的命令提示符（CMD）中依次执行即可：

创建一个临时空目录

mkdir C:\empty_temp

使用 Robocopy 强制镜像清空

执行以下命令，用空目录去“镜像覆盖”残留目录。在这一步中，屏幕上可能会不断输出 EXTRA，这表示 Robocopy 正在逐个删除超长路径下的残留文件和目录：

robocopy C:\empty_temp C:\ProgramData\docker\windowsfilter /MIR /R:0 /W:0

删除已清空的目录

rmdir /s /q C:\ProgramData\docker\windowsfilter
rmdir /s /q C:\empty_temp

待 Robocopy 运行结束并输出统计信息后，直接删除空目录 C:\empty_temp 和残留目录 C:\ProgramData\docker\windowsfilter 即可。

AKS 在 Azure CNI Pod Subnet 模式下的流量路由

Thu, 17 Sep 2026 00:00:00 GMT

在排查一个 AKS Pod 的网络出站流量时，我发现了一个奇怪的现象：

Node 所在子网：nodes（没有关联 NAT Gateway）
Pod 出站出口 IP：匹配的是子网 pods 上绑定的 NAT Gateway 公网 IP。

为什么 Node 所在子网明明没有挂载 NAT Gateway，运行在它上面的 Pod 出网却走到了另一个子网的 NAT Gateway？

排查过程与原因

第一反应是去 Azure Portal 检查 AKS 的网络配置，但在 Portal UI 的集群和 NodePool 页面上，只展示了 Node 所在的子网（nodes），完全找不到 pods 的影子。

为了搞清楚真相，我导出了 AKS 节点的底层资源 JSON 属性（或通过 Azure CLI 查看）。最终在 agentPoolProfiles 配置中找到了答案：

"agentPoolProfiles": [
  {
    "name": "nodepool1",
    "vnetSubnetID": "/subscriptions/.../subnets/nodes",
    "podSubnetID": "/subscriptions/.../subnets/pods"
  }
]

结合 Networking 页面，可以确认集群使用的是 Azure CNI Pod Subnet（动态 IP 分配）模式。

在该模式下，AKS 会将 Node 与 Pod 的 IP 分离在两个不同的子网中：

Node Subnet：专门为 VMSS 节点分配 IP（例如 nodes）。
Pod Subnet：专门为 Pod 动态分配 Azure VNet 内的真实 IP（例如 pods）。

在物理网络层面，流量的路由逻辑是：流量从谁所在的子网吐出，就走哪个子网绑定的路由/NAT Gateway规则。

因此，即便 Node 所在的子网没有绑定 NAT Gateway，只要 Pod Subnet 绑定了 NAT Gateway，Pod 的公网请求就会直接从 Pod Subnet 吐出，带上该 NAT Gateway 的出口 IP。

横向对比：其他 AKS 网络模式的流量出口行为

以下是 Gemini 给出的不同网络模式的对比：

网络模式	Pod 的 IP 来源	物理网络出口归属	公网出站行为逻辑
Azure CNI Pod Subnet	Pod 专用子网 (`pods`)	Pod Subnet	流量直接从 Pod 子网发出，只受 Pod 子网的 NAT Gateway / UDR 路由控制，忽略 Node 子网的配置。
Azure CNI（标准模式）	Node 节点子网 (`nodes`)	Node Subnet	Pod 和 Node 共享同一个物理子网，Pod 的出站出口 IP 完全取决于 Node 子网绑定了什么（如 NAT Gateway 或负载均衡器）。
Azure CNI Overlay	集群内部虚拟网段 (如 `10.244.0.0/16`)	Node Subnet	Pod IP 在 VNet 中不存在。流量在发出宿主机前会被 Node 做一层 SNAT（源地址改写为 Node IP），出口完全受 Node 子网的路由和 NAT 策略控制。
Kubenet	集群内部虚拟网段	Node Subnet	同样采用 Node 侧 SNAT 机制，出口流量完全依赖 Node 子网的出口路由配置。

总结与踩坑心得

出口由底层物理网卡子网决定：在 Azure CNI Pod Subnet 模式下，Pod 拥有真实的 VNet 子网身份。决定 Pod 出站 IP 的是 podSubnetID 绑定的规则，而非 vnetSubnetID（Node 子网）。
Azure Portal UI 并不展示全貌：Portal 界面有时会隐去 podSubnetID 这种高级网络配置。当发现网络行为与 UI 显示不符时，直接查看 ARM Resource JSON 或使用 Azure CLI 查询 agentPoolProfiles 才是最准确的依据。

为 Azure Database for PostgreSQL flexible server 创建 Private Endpoint

Tue, 28 Jul 2026 00:00:00 GMT

在产品环境中，PSQL Server 和应用通常处于不同的网络环境中，甚至位于不同的 Subscription。Azure Database for PostgreSQL Flexible Server 常见的两种接入方式是 VNet Integration 和 Public Access + Private Endpoint。如果希望最小化网络打通范围，并降低安全与合规边界扩散的风险，通常更适合使用 Private Endpoint。

比较

VNet Integration：将 PostgreSQL Flexible Server 部署到委派子网中，再通过 VNet Peering 让应用网络与数据库网络互通。它本质上是把两个网络打通。这样虽然结构直接，但也可能带来额外的安全和合规工作。例如应用所在网络是 PCI 网络时，网络互通后，数据库所在网络通常也需要进入同等安全边界评估范围。

Public Access + Private Endpoint：数据库保留公共入口能力（但可完全关闭），但客户端优先通过 Private Endpoint 从自己的 VNet 私网访问。相比之下，Private Endpoint 更适合只想把“某一个具体 PaaS 实例”私网暴露给消费方，而不希望扩大网络信任边界的场景。Private Link 连接的是某个资源实例，而不是整个服务或整个 VNet，因此更容易控制访问范围，也更有利于隔离和审计。

可以简单理解为：

方案	网络模型	安全边界	适用场景
`VNet Integration + Peering`	VNet 级别互通	边界更大，联通后要一起评估	同一信任域内，长期稳定互通
`Public Access + Private Endpoint`	资源实例级别私网接入	边界更小，更利于隔离	跨团队、跨 Subscription、合规要求较严

微软强调 Private Endpoint 的几个优势，本质上可以概括为：

只把特定的 PostgreSQL 实例私网暴露给客户端，而不是打通整张网络。
可以从本地网络、VPN、ExpressRoute 或已对等互联的网络私下访问，不需要走公网。
有助于降低数据泄露风险，因为访问范围限定在具体资源实例上。
支持跨 Region 私网访问，客户端和服务端不必位于同一区域。

使用 Private Endpoint 的步骤

假设数据库和应用在不同的Subscription，且数据库在 A Subscription，应用在 B Subscription。要让应用通过 Private Endpoint 访问数据库，需要完成以下步骤：

在 A Subscription 中创建 Azure Database for PostgreSQL flexible server 时，启用 Public Access。
在 B Subscription 中按需创建 PrivateDnsZone，并通过 VirtualNetworkLink 将 Private DNS Zone 与应用的 VNet 关联。
在 B Subscription 中的客户端网络所在的 VNet 中创建 Private Endpoint，将其关联到目标子网和 PSQL Server；private_link_service_connections 可以使用自动批准或手动批准模式。
在 B Subscription 中的客户端网络所在的 VNet 中创建 PrivateDnsZoneGroup，将 PrivateDnsZone 与 Private Endpoint 关联起来。

需要注意的是：

Private Endpoint 的 DNS 解析通常依赖于 Private DNS Zone，因此需要在客户端网络中配置 Private DNS Zone，并将其与客户端 VNet 关联。这样，客户端才能将数据库域名解析到 Private Endpoint 的私有 IP 地址。
对于同一种 Private DNS Zone（比如 privatelink.postgres.database.azure.com），一个 VNet 通常只关联一个实例。因此，如果客户端网络需要访问多个 Azure Database for PostgreSQL flexible server，通常会复用同一个 Private DNS Zone，并在该 Zone 中为不同数据库维护各自的 DNS 记录。需要注意的是，如果依赖 PrivateDnsZoneGroup 的自动关联和 Azure 的自动记录管理机制，最好额外验证这些记录不会被覆盖或删除；在更复杂的场景下，也可以采用集中 DNS 管理或手动校验记录的方式。
虽然在 Azure Portal 中可以从数据库页面发起 Private Endpoint 的创建流程，但 Private Endpoint 本身是创建在客户端 VNet 中的资源，因此通常应由客户端网络所在 Subscription 的管理员来创建。如果当前 Identity 只能管理本 Subscription 内的资源，无法同时完成两侧操作，那么更合适的做法是先在客户端侧创建 Manual Private Link Connection，再由数据库所在 Subscription 的管理员审批该连接请求。

参考文档

Networking with Private Link in Azure Database for PostgreSQL flexible server

通过 IIS URL Rewrite 还原原始请求协议（HTTPS）

Sun, 26 Jul 2026 00:00:00 GMT

将应用部署到 Kubernetes 集群时，通常会使用 Ingress Controller、Gateway 等组件完成 TLS 终止（TLS Termination），即客户端与 Ingress Controller 之间使用 HTTPS 协议，而 Ingress Controller 与服务之间使用 HTTP 协议。默认情况下，ASP.NET 会根据请求的协议来判断是否使用 HTTPS，但此时 ASP.NET 看到的请求是 HTTP，因此会误判为非 HTTPS 请求，从而导致一些功能无法正常工作，比如生成的重定向 URL 不正确，或者安全相关的功能失效。解决方法之一，就是使用 URL Rewrite 模块还原请求的协议。

安装 URL Rewrite 模块

Windows 镜像默认没有安装 URL Rewrite 模块，需要手动安装。可以从 IIS 官方网站下载并安装 URL Rewrite 模块，然后根据请求头里的 X-Forwarded-Proto 值来还原请求的协议。

在 Dockerfile 中，可以添加以下指令来安装和配置：


RUN $ErrorActionPreference = 'Stop'; \
    Write-Host 'Downloading IIS URL Rewrite Module...'; \
    $msi = Join-Path $env:TEMP 'rewrite_amd64.msi'; \
    (New-Object Net.WebClient).DownloadFile('https://download.microsoft.com/download/1/2/8/128E2E22-C1B9-44A4-BE2A-5859ED1D4592/rewrite_amd64_en-US.msi', $msi); \
    Write-Host 'Installing URL Rewrite Module...'; \
    $proc = Start-Process msiexec.exe -ArgumentList '/i', $msi, '/quiet', '/norestart' -NoNewWindow -Wait -PassThru; \
    if ($proc.ExitCode -ne 0) { throw ('URL Rewrite install failed with exit code ' + $proc.ExitCode) }; \
    Remove-Item $msi -Force; \
    Write-Host 'Configuring global URL Rewrite rule for gateway TLS termination...'; \
    $config = 'C:\Windows\System32\inetsrv\config\applicationHost.config'; \
    [xml]$xml = Get-Content $config; \
    $webServer = $xml.configuration.'system.webServer'; \
    $rewrite = $webServer.rewrite; \
    if (-not $rewrite) { \
    $rewrite = $webServer.AppendChild($xml.CreateElement('rewrite')) \
    }; \
    $fragment = $xml.CreateDocumentFragment(); \
    $fragment.InnerXml = '<allowedServerVariables><add name=''HTTPS'' /><add name=''SERVER_PORT'' /></allowedServerVariables><globalRules><rule name=''Fix-Forwarded-Proto''><match url=''.*'' /><conditions><add input=''{HTTP_X_FORWARDED_PROTO}'' pattern=''https'' /></conditions><serverVariables><set name=''HTTPS'' value=''on'' /><set name=''SERVER_PORT'' value=''443'' /></serverVariables><action type=''None'' /></rule></globalRules>'; \
    $null = $rewrite.AppendChild($fragment); \
    $xml.Save($config); \
    Write-Host 'URL Rewrite rule successfully applied.'

配置的变化

使用上面的命令安装和配置 URL Rewrite 模块后，C:\Windows\System32\inetsrv\config\applicationHost.config 文件中会新增以下内容：

<configuration>
  <!-- 其他配置 -->
  <configSections>
    <sectionGroup name="system.webServer">
      <!-- 以下为新增 -->
      <sectionGroup name="rewrite">
        <section name="globalRules" overrideModeDefault="Deny" allowDefinition="AppHostOnly" />
        <section name="rules" overrideModeDefault="Allow" />
        <section name="outboundRules" overrideModeDefault="Allow" />
        <section name="providers" overrideModeDefault="Allow" />
        <section name="rewriteMaps" overrideModeDefault="Allow" />
        <section name="allowedServerVariables" overrideModeDefault="Deny" />
      </sectionGroup>
      <!-- 以上为新增 -->
    </sectionGroup>
    <!-- 其他 -->
  </configSections>

  <system.webServer>
    <!-- 其他配置 -->
    <globalModules>
      <!-- 以下为新增 -->
      <add name="RewriteModule" image="%SystemRoot%\system32\inetsrv\rewrite.dll" />
      <!-- 以上为新增 -->
    </globalModules>

    <tracing>
      <traceProviderDefinitions>
        <add name="WWW Server" guid="{......}">
          <areas>
            <!-- 以下为新增 -->
            <add name="Rewrite" value="1024" />
            <!-- 以上为新增 -->
          </areas>
        </add>
        <!-- 其他配置 -->
      </traceProviderDefinitions>
    </tracing>
    <!-- 以下为新增 -->
    <rewrite>
      <allowedServerVariables>
        <add name="HTTPS" />
        <add name="SERVER_PORT" />
      </allowedServerVariables>
      <globalRules>
        <rule name="Fix-Forwarded-Proto">
          <match url=".*" />
          <conditions>
            <add input="{HTTP_X_FORWARDED_PROTO}" pattern="https" />
          </conditions>
          <serverVariables>
            <set name="HTTPS" value="on" />
            <set name="SERVER_PORT" value="443" />
          </serverVariables>
          <action type="None" />
        </rule>
      </globalRules>
    </rewrite>
    <!-- 以上为新增 -->
    <modules>
      <!-- 以下为新增 -->
      <add name="RewriteModule" />
      <!-- 以上为新增 -->
    </modules>
  </system.webServer>
</configuration>

为何不在代码中实现？

在应用代码中根据 X-Forwarded-Proto 恢复请求协议当然也是可行的，例如在 ASP.NET 中使用 Forwarded Headers Middleware。

但在 IIS 场景下，某些重定向可能发生在请求进入应用之前。比较常见的是 IIS 对路径末尾斜杠（trailing slash）的规范化跳转，这类跳转由 IIS 直接返回响应，请求不会进入应用代码。

常见例子包括：

访问目录但 URL 没有末尾斜杠，例如 /docs 被规范化为 /docs/。
访问子应用根路径但没有末尾斜杠，例如 /myapp 被规范化为 /myapp/。
目录配合默认文档时，请求 /portal 往往会先跳转到 /portal/，再由 IIS 返回默认文档。

如果只在代码层处理协议恢复，这类“代码之外”的跳转仍可能使用 HTTP 视角生成结果，导致跳转协议不符合预期。将协议恢复放在 IIS URL Rewrite 层处理，可以更早生效，覆盖这类前置处理路径。

ArgoCD 接入 Azure Entra ID 单点登录

Wed, 22 Jul 2026 00:00:00 GMT

ArgoCD 可以与 Azure Entra ID，实现单点登录（SSO）。本文将介绍如何在 Azure Entra ID 中配置 ArgoCD 的 SSO。

创建 App Registration

在 Azure 创建了 App Registration，系统就会在后台自动创建一个对应的 Enterprise Application。然后，将 App Registration 和 Enterprise Application 的所有者添加到 Azure Entra ID 中，并批准该应用程序。

配置 SSO

添加 Redirect URI （类型选 Web，值设为 https://<argocd-url>/auth/callback）
添加 groups claims。这样就可以通过 Azure Entra ID 的组来控制 ArgoCD 的访问权限：在 App Registration 的配置中找到 Token configuration。点击添加 groups claims，勾选 Groups assigned to the application，并选择Group ID of ID, Access and SAML。

添加 Federated Credentials

在 App Registration 的 Certificates & secrets 中，点击 Federated Credentials 来添加 AKS 的 issuer，以及 ArgoCD Server 的 Namespace 和 Service Account，这样就能实现“无密码”（Secretless）的身份验证。也就是说，AKS 会在 ArgoCD 的 Pod 注入环境变量 AZURE_FEDERATED_TOKEN_FILE，它指向的文件是 AKS 的 Service Account Token 文件，ArgoCD 读取该文件内容，作为 client_assertion（客户端断言）发送给 Azure 的令牌端点 /token，获取 Access Token。

注意： issuer URL 必须与 AKS 集群的 issuerURL 完全一致，包括末尾的斜杠（/）。

添加用户

在 Enterprise Application 中，进入 Manage - Users and Groups 来添加 Role Assignments，以便用户或者用户组可以访问。

使用 az aks command invoke 重启 AKS 中的 Deployment

Wed, 15 Jul 2026 00:00:00 GMT

当重启 Kubernetes 部署时，通常会使用 kubectl rollout restart deployment <deployment-name> -n <namespace> 命令。然而，在某些情况下，可能无法直接访问 AKS 集群的 Kubernetes API，此时可以使用 Azure CLI 的 az aks command invoke 命令来执行该操作。

前置权限

需要具备在目标 AKS 集群上执行 Run Command 的 Azure RBAC 权限。实践中，仅有 Kubernetes RBAC 的 Kubernetes Admin 往往不足以执行 az aks command invoke，建议至少具备该 AKS 资源范围的 Contributor 权限。

重启 Deployment

az aks command invoke --name <cluster-name> --resource-group <resource-group> --subscription "<subscription-id-or-name>" --command "kubectl rollout restart deployment <deployment-name> -n <namespace>" --output json

注意，该命令的退出码为 az 命令的退出码，并不是 kubectl 命令的退出码。即使 kubectl 命令执行失败，az aks command invoke 的退出码仍然可能是 0。好在这个命令返回的 JSON 格式的结果里，包含了 exitCode 字段，表示 kubectl 命令的退出码。可以通过解析该字段来判断 kubectl 命令是否执行成功。

比如当 Deployment 不存在时，返回的 JSON 结果如下：

{
  "exitCode": 1,
  "finishedAt": "2026-07-13T12:57:22+00:00",
  "id": "b1c77d81f142404d825db5f8a490f05a",
  "logs": "Error from server (NotFound): deployments.apps \"abc\" not found\n",
  "provisioningState": "Succeeded",
  "reason": null,
  "startedAt": "2026-07-13T12:57:17+00:00"
}

另外，kubectl rollout restart 执行后会立即返回，并不会等待重启完成。如果想知道重启结果，还需要使用 kubectl rollout status 命令查看 Deployment 状态。可以执行如下命令等待重启完成：

az aks command invoke --name <cluster-name> --resource-group <resource-group> --subscription "<subscription-id-or-name>" --command "kubectl rollout status deployment <deployment-name> -n <namespace>" --output json

返回示例如下：

{
  "exitCode": 0,
  "finishedAt": "2026-07-13T12:59:59+00:00",
  "id": "826c6fba27ae45eeb28956d6f32a6e20",
  "logs": "....",
  "provisioningState": "Succeeded",
  "reason": null,
  "startedAt": "2026-07-13T12:59:54+00:00"
}