1. SpringBlade 初次搭建为什么卡在鉴权与网关配置
SpringBlade 是一套基于 Spring Cloud 的企业级微服务开发平台，后端用 Spring Boot 2.7 + Spring Cloud 2021 + MyBatis 组合，前端提供 React（Sword）和 Vue（Saber）两套框架。它把注册中心、配置中心统一交给 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_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_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_source=taotoken_aicg_blog_end&utm_content=api_keys&utm_campaign=rewrite 。拿到 Key 之后先别急着写进代码，建议放到环境变量或者 Nacos 配置里，避免硬编码。模型对话的调试入口在 https://taotoken.net/models?utm_source=taotoken_aicg_blog_end&utm_content=models&utm_campaign=rewrite ，你可以先用它验证 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: - StripPrefix=1 - id: blade-system uri: lb://blade-system predicates: - Path=/blade-system/** filters: - StripPrefix=1 - id: blade-user uri: lb://blade-user predicates: - Path=/blade-user/** filters: - StripPrefix=1上面这段配了三条路由，分别指向授权服务、系统服务和用户服务。lb://表示从注册中心负载均衡，StripPrefix=1表示转发时去掉第一层路径。比如你请求/blade-system/user/info，网关会转发到blade-system服务的/user/info。
接下来是鉴权白名单，SpringBlade 用blade.secure.skip-url来配置不需要鉴权的路径。这个配置通常放在 Nacos 的公共配置里，本地调试可以写在blade-gateway的application.yml：
blade: 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/api，api-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 'username=admin' \ -d 'password=admin' \ -d 'grant_type=password' \ -d 'scope=all'注意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_source=taotoken_aicg_blog_end&utm_content=models&utm_campaign=rewrite 。在 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-system，lb不能漏。
reading choices：这个报错通常和模型调用相关，出现在解析通道返回结果时。原因是返回的 JSON 结构和预期不一致，可能是model-id填错了，或者通道返回了错误信息。排查时先把请求打到模型对话入口，确认 Key 和 Model ID 可用，再回来看 SpringBlade 里的配置。如果用的是 Cline MCP 或 Codex，检查auth.json或 settings 里的三件套是否完整。
OAuth 相关报错：比如invalid_grant、unauthorized_client。这类报错多半是登录参数不对，检查grant_type是不是password，scope是不是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_source=taotoken_aicg_blog_end&utm_content=coding_plan&utm_campaign=rewrite ，如果你的项目需要持续调用模型，可以了解一下。接入文档在 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite ，里面有各语言的接入示例。
Claude Code 这类工具如果需要接入，配置逻辑和前面说的一样，Base URL、Key、Model ID 三件套配全就行。SpringBlade 本身不依赖这些工具，但如果你在开发过程中用它们辅助编码，配置方式是一致的。
最后提醒一点：生产环境一定要改掉默认的sign-key和默认密码，租户 ID 也不要直接用000000。这些默认值在开发阶段方便，上线前必须替换。鉴权链路的安全性，很大程度上取决于这些基础配置有没有改到位。
跑通这条链路之后，你会发现 SpringBlade 的分包设计和统一鉴权思路其实很省心。前期配置花点时间，后面加业务模块就是复制粘贴的事。遇到问题先看日志，再对照路由和鉴权两处配置，大部分坑都能自己填上。
