微服务版启动

微服务版把业务服务拆成独立进程，向内提供全部业务接口，供 Web 端（工作台/控制台/开发者中心）与移动端（mdp-app）调用；配置中心、注册中心都依赖 Nacos，进程数量和本地开发常用的单体版差很多。如果只是本地改业务逻辑、调页面，建议先用单体版启动；需要按生产形态部署、验证服务拆分与网关路由时再看本文。

你要启动的链路	进程	看哪篇
业务服务（Web/移动端调用）	inner-gateway-server + workbench-server + console-server + open-server	本文
开放平台（对第三方提供接口）	sop-gateway-server + api-server	开放平台启动
定时任务（事件/回调重试等）	PowerJob + worker-server	定时任务启动

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

一、要启动什么

类别	名称	端口	启动类 / 说明
中间件	MySQL	3306	5.7 / 8.0，库名 `mdp`，见环境准备
中间件	Redis	—	6.0+
中间件	Nacos	8848	3.x，同时做配置中心和注册中心
进程	inner-gateway-server	23450	`GatewayServerApplication`（注意类名不带 inner），Web/移动端统一入口
进程	console-server	23451	`ConsoleServerApplication`
进程	open-server	23452	`OpenServerApplication`
进程	workbench-server	23453	`WorkbenchServerApplication`，SSO 认证中心在这里

与业务服务无关的进程

boot-server（23455）不启动——它的功能由 inner-gateway + workbench + console + open 四个进程合起来提供；内置的 zookeeper-server 也不启动，微服务版统一用 Nacos；
api-server（23454）、sop-gateway-server（23456）属开放平台链路，见开放平台启动；
worker-server（23457）、PowerJob（17700）属定时任务链路，见定时任务启动。

二、导入数据库

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

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

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

三、准备 Nacos 配置（关键）

微服务版的业务进程本地只带一个 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_20261005165133.zip（文件名带导出时间戳，以仓库 docs/ 下实际文件为准）。

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 注册中心地址指向你的 Nacos，见开放平台启动。 api-server 即可以提供接口给开放平台调用，也可以提供接口给业务微服务使用。

导出包内容

zip 内为 DEFAULT_GROUP/ 下的 8 个 yml ，其他TEXT格式的配置，是 api 服务启动时自动给dubbo接口生成的，不用理会。

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

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

四、编译打包

1. 环境参数从哪来

业务进程的本地 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. 选择 profile 并编译

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

编译后得到的jar是 ${project-prefix}-${artifactId}.jar，例如 md-console-server.jar、md-inner-gateway-server.jar。

3. 前端切到微服务模式

前端要切到 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）就绪后，按下面顺序启动。顺序不是硬性要求——Feign 不会在启动时校验对端——但注册中心先行、网关收尾，日志更容易看懂：

Nacos（含配置导入完成）
workbench-server → WorkbenchServerApplication（SSO 认证中心）
console-server → ConsoleServerApplication
open-server → OpenServerApplication
inner-gateway-server → GatewayServerApplication

需要开放平台或定时任务时，再按对应章节启动 api-server / sop-gateway-server（开放平台启动）与 worker-server / PowerJob（定时任务启动）。

启动后自检

检查项	期望结果
Nacos → 服务列表（`DEFAULT_GROUP`）	出现 4 个业务应用实例：inner-gateway-server、workbench-server、console-server、open-server（启动开放平台后另有 api-server）。注意 sop-gateway-server、worker-server 不在这里——它们只引 Dubbo 的 Nacos 客户端，不注册 Spring Cloud 实例
浏览器访问网关	`http://localhost:23450/api/workbench/` 能被路由到 workbench-server（网关路由是 `Path=/workbench/` + `StripPrefix=1`）
前端三端	工作台 7700、控制台 7710、开发者中心 7720 能登录，见前端启动

六、和单体版的具体差异

维度	单体版	微服务版
业务后端进程数	1（boot-server）	核心 4 个（inner-gateway + 3 业务服务）
配置位置	全在 jar 内（`application.yml` + `application-{env}.yml`）	业务进程在 Nacos（jar 内只留占位符与导入声明）；worker、sop-gateway 仍在 jar 内
Nacos 角色	在生产环境使用，给worker、sop-gateway做 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}/**`）
前端请求 404 / 跨域	`VITE_GLOB_MODE` 仍是 `boot`（单体模式会剥掉一段路径），改成 `cloud` 后重启 dev server
Sentinel 控制台看不到服务	不影响功能。`mdp.sentinel.dashboard` / `SENTINEL_DASHBOARD` 未指向可用控制台时只有监控与规则推送不可用
开放接口/定时任务相关问题	已拆到对应章节：开放平台 · 常见问题、定时任务 · 常见问题