数据库初始化

server-java 与 server-python 提供 同一套 初始化接口，用于在空库或需要重置 RBAC 数据时一键完成部署。

破坏性操作

每次调用会 删除全部 RBAC 表及数据，再重建表结构并写入默认种子。生产环境请设置 DB_INIT_ALLOW_WEB=false，仅在可控环境使用。

接口

方法	路径	认证
POST	/api/v1/system/database/init	无需登录

成功响应 data 示例：

{
  "initialized": true,
  "message": "数据库已重置并初始化完成",
  "defaultUsername": "admin",
  "defaultPassword": "admin123"
}

HTTP	说明
403	DB_INIT_ALLOW_WEB=false，Web 初始化已禁用
500	SQL 脚本执行失败等

契约见 contracts/openapi/rbac-api.yaml → SystemDatabase。

执行流程

drop.sql   →  删除 sys_* 表（SET FOREIGN_KEY_CHECKS = 0）
schema.sql →  重建 RBAC 表结构
seed       →  写入 admin 角色/权限/菜单、用户 admin / admin123

SQL 源文件：

文件	说明
contracts/sql/drop.sql	删表脚本（契约源）
contracts/sql/schema.sql	建表脚本

运行时由各后端打包到 resources/db/（Java classpath:db/，Python app/resources/db/）。

调用示例

Java（:8080）

curl -X POST http://localhost:8080/api/v1/system/database/init

Swagger：http://localhost:8080/swagger-ui.html → SystemDatabase

Python（:8000）

curl -X POST http://localhost:8000/api/v1/system/database/init

Swagger：http://localhost:8000/docs → SystemDatabase

与 docker-compose MySQL 的关系

docker compose up -d 首次启动时仅自动执行 schema.sql 建表，不会写入 admin 等业务数据。

本地首次跑通推荐顺序：

docker compose up -d
pnpm --filter @xichen-full-stack/server-java dev   # 或 server-python
curl -X POST http://localhost:8080/api/v1/system/database/init
pnpm --filter web dev
# 登录 admin / admin123

环境变量

变量	默认	说明
DB_INIT_ALLOW_WEB	true	设为 false 时拒绝 POST init（生产建议关闭）

• Java：application.yml → app.database-init.allow-web-init
• Python：.env → DB_INIT_ALLOW_WEB

启动行为与容错

server-java / server-python 不要求在启动前已完成 init；仅有 Docker MySQL 自动建表、尚未写入 admin 时，后端仍可正常拉起。

阶段	server-java	server-python
业务 Seed	不在启动时写入；仅 POST init 触发	启动时尝试空库补种（已有用户则跳过）；失败仅 WARN
定时任务	SysJobService.initJobs() 加载 sys_job；缺表 → WARN，不阻断	job_scheduler.init_from_db() 同理
推荐路径	仍应显式调用 POST init	同左

日志示例（可忽略，调用 init 后重启即可）：

Failed to load scheduled jobs on startup (missing sys_job? run POST /api/v1/system/database/init): ...
Failed to seed on startup (missing tables? run POST /api/v1/system/database/init): ...   # 仅 Python

micro-java

与 server-java 相同，须调用 POST /api/v1/system/database/init（经 Gateway :8080）。init 后重启 monitor-service 以加载 Quartz 任务。

与 micro-java 的区别

实现	初始化方式
server-java / server-python / micro-java	POST /api/v1/system/database/init

micro-java 经 Gateway 转发到 system-service；init 后重启 monitor-service 加载定时任务。

相关文档

• 快速开始
• Docker MySQL
• 数据库表结构
• 环境变量