配置职责、生效条件与扩展边界

本章介绍 tio-boot-admin 的内置配置，解释 入门指南 中七个配置调用。新项目应优先使用这些内置配置，只为明确的业务需求增加扩展。

1. 七个配置类分别做什么

因此可以保留完整的标准调用序列，而只配置当前使用的数据源。这里的“按需启用”需要准确理解：数据库连接是否建立由对应连接项控制，路由和拦截器的注册由配置调用完成，具体业务功能还依赖对应服务和表。

不要自行发明 redis.enabled、mongodb.enabled、admin.enabled 等属性；上述配置类没有读取这些开关。不要把“未配置外部服务”误写为“所有相关路由都不会注册”。

2. 只使用 PostgreSQL

jdbc.url=jdbc:postgresql://127.0.0.1:5432/defaultdb
jdbc.user=postgres
jdbc.MaximumPoolSize=5
jdbc.showSql=false

密码放在本地秘密配置或 JDBC_PSWD 环境变量中。保持 Redis 和 MongoDB 的 host 配置项不存在，相应配置调用会直接返回，不要求这两个服务运行。

框架通过 EnvUtils 读取有效配置。若仍尝试连接未使用的服务，应检查环境变量、JVM 参数、命令行参数、app-*.properties 以及本地 .env、secrets.txt、my.txt 是否提供了 host，而不只是检查当前打开的配置文件。

不要使用空字符串关闭数据源。 当前判断是 null，空字符串仍会进入初始化分支。

TioAdminDbConfiguration 初始化连接池与 ActiveRecord，不负责执行建表 SQL 或初始化管理员。所有初始化步骤见 02.md，由用户手动执行。连接配置和静态 Db 使用见 整合数据库。

3. 按需启用 Redis 或 MongoDB

Redis 示例，确认服务和客户端依赖可用后添加：

redis.host=127.0.0.1
redis.port=6379
redis.database=0
redis.cacheName=main

有密码时再通过秘密配置提供 redis.password。redis.timeout 默认值为 60 毫秒，直接传给 Jedis 连接池；可显式配置为 2000。完整依赖、连接配置和读写示例见 整合 Redis。

MongoDB 示例：

mongodb.host=127.0.0.1
mongodb.port=27017
mongodb.authSource=admin
mongodb.username=replace-with-username
mongodb.database=replace-with-database

通过秘密配置提供 mongodb.password。本版本配置类会创建认证信息，配置 host 后需要补齐相关认证项，不能把这个示例当作无认证连接方式。

运行时依赖与服务开关

“没有 host 就不连接”不等于 Maven 会自动补齐客户端 JAR。启用对应功能时，需要检查上游 provided 依赖并在业务工程中显式声明。

以当前框架 POM 为参照：

如遇 ClassNotFoundException / NoClassDefFoundError，先核对运行时依赖与框架版本；不要以重写全部配置类作为解决方式。未启用的服务无需额外部署。

4. 默认鉴权与 Sa-Token 的关系

当前默认链路是：

TioAdminHandlerConfiguration
  → AdminLoginHandler：登录并生成 JWT

TioAdminInterceptorConfiguration
  → UserTokenInterceptor
  → TioBootAdminTokenPredicate：验证 Token 并提供用户 ID

• app.admin.secret.key 是默认 JWT 签名与验证使用的密钥。
• app.admin.token 是框架可选的固定管理 Token；它不是普通管理员登录的必填项。不使用时不配置。
• 默认放行路径来自 TioBootAdminUrls.ALLLOW_URLS，静态文件默认允许放行；需要额外规则时使用框架提供的构造参数。
• 默认配置不要求集成 Sa-Token，也不要求新建 Sa-Token 表、管理员会话表或自行实现 ITokenStorage。
• 17.md：历史 Token 存储方案 仅供有明确兼容需求的旧项目参考，不属于默认接入流程。

不要把登录状态记录和 JWT 校验混为一谈。当前默认 Token 判断主要验证签名和有效期，并不读取额外的持久化会话表；不能据此承诺“退出立即撤销所有旧 JWT”或“自动完成每个业务操作的角色权限校验”。如果项目明确需要这些行为，应作为独立需求使用扩展点实现，不作为所有新项目的必装代码。

已有 HttpInteceptorConfigure，还需要后台拦截器配置吗？

HttpInteceptorConfigure 是拦截器模型的容器；创建并设置该对象，不会自动注册后台 Token 校验。TioAdminInterceptorConfiguration.config() 会复用已有容器（不存在时才创建），向其中加入名为 tio-admin-token 的 UserTokenInterceptor，并设置后台 Token 验证逻辑与放行规则。因此，是否调用该配置类，应根据已有的鉴权规则判断，不能只看容器是否非空。

米旺的配置保留以下调用：

new TioAdminInterceptorConfiguration(new String[] { "/api/mi/**" }).config();
new MiBusinessConfiguration().config();

其中 MiBusinessConfiguration 是米旺应用自己的配置类，向同一个容器追加业务拦截器，只匹配 /api/mi/**。后台配置负责默认保护范围内的其他接口，包括 ApiTable；额外放行业务前缀，是让业务拦截器执行自己的公开、登录用户和管理员规则。仅因为已经有业务拦截器就删除上述后台配置，会移除这层后台 Token 校验。

扩展时应获取已有容器并追加模型，不要再设置一个只包含业务拦截器的新容器，否则会覆盖已注册的后台拦截器。

额外放行路由

在原来的配置位置，替换一次拦截器配置调用即可：

new TioAdminInterceptorConfiguration(new String[] {"/health"}).config();

放行只调整访问规则，不会创建 /health 的 Handler；业务仍需注册该路由。

如果为自定义 H5 / 小程序业务接口放行整个前缀，必须先在匹配后的业务拦截器实现独立鉴权，并逐个声明公开、登录用户、管理员权限。放行只表示跳过这一层后台拦截器，不代表业务接口可以匿名访问。不要把 /api/table/** 一并放行。完整边界与验证方法见 业务 API 与 H5 / 小程序联调。

框架还提供接收 TokenPredicate 的构造方法，用于明确需要自定义认证的场景。不要先调用默认配置，再额外安装一套重复拦截器。

5. Handler 与 ApiTable 不要重复注册

TioAdminHandlerConfiguration 已注册常用路由，例如：

无需把这些路由复制到业务工程中逐个注册。邮件、Google 登录等路由被注册，不代表外部服务已就绪，也不代表数据库表会自动创建。

TioAdminControllerConfiguration 已包含 ApiTableController，主要路由如下：

表格内缩写路径的前缀同为 /api/table/{f}，{f} 是数据库表名。创建记录通常不传 id，由 ApiTable 生成；传入 id 会影响保存或更新的判断。应按前端组件的接口约定使用，不要另写一套同路径接口。

这套接口用于方便对接后台前端的 ApiTable 组件，见 05.md。业务数据库表仍由用户手动准备。面向普通用户的 H5 / 小程序接口，按其业务授权要求单独设计。

6. 扩展与排查

配置扩展行为

管理员拦截器以稳定名称 tio-admin-token 合并到已有 HttpInteceptorConfigure；不再覆盖其他业务拦截器。未命名模型会生成独立名称。方法路由 metadata 与 doBeforeRoute 的用法见 升级指南。

Db 配置支持可选 jdbc.connectionInitSql，用于连接池建立连接时的会话设置，例如固定时区；不要用于自动建表。数据库访问直接调用静态 Db，复用已初始化的默认配置，见 PostgreSQL 实践。

Elasticsearch 连接

通过 elasticsearch.rest.urls 配置单个节点地址，可选配置用户名与密码，再调用 new TioAdminElasticsearchConfig().config()。完整示例见 整合 Elasticsearch。