# xiaolu-server

**Repository Path**: sprouting/xiaolu-server

## Basic Information

- **Project Name**: xiaolu-server
- **Description**: 小鹿AI写作助手后端
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-10-23
- **Last Updated**: 2026-11-03

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# xiaolu-server

小鹿服务端。

## 技术栈

| 技术 | 版本 | 说明 |
| --- | --- | --- |
| JDK | 21 | |
| Spring Boot | 3.5.4 | |
| MyBatis-Plus | 3.5.17 | 分页使用 `mybatis-plus-jsqlparser` |
| Sa-Token | 1.46.0 | 权限认证 |
| H2 | 2.3.232 | 文件模式，单机开箱即用 |
| Druid | 1.2.28 | Spring Boot 3 Starter |
| Liquibase | 4.33.0 | 数据库版本管理 |
| Quartz | Spring Boot Starter 管理 | 定时任务调度 |
| Hutool | 5.8.48 | 工具集 |
| x-file-storage | 2.3.0 | 统一文件存储 |

## 目录结构

```
src/main/java/com/sprouting/xiaolu
├── XiaoluServerApplication.java   启动类
├── annotations/invoke             自定义校验、幂等注解
├── annotations/service            注解实现与 AOP
├── config                         自动填充、跨域、MyBatis-Plus 配置
├── controller                     系统模块控制器
├── dao                            Mapper 接口
├── enums                          返回状态枚举
├── exception                      全局异常处理
├── filter                         XSS 过滤器
├── handle                         Sa-Token 拦截器、监听器
├── interfaces                     常量、缓存 key、校验分组、Mapper 基类
├── model                          BaseModel、ResultJson、实体、BO/QO/VO、配置属性
├── service                        系统模块业务实现
├── task                           启动初始化、文件清理、数据库备份任务
└── utils                          通用工具类
```

## 系统基础模块

已从参考项目迁移以下模块（表名统一 `xl_` 前缀）：

| 模块 | 控制器 | 主要表 |
| --- | --- | --- |
| 登录/开放接口 | `OpenController` | `xl_user`、`xl_role`、`xl_user_role`、`xl_authority`、`xl_role_authority` |
| 管理员工具 | `AdminController` | `xl_user` |
| 用户 | `UserController` | `xl_user`、`xl_user_role`、`xl_dep`、`xl_file_storage` |
| 部门 | `DepController` | `xl_dep`、`xl_user` |
| 角色 | `RoleController` | `xl_role`、`xl_role_authority`、`xl_user_role` |
| 权限 | `AuthorityController` | `xl_authority`、`xl_role_authority` |
| 通知 | `NoticeController` | `xl_notice`、`xl_notice_read` |
| 系统配置 | `SysConfigController` | `xl_sys_config` |
| 字典 | `SysDictController`、`SysDictGroupController` | `xl_sys_dict`、`xl_sys_dict_group` |
| 文件存储 | `FileStorageController` | `xl_file_storage`、`xl_file_part_detail` |
| 数据库备份 | `CustomJobController`（任务 `databaseBackupTask`） | `xl_database_backup` |
| 定时任务 | `CustomJobController`、`CustomJobLogController` | `xl_custom_job`、`xl_custom_job_log` |

初始管理员：`admin / admin`。表结构和初始化数据在：

- 表结构：`src/main/resources/db/changelog/dbScript/h2/db.changelog-master-v1.0.xml`
- 初始化数据：`src/main/resources/db/changelog/dbScript/h2/db.changelog-master-v1.0-init.xml`

完整表设计见 `doc/table-design.md`。

## 本地启动

1. 确认 JDK 21 已安装，且 `JAVA_HOME` 指向 JDK 21。
2. 启动 `XiaoluServerApplication`。
3. 默认端口 `8098`，接口前缀 `/xiaolu`，访问示例：`http://127.0.0.1:8098/xiaolu/`。

H2 数据库默认落在 `E:/temps/xiaoLu/temps/db/20251018dev-xiaoLu.mv.db`，首次启动会自动创建。

## 配置说明

- 通用配置：`src/main/resources/application.properties`
- 生产覆盖：`src/main/resources/application-prod.properties`，只保留环境差异项，通过 `--spring.profiles.active=prod` 启用
- 默认激活的是 `dev` profile，但当前没有 `application-dev.properties`，开发环境配置全部在 `application.properties` 中
- 数据库结构：`src/main/resources/db/changelog/`，新增表结构时在 `dbScript/h2/` 下追加 changelog，并在 `master.xml` 中按顺序 `include`
- Mapper XML：`src/main/resources/mapper/h2/`

## 数据库备份

使用 H2 的 `BACKUP TO` 命令在线备份，避免直接复制 `.mv.db` 时数据库被锁定。

- 由定时任务框架管理，任务注册名为 `databaseBackupTask`，默认每天 02:00 执行一次，可在定时任务页面调整 cron 或立即执行
- 备份文件默认在数据库文件同级目录的 `bak/` 下，可通过 `xiaolu.customize.db.backup.dir` 指定
- 不自动清理旧备份

## 定时任务

所有周期性任务统一由 Quartz 管理，任务配置保存在 `xl_custom_job`，执行日志保存在 `xl_custom_job_log`，不再使用 `@Scheduled`。

新增任务的步骤：

1. 实现 `com.sprouting.xiaolu.task.job.TaskJobExecInterfaces`；
2. 用 `@Service("beanName")` 注册到 Spring，并加 `@JobDescribe("任务名称")` 便于展示；
3. 在定时任务页面或接口中新增任务，`invokeTarget` 填步骤 2 的 Bean 名称。

应用启动时 `SpringbootStartLoading` 会从数据库加载所有启用状态的任务；任务暂停、恢复、立即执行、删除都通过 `CustomJobService` 操作 Quartz。

- 默认最小执行间隔为 60 秒，可通过 `xiaolu.customize.job.min-interval-seconds` 调整，避免误配置高频任务。
- 已内置「清理上传文件」任务：`invokeTarget=cleanUploadedFileTask`，cron `0 * * * * ?`，每分钟执行一次。
- 已内置「数据库备份」任务：`invokeTarget=databaseBackupTask`，cron `0 0 2 * * ?`，默认每天 02:00 执行一次。
- 任务日志会随每次执行写入 `xl_custom_job_log`，可在日志接口中分页查询或清理。

## 启动脚本

`script/startup.bat` 是 Windows 启动脚本：

- 需要与 `xiaolu-server.jar`、前端打包产物 `dist/` 放在同一目录
- 优先使用同目录下的 `jre/`，没有则使用系统 `java`
- 以 `prod` profile 启动，并打开 `http://127.0.0.1:8098/xiaolu/index.html`
- 如需外部配置，把 `application-prod.properties` 放在 jar 同级目录

## 权限白名单

无需登录即可访问的地址在 `xiaolu.customize.auth.whites` 中配置，多个用英文逗号分隔。
这里是去掉 `server.servlet.context-path`（`/xiaolu`）之后的路径，例如 `/open/**`，不要写成 `/xiaolu/open/**`。
Druid 监控页默认放行；H2 控制台默认关闭，如需使用请把 `spring.h2.console.enabled` 改为 `true`（白名单已包含 `/h2-console/**`）。