Tio Boot Docs

Appearance

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

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 配置、依赖或数据表。17.md 是历史可选方案，不是入门步骤。
  4. SQL 由用户手动执行。 启动应用之前，按 手动初始化数据库 建表和创建管理员。应用入口和配置类不执行初始化 SQL，不自动建表、插入管理员或重置密码。
  5. 按用途注册 ApiTable 配置。 TioAdminControllerConfiguration 注册通用表控制器，适合有明确表级权限的后台表格、表单和导出功能。面对账号恢复、双人审批等有领域状态与对象范围的业务，可以复用数据库配置和登录处理器，仅注册专用业务命令，避免通用表写入绕过状态校验。示例见 受限事项与原操作闭环。

1. Maven 工程 ​

推荐目录：

text
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：

xml
  <properties>
    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    <maven.compiler.release>21</maven.compiler.release>
    <tio-boot-admin.version>2.1.6</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>

说明：

  • 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：

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：

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

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

properties
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：

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() {
    // 在这里注册项目自己的业务路由；不要重复注册框架已有路由。
  }
}

以上调用覆盖本章的 PostgreSQL 后台接入。数据源配置负责连接与插件生命周期，Handler 配置负责后台和应用用户相关路由，Controller 配置负责 ApiTable。需要 Elasticsearch 时，先按 整合 Elasticsearch 添加客户端依赖，再增加 TioAdminElasticsearchConfig 的导入与初始化调用；不使用时无需加载该配置类。

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

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

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

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

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

java
import nexus.io.tio.boot.admin.handler.system.SystemCloudFileHandler;
import nexus.io.tio.boot.server.TioBootServer;
import nexus.io.tio.http.server.router.HttpRequestRouter;
java
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：

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 保存为文件后执行：

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

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

shell
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：

json
{"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 验证通用表分页。标准配置会注册这些路由，业务工程无需逐条手动注册。

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

Elasticsearch 的依赖、连接参数与操作示例见 整合 Elasticsearch。

MIT Licensed

Copyright © 2023-present litongjava