consul connect 不是 go 库，而是通过 sidecar 代理实现的服务网格能力；go 服务需监听 127.0.0.1 明文端口、注册时声明 connect 配置块、依赖 intentions 控制访问，业务代码零 tls 改动。
Consul Connect 不是 Go 代码里“引入”的库，而是 Consul 提供的独立服务网格能力——它运行在服务外部，通过 Sidecar 代理（consul connect envoy 或 consul connect native）拦截流量并自动注入 mTLS。你不需要在 Go 代码里写 TLS 配置来启用 Connect，但必须让 Go 服务配合它的通信模型。
Go 服务必须监听 localhost + 明文端口
Consul Connect 的 Sidecar 模式要求服务只暴露本地明文接口，所有加密、认证、策略执行都由 Sidecar 完成。
常见错误现象：connection refused 或 Sidecar 日志报 upstream connect error or disconnect/reset before headers，本质是 Go 服务绑定了 0.0.0.0 或非 127.0.0.1 地址，导致 Sidecar 无法拦截。
- Go 启动时只监听 127.0.0.1:8080（不能是 :8080 或 0.0.0.0:8080）
- 注册到 Consul 的 Address 字段必须留空或填 127.0.0.1（让 Consul 认为该服务走本地 loopback）
- Sidecar 默认从 127.0.0.1:8080 发起上游请求，不改地址就能打通
服务注册时必须声明 connect 配置块
仅注册服务名和端口不够，Consul Connect 需要显式识别哪些服务参与网格。
- 在 api.AgentServiceRegistration 结构中，必须嵌套 Connect 字段：
Connect: &api.AgentServiceConnect{
Native: true, // 或用 Envoy：Native: false, SidecarService: &api.AgentService{...}
},
- 如果用 Native 模式（无需 Envoy），Consul 会自动注入一个轻量级 consul connect sidecar 进程，它监听 localhost:20000（默认）并代理到你的 Go 服务
- 若省略 Connect 块，Consul UI 中该服务的 “Connect” 标签不会显示，意图（Intentions）策略也对其无效
意图（Intentions）配置决定谁可以调用谁
Consul Connect 的访问控制不靠 Go 代码实现，而靠 ACL + Intentions。
- 先确保 ACL 已启用且 token 有 intentions:write 权限
- 创建意图示例（CLI）：
consul intention create user-service order-service这条命令允许
user-service 调用 order-service；反向调用默认拒绝
- 错误现象：403 Forbidden 或 Sidecar 日志出现 intent denied，说明意图未创建，或目标服务名拼写与注册名不一致（注意大小写和服务 ID 区分）
- 意图生效是实时的，无需重启服务或 Sidecar
调试连通性时优先查 Sidecar 日志，不是 Go 日志
当请求失败，90% 的问题出在 Sidecar 层而非 Go 代码： - 查看 Sidecar 日志：consul monitor -type=connect 或直接 journalctl -u consul -f | grep connect
- 关键线索包括：upstream reset（上游服务没响应）、no healthy upstream（目标服务未注册或健康检查失败）、tls handshake error（CA 不匹配，但 Connect 自动管理证书，除非你手动覆盖了 ca_file）
- Go 服务本身无需加载任何证书文件，也不用碰 crypto/tls —— 这正是 Connect 的设计前提：业务代码零 TLS 改动
真正容易被忽略的点是：Sidecar 和 Go 进程必须在同一网络命名空间（如 Docker 同一 network 或 Kubernetes 同一 Pod），否则 127.0.0.1 对 Sidecar 就不是 Go 服务。K8s 场景下务必确认 Init Container 已完成 Consul Agent 启动，且 consul connect inject 注入的 Sidecar 与应用容器共享 network: pod。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
