1. SpringBlade 初次搭建为什么卡在鉴权与网关配置SpringBlade 是一套基于 Spring Cloud 的企业级微服务开发平台后端用 Spring Boot 2.7 Spring Cloud 2021 MyBatis 组合前端提供 ReactSword和 VueSaber两套框架。它把注册中心、配置中心统一交给 Nacos网关层用 Spring Cloud Gateway 做路由转发鉴权则借鉴 OAuth2 思路、用 JWT 做 Token 认证再配合 Secure 模块做权限隔离。对刚接触这套平台的开发者来说真正让人卡住的往往不是业务代码而是「请求怎么从网关进来、怎么被鉴权、怎么转发到具体服务」这条基础链路。我自己第一次跑 SpringBlade 的时候前端登录页能打开但一调接口就返回 401或者网关直接报找不到路由。排查半天才发现问题集中在两个地方一是blade-gateway的路由规则没配对二是blade-auth的鉴权参数和 Token 签发没打通。SpringBlade 的工程结构分得很细blade-auth负责授权服务blade-gateway负责网关blade-service下面是各业务模块blade-service-api放各模块的 API 封装。这种分包方式很规范但对新手来说第一次要同时理解 Nacos 注册、网关路由、JWT 鉴权三件事确实容易乱。这篇笔记就聚焦「初次搭建时的鉴权与网关配置」这个环节给你可复制的网关路由片段和鉴权参数配置再演示一次接口调用验证确认请求能正常通过统一通道完成鉴权。目标很明确让你快速跑通平台基础链路而不是一上来就陷进源码里。如果你之前搭过 Spring Cloud 项目会发现 SpringBlade 的思路并不陌生只是它把很多细节封装进了 BladeTool你需要知道去哪里改配置、改完怎么验证。在动手之前先理清一个概念SpringBlade 的鉴权不是每个微服务各自做而是统一在网关层和授权服务之间完成。客户端拿到的 Token 由blade-auth签发网关负责校验并放行业务服务默认信任网关传来的身份信息。所以配置的重点就落在网关路由和鉴权白名单上。理解了这条主线后面的配置就不会觉得零散。2. 接入前的准备TaoToken 通道与 SpringBlade 鉴权参数怎么对齐在改配置之前需要先明确一件事SpringBlade 的鉴权链路要有一个统一的请求通道所有 Token 校验和模型调用都走这个通道。这里我用 TaoToken 作为统一接入通道来演示它的官网是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 地址是 https://taotoken.net/api 。你需要在控制台创建一个 API Key后面配置里会用到。为什么要在 SpringBlade 里接这个通道因为很多团队在微服务里会同时用到鉴权服务和模型能力如果每个服务各自配一套地址和 Key维护起来很痛苦。统一走一个通道网关层做一次鉴权业务层直接复用链路清晰。TaoToken 在这里扮演的就是「统一入口」的角色Base URL、Key、Model ID 三件套配好后面不管是鉴权校验还是模型调用都从这一个口子走。具体到 SpringBlade你需要关注三个配置位置。第一是blade-gateway的application.yml里面配路由和鉴权白名单第二是blade-auth的application.yml里面配 Token 签发参数和通道地址第三是 Nacos 里的公共配置SpringBlade 默认会把一些共享配置放到 Nacos 的blade命名空间下。如果你本地启动先确认 Nacos 已经跑起来并且blade-gateway、blade-auth都注册上去了。创建 Key 的入口在控制台的 API Keys 页面地址是 https://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite 。拿到 Key 之后先别急着写进代码建议放到环境变量或者 Nacos 配置里避免硬编码。模型对话的调试入口在 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 你可以先用它验证 Key 是否可用再去配 SpringBlade。这里有个容易忽略的点SpringBlade 的鉴权参数里blade.token.sign-key和blade.token.expire是控制 JWT 签发和过期的而通道地址是控制请求往哪发的。两者不要混在一起改。我建议先把通道地址和 Key 配好确认能通再去调 Token 过期时间。顺序反了排查起来会互相干扰。另外SpringBlade 默认的鉴权白名单里包含登录、验证码等接口这些不需要 Token 就能访问。你要做的是把需要鉴权的业务接口路径加到网关的鉴权规则里同时确保blade-auth签发的 Token 能被网关正确解析。这一步对齐了后面的接口调用验证才有意义。3. 可复制的网关路由与鉴权配置片段这一节给你可以直接抄的配置。先看blade-gateway的application.yml重点是路由和鉴权白名单两部分。SpringBlade 的网关基于 Spring Cloud Gateway路由配置支持从 Nacos 动态加载但本地调试时写在application.yml里更直观。spring: cloud: gateway: discovery: locator: enabled: true routes: - id: blade-auth uri: lb://blade-auth predicates: - Path/blade-auth/** filters: - StripPrefix1 - id: blade-system uri: lb://blade-system predicates: - Path/blade-system/** filters: - StripPrefix1 - id: blade-user uri: lb://blade-user predicates: - Path/blade-user/** filters: - StripPrefix1上面这段配了三条路由分别指向授权服务、系统服务和用户服务。lb://表示从注册中心负载均衡StripPrefix1表示转发时去掉第一层路径。比如你请求/blade-system/user/info网关会转发到blade-system服务的/user/info。接下来是鉴权白名单SpringBlade 用blade.secure.skip-url来配置不需要鉴权的路径。这个配置通常放在 Nacos 的公共配置里本地调试可以写在blade-gateway的application.ymlblade: secure: skip-url: - /blade-auth/oauth/token - /blade-auth/oauth/captcha - /blade-auth/oauth/logout - /actuator/** - /v2/api-docs/**这几个路径是登录、验证码、登出和健康检查必须放行否则你连 Token 都拿不到。注意/blade-auth/oauth/token是获取 Token 的入口如果它被拦了后面所有鉴权都无从谈起。然后是blade-auth的通道配置。这里配的是统一通道的 Base URL 和 Key以及 Token 签发参数blade: token: sign-key: bladexisasecretkey expire: 7200 tao: base-url: https://taotoken.net/api api-key: ${TAO_TOKEN_API_KEY:your-api-key-here} model-id: your-model-idsign-key是 JWT 签名密钥生产环境一定要改掉默认值。expire是 Token 过期时间单位秒7200 就是两小时。tao这一段是统一通道配置base-url固定为https://taotoken.net/apiapi-key建议用环境变量注入model-id填你在控制台选定的模型 ID。如果你用的是 Cline MCP 或者 Codex 这类工具配置格式会不一样但三件套不变Base URL、Key、Model ID。比如 Codex 的auth.json里要写全这三个字段Cline MCP 的 settings 里也是同样的三件套。SpringBlade 这边虽然不直接用这些工具但配置逻辑是一致的先对齐三件套再谈其他。配置改完之后重启blade-gateway和blade-auth观察日志里有没有路由加载成功、Nacos 注册成功的提示。如果网关启动时报local proxy failed多半是路由的uri写错了或者目标服务没注册到 Nacos。这时候先去 Nacos 控制台看服务列表确认blade-auth、blade-system都在。4. 验证请求一次接口调用确认鉴权链路通了配置写完最关键的一步是验证。我习惯先用 curl 拿 Token再带着 Token 调业务接口这样能清楚看到每一步的结果。第一步获取 Token。SpringBlade 的登录接口是/blade-auth/oauth/token用 POST 请求参数包括租户 ID、用户名、密码、授权类型等。下面是一个可复制的 curl 示例curl -X POST http://localhost:8080/blade-auth/oauth/token \ -H Content-Type: application/x-www-form-urlencoded \ -H Tenant-Id: 000000 \ -d usernameadmin \ -d passwordadmin \ -d grant_typepassword \ -d scopeall注意Tenant-Id这个请求头SpringBlade 是多租户设计默认租户 ID 是000000。如果这个头没带或者租户 ID 不对会返回租户不存在的错误。请求成功后你会拿到一个 JSON里面有access_token、refresh_token、expires_in等字段。把access_token复制出来下一步要用。第二步带着 Token 调业务接口。比如查当前用户信息curl -X GET http://localhost:8080/blade-system/user/info \ -H Authorization: Bearer 你的access_token \ -H Tenant-Id: 000000如果配置正确你会看到用户信息的 JSON 返回。如果返回 401说明网关没认这个 Token可能是sign-key不一致或者 Token 过期了。如果返回 404说明路由没匹配上检查Path断言和StripPrefix配置。第三步验证统一通道。你可以调一个走 TaoToken 通道的接口确认 Base URL 和 Key 生效。比如模型对话的验证可以用模型对话入口先测 Key地址是 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 。在 SpringBlade 里你可以在blade-auth里加一个测试接口调用通道的/v1/chat/completions确认返回正常。实测下来最容易出问题的是 Token 的sign-key在网关和授权服务里不一致。网关校验 Token 用的密钥必须和blade-auth签发时用的完全一样差一个字符都会 401。所以改配置时两边的sign-key要同步改。如果一切正常你会看到这样的结果登录拿到 Token带 Token 调业务接口返回数据通道调用也正常。这条链路通了SpringBlade 的基础鉴权就算跑通了。后面再往上加业务模块只需要在网关加路由、在白名单里放行登录接口即可。5. 常见报错排查401、local proxy failed、reading choices这一节把几个高频报错列出来对照着排查会快很多。401 Unauthorized这是最常见的。原因通常有三个。一是 Token 没带或者格式不对Authorization头必须是Bearer加 Token中间有空格。二是sign-key不一致网关和blade-auth的签名密钥要完全相同。三是 Token 过期默认两小时过期了要重新拿。排查时先看网关日志如果日志里打印了 Token 解析失败基本就是密钥问题。local proxy failed这个报错一般出现在网关转发阶段。意思是网关找不到目标服务或者目标服务没注册。先去 Nacos 看服务列表确认blade-system、blade-user这些服务都在。如果不在检查对应服务的 Nacos 配置和启动日志。如果服务在但网关还是报这个错检查路由的uri是不是写成了lb://blade-systemlb不能漏。reading choices这个报错通常和模型调用相关出现在解析通道返回结果时。原因是返回的 JSON 结构和预期不一致可能是model-id填错了或者通道返回了错误信息。排查时先把请求打到模型对话入口确认 Key 和 Model ID 可用再回来看 SpringBlade 里的配置。如果用的是 Cline MCP 或 Codex检查auth.json或 settings 里的三件套是否完整。OAuth 相关报错比如invalid_grant、unauthorized_client。这类报错多半是登录参数不对检查grant_type是不是passwordscope是不是all租户 ID 是否正确。SpringBlade 的 OAuth 实现借鉴了标准 OAuth2但有自己的租户逻辑参数对不上就会报这些错。连接超时如果请求一直卡住然后超时检查 Nacos 地址、数据库连接、Redis 连接。SpringBlade 依赖这些基础组件任何一个不通都会导致启动或调用失败。先确保 Nacos 能访问再启动服务。排查时有个小技巧把网关和授权服务的日志级别调到 DEBUG能看到 Token 解析和路由匹配的详细过程。SpringBlade 的日志封装得比较清晰关键信息都能找到。另外改完配置一定要重启对应服务SpringBlade 虽然支持 Nacos 动态刷新但路由和鉴权这类核心配置重启更稳妥。如果你在配置过程中遇到401和local proxy failed交替出现先解决路由问题再解决鉴权问题。路由不通鉴权根本走不到。顺序对了排查效率会高很多。6. 后续开发与统一通道的长期用法基础链路跑通之后后续开发就顺了。加一个新业务模块步骤是固定的在blade-service下建模块配好 Nacos 注册在网关加一条路由如果这个模块有不需要鉴权的接口加到白名单里。业务代码里直接用 BladeTool 封装好的工具类鉴权信息从网关透传过来不用每个服务自己解析 Token。统一通道的长期用法也值得说一下。如果你团队里多个服务都要调模型能力建议把通道配置放到 Nacos 的公共配置里各服务引用同一份配置。这样改 Key 或者换 Model ID 时只需要改一处。TaoToken 的 Coding Plan 适合长期编码和 Agent 场景入口在 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite 如果你的项目需要持续调用模型可以了解一下。接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 里面有各语言的接入示例。Claude Code 这类工具如果需要接入配置逻辑和前面说的一样Base URL、Key、Model ID 三件套配全就行。SpringBlade 本身不依赖这些工具但如果你在开发过程中用它们辅助编码配置方式是一致的。最后提醒一点生产环境一定要改掉默认的sign-key和默认密码租户 ID 也不要直接用000000。这些默认值在开发阶段方便上线前必须替换。鉴权链路的安全性很大程度上取决于这些基础配置有没有改到位。跑通这条链路之后你会发现 SpringBlade 的分包设计和统一鉴权思路其实很省心。前期配置花点时间后面加业务模块就是复制粘贴的事。遇到问题先看日志再对照路由和鉴权两处配置大部分坑都能自己填上。