先说结论用Docker部署Consul不是难点难的是把ACL权限控制一次性配明白。很多人在本地随便跑一个docker run consul就当开发环境用了等服务一上生产才发现没有ACL的Consul等于裸奔谁拿到8500端口都能读写你的配置、踢掉你的服务注册。这篇文章把我最近一次在Docker环境里从零创建Consul并加上ACL权限控制的完整过程整理出来包括设计思路、Docker参数解析、ACL初始化流程、客户端接入验证还有几个我踩过之后觉得必须写下来的坑。适合正在上手Consul、或者已经跑起来但还没加ACL的同学照着操作一遍就能跑通。1. 整体设计思路为什么要给Consul加ACL1.1 没有ACL的Consul有多危险Consul在微服务体系里扮演服务注册中心加配置中心的角色它存储的是“哪个服务在哪个地址、端口、健康状态是什么、配置项的值是多少”这类基础设施元数据。如果你把它暴露在没有防护的网络里别人可以顺手做三件事直接读KV存储把数据库地址、Redis密码、各种业务配置全部打包带走调用PUT /v1/agent/service/register伪造一个服务实例把流量引到恶意地址上调用leave或者批量反注册接口让整个服务发现链路瞬间塌掉。这些操作不需要多高深的技术一个curl命令就够了。我在第一次给Consul加ACL之前一直觉得“反正只在内网用没有什么风险”后来做安全审计的时候才意识到纯内网的默认信任模型在容器化环境里根本不成立一个被攻破的旁路容器就可能直接打到Consul的未授权接口。1.2 ACL模型与Docker部署的配合方式Consul的ACL体系在1.4版本之后全面升级成以Token为中心的模型。每个Token挂载一个或多个PolicyPolicy里面写规则规则针对service、node、key、agent、session、event等资源定义read、write、deny操作。理解起来其实很像文件权限Token是你登录用的身份Policy是你分配到的角色Rule是角色里具体的权限描述。ACL有两种工作模式默认允许default allow和默认拒绝default deny。开发环境图省事可以用默认允许但生产环境几乎都是默认拒绝——没写规则就拒绝访问然后通过匿名Token和专门创建的Token放行特定资源。这在Docker部署里反而简单只要在配置文件里把acl.enabled打开再设置acl.default_policy denyConsul不管是以容器还是二进制方式跑行为完全一致。后面所有初始化操作都跑在容器内部数据写进挂载好的/consul/data目录重启不丢配置。1.3 方案选型的关键决策在这个项目里我做了几个决策先说清楚为什么免得你照搬后发现版本不同踩坑镜像选择hashicorp/consul:1.18.2而不是latest。latest的坑在于每次拉取版本可能都不一样ACL在1.15和1.18的细节略有差异固定版本号能保证你看到的命令行为和我一致端口只暴露8500给外部访问8600DNS接口保持容器内部可用就行不一定要映射出去8300、8301、8302这些端口是Server间通信用的单节点部署情况下完全没必要暴露到宿主机数据卷挂载/consul/data而不是整个/consul目录。/consul下除了data还有config如果整个挂载会导致容器内配置文件路径混乱除非你特意做多层挂载否则保持最小化挂载是最稳妥的。2. Docker环境准备与基础部署2.1 准备Docker环境与镜像宿主机Docker版本建议不低于20.10太老的版本在端口映射和容器网络方面的行为有差异。我当前用的是Ubuntu 22.04 Docker 24.0.7Docker Compose v2可用可不用单节点Consul用docker run就够干净了。拉取镜像时注意如果服务器在国内镜像源下载可能慢可以提前配置镜像加速器。不过Consul镜像大概几十MB只要网络不算太差直接拉取能接受docker pull hashicorp/consul:1.18.2拉取完可以顺手确认一下镜像信息docker image inspect hashicorp/consul:1.18.2 --format {{.Os}} {{.Architecture}}输出正常显示linux amd64或者linux arm64就可以继续了。2.2 数据目录与配置目录准备先规划好宿主机上的目录结构。我习惯这样建mkdir -p /opt/consul/data mkdir -p /opt/consul/config/opt/consul/data是数据持久化目录容器内部会映射为/consul/data。之所以单独划出来是因为Consul的Raft状态文件、服务注册快照、KV存储全部写在这里容器删了重建不影响数据。/opt/consul/config用来放ACL配置等JSON文件映射到容器内部的/consul/configConsul启动时会自动读取这个目录下所有.json和.hcl格式的配置。在config目录里新建一个acl.json{ acl: { enabled: true, default_policy: deny, enable_token_persistence: true } }这里重点解释一下三项配置“enabled”是总开关没它什么都白搭“default_policy”设为deny表示没Token或者Token没有匹配权限时所有请求一律拒绝enable_token_persistence是让节点把Token持久化在本地Agent重启之后Token还在省去每次重启都要重新读取配置的麻烦。 提示对于全新部署这样直接启用ACL没问题。如果Consul已经跑了一段时间且里面已经有服务在注册直接开ACL要注意数据兼容问题后面第五节细说。2.3 启动Consul容器并验证基础状态配置文件和目录都准备好后执行启动命令docker run -d \ --name consul-server \ --restartalways \ -p 8500:8500 \ -p 8600:8600/udp \ -v /opt/consul/data:/consul/data \ -v /opt/consul/config:/consul/config \ hashicorp/consul:1.18.2 \ agent -server -bootstrap-expect1 -ui -client0.0.0.0 -data-dir/consul/data参数逐个说--name consul-server给容器起固定名称后面进容器执行命令方便--restartalways让Docker守护进程在容器崩溃或宿主机重启后自动拉起节点对注册中心这种基础设施服务几乎是必选项-p 8500:8500暴露HTTP API和UI端口-p 8600:8600/udp暴露DNS接口-v /opt/consul/data:/consul/data数据持久化-v /opt/consul/config:/consul/config将外部的ACL配置注入容器agent -server表示以Server模式启动-bootstrap-expect1表示单节点环境允许自己选举为Leader-ui开启内置Web界面-client0.0.0.0让客户端接口监听所有网卡这样外部才能通过8500访问-data-dir/consul/data指定数据目录。启动后先别急着访问UI等几秒让Leader选举完成再通过容器日志确认状态docker logs consul-server --tail 20正常应该能看到类似 “Leader election complete” 或者 “Adding server” 之类的日志。接着访问http://localhost:8500/ui如果看到Consul的Web界面但界面里的服务列表、KV页面等操作全部被拒绝或提示无权限这就说明ACL已经生效了。此刻正是预期状态——UI还能打开但所有数据都会报Permission denied因为没有携带Token。3. ACL配置关键流程从初始化Token到策略分配3.1 Bootstrap初始化获取管理Token启用了ACL之后第一个要做的事是生成初始的Token也就是bootstrap token。只有完成bootstrapConsul才会产生默认的management策略和管理员Token。注意这个操作只能成功一次一旦生成下次再执行会直接报错所以拿到Token后务必第一时间备份。进容器里执行docker exec -it consul-server consul acl bootstrap输出结果类似AccessorID: 6b1f2f1d-....-.... SecretID: 7f4f3e1a-....-.... Namespace: default Description: Bootstrap Token Policies: global-managementSecretID是你真正需要保存的密钥它就是管理员身份。建议立刻执行echo 7f4f3e1a-....-.... /opt/consul/bootstrap.token chmod 600 /opt/consul/bootstrap.token这个Token一旦丢失没有任何办法找回只能清空数据目录重建整个集群。把Token存成文件配合chmod 600限权是我目前试下来最简单又相对安全的方式。用这个Token验证一下当前ACL状态curl -H X-Consul-Token: 7f4f3e1a-....-.... http://localhost:8500/v1/acl/tokens能返回Token列表说明管理员身份可用。 注意bootstrap前确保数据目录是空的或者Consul从启动起就是ACL enabled状态。如果之前以无ACL模式运行过且写入了数据bootstrap时可能出现“Unexpected response code: 403”的坑后面专门讲。3.2 配置匿名Token与默认放行策略管理Token能做的只是让管理员进系统Consul服务发现场景里还有两类流量需要处理一是Consul集群内部节点间的交互二是未登录状态下对部分基础数据的读取。对于大多数中小型部署建议给匿名Token设置一组最小权限让任何人未带Token都能读取服务列表和节点列表但禁止修改。这样业务系统查询服务地址时不用带Token体验顺滑同时写操作完全被堵死。先把匿名Token的ID查出来docker exec -it consul-server consul acl token list输出里anonymous这一行的AccessorID就是匿名Token的ID通常就是00000000-0000-0000-0000-000000000002。然后创建一个只读策略绑定到匿名Token上docker exec -it consul-server consul acl policy create \ -name global-readonly \ -rules node_prefix { policy read } service_prefix { policy read } key_prefix { policy read }这里node_prefix 、service_prefix 、key_prefix 三个规则都声明对所有节点、服务、KV键路径执行read也就是全局只读。接着把策略绑定给匿名Tokendocker exec -it consul-server consul acl token update \ -id 00000000-0000-0000-0000-000000000002 \ -policy-name global-readonly更新完试试不带Token访问curl http://localhost:8500/v1/catalog/services如果正常返回JSON服务列表说明全局只读策略已经生效再试写操作curl -X PUT http://localhost:8500/v1/kv/test -d hello这条命令应该被拒绝返回Permission denied这样就形成了“可读不可写”的基线状态。对只做服务发现的集群来说这种配置在安全和便利之间平衡得比较好。3.3 为服务和Agent创建专属Token只读策略能解决查询问题但业务服务还要能注册自己。如果一个服务都能被任意注册等于伪造流量的大门是敞开的所以给每个服务分配独立Token才是最标准的做法。Consul提供了service-identity参数它自动生成一条规则只允许操作匹配的服务名。比如为名为web的服务创建注册Tokendocker exec -it consul-server consul acl token create \ -service-identityweb:dc1 \ -description token for web serviceweb:dc1前面的web是服务名后面的dc1是数据中心名。执行完后输出中会有SecretID记录下来给业务服务使用。服务注册时在HTTP请求头里带上Tokencurl -H X-Consul-Token: web服务的SecretID \ -X PUT \ -d {ID:web-1,Name:web,Address:10.0.0.10,Port:8080} \ http://localhost:8500/v1/agent/service/register这样这个Token只能注册和反注册名字叫web的服务干不了别的。同样Agent的操作也得有Token。因为Consul节点本身在注册、健康检查、同步时会调用/v1/agent/*接口需要定义一个带agent权限的策略。创建node-write策略docker exec -it consul-server consul acl policy create \ -name node-write \ -rules node_prefix { policy write } service_prefix { policy write }再针对本节点绑定Tokendocker exec -it consul-server consul acl token create \ -node-identitynode1:dc1 \ -description token for consul server nodenode-identity跟service-identity同理简化了节点注册的权限控制。如果有agent加入集群把对应Token配置到它的配置文件的acl.tokens.agent字段即可。3.4 配置持久化与UI登录容器里创建的Token默认存在内存里虽然配置了enable_token_persistence但更稳妥的做法是把管理Token写进Consul配置避免重启后成员Token丢失导致的连锁问题。在/opt/consul/config/token.json里加入{ acl: { tokens: { master: 7f4f3e1a-....-.... } } }坑我一开始用的是acl.tokens.agent字段它在某些版本里只影响Agent级别的操作HTTP API读取服务列表还是需要请求头带Token。真正让Consul内部及该节点拥有全局管理能力的是acl.tokens.master。配好之后重启容器让配置生效docker restart consul-server重启后打开http://localhost:8500/ui在登录框里输入管理Token或任意有效Token就能看到Web界面正常展示节点、服务、KV。如果输入的是全局只读Token则能看到数据但不能修改。4. HTTP API接入验证与客户端配置4.1 API访问验证矩阵ACL加完不能只看本地curl要把整个访问链路按“带Token / 不带Token / 不同Token”分别验证一遍。我在项目里建了一个验证矩阵全部跑通了才意识到配置没有遗漏场景请求方式预期结果查询服务列表不带Token成功匿名只读策略查询KV不带Token成功匿名只读策略注册新服务不带Token403拒绝写KV不带Token403拒绝注册web服务带web专用Token成功注册mysql服务带web专用Token403拒绝删除web服务不带Token403拒绝删除web服务带web专用Token成功把这些请求用脚本批量跑一遍比肉眼观察界面好用得多。4.2 服务注册与发现的完整示例假设我有个Java应用需要注册到Consul在Spring Cloud Consul里配置Token最常见的方式是通过bootstrap.yml指定spring: cloud: consul: host: 127.0.0.1 port: 8500 discovery: register: true service-name: web instance-id: web-1 # 这里配置服务注册Token # 不写这个字段容器启动后会报 403 # token: web服务的SecretIDConsul Client类库在注册时会把Token加到X-Consul-Token头里因此服务注册逻辑无需额外编码但前提是给它的Token权限与服务名匹配。如果报403先检查Token的service-identity与配置里的spring.application.name是否一致。对于直接用HTTP API的Python脚本Token需要在请求头里显式写import requests headers {X-Consul-Token: web服务的SecretID} resp requests.put( http://127.0.0.1:8500/v1/agent/service/register, headersheaders, json{ID: web-1, Name: web, Address: 10.0.0.10, Port: 8080} ) print(resp.status_code)大多数语言的Consul客户端库都支持Token配置项比如Go的consul/api库在Config.Token字段里设置即可。4.3 健康检查与DNS查询在ACL下的表现加了ACL之后健康检查和DNS接口的行为值得单独提一下。健康检查会由Agent代表服务发出通常不需要显式带Token但Agent自身需要执行agent相关权限。如果不给Agent配置Token你会看到Consul日志里持续刷出 “Permission denied: agent master token is required” 之类的错误。所以上一节里创建一个node-write或agent权限的Token给Agent是必须的不只是接入方便的问题。DNS查询则不受ACL默认拒绝的影响。DNS接口对于匿名查询通常只返回已经注册过的服务记录而且它只暴露IP和端口不暴露KV配置数据。我在实际使用中保持内部服务通过DNS方式访问外部系统则走带Token的HTTP API两边都正常。如果发现通过DNS查不到某服务先确认服务注册时的Token身份是否有效以及服务健康检查是否为passing状态。ACL通常不会直接导致“服务不存在”但Token没注册成功会导致服务根本没写进目录表现结果看起来像DNS查不到。5. 常见问题与排查技巧实录5.1 初始化失败Unexpected response code: 403这是我自己当时卡得最久的问题也看到很多人问。起因是我第一次启动容器时忘了加ACL配置等服务注册了一批数据后又想通过配置开启ACL结果执行consul acl bootstrap时提示403。原因在于Consul一旦在无ACL模式下运行过内部已经形成了一种“无Token即全权限”的状态。数据目录里有旧的Raft日志切换ACL后旧的日志不会自动给所有人分配身份bootstrap操作会被判定为没有权限。解决办法有两个如果业务数据不重要像我这样直接清掉数据目录重建如果数据不能丢需要开启一个临时过程先在配置里设置acl.enabled true但保持acl.default_policy allow然后bootstrap获取管理Token再把default_policy改成deny最后重启。这个过程也要小心中间状态等于未授权访问仍然开放所以尽量在维护窗口操作。我当时数据还没上线直接执行了清理docker stop consul-server rm -rf /opt/consul/data/* docker start consul-server接着在容器里重新bootstrap问题解决。5.2 UI能打开但所有操作报错UI能打开说明端口和Web服务正常所有操作报权限错误说明ACL已生效但你还没登录或者说没把Token传给UI。新版Consul UI在ACL启用后会要求输入Token输入管理Token就能看到全部数据。如果没有登录框可能是浏览器缓存了旧页面清理缓存或强制刷新CtrlShiftR即可。如果输入Token后仍然报错检查Token是否过期。Consul Token默认没有过期时间但如果你在创建Token时加了-validity-period参数超过这个时间Token就会自动失效。普通场景不建议设置有效期除非你有轮换机制。5.3 容器重启后Token丢失明明创建了Token容器一重启Token就消失所有请求重新403。这个坑的本质是Token没有持久化。两个层面分别排查一是确认启动配置挂了enable_token_persistence这个配置还可能需要配合-data-dir才能生效数据目录就是/consul/data二是Token是运行时通过API创建的没有写入配置文件。Consul只在节点本身持久化由Agent发起的Token而通过API创建的业务Token在重启后会有不一致的表现。稳妥做法是把Token固化到配置文件里见前面3.4节的acl.tokens.master方式。业务Token则建议服务启动时从配置中心或环境变量注入不要让Container重建后再手动补Token。5.4 策略匹配与服务名大小写问题Consul的service-identity规则是精确匹配的。如果服务注册时的Name是WebToken创建时用的却是web权限会匹配失败。我踩过一次业务侧服务名带了环境后缀web-staging而策略只写了web排查半天日志才发现是规则前缀不匹配导致403。遇到这类问题用consul acl policy list和consul acl token read -self查看实际生效的策略比在日志里猜快得多。如果实在找不到原因把web的规则写成service web-staging / web这种多段形式也不要偷懒给所有服务开全局写权限否则ACL形同虚设。5.5 快速排查命令速查最后把这次排查用到的命令整理成速查表省得每次翻文档需求命令查看所有Tokendocker exec consul-server consul acl token list查看Token详情docker exec consul-server consul acl token read -id AccessorID查看所有策略docker exec consul-server consul acl policy list查看策略规则docker exec consul-server consul acl policy read -name 策略名带Token访问服务列表curl -H X-Consul-Token: SecretID localhost:8500/v1/catalog/services模拟非法注册curl -X PUT localhost:8500/v1/agent/service/register -d {}写在最后我在实际跑完这轮部署之后的体会是ACL的核心价值不是挡住外部攻击而是在默认不信任的基础上把每一次访问都变成显式的授权行为。Docker让Consul的部署变得极其轻量但也容易让人忽略权限配置一旦跳过ACL后续补权限的成本远比一开始就配上要高。建议所有用Consul做服务发现的团队无论规模大小都至少在容器启动阶段就把ACL打开然后把管理Token放进密钥管理或本地限权文件业务服务统一通过Token访问。一个小提醒每次docker exec执行ACL相关命令时记得先export CONSUL_HTTP_TOKENSecretID这个环境变量能让你少打很多次重复的Token参数。希望这套流程能帮你少踩几个坑。
Docker部署Consul后，ACL权限配置实战指南
先说结论用Docker部署Consul不是难点难的是把ACL权限控制一次性配明白。很多人在本地随便跑一个docker run consul就当开发环境用了等服务一上生产才发现没有ACL的Consul等于裸奔谁拿到8500端口都能读写你的配置、踢掉你的服务注册。这篇文章把我最近一次在Docker环境里从零创建Consul并加上ACL权限控制的完整过程整理出来包括设计思路、Docker参数解析、ACL初始化流程、客户端接入验证还有几个我踩过之后觉得必须写下来的坑。适合正在上手Consul、或者已经跑起来但还没加ACL的同学照着操作一遍就能跑通。1. 整体设计思路为什么要给Consul加ACL1.1 没有ACL的Consul有多危险Consul在微服务体系里扮演服务注册中心加配置中心的角色它存储的是“哪个服务在哪个地址、端口、健康状态是什么、配置项的值是多少”这类基础设施元数据。如果你把它暴露在没有防护的网络里别人可以顺手做三件事直接读KV存储把数据库地址、Redis密码、各种业务配置全部打包带走调用PUT /v1/agent/service/register伪造一个服务实例把流量引到恶意地址上调用leave或者批量反注册接口让整个服务发现链路瞬间塌掉。这些操作不需要多高深的技术一个curl命令就够了。我在第一次给Consul加ACL之前一直觉得“反正只在内网用没有什么风险”后来做安全审计的时候才意识到纯内网的默认信任模型在容器化环境里根本不成立一个被攻破的旁路容器就可能直接打到Consul的未授权接口。1.2 ACL模型与Docker部署的配合方式Consul的ACL体系在1.4版本之后全面升级成以Token为中心的模型。每个Token挂载一个或多个PolicyPolicy里面写规则规则针对service、node、key、agent、session、event等资源定义read、write、deny操作。理解起来其实很像文件权限Token是你登录用的身份Policy是你分配到的角色Rule是角色里具体的权限描述。ACL有两种工作模式默认允许default allow和默认拒绝default deny。开发环境图省事可以用默认允许但生产环境几乎都是默认拒绝——没写规则就拒绝访问然后通过匿名Token和专门创建的Token放行特定资源。这在Docker部署里反而简单只要在配置文件里把acl.enabled打开再设置acl.default_policy denyConsul不管是以容器还是二进制方式跑行为完全一致。后面所有初始化操作都跑在容器内部数据写进挂载好的/consul/data目录重启不丢配置。1.3 方案选型的关键决策在这个项目里我做了几个决策先说清楚为什么免得你照搬后发现版本不同踩坑镜像选择hashicorp/consul:1.18.2而不是latest。latest的坑在于每次拉取版本可能都不一样ACL在1.15和1.18的细节略有差异固定版本号能保证你看到的命令行为和我一致端口只暴露8500给外部访问8600DNS接口保持容器内部可用就行不一定要映射出去8300、8301、8302这些端口是Server间通信用的单节点部署情况下完全没必要暴露到宿主机数据卷挂载/consul/data而不是整个/consul目录。/consul下除了data还有config如果整个挂载会导致容器内配置文件路径混乱除非你特意做多层挂载否则保持最小化挂载是最稳妥的。2. Docker环境准备与基础部署2.1 准备Docker环境与镜像宿主机Docker版本建议不低于20.10太老的版本在端口映射和容器网络方面的行为有差异。我当前用的是Ubuntu 22.04 Docker 24.0.7Docker Compose v2可用可不用单节点Consul用docker run就够干净了。拉取镜像时注意如果服务器在国内镜像源下载可能慢可以提前配置镜像加速器。不过Consul镜像大概几十MB只要网络不算太差直接拉取能接受docker pull hashicorp/consul:1.18.2拉取完可以顺手确认一下镜像信息docker image inspect hashicorp/consul:1.18.2 --format {{.Os}} {{.Architecture}}输出正常显示linux amd64或者linux arm64就可以继续了。2.2 数据目录与配置目录准备先规划好宿主机上的目录结构。我习惯这样建mkdir -p /opt/consul/data mkdir -p /opt/consul/config/opt/consul/data是数据持久化目录容器内部会映射为/consul/data。之所以单独划出来是因为Consul的Raft状态文件、服务注册快照、KV存储全部写在这里容器删了重建不影响数据。/opt/consul/config用来放ACL配置等JSON文件映射到容器内部的/consul/configConsul启动时会自动读取这个目录下所有.json和.hcl格式的配置。在config目录里新建一个acl.json{ acl: { enabled: true, default_policy: deny, enable_token_persistence: true } }这里重点解释一下三项配置“enabled”是总开关没它什么都白搭“default_policy”设为deny表示没Token或者Token没有匹配权限时所有请求一律拒绝enable_token_persistence是让节点把Token持久化在本地Agent重启之后Token还在省去每次重启都要重新读取配置的麻烦。 提示对于全新部署这样直接启用ACL没问题。如果Consul已经跑了一段时间且里面已经有服务在注册直接开ACL要注意数据兼容问题后面第五节细说。2.3 启动Consul容器并验证基础状态配置文件和目录都准备好后执行启动命令docker run -d \ --name consul-server \ --restartalways \ -p 8500:8500 \ -p 8600:8600/udp \ -v /opt/consul/data:/consul/data \ -v /opt/consul/config:/consul/config \ hashicorp/consul:1.18.2 \ agent -server -bootstrap-expect1 -ui -client0.0.0.0 -data-dir/consul/data参数逐个说--name consul-server给容器起固定名称后面进容器执行命令方便--restartalways让Docker守护进程在容器崩溃或宿主机重启后自动拉起节点对注册中心这种基础设施服务几乎是必选项-p 8500:8500暴露HTTP API和UI端口-p 8600:8600/udp暴露DNS接口-v /opt/consul/data:/consul/data数据持久化-v /opt/consul/config:/consul/config将外部的ACL配置注入容器agent -server表示以Server模式启动-bootstrap-expect1表示单节点环境允许自己选举为Leader-ui开启内置Web界面-client0.0.0.0让客户端接口监听所有网卡这样外部才能通过8500访问-data-dir/consul/data指定数据目录。启动后先别急着访问UI等几秒让Leader选举完成再通过容器日志确认状态docker logs consul-server --tail 20正常应该能看到类似 “Leader election complete” 或者 “Adding server” 之类的日志。接着访问http://localhost:8500/ui如果看到Consul的Web界面但界面里的服务列表、KV页面等操作全部被拒绝或提示无权限这就说明ACL已经生效了。此刻正是预期状态——UI还能打开但所有数据都会报Permission denied因为没有携带Token。3. ACL配置关键流程从初始化Token到策略分配3.1 Bootstrap初始化获取管理Token启用了ACL之后第一个要做的事是生成初始的Token也就是bootstrap token。只有完成bootstrapConsul才会产生默认的management策略和管理员Token。注意这个操作只能成功一次一旦生成下次再执行会直接报错所以拿到Token后务必第一时间备份。进容器里执行docker exec -it consul-server consul acl bootstrap输出结果类似AccessorID: 6b1f2f1d-....-.... SecretID: 7f4f3e1a-....-.... Namespace: default Description: Bootstrap Token Policies: global-managementSecretID是你真正需要保存的密钥它就是管理员身份。建议立刻执行echo 7f4f3e1a-....-.... /opt/consul/bootstrap.token chmod 600 /opt/consul/bootstrap.token这个Token一旦丢失没有任何办法找回只能清空数据目录重建整个集群。把Token存成文件配合chmod 600限权是我目前试下来最简单又相对安全的方式。用这个Token验证一下当前ACL状态curl -H X-Consul-Token: 7f4f3e1a-....-.... http://localhost:8500/v1/acl/tokens能返回Token列表说明管理员身份可用。 注意bootstrap前确保数据目录是空的或者Consul从启动起就是ACL enabled状态。如果之前以无ACL模式运行过且写入了数据bootstrap时可能出现“Unexpected response code: 403”的坑后面专门讲。3.2 配置匿名Token与默认放行策略管理Token能做的只是让管理员进系统Consul服务发现场景里还有两类流量需要处理一是Consul集群内部节点间的交互二是未登录状态下对部分基础数据的读取。对于大多数中小型部署建议给匿名Token设置一组最小权限让任何人未带Token都能读取服务列表和节点列表但禁止修改。这样业务系统查询服务地址时不用带Token体验顺滑同时写操作完全被堵死。先把匿名Token的ID查出来docker exec -it consul-server consul acl token list输出里anonymous这一行的AccessorID就是匿名Token的ID通常就是00000000-0000-0000-0000-000000000002。然后创建一个只读策略绑定到匿名Token上docker exec -it consul-server consul acl policy create \ -name global-readonly \ -rules node_prefix { policy read } service_prefix { policy read } key_prefix { policy read }这里node_prefix 、service_prefix 、key_prefix 三个规则都声明对所有节点、服务、KV键路径执行read也就是全局只读。接着把策略绑定给匿名Tokendocker exec -it consul-server consul acl token update \ -id 00000000-0000-0000-0000-000000000002 \ -policy-name global-readonly更新完试试不带Token访问curl http://localhost:8500/v1/catalog/services如果正常返回JSON服务列表说明全局只读策略已经生效再试写操作curl -X PUT http://localhost:8500/v1/kv/test -d hello这条命令应该被拒绝返回Permission denied这样就形成了“可读不可写”的基线状态。对只做服务发现的集群来说这种配置在安全和便利之间平衡得比较好。3.3 为服务和Agent创建专属Token只读策略能解决查询问题但业务服务还要能注册自己。如果一个服务都能被任意注册等于伪造流量的大门是敞开的所以给每个服务分配独立Token才是最标准的做法。Consul提供了service-identity参数它自动生成一条规则只允许操作匹配的服务名。比如为名为web的服务创建注册Tokendocker exec -it consul-server consul acl token create \ -service-identityweb:dc1 \ -description token for web serviceweb:dc1前面的web是服务名后面的dc1是数据中心名。执行完后输出中会有SecretID记录下来给业务服务使用。服务注册时在HTTP请求头里带上Tokencurl -H X-Consul-Token: web服务的SecretID \ -X PUT \ -d {ID:web-1,Name:web,Address:10.0.0.10,Port:8080} \ http://localhost:8500/v1/agent/service/register这样这个Token只能注册和反注册名字叫web的服务干不了别的。同样Agent的操作也得有Token。因为Consul节点本身在注册、健康检查、同步时会调用/v1/agent/*接口需要定义一个带agent权限的策略。创建node-write策略docker exec -it consul-server consul acl policy create \ -name node-write \ -rules node_prefix { policy write } service_prefix { policy write }再针对本节点绑定Tokendocker exec -it consul-server consul acl token create \ -node-identitynode1:dc1 \ -description token for consul server nodenode-identity跟service-identity同理简化了节点注册的权限控制。如果有agent加入集群把对应Token配置到它的配置文件的acl.tokens.agent字段即可。3.4 配置持久化与UI登录容器里创建的Token默认存在内存里虽然配置了enable_token_persistence但更稳妥的做法是把管理Token写进Consul配置避免重启后成员Token丢失导致的连锁问题。在/opt/consul/config/token.json里加入{ acl: { tokens: { master: 7f4f3e1a-....-.... } } }坑我一开始用的是acl.tokens.agent字段它在某些版本里只影响Agent级别的操作HTTP API读取服务列表还是需要请求头带Token。真正让Consul内部及该节点拥有全局管理能力的是acl.tokens.master。配好之后重启容器让配置生效docker restart consul-server重启后打开http://localhost:8500/ui在登录框里输入管理Token或任意有效Token就能看到Web界面正常展示节点、服务、KV。如果输入的是全局只读Token则能看到数据但不能修改。4. HTTP API接入验证与客户端配置4.1 API访问验证矩阵ACL加完不能只看本地curl要把整个访问链路按“带Token / 不带Token / 不同Token”分别验证一遍。我在项目里建了一个验证矩阵全部跑通了才意识到配置没有遗漏场景请求方式预期结果查询服务列表不带Token成功匿名只读策略查询KV不带Token成功匿名只读策略注册新服务不带Token403拒绝写KV不带Token403拒绝注册web服务带web专用Token成功注册mysql服务带web专用Token403拒绝删除web服务不带Token403拒绝删除web服务带web专用Token成功把这些请求用脚本批量跑一遍比肉眼观察界面好用得多。4.2 服务注册与发现的完整示例假设我有个Java应用需要注册到Consul在Spring Cloud Consul里配置Token最常见的方式是通过bootstrap.yml指定spring: cloud: consul: host: 127.0.0.1 port: 8500 discovery: register: true service-name: web instance-id: web-1 # 这里配置服务注册Token # 不写这个字段容器启动后会报 403 # token: web服务的SecretIDConsul Client类库在注册时会把Token加到X-Consul-Token头里因此服务注册逻辑无需额外编码但前提是给它的Token权限与服务名匹配。如果报403先检查Token的service-identity与配置里的spring.application.name是否一致。对于直接用HTTP API的Python脚本Token需要在请求头里显式写import requests headers {X-Consul-Token: web服务的SecretID} resp requests.put( http://127.0.0.1:8500/v1/agent/service/register, headersheaders, json{ID: web-1, Name: web, Address: 10.0.0.10, Port: 8080} ) print(resp.status_code)大多数语言的Consul客户端库都支持Token配置项比如Go的consul/api库在Config.Token字段里设置即可。4.3 健康检查与DNS查询在ACL下的表现加了ACL之后健康检查和DNS接口的行为值得单独提一下。健康检查会由Agent代表服务发出通常不需要显式带Token但Agent自身需要执行agent相关权限。如果不给Agent配置Token你会看到Consul日志里持续刷出 “Permission denied: agent master token is required” 之类的错误。所以上一节里创建一个node-write或agent权限的Token给Agent是必须的不只是接入方便的问题。DNS查询则不受ACL默认拒绝的影响。DNS接口对于匿名查询通常只返回已经注册过的服务记录而且它只暴露IP和端口不暴露KV配置数据。我在实际使用中保持内部服务通过DNS方式访问外部系统则走带Token的HTTP API两边都正常。如果发现通过DNS查不到某服务先确认服务注册时的Token身份是否有效以及服务健康检查是否为passing状态。ACL通常不会直接导致“服务不存在”但Token没注册成功会导致服务根本没写进目录表现结果看起来像DNS查不到。5. 常见问题与排查技巧实录5.1 初始化失败Unexpected response code: 403这是我自己当时卡得最久的问题也看到很多人问。起因是我第一次启动容器时忘了加ACL配置等服务注册了一批数据后又想通过配置开启ACL结果执行consul acl bootstrap时提示403。原因在于Consul一旦在无ACL模式下运行过内部已经形成了一种“无Token即全权限”的状态。数据目录里有旧的Raft日志切换ACL后旧的日志不会自动给所有人分配身份bootstrap操作会被判定为没有权限。解决办法有两个如果业务数据不重要像我这样直接清掉数据目录重建如果数据不能丢需要开启一个临时过程先在配置里设置acl.enabled true但保持acl.default_policy allow然后bootstrap获取管理Token再把default_policy改成deny最后重启。这个过程也要小心中间状态等于未授权访问仍然开放所以尽量在维护窗口操作。我当时数据还没上线直接执行了清理docker stop consul-server rm -rf /opt/consul/data/* docker start consul-server接着在容器里重新bootstrap问题解决。5.2 UI能打开但所有操作报错UI能打开说明端口和Web服务正常所有操作报权限错误说明ACL已生效但你还没登录或者说没把Token传给UI。新版Consul UI在ACL启用后会要求输入Token输入管理Token就能看到全部数据。如果没有登录框可能是浏览器缓存了旧页面清理缓存或强制刷新CtrlShiftR即可。如果输入Token后仍然报错检查Token是否过期。Consul Token默认没有过期时间但如果你在创建Token时加了-validity-period参数超过这个时间Token就会自动失效。普通场景不建议设置有效期除非你有轮换机制。5.3 容器重启后Token丢失明明创建了Token容器一重启Token就消失所有请求重新403。这个坑的本质是Token没有持久化。两个层面分别排查一是确认启动配置挂了enable_token_persistence这个配置还可能需要配合-data-dir才能生效数据目录就是/consul/data二是Token是运行时通过API创建的没有写入配置文件。Consul只在节点本身持久化由Agent发起的Token而通过API创建的业务Token在重启后会有不一致的表现。稳妥做法是把Token固化到配置文件里见前面3.4节的acl.tokens.master方式。业务Token则建议服务启动时从配置中心或环境变量注入不要让Container重建后再手动补Token。5.4 策略匹配与服务名大小写问题Consul的service-identity规则是精确匹配的。如果服务注册时的Name是WebToken创建时用的却是web权限会匹配失败。我踩过一次业务侧服务名带了环境后缀web-staging而策略只写了web排查半天日志才发现是规则前缀不匹配导致403。遇到这类问题用consul acl policy list和consul acl token read -self查看实际生效的策略比在日志里猜快得多。如果实在找不到原因把web的规则写成service web-staging / web这种多段形式也不要偷懒给所有服务开全局写权限否则ACL形同虚设。5.5 快速排查命令速查最后把这次排查用到的命令整理成速查表省得每次翻文档需求命令查看所有Tokendocker exec consul-server consul acl token list查看Token详情docker exec consul-server consul acl token read -id AccessorID查看所有策略docker exec consul-server consul acl policy list查看策略规则docker exec consul-server consul acl policy read -name 策略名带Token访问服务列表curl -H X-Consul-Token: SecretID localhost:8500/v1/catalog/services模拟非法注册curl -X PUT localhost:8500/v1/agent/service/register -d {}写在最后我在实际跑完这轮部署之后的体会是ACL的核心价值不是挡住外部攻击而是在默认不信任的基础上把每一次访问都变成显式的授权行为。Docker让Consul的部署变得极其轻量但也容易让人忽略权限配置一旦跳过ACL后续补权限的成本远比一开始就配上要高。建议所有用Consul做服务发现的团队无论规模大小都至少在容器启动阶段就把ACL打开然后把管理Token放进密钥管理或本地限权文件业务服务统一通过Token访问。一个小提醒每次docker exec执行ACL相关命令时记得先export CONSUL_HTTP_TOKENSecretID这个环境变量能让你少打很多次重复的Token参数。希望这套流程能帮你少踩几个坑。
