micro-java 本地启动

本文在 MySQL 已就绪 的前提下，启动 micro-java 全套微服务并与 Web 管理后台联调。

环境要求

工具	版本
JDK	17+
Maven	3.9+
Docker Desktop	MySQL；建议同时用容器跑 Nacos / RabbitMQ
Node.js + pnpm	仅用于 pnpm --filter @xichen-micro/* dev 包装命令

1. 启动 MySQL

docker compose up -d

首次启动自动执行 contracts/sql/schema.sql。

2. 启动中间件

micro-java 至少需要 Nacos 与 RabbitMQ（system-service 默认 app.messaging.type=rabbitmq）。

方式 A：Docker 快速拉起（推荐）

# Nacos 2.x（单机模式）
docker run -d --name xichen-nacos -p 8848:8848 -p 9848:9848 \
  -e MODE=standalone \
  nacos/nacos-server:v2.3.2

# RabbitMQ（含管理界面 :15672，默认 guest/guest — 生产请改账号）
docker run -d --name xichen-rabbitmq -p 5672:5672 -p 15672:15672 \
  -e RABBITMQ_DEFAULT_USER=xichen \
  -e RABBITMQ_DEFAULT_PASS=xichen123 \
  rabbitmq:3-management

与 system-service 默认配置对齐：RABBITMQ_USER=xichen、RABBITMQ_PASSWORD=xichen123。

方式 B：简化本地（关闭可选组件）

若暂不安装 Seata，启动 system-service 前设置：

# PowerShell
$env:SEATA_ENABLED="false"

Seata 关闭后，assignRoles 的 @GlobalTransactional 退化为本地事务，RBAC 主流程仍可验证。

Kafka 仅在 MESSAGING_TYPE=kafka 时需要；默认 RabbitMQ 即可。

详见 中间件依赖。

3. 编译 Maven 多模块

cd packages/micro-java
mvn install -DskipTests

修改 xichen-common 或 xichen-domain 后须重复此步骤。

4. 启动微服务（顺序建议）

开 三个终端，先业务服务、最后网关：

# 终端 1 — 认证服务 :8081
pnpm --filter @xichen-micro/auth-service dev

# 终端 2 — 系统服务 :8082（可选 SEATA_ENABLED=false）
pnpm --filter @xichen-micro/system-service dev

# 终端 3 — 网关 :8080（等 Nacos 中已有上述两个实例）
pnpm --filter @xichen-micro/gateway dev

或在 packages/micro-java 目录：

mvn -pl auth-service spring-boot:run
mvn -pl system-service spring-boot:run
mvn -pl gateway spring-boot:run

5. 验证后端

curl http://localhost:8080/api/v1/health
# 期望 data.service = auth-service

curl -X POST http://localhost:8080/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d "{\"username\":\"admin\",\"password\":\"admin123\"}"

Nacos 控制台 http://localhost:8848/nacos（默认 nacos/nacos）应能看到 auth-service、system-service、gateway 注册。

6. 联调 Web 管理后台

pnpm --filter @xichen-full-stack/types build
pnpm --filter @xichen-full-stack/auth build
pnpm --filter @xichen-full-stack/api-client build

pnpm --filter web dev

packages/web/.env.development：

VITE_API_BASE_URL=http://localhost:8080

浏览器 http://localhost:5173 ，账号 admin / admin123。

7. 验证清单

• [ ] Nacos 中三个服务均为健康实例
• [ ] GET /api/v1/health 经网关正常
• [ ] 登录成功，侧边栏菜单显示
• [ ] 用户 / 角色 / 菜单 CRUD 可用
• [ ] 新建用户后 system-service 日志出现 [RabbitMQ] Received UserCreatedEvent
• [ ] 停止 auth-service 后，登录请求经网关返回 503 fallback（熔断演示）

常见问题

• Nacos 未启动 → gateway 报 503 或无法解析 lb://auth-service
• RabbitMQ 未启动 → system-service 启动失败（连接拒绝）
• JWT 校验失败 → 确认 auth-service 与 system-service 的 JWT_SECRET 一致
• 菜单为空 → 确认 system-service 已启动并完成 DataSeeder（依赖 MySQL 空库首次写入）

更多排障见 常见问题 — micro-java。

相关文档

• 概览
• 中间件
• 切换后端