入门指南：使用框架内置配置

tio-boot-admin 是基于 tio-boot 的后台管理中间层，封装了数据库配置、登录处理器、鉴权拦截器和 ApiTable 通用表接口。接入项目时，调用这些配置类，再添加项目自己的业务代码即可。

本章以 Java 21、tio-boot-admin、PostgreSQL 为例，代码使用 nexus.io 包名。依赖版本应与使用的框架源码保持一致。

接入原则

1. 使用框架已有配置。 不需要重新编写连接池、后台登录路由、Token 拦截器或 ApiTable 控制器。
2. 按连接配置启用数据源。 可以保留 Redis、MongoDB 配置类调用；不使用时不配置对应连接项。准确条件见 配置职责与生效条件。
3. 默认不集成 Sa-Token。 当前默认鉴权基于框架的 Token/JWT 实现。除非项目明确需要兼容旧系统，不添加 Sa-Token 配置、依赖或数据表。16.md 是历史可选方案，不是入门步骤。
4. SQL 由用户手动执行。 启动应用之前，按 手动初始化数据库 建表和创建管理员。应用入口和配置类不执行初始化 SQL，不自动建表、插入管理员或重置密码。
5. 保留 ApiTable 配置。 TioAdminControllerConfiguration 已注册通用表控制器，用于对接后台前端的表格、表单和导出功能。

1. Maven 工程

推荐目录：

admin-service/
├─ pom.xml
├─ .env                         # 本地密码和密钥，不提交
├─ sql/
│  └─ init-postgresql.sql        # 用户保存并手动执行的 SQL
└─ src/main/
   ├─ java/com/example/admin/
   │  ├─ AdminApplication.java
   │  └─ config/AdminAppConfig.java
   └─ resources/
      ├─ app.properties
      └─ app-dev.properties

pom.xml：

<project xmlns="http://maven.apache.org/POM/4.0.0"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
  <modelVersion>4.0.0</modelVersion>
  <groupId>com.example</groupId>
  <artifactId>admin-service</artifactId>
  <version>1.0.0</version>
  <properties>
    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    <maven.compiler.release>21</maven.compiler.release>
    <tio-boot-admin.version>2.1.5</tio-boot-admin.version>
  </properties>
  <dependencies>
    <dependency>
      <groupId>nexus.io</groupId>
      <artifactId>tio-boot-admin-web</artifactId>
      <version>${tio-boot-admin.version}</version>
    </dependency>
    <dependency>
      <groupId>org.postgresql</groupId>
      <artifactId>postgresql</artifactId>
      <version>42.5.0</version>
    </dependency>
    <dependency>
      <groupId>org.slf4j</groupId>
      <artifactId>slf4j-api</artifactId>
      <version>2.0.1</version>
    </dependency>
    <dependency>
      <groupId>com.alibaba</groupId>
      <artifactId>easyexcel</artifactId>
      <version>4.0.3</version>
    </dependency>
  </dependencies>
  <build>
    <finalName>admin-service</finalName>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-compiler-plugin</artifactId>
        <version>3.14.1</version>
        <configuration><parameters>true</parameters></configuration>
      </plugin>
      <plugin>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-maven-plugin</artifactId>
        <version>2.7.18</version>
        <configuration><mainClass>com.example.admin.AdminApplication</mainClass></configuration>
        <executions>
          <execution><goals><goal>repackage</goal></goals></execution>
        </executions>
      </plugin>
    </plugins>
  </build>
</project>

说明：

• tio-boot-admin-web 已传递依赖 tio-boot-admin-base，无需重复声明同版本的 base。
• PostgreSQL 驱动由业务工程显式引入；切换数据库时替换驱动和连接配置。
• easyexcel 用于 ApiTable 导出；上游以 provided 声明的依赖不一定进入业务项目运行时，因此此处显式引入。
• 固定 SLF4J 2.x，与框架日志实现对应，避免其他依赖引入 1.x 导致无日志。
• 此示例不使用 Lombok。业务代码需要时再添加其依赖和注解处理配置。
• spring-boot-maven-plugin 仅用于生成可执行 JAR，运行入口仍是 TioApplication，无需改用 Spring Boot 容器。
• Redis、MongoDB 等可选客户端的依赖与连接开关是两个问题，见 03.md。

2. 配置文件

src/main/resources/app.properties：

app.name=admin-service
app.env=dev
server.port=8100
server.http.response.cors.enable=true
http.response.showExceptionDetails=false
server.http.request.printUrl=false
http.multipart.max-request-size=20971520
http.multipart.max-file-size=10485760

src/main/resources/app-dev.properties：

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

在启动工作目录创建 .env，填写当前环境的真实值：

jdbc.pswd=replace-with-your-database-password
app.admin.secret.key=replace-with-your-own-random-signing-secret

把 .env、secrets.txt、my.txt 等实际用于保存凭据的本地文件加入 .gitignore。文档中的密码和密钥都是占位符，不要写入真实项目凭据。

也可以使用 JDBC_URL、JDBC_USER、JDBC_PSWD、APP_ADMIN_SECRET_KEY 等环境变量。EnvUtils 支持将配置键中的点转换为下划线再转大写；环境变量优先于属性文件。

仅使用 PostgreSQL 时，不要添加 redis.host 和 mongodb.host，也不要把它们写成空字符串。未配置与配置了空值并不等价。

3. 标准配置类

src/main/java/com/example/admin/config/AdminAppConfig.java：

package com.example.admin.config;

import nexus.io.context.BootConfiguration;
import nexus.io.tio.boot.admin.config.TioAdminControllerConfiguration;
import nexus.io.tio.boot.admin.config.TioAdminDbConfiguration;
import nexus.io.tio.boot.admin.config.TioAdminHandlerConfiguration;
import nexus.io.tio.boot.admin.config.TioAdminInterceptorConfiguration;
import nexus.io.tio.boot.admin.config.TioAdminMongoDbConfiguration;
import nexus.io.tio.boot.admin.config.TioAdminRedisDbConfiguration;

public class AdminAppConfig implements BootConfiguration {
  @Override
  public void config() {
    new TioAdminDbConfiguration().config();
    new TioAdminRedisDbConfiguration().config();
    new TioAdminMongoDbConfiguration().config();
    new TioAdminInterceptorConfiguration().config();
    new TioAdminHandlerConfiguration().config();

    configHandler();

    new TioAdminControllerConfiguration().config();
  }

  private void configHandler() {
    // 在这里注册项目自己的业务路由；不要重复注册框架已有路由。
  }
}

这六个调用已经覆盖标准后台接入。数据源配置负责连接与插件生命周期，Handler 配置负责后台和应用用户相关路由，Controller 配置负责 ApiTable。

数据库连接项缺失时，相应数据源配置直接返回；拦截器和路由配置则是注册行为。调用配置类、连接服务、接口具备完整业务能力是不同阶段，详细说明见 03.md。

即使应用已经设置 HttpInteceptorConfigure，也不能据此省略 TioAdminInterceptorConfiguration：前者是容器，后者负责注册后台 Token 校验。它会复用已有容器并保留其他拦截器；只有已注册后台鉴权或应用已完整接管后台鉴权时，才可省略该调用。业务前缀的用户鉴权不能代替后台和 ApiTable 接口的鉴权，具体边界见 配置职责与扩展边界。

通过 BootConfiguration 显式传入配置类时，不需要再给同一个配置方法添加 @AConfiguration / @Initialization 以重复初始化。

可选：补充统一云文件路由

需要上传功能时，可将上面的 configHandler() 替换为下列实现，并补齐三个 import：

import nexus.io.tio.boot.admin.handler.system.SystemCloudFileHandler;
import nexus.io.tio.boot.server.TioBootServer;
import nexus.io.tio.http.server.router.HttpRequestRouter;

private void configHandler() {
  HttpRequestRouter r = TioBootServer.me().getRequestRouter();
  if (r == null) {
    return;
  }
  SystemCloudFileHandler handler = new SystemCloudFileHandler();
  r.add("/api/system/file/cloud/upload", handler::upload);
  r.add("/api/system/file/cloud/md5", handler::getUploadRecordByMd5);
  r.add("/api/system/file/cloud/url", handler::getUrl);
}

本版本标准 Handler 配置没有自动调用内部的云文件路由注册方法，因此可以像这样补充。注册路由后，还需根据 文件上传 配置存储平台、客户端依赖和相关表；路由存在不代表云存储已经配置完成。

4. 启动类

src/main/java/com/example/admin/AdminApplication.java：

package com.example.admin;

import com.example.admin.config.AdminAppConfig;
import nexus.io.tio.boot.TioApplication;

public class AdminApplication {
  public static void main(String[] args) {
    long start = System.currentTimeMillis();
    TioApplication.run(AdminApplication.class, new AdminAppConfig(), args);
    System.out.println((System.currentTimeMillis() - start) + "(ms)");
  }
}

入口只启动应用，不加入 SQL 初始化分支、自动迁移、管理员创建或密码生成逻辑。

5. 手动初始化，然后运行

先阅读 02.md，在目标数据库中手动执行对应建表和管理员初始化 SQL。可使用数据库客户端，也可将已检查、已替换占位值的 SQL 保存为文件后执行：

psql -h 127.0.0.1 -p 5432 -U postgres -d defaultdb -W -v ON_ERROR_STOP=1 -f sql/init-postgresql.sql

然后在工程目录构建、启动：

mvn package
java -jar target/admin-service.jar

默认后端地址为 http://127.0.0.1:8100，它提供接口，不会自动生成后台前端页面。

本示例没有设置上下文路径。如果项目设置 server.context-path=/admin，下文所有外部请求地址都要加 /admin，例如 /admin/api/login/account；Java 注册路由时仍使用 /api/login/account。不要把业务项目已有的上下文配置与本章默认地址混用。

6. 验证并连接前端

使用手动创建的管理员调用 POST /api/login/account：

{"username":"admin","password":"填写你手动设置的初始密码","type":"account"}

成功后取 data.token，用 Authorization: Bearer <token> 调用 /api/currentUser。

再调用 /api/table/tio_boot_admin_system_constants_config/page?current=1&pageSize=10 验证通用表分页。标准配置会注册这些路由，业务工程无需逐条手动注册。

完整后台前端集成见 04.md。若登录失败，先核对目标数据库、手动执行的 SQL、密码摘要及签名密钥；不要通过自动重建数据库或增加另一套鉴权实现来绕过问题。