准备工作

本页帮助你确认源码和环境是否准备齐全。安装完成后进入快速开始，按步骤启动数据服务、后端和前端。

1. 确认拿到配套源码

使用与你购买版本配套的 Java 后端和管理端源码。建议放在同一父目录，便于切换终端；两个目录之间没有必须保持相对路径的运行依赖。

text

工作目录/
├── art-design-pro-x-java/   # 后端：含 pom.xml、mvnw、scripts/
└── art-design-pro-x-ui/     # 前端：含 package.json、src/

用 IDE 打开后端的整个根目录，等待 Maven 多模块导入完成。只打开 art-admin 会遗漏其他模块和根目录配置。源码获取与授权以你的购买交付方式为准，不需要另找公开仓库替代商用源码。

场景	推荐方式	继续阅读
本机体验或修改源码	Docker 运行 MySQL/Redis，本机运行 Java 和前端	快速开始
已有 MySQL/Redis	填写已有连接，本机运行 Java 和前端	快速开始中的“使用已有数据服务”
部署到客户服务器	随包 Docker 运行后端和数据服务，独立部署前端	部署运维
使用客户已有数据库	JAR 或独立应用容器连接已有服务	部署运维中的“JAR 交付”

首次本地体验建议使用第一种。sh scripts/deploy.sh dev 是本地数据服务入口，update 是生产部署入口，两者使用不同的配置和数据卷。

工具	要求	用途
JDK	21	编译和运行 Java；IDE 项目 SDK 也选 21
Docker	Docker Desktop，或 Engine + Compose v2（支持 `--wait`）	随包 MySQL/Redis；自备数据服务时可跳过
Node.js	20.19+	前端和 `scripts/dev.mjs` 启动脚本
pnpm	8.8+	前端依赖安装与启动
Maven	仓库已提供 Wrapper	无需额外安装 Maven

在后端根目录逐项检查：

bash

java -version
./mvnw -version
node -v
pnpm -v
docker version
docker compose version

Java 和 Maven 输出的 Java 版本都应为 21。docker version 应能连接 Server；只有 Client 信息通常说明 Docker Engine 尚未启动。首次构建需下载 Maven 依赖和 Docker 镜像，耗时取决于网络。

Windows 用户

PowerShell 中将 ./mvnw 换成 .\mvnw.cmd。node scripts/dev.mjs 和前端 pnpm 命令可以在 PowerShell 执行。

随包 sh scripts/deploy.sh 使用 POSIX Shell，建议在 Docker Desktop 已启用 WSL 2 集成的环境执行，并将源码、JDK、IDE 终端放在同一 WSL 环境中。不要把 macOS 的 /opt/homebrew 路径复制到 Windows。

macOS 已装 JDK 21，新终端仍显示 Java 17

安装 JDK 与设置默认 JDK 是两件事。先找到实际 JDK 21 目录，再将 JAVA_HOME 及其 bin 写入当前 Shell 的启动文件；仅在终端执行 export 只对当前会话生效。

例如使用 Homebrew 安装 openjdk@21 的 zsh 用户，可在 ~/.zshrc 的 Homebrew 初始化之后添加：

bash

export JAVA_HOME="$(brew --prefix openjdk@21)/libexec/openjdk.jdk/Contents/Home"
export PATH="$JAVA_HOME/bin:$PATH"

保存后重新打开终端，再检查 java -version、./mvnw -version。IDE 另外选择 JDK 21；修改 Shell 配置不会自动修改 IDE 的项目 SDK。

服务	本地默认端口	配置入口
前端	3000	前端开发服务，以启动终端显示为准
Java	13001	`config/application-dev.yml` 的 `server.port`
MySQL	3306	同一 YAML 的 JDBC URL
Redis	16379	同一 YAML 的 `spring.data.redis.port`

已经安装本机 MySQL 时，3306 可能被占用。可以保留它，将本项目 Docker MySQL 的本机端口改为 13306，具体步骤见端口冲突处理。删除容器或清空数据库不能释放其他进程占用的端口。