easy-next-admin/docs/getting-started.md

本地开发

本文说明如何在本地启动 EasyNextAdmin，并确认前后端、数据库和接口文档可用。

环境要求

工具	建议版本	用途
JDK	17+	运行 Spring Boot 3 服务端
Maven	3.9+	后端依赖管理和构建
Node.js	22 LTS 或 24 LTS	前端开发和构建；不再建议使用已 EOL 的 Node.js 20
npm	随 Node.js 安装	前端依赖管理
Docker	24+	本地启动 MySQL、Redis
Docker Compose	v2	编排本地依赖

根目录配置文件

.editorconfig 用于统一不同 IDE 和编辑器的基础格式，不需要手动执行。IntelliJ IDEA、WebStorm 通常会自动识别；VS Code 需要安装 EditorConfig 插件。当前规则要求 UTF-8、LF 换行、文件末尾保留换行、去除行尾空格，默认 2 空格缩进，Java 文件使用 4 空格。

默认启动不需要额外 .env 文件。docker-compose.yml 已经在 ${变量名:-默认值} 中写了本地默认值；如果没有 .env，Docker Compose 会直接使用这些默认值。比如 ${MYSQL_PORT:-3306}:3306 表示宿主机默认使用 3306 端口访问容器内 MySQL。

变量	默认值	说明
MYSQL_IMAGE	mysql:8.4	本地 MySQL 镜像，固定在 8.4 LTS 通道
REDIS_IMAGE	redis:7.4-alpine	本地 Redis 镜像，固定在 7.4 Alpine 通道
MYSQL_PORT	3306	MySQL 映射到宿主机的端口
MYSQL_ROOT_PASSWORD	123456	本地 root 密码，仅用于开发
REDIS_PORT	6379	Redis 映射到宿主机的端口
REDIS_PASSWORD	111222	本地 Redis 密码，仅用于开发

临时覆盖端口时，可以直接在命令前加环境变量：

MYSQL_PORT=13306 REDIS_PORT=16379 docker compose up -d

如果经常需要覆盖，也可以自己创建根目录 .env，该文件不会提交到仓库：

MYSQL_PORT=13306
REDIS_PORT=16379
MYSQL_ROOT_PASSWORD=123456
REDIS_PASSWORD=111222

生产环境应使用部署平台的密钥管理、环境变量或配置中心，不复用本地演示密码。

启动依赖

docker-compose.yml 只负责本地开发依赖，不启动业务应用：

• MySQL 8.4 LTS，Docker 镜像 mysql:8.4，默认端口 3306，库名 easy-next-admin，root 密码 123456，新数据卷默认使用 caching_sha2_password
• Redis 7.4，Docker 镜像 redis:7.4-alpine，默认端口 6379，密码 111222

docker compose up -d

停止依赖：

docker compose down

启动服务端

cd easy-next-admin-server
mvn spring-boot:run

默认配置：

• 服务端口：8080
• 数据库：jdbc:mysql://localhost:3306/easy-next-admin；本地默认 URL 带 createDatabaseIfNotExist=true
• 默认 profile：local
• Flyway：启动时自动执行 db/migration/V1__init.sql
• OpenAPI：http://127.0.0.1:8080/swagger-ui.html

本地默认使用 root 演示账号，因此数据库不存在时可以自动创建，再由 Flyway 初始化。若通过 MYSQL_URL 覆盖默认连接，需要自行保留 createDatabaseIfNotExist=true，或者提前创建数据库。这个便利能力只属于 local profile；生产环境应由 DBA 预建库并给应用账号授予目标 schema 内的最小权限，不授予全局建库权限。

Redis 在当前脚手架中默认启用。local profile 会使用 application-local.yaml 中的本地连接默认值：redis://localhost:6379，密码 111222。因此前面执行过 docker compose up -d 后，直接 mvn spring-boot:run 即可连接本地 Redis。

Redis 连接和能力开关统一放在 easy 命名空间下。需要排查连接参数或显式覆盖时，可以这样启动：

mvn spring-boot:run \
  -Dspring-boot.run.arguments="--easy.features.redis=true --easy.spring.redis.password=111222"

启用 Redis 后，缓存、会话、验证码、重复请求、幂等、限流和分布式锁会自动切到 Redis/Redisson 实现。临时不想启动 Redis 时，可用启动参数覆盖 --easy.features.redis=false，这些运行态能力会回退到本地内存或 MySQL。

Kafka 默认不启用。如果本地需要调试 Kafka 基础设施，启动时增加 --easy.features.kafka=true --easy.spring.kafka.bootstrap-servers=127.0.0.1:9092。

启动前端

cd easy-next-admin-web
npm ci
npm run dev

默认前端启动也不需要额外 .env 文件。前端代码默认请求 /api，Vite 开发服务器默认把 /api/** 和 /storage/** 代理到 http://localhost:8080。

如果需要长期覆盖前端配置，可以自己创建 easy-next-admin-web/.env.local。这套变量只给 Vite 前端使用，和根目录 .env 不是一回事：

• 根目录 .env：给 Docker Compose 用，控制 MySQL、Redis 镜像、端口和密码。
• easy-next-admin-web/.env.local：给前端开发和构建用，控制接口基础路径和本地代理目标。

本地个性化配置建议写入 easy-next-admin-web/.env.local，该文件不会提交到仓库：

cd easy-next-admin-web
touch .env.local

如果后端不是 8080 端口，改 .env.local：

VITE_API_BASE_URL=/api
VITE_API_PROXY_TARGET=http://127.0.0.1:8081

Vite 默认地址：

http://127.0.0.1:5174

前端开发服务器会把 /api/** 代理到 VITE_API_PROXY_TARGET。也可以临时通过命令行覆盖后端地址：

VITE_API_PROXY_TARGET=http://127.0.0.1:8081 npm run dev

演示账号

登录页会从 GET /api/auth/demo-accounts 读取演示账号。该接口只在 local profile 返回账号清单，非本地环境返回空列表，避免生产登录页暴露初始化密码。

角色	账号	密码
超级管理员	admin	admin
部门负责人	manager	easynext
普通员工	staff	easynext
审计人员	auditor	easynext

这些账号用于本地开发，方便第一次启动后直接验证权限、流程、审计和监控页面。正式生产环境必须替换初始化密码，且不要启用 local profile。

首次登录只校验账号密码。同一用户名和客户端 IP 登录失败后，后续登录会要求验证码。

本地检查路径

启动完成后按下面顺序检查：

检查项	地址
前端登录页	http://127.0.0.1:5174/login
工作台	http://127.0.0.1:5174/dashboard
后端健康检查	http://127.0.0.1:8080/actuator/health
OpenAPI UI	http://127.0.0.1:8080/swagger-ui.html
OpenAPI JSON	http://127.0.0.1:8080/v3/api-docs

常见问题

MySQL 端口被占用

调整环境变量后再启动依赖：

MYSQL_PORT=13306 docker compose up -d

然后启动服务端时覆盖数据源地址：

cd easy-next-admin-server
mvn spring-boot:run \
  -Dspring-boot.run.arguments="--spring.datasource.url=jdbc:mysql://localhost:13306/easy-next-admin?serverTimezone=GMT%2B8&characterEncoding=UTF-8&connectionCollation=utf8mb4_unicode_ci&useSSL=false&allowPublicKeyRetrieval=true"

MySQL 提示 mysql_native_password is not loaded

这通常说明当前机器复用了旧 MySQL 数据卷，里面的 root 账号仍绑定 mysql_native_password。MySQL 8.4 默认禁用这个旧插件；全新数据卷会使用默认 caching_sha2_password，正常不会出现这个错误。

如果这是全新脚手架，本地数据不需要保留，直接删除旧数据卷重新初始化。这个操作会清空本地数据库：

docker compose down
docker volume rm easy-next-admin_mysqlData
docker compose up -d

如果本地数据需要保留，先临时启用旧插件完成账号迁移，迁移后再移除临时配置。可以在本机临时给 MySQL 启动参数追加 --mysql-native-password=ON，不要把它作为脚手架默认配置提交。容器启动后先检查账号认证插件：

docker compose exec mysql mysql -uroot -p123456 -e "SELECT user, host, plugin FROM mysql.user;"

确认能登录后，把 root 账号迁移到 MySQL 8.4 默认认证方式：

docker compose exec mysql mysql -uroot -p123456 -e "ALTER USER 'root'@'%' IDENTIFIED WITH caching_sha2_password BY '123456'; ALTER USER 'root'@'localhost' IDENTIFIED WITH caching_sha2_password BY '123456'; FLUSH PRIVILEGES;"

Flyway 校验失败

本地开发库可以直接备份并删除，再让 local 默认连接自动建库并由 Flyway 执行单一 V1 基线：

mkdir -p work/db-backups
docker exec easy-next-admin-mysql mysqldump --default-character-set=utf8mb4 -uroot -p123456 --single-transaction --set-gtid-purged=OFF easy-next-admin > "work/db-backups/easy-next-admin-$(date +%Y%m%d%H%M%S).sql"
docker exec easy-next-admin-mysql mysql -uroot -p123456 -e "DROP DATABASE IF EXISTS \`easy-next-admin\`;"
cd easy-next-admin-server
mvn clean spring-boot:run

这里使用 clean 是为了同时删除 target/classes 中可能残留的旧迁移文件。重建完成后，flyway_schema_history 应只有 V1__init.sql 一条成功记录。不要再手工导入 V1 后同时启动 Flyway，避免初始化来源分叉。

前端接口 404 或连接失败

确认后端在 8080 端口运行，或通过 VITE_API_PROXY_TARGET 指向正确地址。前端 Axios 的业务前缀是 /api，不要在页面里直接请求完整后端域名。