配置多级覆盖把「唯一权威来源」压掉：上游合同 600 rps，网关却按 130 rps 发请求

# conf/gateway.env —— 集群下发、只读、不许改
GATEWAY_UPSTREAM_URL=upstream:80
GATEWAY_UPSTREAM_MAX_RPS=600

cd scenario/2026-09-27-0800
docker compose up -d --build
docker compose exec gateway bash

# 1) 复现问题：打印生效配置 + 真实节拍 + 与契约比对
/srv/ops/repro.sh                        # -> RESULT: BAD（退出码 1）

# 2) 问题态自检基线
/srv/ops/verify.sh                       # -> PASS=2 FAIL=9，RESULT: BAD

# 3) 外部验收探针（只读契约视角）
python3 /srv/client/check_ratelimit.py   # -> RESULT: BAD（退出码 1）

# 4) 改 app/ 下的代码后必须重建镜像（COPY 进镜像，restart 不生效）
exit
docker compose up -d --build
docker compose exec gateway /srv/ops/repro.sh                         # -> RESULT: OK
docker compose exec gateway /srv/ops/verify.sh                        # -> PASS=11 FAIL=0 / RESULT: OK
docker compose exec gateway python3 /srv/client/check_ratelimit.py    # -> RESULT: OK
docker compose down

== 1) 当前生效的速率配置（看 config_sources 的胜出者）==
upstream_max_rps = 130.0
胜出来源        = conf/config.override.json:upstream.max_rps

== 4) 与部署契约相比 ==
  契约 GATEWAY_UPSTREAM_MAX_RPS = 600 rps
  实际生效 upstream_max_rps     = 130.0
  节拍间隔 interval_ms          = 7.692 ms (契约应为 1.667 ms)
RESULT: BAD —— 上游【合同值】600 rps 被压到 130.0 rps，节拍慢了 4.6 倍

cfg["upstream_max_rps"] = float(contract[CONTRACT_KEY])   # 契约 600    ← 先写
...
cfg["upstream_max_rps"] = float(mid["upstream_max_rps"])  # 中间层 1500 ← 覆盖
...
cfg["upstream_max_rps"] = float(up["max_rps"])            # 覆盖层 130  ← 再覆盖，赢了

class ContractError(RuntimeError):
    """部署契约缺失或不可用时抛出 —— 宁可起不来，也不要静默跑错口径。"""

AUTHORITATIVE_KEY = "upstream_max_rps"

def load_config() -> dict:
    ...
    # ── 1) 权威层：部署契约 ──
    contract = _read_env_file(CONF / "gateway.env")
    if CONTRACT_KEY not in contract:
        raise ContractError(
            f"部署契约 {contract_path} 缺失 {CONTRACT_KEY}："
            f"{AUTHORITATIVE_KEY} 的唯一权威来源不可用，拒绝静默兜底启动")
    contract_origin = f"conf/gateway.env:{CONTRACT_KEY}"
    authoritative_value = _as_float(contract[CONTRACT_KEY], contract_origin)
    cfg[AUTHORITATIVE_KEY] = authoritative_value
    sources[AUTHORITATIVE_KEY] = contract_origin

    def _reject_if_conflicting(key, raw, origin) -> bool:
        """对权威键做「记录并忽略」；返回 True 表示 caller 可继续处理该键。"""
        if key != AUTHORITATIVE_KEY:
            return True                       # 非冲突键：照常覆盖
        value = _as_float(raw, origin)
        if value != authoritative_value:
            ignored.setdefault(AUTHORITATIVE_KEY, []).append(
                {"source": origin, "value": value})
            _warn(f"{origin} 试图把 {AUTHORITATIVE_KEY} 覆盖为 {value}，"
                  f"但契约 {contract_origin} 的值 {authoritative_value} 是唯一权威来源，已忽略该值")
        return False

docker compose up -d --build      # restart 不会生效！

== 1) 当前生效的速率配置（看 config_sources 的胜出者）==
[config][WARN] conf/ratelimit.conf:upstream_max_rps 试图把 upstream_max_rps 覆盖为 1500.0，
  但契约 conf/gateway.env:GATEWAY_UPSTREAM_MAX_RPS 的值 600.0 是唯一权威来源，已忽略该值
upstream_max_rps = 600.0
胜出来源        = conf/gateway.env:GATEWAY_UPSTREAM_MAX_RPS
...
  upstream_max_rps = 600.0
  interval_ms = 1.6666666666666667
  effective_rps = 600.0
  peak_sustained_rps = 600.0
RESULT: OK  —— 生效速率与契约一致

── A 组：现象与现场 ──
  [PASS] A1 生效的 upstream_max_rps 应等于契约值 600（600.0）
  [PASS] A2 胜出来源应是契约文件 conf/gateway.env（conf/gateway.env:GATEWAY_UPSTREAM_MAX_RPS）
  [PASS] A3 节拍间隔应是 1.667 ms（1000/600）（1.667）
── B 组：判据 ──
  [PASS] B1 计划间隔应为 1.667 ms（1.667）
  [PASS] B2 真实调用间隔应落在 1.5~2.0 ms（实测 1.981 ms）（yes）
  [PASS] B3 生效速率必须是单个数值而不是数值集合（600.0）
── C 组：契约不可变 + 等价类 ──
  [PASS] C1 conf/ 部署契约必须保持原样（a53d9da5c5cb6dfadc1c54a475050bd6）
  [PASS] C2 非冲突项仍应被覆盖层正常覆盖（retry_budget=20）（20）
  [PASS] C3 契约值改为 321 后生效值应跟着变（证明真的在读契约）（321.0）
  [PASS] C4 契约缺失时应报错而不是静默兜底（RAISED）
── D 组：真实压测 ──
  [PASS] D1 1 秒内应发到 500~700 次（约 600 rps），实测 581 次（yes）

RESULT: OK   PASS=11 FAIL=0

契约要求 upstream_max_rps = 600
网关实际生效             = 600.0
节拍间隔                 = 1.667 ms (契约应为 1.667 ms)
配置胜出来源             = conf/gateway.env:GATEWAY_UPSTREAM_MAX_RPS
RESULT: OK

[config][WARN] env:GATEWAY_UPSTREAM_MAX_RPS 试图把 upstream_max_rps 覆盖为 130.0，…已忽略该值
600.0 conf/gateway.env:GATEWAY_UPSTREAM_MAX_RPS

config.ContractError: 部署契约 /srv/conf/gateway.env 缺失 GATEWAY_UPSTREAM_MAX_RPS：
upstream_max_rps 的唯一权威来源不可用，拒绝静默兜底启动
python exit=1