快速开始

本节使用 Docker 数据服务 + 本机 Java + 本机前端 完成本地启动。先完成 准备工作。所有后端命令都在含 pom.xml 和 scripts/ 的 art-design-pro-x-java 根目录执行。

1. 启动 MySQL 和 Redis

先打开 Docker Desktop，等待 Engine 运行，然后执行：

sh scripts/deploy.sh dev

脚本会准备开发配置、生成缺少的凭据，并启动两个数据服务。首次会构建 Java 镜像来生成和检查配置，所以看到镜像构建输出是正常的。

看到 MySQL、Redis 均为 Healthy 后继续。此时本机 Java 后端还未启动。

生成的文件	用途
config/application-dev.yml	本机 Java 的数据库、Redis、存储等配置
deploy/compose.dev.yml	Docker 资源和 MySQL 管理员凭据

默认 MySQL 为 127.0.0.1:3306/art_design，Redis 为 127.0.0.1:16379。已有配置会保留，无需每次复制模板或填写新密码。若出现 address already in use，先按 端口冲突处理 调整端口，再重试。

使用已有 MySQL / Redis（替代本步骤）

已有服务时不执行 dev。首次安装准备一个空 MySQL 8 数据库，例如由有建库权限的账号执行：

CREATE DATABASE art_design CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

将 config/application-dev.example.yml 复制为 config/application-dev.yml，填写实际连接信息。文件已存在时直接编辑，不覆盖它。应用账号需要该库迁移建表与读写权限；Redis 无密码才填写空字符串，自装 Redis 常用 6379。

配置示例见 应用配置。不导入其他后端的 SQL，由 Java 首次启动时执行 Flyway 初始化。

2. 启动 Java 后端（三选一）

三种方式都使用 JDK 21、dev 环境和根目录 config/。一次只运行一种方式，否则会重复占用 13001。

命令行启动

node scripts/dev.mjs

脚本先编译并安装各模块，再启动 art-admin。终端持续运行是正常现象，停止时按 Ctrl+C。日志也写入根目录 logs/art-design-pro-x-java.log。

IntelliJ IDEA 调试

打开后端根目录并完成 Maven 导入。在 Run → Edit Configurations 创建 Application 配置：

字段	值
Name	Java 后端（本地开发）
JRE / JDK	21
Main class	com.artd.ArtDesignApplication
Classpath module	art-admin
Working directory	后端根目录，可使用 $PROJECT_DIR$
Program arguments	--spring.profiles.active=dev --spring.config.additional-location=file:./config/

保存后点击 Run 或 Debug。其他公共模块无需单独启动。

VS Code 调试

1. 打开后端根目录，安装推荐 Java 扩展，等待 Java/Maven 导入完成。
2. 确认项目使用 JDK 21。
3. 进入左侧 运行和调试，选择 Java 后端（本地开发）。
4. 按 F5 启动。

仓库的 .vscode/launch.json 已设置主类、工作目录和配置路径。Spring Boot Dashboard 的自动运行配置若没有带上这些设置，可能读不到根目录 YAML；首次运行优先使用上述随包配置。

确认启动成功

首次启动 Flyway 自动创建表和初始数据。等待日志出现 Art Design Pro X 启动成功，再打开：

• 健康检查：http://localhost:13001/actuator/health，应返回 {"status":"UP"}。
• 接口文档：http://localhost:13001/swagger-ui.html，开发环境默认开启。

如已修改端口，请替换上述地址。健康检查未通过时，先处理后端控制台中的首个关键错误，再启动前端，排查入口见 常见问题。

3. 启动前端

另开终端进入 art-design-pro-x-ui。编辑该项目 .env.development，确认只保留一个启用的代理目标：

VITE_API_URL = /
VITE_API_PROXY_URL = http://localhost:13001

如果存在指向 Nest.js 13000 的代理行，将其注释。然后在前端目录执行：

pnpm install
pnpm dev

浏览器打开终端显示的地址，默认 http://localhost:3000。pnpm install 在首次或依赖变化时运行；修改代理后需重启 pnpm dev。

4. 第一次登录

全新数据库的初始账号为 admin / Admin@2026。登录后修改密码，刷新一次浏览器确认会话正常，再进入文件中心试传一张图片。

列表为空是正常的

交付库包含管理员、角色、菜单和基础配置，不包含演示部门、商品、仓库、库存、订单或审批实例。按照 首次使用 配置自己的业务数据。

检查项	预期结果
登录与首页	成功登录，菜单正常展示
刷新浏览器	能恢复当前会话，无反复跳回登录页
文件中心	图片上传、预览和下载正常
后端控制台	没有持续数据库、Redis 连接错误

未配置 AI、OSS 或在线支付不影响完成上述步骤。

日常启动与停止

数据服务仍运行时，直接启动后端和前端。数据服务已停止时，先执行 sh scripts/deploy.sh dev，无需重新初始化配置。

停止前后端分别使用终端 Ctrl+C 或 IDE 停止按钮。需要停止开发数据服务，可在后端根目录执行：

docker compose --env-file /dev/null -p art-design-pro-x-java-dev -f docker-compose.yml -f deploy/compose.dev.yml stop mysql redis

这会保留数据卷，下次仍用 dev 启动。sh scripts/deploy.sh status 查看的是生产项目，本地开发状态与日志的命令见 常见问题。

公共模块修改后，停止本地后端并重新运行 node scripts/dev.mjs，让依赖模块重新安装。接下来阅读 首次使用 或 项目结构。