开发环境准备
工具与平台
| 项目 | 用途 |
|---|---|
| Java 17、Maven | 编译后端，版本与 Macula Boot Parent 保持一致 |
| Node.js 22、npm | 当前 Samples Admin 的 Dockerfile 使用 Node 22；按 package-lock.json 安装依赖 |
| Docker Compose v2 | 启动本地中间件或完整应用容器 |
| Macula Cloud | 已运行的 Gateway、IAM、System，提供登录、菜单、用户与权限能力 |
Samples 不重复部署认证中心和系统管理。开始前，在 Macula Cloud 中登记 macula-samples-admin-bff 应用及管理端使用的 OAuth Client。
获取源码
git clone https://github.com/macula-projects/macula-samples.git
cd macula-samples
单个仓库包含后端模块、Admin 前端和部署目录。将根 pom.xml 导入 IDE，即可加载全部后端 Maven 模块；Admin 在自己的目录安装前端依赖。
也支持多仓模式，各模块可在独立仓库中维护，通过工作区统一组织，参考 macula-samples-workspace。本章后续步骤以单仓项目为准。
本地连接准备
Samples 的默认宿主机端口与 Macula Cloud 分开：MySQL 23306、Redis 26379、Nacos 28848、Samples Gateway 6000、Samples Admin 5800。
在 deploy/.env 中维护 Compose / Vite 使用的本地环境值。IDE 启动 Java 服务时使用 local profile，需覆盖的值在 IDE 环境变量中显式设置，Java 不会自动读取该 .env 文件。