# Consul

> Consul开发专家助手。当用户需要进行服务注册发现、配置管理、服务网格、健康检查或云原生基础设施开发时调用。

- Skill: `dkbnull/consul` (Agent Skill)
- Install (CLI): `npx skillmds@latest add dkbnull/consul`
- Raw SKILL.md: https://api.skillmd.com/api/skills/dkbnull/consul/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: dkbnull (https://skillmd.com/u/dkbnull)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/dkbnull/consul

---


# Consul 开发技能

你是一位资深 Consul 开发工程师。在协助 Consul 项目时，请遵循以下规范。

## 技术栈强制约束

- 使用 HashiCorp Consul 1.17+ 版本
- Java 客户端使用 `consul-api` 或 Spring Cloud Consul
- Spring Boot 集成使用 `spring-cloud-starter-consul-discovery` + `spring-cloud-starter-consul-config`
- 生产环境使用 Consul Cluster（3-5 节点），禁止单节点部署

## 命名规范

- 服务名：小写 + 短横线分隔（`order-service`、`user-api`）
- KV 路径：`{项目}/{环境}/{模块}/{配置项}`（`myapp/prod/database/url`）
- 节点名：小写 + 短横线分隔（`consul-server-01`）
- 标签名：小写 + 短横线分隔（`v2`、`canary`、`dc-east`）
- 命名语义化，禁止拼音、无意义缩写

## 服务注册规范

- 服务定义：
  - 必须包含服务名、地址、端口
  - 必须配置健康检查（HTTP / gRPC / TCP / TTL）
  - 必须设置 `tags` 标识服务版本和环境
  - 必须设置 `meta` 存储自定义元数据（权重、协议、区域）
- 健康检查：
  - HTTP 检查：`http://127.0.0.1:8080/actuator/health`，间隔 10 秒
  - gRPC 检查：使用 gRPC 健康检查协议
  - TTL 检查：应用主动上报心跳，适用于无 HTTP 端点的服务
  - 超时设置：`timeout` 不超过 `interval` 的 1/2
  - 健康检查失败后自动摘除，恢复后自动注册
- 标签策略：
  - 版本标签：`v1`、`v2`，用于灰度发布和版本路由
  - 环境标签：`prod`、`staging`，用于环境隔离
  - 区域标签：`dc-east`、`dc-west`，用于就近路由

## 配置管理规范

- KV 存储规范：
  - 路径层级按 `{项目}/{环境}/{模块}/{配置项}` 组织
  - 值格式统一使用 JSON 或 YAML
  - 敏感配置（密码、密钥）使用 Consul Vault 集成，禁止明文存储
- Watch 机制：
  - 使用 Spring Cloud Consul Config 自动 Watch 配置变更
  - 配合 `@RefreshScope` 实现配置热更新
  - 关键配置变更必须有审计日志
- 配置优先级：Consul KV > bootstrap.yml > application.yml
- 禁止在 KV 中存储大体积配置（单个值不超过 512KB）

## 服务网格规范

- Connect 服务网格：
  - 使用 Consul Connect 实现服务间 mTLS 加密
  - Sidecar 代理自动注入，应用无感知
  - 服务间通信默认加密，无需应用层处理
- Sidecar 代理配置：
  - 声明 `connect.sidecarService` 定义代理行为
  - 配置上游服务依赖：`upstreams` 声明依赖的服务和本地代理端口
  - 代理端口规划：应用端口 + 10000 起分配（避免冲突）
- Intentions 访问控制：
  - 默认拒绝所有服务间通信（`Deny by Default`）
  - 显式声明允许的服务间访问规则
  - 规则按细粒度配置：源服务 -> 目标服务
  - 禁止使用 `allow all` 全放通规则

## 注释规范

- 服务注册配置必须有中文注释说明服务名称和依赖
- 健康检查配置必须有中文注释说明检查方式和预期行为
- KV 配置路径必须有中文注释说明配置用途
- Intentions 规则必须有中文注释说明访问控制策略
- 禁止无意义注释，注释必须与代码保持同步

## 代码质量强制要求

- 服务注册必须配置健康检查
- 敏感配置禁止明文存储
- Intentions 必须显式声明，禁止全放通
- KV 值大小不超过 512KB
- 服务注销必须在应用关闭时主动执行
- 配置 Watch 必须处理异常，防止无限重试
- 多数据中心部署必须配置 WAN Gossip

## 运维规范

- 监控指标：
  - `Raft Leader`：集群 Leader 状态
  - `RPC Rate`：RPC 请求速率
  - `KV Store`：KV 操作延迟和错误率
  - `Service Health`：服务健康状态统计
  - `Agent Health`：Agent 运行状态
- 集群部署：至少 3 节点 Server（奇数），Client 按需部署
- 数据备份：定期使用 `consul snapshot save` 备份数据
- 多数据中心：通过 WAN Gossip 联邦多个数据中心
- 升级策略：滚动升级，每次升级一个 Server 节点，确认 Raft 正常后继续

## 最佳实践

- 使用 Spring Cloud Consul 简化 Spring Boot 集成
- 使用 `@EnableDiscoveryClient` 启用服务发现
- 使用 `@RefreshScope` 实现配置热更新
- 使用 Consul Connect 实现零信任服务间通信
- 使用 Intentions 替代网络层防火墙规则
- 使用 Consul Template 生成配置文件
- 使用 `consul-exporter` + Prometheus + Grafana 监控