快速开始

受众：开发者 摘要：快速开始。环境要求 / 启动基础环境 / 启动应用 / 账号初始化 / Lite 兼容模式 / 常用验证。

本文档用于快速启动项目。

环境要求

• JDK 17+
• Maven 3.9+
• Docker Desktop，推荐用于启动 MySQL、Redis、PostgreSQL

默认数据库和中间件版本：

• MySQL 8.4 LTS，Docker 完整环境默认使用
• PostgreSQL 15+
• Redis 8，Docker 完整环境默认使用
• H2 2.x，仅用于 lite 兼容 / 隔离诊断模式

启动基础环境

Docker 文件统一放在 docker/ 目录：

docker compose -f docker/docker-compose.yml up -d mysql redis

默认基础环境包括 MySQL 和 Redis。PostgreSQL 按 profile 启动。

查看 MySQL 和 Redis 状态：

docker compose -f docker/docker-compose.yml ps mysql redis

启动应用

./mvnw -pl spring-open-application spring-boot:run

全新 checkout 或执行过 mvn clean 后，先运行 ./mvnw -pl spring-open-application -am install -DskipTests -DskipITs -DskipFrontend 安装应用依赖，再启动应用。不要把 -am 和 spring-boot:run 组合使用，避免 Maven 把运行目标施加到 reactor 里的 POM 模块。

使用 IDEA 或 JRebel 启动时，建议在当前 Run Configuration 的 VM options 中加入 -XX:InitialCodeCacheSize=64m -XX:ReservedCodeCacheSize=512m -XX:+UseCodeCacheFlushing，避免本地启动或热加载时 JVM CodeCache 过小，出现 CodeCache is full. Compiler has been disabled. 警告。如果控制台仍显示 CodeCache: size=49152Kb，就表示这些参数没有进入当前 JVM，需要检查 JRebel 实际使用的运行配置。

启动后默认访问：

• API 根路径：http://localhost:8000
• OpenAPI UI：http://localhost:8000/swagger-ui.html
• 产品入口：http://localhost:8000/

常用页面入口：

入口	路径
Admin 后台管理端	http://localhost:8000/admin/
App H5 用户端	http://localhost:8000/app/
PC 用户端	http://localhost:8000/pc/
企业安装向导	http://localhost:8000/install/
开发文档	http://localhost:8000/docs/

使用 Docker 完整环境并启用 Nginx profile 时，统一从 http://127.0.0.1:8080/ 进入产品导航页，再跳转后台管理、移动端 H5、PC 站点、开发文档和 OpenAPI。

账号初始化

项目不提供固定默认测试账号，也不内置默认密码。

首次部署通过 安装向导 创建首个超级管理员。安装向导会在系统没有用户时创建管理员并挂载 super-admin 角色，安装完成后入口会自动失效或回到产品入口。

项目只保留 Install 受控管理员初始化入口，不再提供平行初始化 API；不引入安装模块时，需要由应用装配方自行提供受控的部署期初始化流程或预置管理员数据。

普通用户账号不通过默认种子生成。用户端账号应通过账号密码注册、短信 / 邮箱验证码注册、OAuth / Telegram / 钱包等外部身份登录创建。前端是否展示注册入口，以 GET /api/v1/auth/capabilities 返回的注册能力为准。

Lite 兼容模式

普通开发不推荐使用 lite，也不要把它作为绕开 MySQL / Redis 等基础依赖的默认方案。项目保留该 profile 只用于历史兼容、隔离诊断或极少数单进程验证场景：

• 数据库使用 H2 文件
• Cache / Redis 能力使用内存或文件实现替代
• H2 文件默认放在 storage/database/
• 默认 H2 连接参数已经处理 Liquibase 二次启动识别问题；不要通过删除数据库文件来规避迁移错误。

普通功能开发、联调、截图和业务验收应使用默认 dev profile，并启动 MySQL / Redis 等真实基础设施。lite 不作为生产、多实例或日常开发建议。

目录语义

目录	说明
storage/runtime/	临时运行文件，可删除
storage/runtime/cache/	文件缓存目录，实际缓存文件不进入 Git
public/	公开静态资源，可挂载到根路由访问
storage/runtime/logs/	Spring Boot 日志目录，实际日志文件不进入 Git
storage/	存储根目录，包含私有持久化文件、运行临时目录和日志目录
docs/	框架正式文档入口，当前中文文档在 docs/zh-CN/

常用验证

./mvnw -pl spring-open-application -am test -DskipITs

文档或格式变更：

git diff --check

前端视图聚合构建：

./mvnw -f spring-open-views/pom.xml package -DskipTests -DskipITs

这个命令会依次构建 Docs、Install、App、Admin 和 PC 视图，并把静态产物导出到 public/docs、public/install、public/app、public/admin 和 public/pc。