本地启动

图 1 · 本地起服务的先后顺序

环境依赖

依赖	版本 / 说明	是否必需
JDK	25	必需
Maven	3.9+	必需
Node.js	>= 26.7.0（`asone-front/.nvmrc` = `v26.7.0`）	前端必需
pnpm	11+	前端必需
MySQL	8.0+	必需
Redis	6.0+	必需
XXL-JOB Admin	3.5.x	联调定时任务时必需，本地默认关闭执行器
SMTP / 阿里云 OSS、验证码、短信	—	按需，缺失时相关功能不可用

1. 初始化数据库

CREATE DATABASE IF NOT EXISTS asone_dev
  DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_0900_ai_ci;

导入全量 DDL。Flowable 的 ACT_* 表由引擎启动时自动创建，数据库账号需要 DDL 权限。

2. 准备配置

后端从 asone-server-boot/src/main/resources/application.yml 读取默认配置，local Profile 的 application-local.yml 只覆盖差异项（本地 MySQL 库、立即停机、p6spy SQL 日志、关闭 Sentry、关闭执行器注册、开启本地 Swagger 分组）。

Redis 与其余连接信息如需指向本机，用环境变量覆盖，不要把本地或生产凭据提交进仓库：

export SPRING_DATASOURCE_URL='jdbc:mysql://127.0.0.1:3306/asone_dev?serverTimezone=Asia/Shanghai&useUnicode=true&tinyInt1isBit=false'
export SPRING_DATASOURCE_USERNAME=root
export SPRING_DATASOURCE_PASSWORD=<本地口令>
export SPRING_DATA_REDIS_HOST=127.0.0.1
export SPRING_DATA_REDIS_PORT=6379
export SPRING_DATA_REDIS_PASSWORD=<本地口令>

3. 启动后端

cd asone-server
mvn clean package -DskipTests=true
java -jar asone-server-boot/target/asone-server-boot-0.0.1-SNAPSHOT.jar \
  --spring.profiles.active=local

或者用 Maven 直接跑（先安装依赖模块，再在启动模块运行）：

cd asone-server
mvn -DskipTests=true install
cd asone-server-boot
mvn spring-boot:run -Dspring-boot.run.profiles=local

启动后可访问：

地址	说明
`http://localhost:8001/actuator/health`	健康检查（`show-details: always`）
`http://localhost:8001/swagger-ui.html`	接口文档
`http://localhost:8001/v3/api-docs/asone-server`	OpenAPI JSON（前端 `pnpm openapi` 的数据源）

local 下 xxl.job.executor.enabled=false，不会注册执行器、不监听 9999 回调端口；需要联调调度时手动改回 true，并本地起一个 XXL-JOB Admin。

4. 启动前端

cd asone-front
pnpm install
pnpm dev

访问 http://localhost:8000，开发服务器按 config/proxy.ts 把 /api/** 代理到 http://localhost:8001。

接口有变动时重新生成接口层：

cd asone-front && pnpm openapi

5. 验证

curl -sS http://localhost:8001/actuator/health
curl -sS -o /dev/null -w "%{http_code}\n" http://localhost:8000/
# 未带令牌访问受保护接口，应返回 401
curl -sS -o /dev/null -w "%{http_code}\n" http://localhost:8001/api/system/admin/page

6. 提交前检查

cd asone-server && mvn -q -DskipTests clean compile
cd asone-front && pnpm lint

本地开发注意

后台登录接口除账号密码外还要求阿里云验证码，命中非信任设备时还会走邮箱 / 短信两步验证，因此登录全流程只能在浏览器里人工完成；curl 只能验证到「接口通了、参数被正确校验」这一层。
数据库一律只读，需要写库先取得明确同意，见后端规范。
xxl-job/xxl-job/ 是上游 submodule 源码，本地不要修改，也不要纳入检索与审查范围。
前端 prepare 脚本会执行 husky 安装与 max setup，首次 pnpm install 必须在仓库根可访问 .husky 的前提下完成。