consul中存网关路由规则需严格遵循网关约定的key路径与value格式：spring cloud gateway用config/gateway/routes/前缀、json值；traefik用traefik/http/routers|services/前缀、toml值且key带@consul后缀；须启用watch、校验acl权限、避免语法错误与点号分隔符。
Consul 里怎么存网关路由规则才被正确读取
Consul 本身不认“路由规则”这个概念，它只存键值对。网关（比如 Spring Cloud Gateway 或 Traefik）靠自己约定的 key 路径和 value 格式去拉取配置。存错路径或格式，网关就当没这回事。
常见错误现象：spring.cloud.gateway.discovery.locator.enabled=true 开着但路由没生效；Traefik 的 consulcatalog provider 没发现任何服务；curl http://consul:8500/v1/kv/ 查不到预期 key。
- Spring Cloud Gateway 推荐用前缀
config/gateway/routes/，每个 route 单独一个 key，value 是 JSON 格式字符串（不是 YAML），必须包含id、uri、predicates字段 - Traefik v2+ 通常监听
traefik/http/routers/和traefik/http/services/下的 key，value 是 TOML 片段，且要求 key 名带@consul后缀（如traefik/http/routers/myrouter@consul） - 避免在 key 中使用点号（
.）——Consul 支持，但某些网关客户端会把点误解析为嵌套分隔符，改用连字符（-）更稳 - value 必须是合法 JSON/TOML/纯文本，不能有 BOM、尾随逗号、注释；用
consul kv put写入时，别漏掉-从 stdin 读取，否则空内容也写进去了
网关启动后不自动加载 Consul 新增的路由
不是所有网关都默认开启 Consul 配置热刷新。即使开了，也依赖 Consul 的 watch 机制是否被正确触发，以及网关自身是否监听了对应 key 前缀的变化。
常见错误现象：手动 consul kv put config/gateway/routes/test '{...}' 后，GET /actuator/gateway/routes 里没出现新路由；日志里没有 Watch returned new results 类提示。
- Spring Cloud Gateway 需显式启用
spring.cloud.consul.config.watch.enabled=true，且spring.cloud.consul.config.format=KEY_VALUE（不能是 YAML/FILES） - watch 默认间隔是 10 秒，不是实时；如果 Consul 集群有多个节点，确保网关连接的是 leader 节点，否则 watch 可能延迟或丢失事件
- Traefik 的
consulcatalogprovider 是轮询式发现，不依赖 watch；但consulKV provider 才支持 watch，需确认你用的是后者并配了watch = true - 检查网关日志里有没有
ConsulClientException或Retry-After相关告警——Consul 限流或 ACL 权限不足会导致 watch 静默失败
路由更新时出现 404 或 503，而不是平滑切换
Consul KV 更新是原子的，但网关加载新路由不是原子操作。如果新路由配置有语法错误、目标服务不存在、或 predicate 冲突，网关可能部分加载失败，导致已有流量打到无效 endpoint。
使用场景：上线灰度路由、切流、下线旧服务。这时候你想要的是“新配置校验通过再生效”，而不是“一写就上”。
- Spring Cloud Gateway 不校验
uri是否可达，只校验 JSON 结构；务必在uri值里写完整协议+host+port（如http://user-service:8080），别写lb://user-service——那需要服务发现配合，和 Consul KV 无关 - Traefik 要求 router 和 service 必须成对存在；单独加一个
routers/foo但没配对应的services/foo，整个 router 会被跳过，不报错也不生效 - 避免在高并发时段直接覆盖关键路由 key；推荐用临时 key + 原子 rename（Consul 不支持 rename，得靠应用层双写+开关控制），或者用带版本号的 key（如
routes/api-v2.1）配合网关的条件加载逻辑 - 网关内存里的路由表是不可变对象，每次更新都会重建全量列表；如果路由数超 200，GC 压力明显，观察
Full GC频次比平时高，就得考虑拆分 key 前缀做分片
ACL 权限配错导致 Consul 返回 403 却不报具体原因
Consul ACL 默认是 deny-all，哪怕只读路由配置，也需要明确授权 key 前缀的 read 权限。网关客户端收到 403 后往往只打印 “failed to read from consul”，不会告诉你缺哪个权限。
性能影响：ACL 规则越多，Consul server 的匹配开销越大；但没 ACL 比配错更危险——等于把路由规则裸奔在公网。
- 最小权限原则：网关 token 只需要
key_prefix "config/gateway/" { policy = "read" }，千万别给key "" { policy = "read" } - 如果用了 namespace（Consul 1.7+），ACL rule 必须加上
namespace前缀，比如namespace "default" { key_prefix "config/" { policy = "read" } } - 用
consul acl token read -id=xxx确认 token 绑定的 policy 内容；再用consul kv get -token=xxx config/gateway/routes/test手动测试，比看网关日志更快定位是不是权限问题 - 开发环境图省事关掉 ACL？可以，但要同步关掉 Consul 的
verify_outgoing = false和 TLS 配置，否则网关连不上会卡在 handshake 阶段，超时时间长达 30 秒
Consul 做动态路由的核心不是“能不能存”，而是网关和 Consul 之间那几条约定好的 key 路径、value 格式、watch 行为和权限边界。错一个，整条链就断在你看不见的地方。
