单体版启动

为了方便本地开发，MDP 单体版支持按需启动：不同开发场景只起需要的进程，其余一律不用管。

开发场景	需要启动的进程	依赖中间件	worker-server 两个开关
前后端对接（Web / App 业务）	boot-server	mysql、redis	不涉及
对外开放接口	zookeeper-server、sop-gateway-server、worker-server	mysql、redis、zookeeper（dev）	dubbo.enabled: true powerjob.worker.enabled: false
定时任务	PowerJob、worker-server	mysql、redis	dubbo.enabled: false powerjob.worker.enabled: true
全功能自测	以上全部	mysql、redis、zookeeper（dev）	两项都 true（一次启动兼两职）

测试、生产环境

上表只是本地开发的裁剪方式。测试和生产环境必须启动全部进程才能提供全功能，且注册中心必须用 Nacos（内置 zookeeper-server 仅供开发演示）。微服务版的启动方式见微服务版启动，各服务职责与端口见服务介绍。

一、公共准备

无论哪个场景，下面 4 步都只做一次。

1. 准备中间件

中间件	版本	说明
MySQL	5.7 / 8.0（也支持达梦、PostgreSQL）	必装，见环境准备
Redis	6.0+	必装
ZooKeeper	3.x	仅「对外开放接口」场景需要。可以额外部署，也可以直接跑项目内置的 zookeeper-server（见第三节）

单体版的配置全部在 jar 内，不接 Nacos 配置中心，所以这一步不需要 Nacos（生产环境除外，它要用 Nacos 做 Dubbo 注册中心）。

2. 建库、导入 SQL

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

然后导入 docs/mdp.sql。

只需导入一次

mdp 库由 boot-server、worker-server、sop-gateway-server 三个服务共用，无论哪个场景都只需要准备一次。已导入过就不要重复导入，会覆盖表数据。

3. 编译根工程

在 IDEA 的 Maven 面板选择根工程 mdp 执行 install，或命令行执行：

# 若编译报错：找不到 mdp-parent ，可以先编译 mdp-parent ，然后再编译 根项目项目
mvn clean install

根工程聚合 mdp-parent、mdp-base、mdp-apps、mdp-sdk 四个模块。第一次编译耗时较长，之后可只编译改动的模块。

4. 确认要改哪个配置文件

服务	要改的文件	该环境文件里有什么
boot-server	mdp-apps/md-server/boot-server/src/main/resources/application-{env}.yml	只有 Redis、数据源
worker-server	mdp-apps/md-server/worker-server/src/main/resources/application-{env}.yml	Redis、数据源、dubbo.enabled、dubbo.registry.address、powerjob.worker.enabled
sop-gateway-server	mdp-apps/md-gateway/sop-gateway-server/src/main/resources/application-{env}.yml	Redis、数据源、dubbo.registry.address

{env} 取 dev / test / prod，由 application.yml 里的 spring.profiles.active: '@profile.active@' 决定——它是编译期由 Maven profile 注入的，默认 dev。

文件存储不在环境文件里

x-file-storage（含 storage-path）配在主 application.yml（boot-server 在 :307、worker-server 在 :297），不在 application-{env}.yml。要改文件存放目录，去主配置里改。

其余配置（缓存前缀、端口、MyBatis-Flex、sa-token、Dubbo 协议与超时等）也都在各自主 application.yml，首次使用不建议修改。

编译期占位符的完整机制见编译期配置（filters）。

三个服务的 Redis database 必须一致

boot-server、worker-server、sop-gateway-server 使用同一个 mdp.cache.cachePrefix: mdp，即共享同一套缓存（应用信息、接口元数据、登录态）。三者 spring.data.redis.database 不一致时，会出现「接口配好了却调不通」「缓存读了个空」这类很难定位的现象。

二、启动业务服务 boot-server

业务服务提供对内接口，供 Web 端、移动端调用，是绝大多数开发场景唯一需要启动的服务。

1. 修改 boot-server/src/main/resources/application-dev.yml（只有 Redis、数据源两块）：

   • Redis：host、port、password、database 按本地环境填写；
   • 数据源：url、username、password 按本地环境填写。若使用达梦、Oracle 等其他数据库，需同步修改 driverClassName 并替换 pom.xml 中的驱动。

   spring:
     data:
       redis:
         host: <REDIS_HOST>
         port: <REDIS_PORT>
         password: '<REDIS_PASSWORD>'
         database: 6          # 与 worker-server、sop-gateway-server 保持一致
     datasource:
       druid:
         driverClassName: com.mysql.cj.jdbc.Driver
         username: '<DB_USERNAME>'
         password: '<DB_PASSWORD>'
         url: jdbc:mysql://<DB_HOST>:3306/mdp?serverTimezone=Asia/Shanghai&characterEncoding=utf8&useUnicode=true&useSSL=false&autoReconnect=true&zeroDateTimeBehavior=convertToNull&allowMultiQueries=true&nullCatalogMeansCurrent=true

2. 如需修改文件存放目录，改 application.yml 的 x-file-storage，只需动 storage-path，其他参数不用改。开发环境默认本地存储方便调试，测试、生产环境务必换成 OSS：

   如何将存储修改为其他OSS，参考文档： x-file-storeage

   # boot-server/src/main/resources/application.yml
   dromara:
     x-file-storage:
       default-platform: localPlusExt   # localPlusExt 是项目增强的配置
       thumbnail-suffix: ".min.jpg"
       local-plus:
         - platform: localPlus
           domain: http://127.0.0.1:${server.port}/preview/   # 需与 path-patterns 保持一致，/ 结尾
           base-path: local-plus/
           path-patterns: /preview/**
           storage-path: <FILE_STORAGE_PATH>   # 文件存放根目录，例如 /data/mdp/、D:/data/mdp/
           enableStorage: true
           enableAccess: true

3. 启动 BootServerApplication：

   

4. 验证：boot-server 监听 23455。前端切到单体模式即可访问，三端地址 http://localhost:7700（工作台）、7710（控制台）、7720（开发者中心）——前端出厂就是 boot 模式，直接 pnpm dev 即可，步骤见前端启动。

boot-server 的 pom.xml 不引 Dubbo、不引 Nacos，也不做 Dubbo 注册——单体版核心业务链路是纯进程内调用，没有注册中心也能启动。

三、启动开放接口服务

需要「第三方调用 MDP 接口」时才按照本章节启动项目。开放接口由 sop-gateway-server（对外入口）+ worker-server（接口实现）构成，前者通过 Dubbo 泛化调用打到后者，因此必须有注册中心。

1. 启动 zookeeper-server（仅 dev）

不用额外安装 ZooKeeper：直接运行 ZookeeperRegistryServer 的 main 方法，它会在 2181 端口拉起一个嵌入式 ZooKeeper。

仅限开发演示

内置 ZooKeeper 禁止用于生产（启动时会打 WARN 日志提示）。测试、生产环境请改用 Nacos：把 Maven profile 切到 test / prod 重新编译，Dubbo 的注册中心依赖与地址会自动换成 Nacos。

2. 启动 sop-gateway-server

1. 数据库、SQL 已在第一节准备完成，此处不用重复导入。

2. 修改 sop-gateway-server/src/main/resources/application-dev.yml（这个文件只有三块配置）：

   spring:
     data:
       redis:
         host: <REDIS_HOST>
         port: <REDIS_PORT>
         password: '<REDIS_PASSWORD>'
         database: 6          # 与 boot-server、worker-server 保持一致
     datasource:
       druid:
         driverClassName: com.mysql.cj.jdbc.Driver
         username: '<DB_USERNAME>'
         password: '<DB_PASSWORD>'
         url: jdbc:mysql://<DB_HOST>:3306/mdp?serverTimezone=Asia/Shanghai&characterEncoding=utf8&useUnicode=true&useSSL=false&autoReconnect=true&zeroDateTimeBehavior=convertToNull&allowMultiQueries=true&nullCatalogMeansCurrent=true
   
   dubbo:
     registry:
       address: zookeeper://localhost:2181   # dev 用内置 zookeeper；test/prod 换成 nacos://...

3. 启动 SopGatewayServerApplication：

   

sop-gateway-server 监听 23456，是第三方唯一可访问的入口，专属配置见开放平台网关配置。

3. 启动 worker-server（接口角色）

1. 修改 worker-server/src/main/resources/application-dev.yml：Redis、数据源同上，另外两处开关按「只跑开放接口」配置：

   dubbo:
     # ⭐️ 需要使用开放接口功能时开启
     enabled: true
     registry:
       # dev 使用本地 zookeeper（启动 ZookeeperRegistryServer 即可）
       address: zookeeper://localhost:2181
   
   powerjob:
     worker:
       # ⭐️ 只测开放接口、不测定时任务时保持 false（dev 出厂值就是 false）
       enabled: false

   application-dev.yml 全文就这四块（Redis、数据源、dubbo、powerjob），没有 x-file-storage——worker-server 的文件存储配置同样在主 application.yml（:297），需要存文件时去那里改 storage-path。

2. 启动 WorkerServerApplication：

   

worker-server 的配置不来自 Nacos

即使在微服务版里，worker-server 也不接入 Nacos 配置中心（它的 application.yml 没有 spring.config.import），Nacos 对它只承担 Dubbo 服务发现。所以切换环境时，worker-server 的数据库、Redis 都要单独在 application-{env}.yml 里改。原因见架构介绍第 4 节。

两处 Dubbo 细节：dubbo.protocol.port: -1 表示随机端口，无需为 Dubbo 单独放行固定端口（但容器化部署时要注意网络策略）；dubbo.consumer.retries: 0 是有意关闭重试，避免超时重试导致服务端重复处理同一请求。

四、启动定时任务

定时调度使用开源项目 PowerJob：PowerJob 是调度器，MDP 把 worker-server 作为执行器（全项目只有 worker-server 引入 md-powerjob-worker-spring-boot-starter）。

1. 启动调度器 PowerJob

1. 下载源码：

   git clone https://github.com/PowerJob/PowerJob.git

2. 修改 powerjob-server-starter/src/main/resources/application-daily.properties：数据库连接、端口（必须是 17700，与 worker-server 的 powerjob.worker.server-address 保持一致），其他配置参阅 PowerJob 官方文档。

   ####### Database properties(Configure according to the the environment) #######
   spring.datasource.core.driver-class-name=com.mysql.cj.jdbc.Driver
   spring.datasource.core.jdbc-url=jdbc:mysql://<DB_HOST>:3306/powerjob-daily?useUnicode=true&characterEncoding=UTF-8&serverTimezone=Asia/Shanghai
   spring.datasource.core.username=<DB_USERNAME>
   spring.datasource.core.password=<DB_PASSWORD>
   
   ####### Storage properties(Delete if not needed)  #######
   oms.storage.dfs.mysql_series.driver=com.mysql.cj.jdbc.Driver
   oms.storage.dfs.mysql_series.url=jdbc:mysql://<DB_HOST>:3306/powerjob-daily?useUnicode=true&characterEncoding=UTF-8&serverTimezone=Asia/Shanghai
   oms.storage.dfs.mysql_series.username=<DB_USERNAME>
   oms.storage.dfs.mysql_series.password=<DB_PASSWORD>
   
   # 必须与 worker-server 的 powerjob.worker.server-address 端口一致
   server.port=17700

   需要单独准备一个 PowerJob 使用的库（示例 powerjob-daily），建表方式以 PowerJob 官方文档为准。

3. 编译源码：

   

4. 启动 PowerJobServerApplication：

   

5. 在 PowerJob 控制台新建应用，名称必须为 MDP（worker-server/src/main/resources/application.yml 里的 powerjob.worker.app-name: MDP）。

   这一步不能省

   应用未预先注册时 worker 启动会失败——这是 PowerJob 官方 starter 的 fail fast 行为（PowerJobAutoConfiguration 要求 appName 与提交到 server 的应用名一致），报错信息里会直接点出 appName。

2. 启动执行器 worker-server

1. 修改 worker-server/src/main/resources/application-dev.yml，按「只跑定时任务」配置两个开关：

   dubbo:
     # ⭐️ 只测定时任务、不测开放接口时关闭，可省掉 zookeeper 与 sop-gateway-server
     enabled: false
   
   powerjob:
     worker:
       # ⭐️ 作为执行器，这里必须是 true
       enabled: true

2. 启动 WorkerServerApplication（同第三节第 3 步，截图一致，此处不再重复）。

3. 验证：回到 PowerJob 控制台，应用 MDP 下应能看到在线 worker 实例；新建一个测试任务指定该应用，执行后能在 worker-server 日志中看到执行记录。

一次启动兼任两职

把 dubbo.enabled 和 powerjob.worker.enabled 同时设为 true，worker-server 就同时承接开放接口与定时任务——单体版正是靠这个组合少起一个进程。两个开关的源码依据、四种组合的效果以及各环境出厂值见架构介绍 3.3 节。

五、端口与启动类速查

服务	启动类	端口
boot-server	BootServerApplication	23455
worker-server	WorkerServerApplication	23457
sop-gateway-server	SopGatewayServerApplication	23456
zookeeper-server（内置）	ZookeeperRegistryServer	2181
PowerJob 调度中心	PowerJobServerApplication	17700

单体版的推荐启动顺序（箭头指向谁谁就先启动）：

六、常见问题

现象	原因与处理
worker-server 启动报 serverAddress can't be null 或连不上调度中心	powerjob.worker.enabled 为 true 但没起 PowerJob。不测定时任务就把它设为 false；别用 allow-lazy-connect-server 代替开关
任务在 PowerJob 上创建了但一直不执行	检查是否按第四节第 5 步注册了应用 MDP，以及 worker 在线状态、server-address 端口是否为 17700
开放接口调用报找不到服务提供者	注册中心没起（dev 的 zookeeper-server）、worker-server 的 dubbo.enabled 为 false、或 worker 与网关连的不是同一个注册中心
接口配好了却调不通、缓存像没生效	三个服务的 spring.data.redis.database 不一致（见第一节末尾提醒）
前端请求 404	VITE_GLOB_MODE 必须是 boot，且 VITE_PROXY 中 boot 那条的 target 端口与 boot-server 一致（23455），见前端配置
测试/生产环境误用内置 zookeeper	内置 ZooKeeper 仅供演示。切 Maven profile 到 test / prod 重新编译，注册中心会自动换成 Nacos，地址由 @config.nacos.*@ 注入，见编译期配置（filters）