配置

后端配置

建议

在接触其他项目的过程中，发现大家基本上将系统的所有配置都放到了application.yml中，导致yml非常长且不好维护。因此萌生想法：将yml根据功能进行拆分，便产生了现在这种结构。

配置	描述
`/config/${spring.profiles.active}/*.yml`	仓库根目录下按环境和功能拆分的外部配置文件。
`sz-service/sz-service-admin/src/main/resources/application.yml`	启动服务根配置，负责导入子配置和承载通用配置。
`sz-service/sz-service-admin/src/main/resources/application-${spring.profiles.active}.yml`	启动服务的环境配置，一般配置 API 前缀或开放端口。

配置引用顺序：

./application.yml -> ./application-${spring.profiles.active}.yml

./application.yml -> /config/${spring.profiles.active}/*.yml

配置优先级：

./application-${spring.profiles.active}.yml >= /config/${spring.profiles.active}/*.yml >= ./application.yml

text

sz-boot-parent/
├── config/
│   └── {dev,local,preview,prod}/               # 四个环境目录文件集合一致
│       ├── audit-log.yml
│       ├── knife4j.yml                         # OpenAPI 配置（沿用历史文件名）
│       ├── mybatis-flex.yml
│       ├── mysql.yml
│       ├── oss.yml
│       ├── page-helper.yml
│       ├── postgresql.yml
│       ├── redis.yml
│       └── sa-token.yml
└── sz-service/sz-service-admin/src/main/resources/
    ├── application.yml                         # 主配置文件
    ├── application-dev.yml
    ├── application-local.yml
    ├── application-preview.yml
    └── application-prod.yml

配置详解

WARNING

以下配置为示例配置，具体需结合自己情况进行调整。不建议生产环境直接使用！！！

根配置

application.yml

yaml

DB_TYPE: mysql
spring:
  threads:
    virtual:
      # 启用虚拟线程
      enabled: true
  profiles:
    # 默认启动local环境配置
    active: local
  config:
    # 根据环境变量导入配置
    import:
      - file:config/${spring.profiles.active}/knife4j.yml
      - file:config/${spring.profiles.active}/audit-log.yml
      - file:config/${spring.profiles.active}/oss.yml
      - file:config/${spring.profiles.active}/mybatis-flex.yml
      - file:config/${spring.profiles.active}/${DB_TYPE}.yml
      - file:config/${spring.profiles.active}/page-helper.yml
      - file:config/${spring.profiles.active}/redis.yml
      - file:config/${spring.profiles.active}/sa-token.yml
  # Spring MVC 路径匹配策略
  mvc:
    path-match:
      matching-strategy: ant_path_matcher
  application:
   # 服务名
    name: admin-service
  # 文件大小限制
  servlet:
    multipart:
      max-file-size: 10MB
      max-request-size: 15MB
 # -- sz-admin 自定义参数配置 --    
sz:
  # api 业务前缀。该配置由 ApiPrefixConfiguration 读取，并按 Controller 所在包名追加到 Spring MVC 路径上
  api-prefix:
    modules:
      admin:
        enabled: true
        prefix: /admin
      audit:
        enabled: true
        prefix: /audit
      generator:
        enabled: true
        prefix: /generator
  # 是否启用数据权限拼接
  data-scope:
    enabled: true
    # 数据逻辑实现最小验证（查询）单位：dept 部门（dept_scope字段）、user 用户 (create_id 字段),默认user。
    logic-min-unit: user
    # 是否允许查看管理员创建的数据。
    allow-admin-view: false
  debounce:
    # 是否启用防抖功能
    enabled: true
    # 全局防抖时间，单位毫秒（默认1000ms）
    global-lock-time: 500
    # 是否忽略GET请求
    ignore-get-method: true
  # 生成工具
  generator:
    path:
      # 前端项目地址
      web:
      # 后端项目地址，默认自动检测springboot项目路径，无需配置。
      api:
    # 模块名，指定代码生成的模块
    module-name: sz-module
    service-name: sz-module-admin
    global:
      author: sz-admin
      packages: com.sz.admin
      ignore-table-prefix:
        enabled: true
        prefixes:
          - t_
  # 微信生态
  wechat:
    # 小程序
    mini:
      app-id: your_app_id
      app-secret: your_app_secret

API 前缀说明

sz.api-prefix 不是 server.servlet.context-path，它不会改变整个服务的上下文路径，而是由 ApiPrefixConfiguration 在 Spring MVC 路由注册阶段收集各业务模块提供的 ApiPrefixRegister，再按 Controller 包名追加业务前缀。

当前代码中的规则如下：

配置项	默认值	生效包名	说明
`sz.api-prefix.modules.admin.prefix`	`/admin`	`com.sz.admin.system`、`com.sz.admin.teacher`、`com.sz.applet`、`com.sz.security.controller`、`com.sz.www`	管理端、认证、安全、示例和官网相关 Controller
`sz.api-prefix.modules.audit.prefix`	`/audit`	`com.sz.audit.controller`	审计模块 Controller
`sz.api-prefix.modules.generator.prefix`	`/generator`	`com.sz.generator.controller`	代码生成器 Controller

示例：

Controller 原始路径	业务前缀	`server.servlet.context-path`	最终访问路径
`/auth/login`	`/admin`	`/api`	`/api/admin/auth/login`
`/sys-user`	`/admin`	`/api`	`/api/admin/sys-user`
`/resource/file/logo/**`	`/admin`	`/api`	`/api/admin/resource/file/logo/**`
`/sys-operation-log`	`/audit`	`/api`	`/api/audit/sys-operation-log`
`/generator-table`	`/generator`	`/api`	`/api/generator/generator-table`

ApiPrefixConfiguration 会对配置值做规范化处理：为空时表示不追加前缀；没有 / 开头时会自动补 /；末尾多余 / 会被移除。因此 admin、/admin、/admin/ 最终都会归一为 /admin。

IMPORTANT

如果你调整了 sz.api-prefix.modules.<module>.prefix，需要同步调整前端对应的 VITE_<MODULE>_API_BASE、Nginx 代理、资源访问 base-url、Sa-Token 白名单以及第三方回调地址。不要只改后端前缀，否则前端请求和鉴权白名单会同时失配。

环境配置

application-dev.yml

yaml

# 服务器配置
server:
  # Servlet 配置
  servlet:
    # 设置服务上下文路径为 /api
    context-path: /api
  # 设置端口为 9991
  port: 9991

TIP

server.servlet.context-path 只配置到 /api。管理端、审计和生成器接口再由 sz.api-prefix.modules.admin.prefix=/admin、sz.api-prefix.modules.audit.prefix=/audit、sz.api-prefix.modules.generator.prefix=/generator 追加业务前缀，因此最终访问路径分别是 /api/admin/**、/api/audit/** 和 /api/generator/**。Actuator 健康检查不属于上述 Controller 包名范围，不会追加业务前缀，路径为 /api/actuator/health。

子配置

Liquibase 配置

当前版本不再使用 Flyway。Liquibase 配置放在数据库类型配置文件中，例如 mysql.yml 或 postgresql.yml：

yaml

spring:
  liquibase:
    change-log: classpath:db/changelog/changelog-master.xml
    enabled: true
    database-change-log-lock-table: databasechangeloglock
    database-change-log-table: databasechangelog

knife4j.yml OpenAPI / springdoc 配置

yaml

# OpenAPI 文档配置
# 说明：文件名当前仍沿用历史 knife4j.yml，但 Spring Boot 4.x 主线已暂停使用 Knife4j，实际生效配置为 springdoc。
springdoc:
  default-flat-param-object: true
  swagger-ui:
    # 是否开启 swagger-ui，【生产环境】建议关闭
    enabled: true
    # Swagger UI 页面路径
    path: /swagger-ui.html
    # 标签排序方式（按字母顺序）
    tags-sorter: alpha
    # 操作排序方式（按字母顺序）
    operations-sorter: alpha
  api-docs:
    # OpenAPI 文档路径
    path: /v3/api-docs
  # 文档分组配置
  group-configs:
  	  # 组名
    - group: 'admin'
      # 匹配路径
      paths-to-match: '/**'
      # 扫描的包
      packages-to-scan: com.sz.admin
    - group: 'generator工具'
      paths-to-match: '/**'
      packages-to-scan: com.sz.generator
    - group: 'www网站'
      paths-to-match: '/**'
      packages-to-scan: com.sz.www
    - group: '微信小程序'
      paths-to-match: '/**'
      packages-to-scan: com.sz.applet

IMPORTANT

v2.0.0 基于 Spring Boot 4.x，Knife4j 还未作为当前主线完成适配，实际业务中已暂停使用 Knife4j UI，接口文档以 springdoc-openapi-starter-webmvc-ui 提供的 Swagger UI / OpenAPI JSON 为准。仓库中 knife4j.yml 目前只是沿用历史文件名，内容应按 springdoc 配置理解。

常用访问地址：

能力	地址
Swagger UI	`http://127.0.0.1:9991/api/swagger-ui.html`
OpenAPI JSON	`http://127.0.0.1:9991/api/v3/api-docs`

如果后续将文件重命名为 springdoc.yml，需要同步修改 application.yml 中的 spring.config.import 路径；否则保持当前文件名即可。

oss.yml

yaml

sz:
  # S3 兼容对象存储接入配置，供 sz-common-oss 使用
  oss:
    provider: MINIO
    endpoint: your-minio-host:9000
    accessKey: your-access-key
    secretKey: your-secret-key
    bucketName: test
    domain: http://your-minio-host:9000
    scheme: http

  # 业务资源场景配置，供 sz-common-resource 使用
  resource:
    root: ./data
    default-storage-type: LOCAL
    max-size: 50MB
    security:
      allowed-exts: [jpg, jpeg, png, gif, bmp, webp, svg, ico, pdf, doc, docx, xls, xlsx, ppt, pptx, rtf, txt, csv, zip, rar, 7z, tar, gz, mp3, wav, ogg, mp4, mov, avi, wmv]
    scenes:
      - code: admin.user.logo
        name: 账户头像
        type: LOCAL
        serve-mode: DIRECT
        base-url: http://127.0.0.1:9991/api/admin/resource/file/logo
        path: logo
        naming: ORIGINAL
        path-strategy: BIZ_DATE
        exts: [svg, png, jpg, jpeg, webp, gif]
        max-size: 3
      - code: template.excel
        name: 模板文件管理 / 导入模板
        type: LOCAL
        serve-mode: PROTECTED
        path: template
        naming: ORIGINAL
        path-strategy: DATE
        exts: [xls, xlsx]
        max-size: 10
      - code: teacher.attachment
        name: 教师统计 / 附件
        type: LOCAL
        serve-mode: PROTECTED
        path: teacher-attachments
        naming: ORIGINAL
        path-strategy: BIZ_DATE
        exts: [png, jpg, jpeg, webp, gif, pdf, doc, docx, xls, xlsx]
        max-size: 10
      - code: teacher.richtext
        name: 教师富文本
        type: LOCAL
        serve-mode: DIRECT
        path: teacher-richtext
        base-url: http://127.0.0.1:9991/api/admin/resource/file/teacher-richtext
        naming: UUID
        path-strategy: DATE
        exts: [png, jpg, jpeg, webp, gif, pdf, doc, docx, xls, xlsx]
        max-size: 5
      - code: system.temp
        name: 临时公开文件
        type: LOCAL
        serve-mode: DIRECT
        path: temp
        base-url: http://127.0.0.1:9991/api/admin/resource/file/temp
        naming: ORIGINAL
        path-strategy: DATE
        exts: [png, jpg, jpeg, webp, gif, pdf, doc, docx, xls, xlsx]
        max-size: 10
      - code: system.protected
        name: 通用业务附件
        type: LOCAL
        serve-mode: PROTECTED
        path: protected
        naming: ORIGINAL
        path-strategy: DATE
        exts: [png, jpg, jpeg, webp, gif, pdf, doc, docx, xls, xlsx]
        max-size: 10

IMPORTANT

v2.0.0 起不再使用历史根级 oss: 作为主配置。sz.oss 只负责厂商接入凭据，sz.resource 负责上传场景、路径、命名、白名单和访问模式。业务上传组件应传入 sceneCode，对应 sz.resource.scenes[].code。

mybatis-flex.yml

yaml

# mybatis-flex配置
mybatis-flex:
  # MyBatis配置
  configuration:
    # 将数据库字段的下划线命名转换为驼峰命名
    map-underscore-to-camel-case: true
    # 对null值进行jdbc类型处理
    jdbc-type-for-null: null
    # 自动映射行为（完全映射）
    auto-mapping-behavior: full
    # 未知列的自动映射行为（不映射）
    auto-mapping-unknown-column-behavior: none
    # 是否启用缓存
    cache-enabled: false
  # 全局配置
  global-config:
    # 逻辑删除字段的已删除值
    deleted-value-of-logic-delete: "T"
    # 逻辑删除字段的未删除值
    normal-value-of-logic-delete: "F"
# 雪花ID配置
sz:
  id:
    worker-id: ${SZ_WORKER_ID:1}          # 工作机器ID，范围 0-31
    datacenter-id: ${SZ_DATACENTER_ID:1}  # 数据中心ID，范围 0-31

sz.id.worker-id 和 sz.id.datacenter-id 会被 SzSnowflakeProperties 读取，并在 MybatisFlexConfiguration 中创建全局 Hutool Snowflake 实例。框架随后把 SzIdGenerator 注册为 MyBatis-Flex 全局 KeyGenerator，因此 v2.0.0 中使用雪花主键的实体可以通过全局策略生成 Long 类型 ID。

IMPORTANT

这两个值只负责运行期新数据的 ID 生成，不会自动迁移旧库中的自增 ID、UUID 或字符串 ID。存量系统升级时，需要先阅读升级指南 - 全局 ID 迁移，确认主键、外键和关系表是否需要映射迁移。

CAUTION

多节点部署时，每个后端节点必须使用不同的 SZ_WORKER_ID / SZ_DATACENTER_ID 组合。若多个节点沿用默认 1/1，高并发写入时可能生成重复 ID，最终表现为主键冲突。编码侧主键声明建议参考规范 - 主键ID 与全局雪花ID策略。

mysql.yml

yaml

# mysql配置
spring:
  datasource:
  	# 驱动
    driver-class-name: com.mysql.cj.jdbc.Driver
    # jdbc
    url: jdbc:mysql://127.0.0.1:3306/sz_admin_preview?useUnicode=true&characterEncoding=UTF-8&serverTimezone=GMT%2B8&useSSL=false&allowPublicKeyRetrieval=true
    username: root
    password: your-mysql-password
    hikari:
      #连接池名
      pool-name: HikariCP
      #最小空闲连接数
      minimum-idle: 5
      # 空闲连接存活最大时间，默认10分钟
      idle-timeout: 600000
      # 连接池最大连接数，默认是10
      maximum-pool-size: 10
      # 此属性控制从池返回的连接的默认自动提交行为,默认值：true
      auto-commit: true
      # 此属性控制池中连接的最长生命周期，值0表示无限生命周期，默认30分钟
      max-lifetime: 1800000
      # 数据库连接超时时间,默认30秒
      connection-timeout: 30000
      # 连接测试query
      connection-test-query: SELECT 1
  liquibase:
    change-log: classpath:db/changelog/changelog-master.xml
    enabled: true
    database-change-log-lock-table: databasechangeloglock
    database-change-log-table: databasechangelog

postgresql.yml

yaml

spring:
  datasource:
    driver-class-name: org.postgresql.Driver
    url: jdbc:postgresql://127.0.0.1:5432/sz_admin_preview
    username: postgres
    password: your-password
  liquibase:
    change-log: classpath:db/changelog/changelog-master.xml
    enabled: true
    database-change-log-lock-table: databasechangeloglock
    database-change-log-table: databasechangelog

WARNING

切换 PostgreSQL 时，除了设置 DB_TYPE=postgresql，还必须选择 Maven 的 postgresql profile；默认 MySQL 使用 mysql profile。不要再通过编辑 POM、注释依赖来切换数据库方言模块。

page-helper.yml

yaml

# pagehelper配置
page-helper:
  # 自动识别分页方言
  autoDialect: true
  # 是否启用分页合理化
  reasonable: false
  # 是否支持方法参数（支持）
  supportMethodsArguments: true
  # 分页参数设置
  params: count=countSql

redis.yml

yaml

# redis
spring:
  data:
    redis:
      #单机配置
      host: 127.0.0.1
      port: 6379
      # 数据索引
      database: 0
      # 连接超时时间（毫秒）
      timeout: 50000
      ###连接池配置###
      jedis:
        pool:
          # 连接池最大连接数（使用负值表示没有限制）
          max-active: 100
          # 连接池最大阻塞等待时间（使用负值表示没有限制）
          max-wait: -1
          # 连接池中的最大空闲连接
          max-idle: 30
          # 连接池中的最小空闲连接
          min-idle: 10
      password: your-redis-password

# 开启redis监听 (自定义配置)
redis:
  listener:
    enable: true

sa-token.yml

yaml

# sa-token
sa-token:
  # token名称 (同时也是cookie名称)
  token-name: Authorization
  # 是否开启自动续签
  auto-renew: true
  # token固定超时 设为七天 (必定过期) 单位: 秒
  timeout: 604800			# 全局变量，最终时间在【客户端管理】中进行设置
  # 多端不同 token 有效期 可查看 LoginHelper.loginByDevice 方法自定义
  # token最低活跃时间 (指定时间无操作就过期) 单位: 秒
  active-timeout: 86400	 	# 全局变量，最终时间在【客户端管理】中进行设置
  # 是否允许同一账号并发登录 (为true时允许一起登录, 为false时新登录挤掉旧登录)
  is-concurrent: true
  # 在多人登录同一账号时，是否共用一个token (为true时所有登录共用一个token, 为false时每次登录新建一个token)
  is-share: false
  # token 风格（默认可取值：uuid、simple-uuid、random-32、random-64、random-128、tik）
  token-style: uuid
  # 是否输出操作日志
  is-log: true
  # jwt秘钥
  jwt-secret-key: change-me-to-a-long-random-secret # 必须替换为自己的高强度随机密钥
  # 允许动态设置 token 有效期
  dynamic-active-timeout: true
  # 允许从 请求参数 读取 token
  is-read-body: false
  # 允许从 header 读取 token
  is-read-header: true
  # 关闭 cookie 鉴权 从根源杜绝 csrf 漏洞风险
  is-read-cookie: false
  # token前缀
  token-prefix: "Bearer"
  # 同一账号最大登录数量，-1代表不限
  max-login-count: -1  # 默认同一账号最大登录数量=12
# 接口白名单(放行接口-不鉴权)
router:
  whitelist:
    - "/v3/api-docs/**"
    - "/swagger-ui/**"
    - "/swagger-ui.html"
    - "/www/**"
    - "/wechat/**"

NOTE

上述列表与当前 local profile 一致；prod/sa-token.yml 默认未启用任何 router.whitelist。登录等无需鉴权的接口由代码上的 @SaIgnore 控制，不要为了“能访问”直接扩大生产白名单。server.servlet.context-path=/api 不写入白名单，外部访问路径才会带 /api。

前端配置

前端配置相对比较简单，这里重点说明 .env.development.local 和 .env.production。仓库内已有 .env、.env.development、.env.production，本地个性化配置建议放到 .env.development.local，避免覆盖团队共享配置。

IMPORTANT

需要注意的是VITE_APP_CLIENT_ID配置，它是【客户端管理】颁发的可用ID。建议针对不同环境颁发不同的ID。

.env.development.local

用于本地开发调试的环境

properties

# 本地环境
VITE_USER_NODE_ENV=development
# 公共基础路径
VITE_PUBLIC_PATH=/
# 管理端、审计和生成器接口前缀
VITE_ADMIN_API_BASE=/api/admin
VITE_AUDIT_API_BASE=/api/audit
VITE_GENERATOR_API_BASE=/api/generator
# 自定义模块拼接 API 地址时使用的上下文路径
VITE_API_CONTEXT_PATH=/api
VITE_API_PROXY_TARGET=http://127.0.0.1:9991
# 开发环境 websocket 服务地址。若不填写此地址，WebSocket 客户端不会启动
VITE_SOCKET_URL=ws://127.0.0.1:9993/socket
# 授权的clientID
VITE_APP_CLIENT_ID=195da9fcce574852b850068771cde034

本地开发时，vite.config.mts 会读取 VITE_ADMIN_API_BASE、VITE_AUDIT_API_BASE、VITE_GENERATOR_API_BASE 和 VITE_API_CONTEXT_PATH 动态生成代理规则，并把它们转发到 VITE_API_PROXY_TARGET。因此前端代码中 adminHttp.get('/sys-user') 的实际请求路径是 /api/admin/sys-user，再由 Vite 代理到后端服务。

.env.production

用于线上发布的环境，build 生成dist。结合Nginx或Apache服务器使用。

properties

# 线上环境
VITE_USER_NODE_ENV=production

# 公共基础路径
VITE_PUBLIC_PATH=/

# 线上环境接口前缀
VITE_ADMIN_API_BASE=/api/admin
VITE_AUDIT_API_BASE=/api/audit
VITE_GENERATOR_API_BASE=/api/generator
VITE_API_CONTEXT_PATH=/api
VITE_APP_CLIENT_ID=195da9fcce574852b850068771cde034
# websocket 服务地址。Nginx 同域代理时可使用 /socket；跨域直连时使用 ws:// 或 wss://
VITE_SOCKET_URL=/socket
# 是否对 admin 用户绕过前端按钮权限验证；生产默认不绕过
VITE_ADMIN_BYPASS_PERMISSION=false

生产环境通常由 Nginx 接管 /api/admin/**、/api/audit/** 和 /api/generator/** 代理。若后端 sz.api-prefix 改为其他值，生产环境的这些变量和 Nginx location 也必须同步调整。

.env

通用配置

properties

# title
VITE_APP_TITLE='Sz Admin'

# （本地）运行端口号
VITE_PORT=9848

# （本地）启动时自动打开浏览器
VITE_OPEN=true
# clientId
VITE_APP_CLIENT_ID=195da9fcce574852b850068771cde034
# HTTP请求最大超时时间（ms）120s
VITE_APP_HTTP_TIMEOUT=120000

配置 ​

后端配置 ​

配置详解 ​

根配置 ​

application.yml ​

API 前缀说明 ​

环境配置 ​

application-dev.yml ​

子配置 ​

Liquibase 配置 ​

knife4j.yml OpenAPI / springdoc 配置 ​

oss.yml ​

mybatis-flex.yml ​

mysql.yml ​

postgresql.yml ​

page-helper.yml ​

redis.yml ​

sa-token.yml ​

前端配置 ​

.env.development.local ​

.env.production ​

.env ​

配置

后端配置

配置详解

根配置

application.yml

API 前缀说明

环境配置

application-dev.yml

子配置

Liquibase 配置

knife4j.yml OpenAPI / springdoc 配置

oss.yml

mybatis-flex.yml

mysql.yml

postgresql.yml

page-helper.yml

redis.yml

sa-token.yml

前端配置

.env.development.local

.env.production

.env