微服务版启动

微服务版把核心业务拆成独立进程，配置中心、注册中心都依赖 Nacos，进程数量和本地开发常用的单体版差很多。如果只是本地改业务逻辑、调页面，建议先用单体版启动；需要按生产形态部署、验证服务拆分与网关路由时再看本文。

整体设计（为什么这样拆、worker-server 与 api-server 的分工）见架构介绍，各服务的功能清单见服务介绍，配置文件的分层与优先级见后端配置-微服务版。

一、要启动什么

类别	名称	端口	启动类 / 说明
中间件	MySQL	3306	5.7 / 8.0，库名 `mdp`，见环境准备
中间件	Redis	—	6.0+
中间件	Nacos	8848	3.x，同时做配置中心和注册中心
进程	inner-gateway-server	23450	`GatewayServerApplication`（注意类名不带 inner）
进程	console-server	23451	`ConsoleServerApplication`
进程	open-server	23452	`OpenServerApplication`
进程	workbench-server	23453	`WorkbenchServerApplication`，SSO 认证中心在这里
进程	api-server	23454	`ApiServerApplication`，对外开放接口实现
进程	sop-gateway-server	23456	`SopGatewayServerApplication`，第三方入口
进程	worker-server	23457	`WorkerServerApplication`，只做定时任务执行器
进程	PowerJob	17700	开源调度中心，`PowerJobServerApplication`

单体版有、微服务版没有的进程

boot-server（23455）不启动——它的功能由 inner-gateway + workbench + console + open 四个进程合起来提供。内置的 zookeeper-server 也不启动，微服务版统一用 Nacos。

二、导入数据库

与单体版完全相同，一个库共用：

CREATE DATABASE IF NOT EXISTS `mdp` CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci;

导入 docs/mdp.sql。已导入过请勿重复导入，会覆盖数据。

三、准备 Nacos 配置（关键）

微服务版的 5 个业务进程（inner-gateway / console / open / workbench / api）本地只带一个 application.yml，其余配置全部从 Nacos 拉取。它们的 spring.config.import 写死了 4 个 dataId：

# console-server/src/main/resources/application.yml
spring:
  config:
    import:
      - nacos:common.yml?group=${mdp.nacos.group}&refresh=true
      - nacos:redis.yml?group=${mdp.nacos.group}&refresh=true
      - nacos:db.yml?group=${mdp.nacos.group}&refresh=true
      - nacos:${spring.application.name}.yml?refresh=true   # 例如 console-server.yml

所以 Nacos 里必须存在这些 dataId，服务才能启动。项目已提供一份可直接导入的导出包：docs/nacos_config_export_20260520100658.zip。

1. 创建命名空间

在 Nacos 控制台新建一个命名空间，并记下命名空间 ID（一串 UUID，不是名称）。配置里的 mdp.nacos.namespace 用的是 ID，填错会表现为「项目启动报错」。

2. 导入配置

选中刚建的命名空间 → 配置管理 → 导入，上传导出包。导入后会得到 8 个 dataId（group 都是 DEFAULT_GROUP）：

dataId	作用	首次部署必须检查的项
`common.yml`	全服务共用：`mdp.system`、`mdp.scan`、`mdp.echo` 等	`mdp.system.mode` 必须是 `cloud`
`redis.yml`	`spring.data.redis`、`spring.cache`、`mdp.cache`	host、port、password、database
`db.yml`	`spring.datasource.druid`、MyBatis-Flex、ID 生成策略	url、username、password
`inner-gateway-server.yml`	端口 23450、网关路由、`mdp.ignore` 鉴权白名单	路由与端口
`workbench-server.yml`	端口 23453、`sa-token.sso-server`	SSO 相关地址
`console-server.yml`	端口 23451、文件存储、`sa-token.sso-client`	文件存储 `storage-path`
`open-server.yml`	端口 23452、springdoc 分组、`sa-token.sso-client`	—
`api-server.yml`	端口 23454、`dubbo`（含 `enabled: true`、注册中心地址）、文件存储	Dubbo 注册中心地址指向你的 Nacos

导出包里还有 Dubbo 元数据

zip 内的 mapping/…、dubbo/… 条目是导出时附带的 Dubbo 元数据残留，导入后可以直接删除，不影响运行。

3. worker-server、sop-gateway-server 不在 Nacos 里

这两个进程不接入 Nacos 配置中心（application.yml 里没有 spring.config.import，导出包里也没有它们的 dataId），配置仍像单体版那样写在 jar 内的 application-{env}.yml 中。Nacos 对它们只承担 Dubbo 服务发现。

微服务版部署 worker-server 务必关掉开放接口能力

worker-server 同时打包了「开放接口」和「定时任务执行器」两种能力，test / prod 环境出厂值是两项全开。微服务版里开放接口应由 api-server 承担，所以要显式覆盖：

# worker-server/src/main/resources/application-{env}.yml
dubbo:
  enabled: false        # 不导出 provider、不向网关上报接口，只做执行器
powerjob:
  worker:
    enabled: true       # 执行器角色必须开

漏掉 dubbo.enabled: false 的后果：worker-server 会和 api-server 注册成同一批开放接口的 provider，被 sop-gateway-server 轮询到，表现为「同样的接口有时通有时不通」。开关原理见架构介绍 3.3 节。

四、编译打包

1. 环境参数从哪来

5 个业务进程的本地 application.yml 只有占位符，实际值有两个来源，环境变量优先：

mdp:
  nacos:
    ip: ${NACOS_IP:@config.nacos.ip@}
    port: ${NACOS_PORT:@config.nacos.port@}
    namespace: ${NACOS_NAMESPACE:@config.nacos.namespace@}
    username: ${NACOS_USERNAME:@config.nacos.username@}
    password: ${NACOS_PASSWORD:@config.nacos.password@}
  sentinel:
    dashboard: ${SENTINEL_DASHBOARD:@config.sentinel.dashboard@}

@config.xxx@ 部分：编译期由 mdp-apps/src/main/filters/config-{env}.properties 替换，改这里要重新打包；
大写环境变量部分：运行期注入，不用重新打包，适合 CI/CD 与多环境部署。

环境变量	对应 filters 键
`NACOS_IP` / `NACOS_PORT`	`config.nacos.ip` / `config.nacos.port`
`NACOS_NAMESPACE`	`config.nacos.namespace`（填命名空间 ID）
`NACOS_USERNAME` / `NACOS_PASSWORD`	`config.nacos.username` / `config.nacos.password`
`SENTINEL_DASHBOARD`	`config.sentinel.dashboard`

机制与可覆盖的其他键见编译期配置（filters）。

2. 改 sop-gateway-server 的注册中心依赖

微服务版必须改以下配置：

<!-- mdp-apps/md-gateway/sop-gateway-server/pom.xml，dev profile 内 -->

<!-- 修改前 -->
<dependencies>
    <!-- zookeeper注册中心 -->
    <dependency>
        <groupId>org.apache.dubbo</groupId>
        <artifactId>dubbo-zookeeper-curator5-spring-boot-starter</artifactId>
    </dependency>
</dependencies>

<!-- 修改后 -->
<dependencies>
    <!-- nacos注册中心：微服务版与 api-server 保持一致 -->
    <dependency>
        <groupId>org.apache.dubbo</groupId>
        <artifactId>dubbo-nacos-spring-boot-starter</artifactId>
    </dependency>
</dependencies>

只换依赖还不够，sop-gateway-server 不接 Nacos 配置中心，注册中心地址来自它自己的 yml，得一并改：

# 修改前：sop-gateway-server/src/main/resources/application-dev.yml
dubbo:
  registry:
    address: zookeeper://localhost:2181

# 修改后：地址、账号、命名空间按你的 Nacos 填写，命名空间填 ID
dubbo:
  registry:
    address: nacos://<NACOS_HOST>:<NACOS_PORT>
    parameters:
      namespace: <NACOS_NAMESPACE_ID>
      username: <NACOS_USERNAME>
      password: <NACOS_PASSWORD>

上面的尖括号值不要明文写死。sop-gateway-server 的 pom.xml 已开启资源过滤（:175-182）并挂了 filters 文件（:163-165），可以直接用和其他服务一致的写法，运行期用环境变量覆盖、编译期由 mdp-apps/src/main/filters/config-{env}.properties 兜底：

dubbo:
  registry:
    address: nacos://${NACOS_IP:@config.nacos.ip@}:${NACOS_PORT:@config.nacos.port@}
    parameters:
      namespace: ${NACOS_NAMESPACE:@config.nacos.namespace@}
      username: ${NACOS_USERNAME:@config.nacos.username@}
      password: ${NACOS_PASSWORD:@config.nacos.password@}

改完后 dev 环境就能直接联调微服务版开放接口；test / prod profile 本来就引 Nacos，不需要这处改动。

worker-server 要不要改

不用。微服务版建议把 worker-server 配成纯执行器（dubbo.enabled: false），Dubbo 自身的自动装配会被这个开关整体关掉，根本不会去连注册中心，所以它的 dev profile 仍引 ZooKeeper 也无所谓。

只有当你让 worker-server 在微服务版里也承担开放接口（dubbo.enabled: true）时，才需要按同样方式替换它的注册中心客户端并改地址（位置：worker-server/pom.xml:175）。

3. 选择 profile 并编译

# 默认 dev（activeByDefault）
mvn clean install
# 指定测试环境
mvn clean install -Ptest
# 指定生产环境
mvn clean install -Pprod

产物名是 ${project-prefix}-${artifactId}.jar，例如 md-console-server.jar、md-inner-gateway-server.jar。

test / prod profile 下 sop-gateway-server 的注册中心客户端本来就是 Nacos；只有以 dev profile 打包本地联调时，才需要上一步那处改动。

4. 前端切到微服务模式

前端要切到 cloud 模式，代理才会把 /api/** 原样转发到 http://localhost:23450（网关）。不改文件的办法是用带模式后缀的启动命令：

pnpm dev:cloud                                        # 交互式选择应用
pnpm --filter @vben/web-workbench run dev:cloud       # 直接起指定应用

改 apps/*/.env 的 VITE_GLOB_MODE=cloud 也可以，但会影响 pnpm dev:workbench 等所有不带后缀的命令。详见前端启动与前端配置。

五、启动

中间件（MySQL、Redis、Nacos）就绪后，按下面顺序启动。顺序不是硬性要求——Dubbo 的 consumer.check 和 registry.check 都是 false，Feign 也不会在启动时校验对端——但注册中心先行、网关收尾，日志更容易看懂：

Nacos（含配置导入完成）
inner-gateway-server → GatewayServerApplication
workbench-server → WorkbenchServerApplication（SSO 认证中心）
console-server → ConsoleServerApplication
open-server → OpenServerApplication
api-server → ApiServerApplication
worker-server → WorkerServerApplication（已按第三节配好两个开关）
sop-gateway-server → SopGatewayServerApplication（dev 包需先完成第四节第 2 步，否则它连的是 ZooKeeper）
PowerJob → 部署方式与单体版完全一致（server.port=17700、控制台需预建应用 MDP），步骤见单体版启动第四节

启动后自检

检查项	期望结果
Nacos → 服务列表（`DEFAULT_GROUP`）	出现 5 个应用实例：inner-gateway-server、workbench-server、console-server、open-server、api-server。注意 sop-gateway-server、worker-server 不在这里——它们只引 Dubbo 的 Nacos 客户端，不注册 Spring Cloud 实例
Nacos → 服务列表（Dubbo 分组，默认 `dubbo`）	出现 4 个开放接口的 provider 条目（Org / User / Msg / Token），提供者应为 api-server
浏览器访问网关	`http://localhost:23450/api/workbench/` 能被路由到 workbench-server（网关路由是 `Path=/workbench/` + `StripPrefix=1`）
PowerJob 控制台	应用 `MDP` 下有在线 worker
前端三端	工作台 7700、控制台 7710、开发者中心 7720 能登录，见前端启动

六、和单体版的具体差异

维度	单体版	微服务版
后端进程数	1（boot）+ 按需 2～3	核心 5 个 + 开放接口 2 个 + 执行器 + 调度器
配置位置	全在 jar 内（`application.yml` + `application-{env}.yml`）	5 个业务进程在 Nacos（jar 内只留占位符与导入声明）；worker、sop-gateway 仍在 jar 内
Nacos 角色	仅 test / prod 做 Dubbo 注册中心	配置中心 + 服务发现 + Dubbo 注册中心，三职缺一不可
跨域调用	`*-boot-impl` 进程内直调	`*-cloud-impl` 经 OpenFeign 调对端 web 层
Dubbo 用途	开放平台链路（sop-gateway → worker-server）	只有 api-server 和 sop-gateway 引 Dubbo（sop-gateway → api-server）
worker-server 角色	执行器 + 开放接口实现	只做执行器，靠 `dubbo.enabled: false` 关掉另一职
SSO 认证中心	boot-server	workbench-server
前端入口	直连 boot-server:23455（前端会去掉一段路径）	统一走 inner-gateway:23450（`/api/{服务段}/**`）

七、常见问题

现象	原因与处理
启动即失败，日志提到 `config dataId not exist` / 拉取配置为空	Nacos 里缺 dataId。核对命名空间 ID、`group=DEFAULT_GROUP`，以及 `{服务名}.yml` 是否与 `spring.application.name`（= Maven artifactId，如 `console-server`）完全一致
连不上 Nacos	检查 `NACOS_IP` / `NACOS_PORT` 环境变量与 `config-{env}.properties` 是否指向同一套；Nacos 开了鉴权时 `NACOS_USERNAME` / `NACOS_PASSWORD` 必须给
网关返回 503	目标服务没注册到同一个命名空间与 group；或路由前缀写错（必须是 `/api/{workbench\|console\|open}/**`）
第三方调开放接口报找不到服务	注册中心不一致：api-server 固定用 Nacos，而 sop-gateway-server 以 `dev` profile 打包时连的是 ZooKeeper。按第四节第 2 步换依赖并改 `dubbo.registry.address`
定时任务不执行	worker-server 没起、`powerjob.worker.enabled` 为 `false`（dev 出厂就是 `false`）、或 PowerJob 里没建应用 `MDP`
开放接口时通时不通	worker-server 漏配 `dubbo.enabled: false`，与 api-server 同时成了 provider
前端请求 404 / 跨域	`VITE_GLOB_MODE` 仍是 `boot`（单体模式会剥掉一段路径），改成 `cloud` 后重启 dev server
Sentinel 控制台看不到服务	不影响功能。`mdp.sentinel.dashboard` / `SENTINEL_DASHBOARD` 未指向可用控制台时只有监控与规则推送不可用