重要配置项详解
本文汇总 MDP 平台的重要配置项，逐项给出可选值、默认值、建议值，并标注单体版与微服务版分别位于哪个配置文件。
位置标注约定：
| 标注 | 含义 |
|---|---|
| 单体：主文件 | mdp-apps/md-server/boot-server/src/main/resources/application.yml |
| 单体：env 文件 | 同目录 application-{dev/test/prod}.yml（环境差异覆盖） |
| 微服务：common.yml | Nacos common.yml（全服务共用） |
| 微服务：db.yml / redis.yml | Nacos db.yml / redis.yml（按中间件维度共用） |
| 微服务：服务 yml | Nacos 上 {服务名}.yml（服务专属，优先级最高） |
各配置项对应的可选值/默认值以代码为准。
1. mdp.system —— 系统核心配置
绑定类：SystemProperties（标注 @RefreshScope，Nacos 修改后动态生效）。
| 配置项 | 可选值 | 默认值 | 建议值 | 单体版 | 微服务版 |
|---|---|---|---|---|---|
| mdp.system.mode | boot / cloud | 不配时按 cloud 装配（matchIfMissing = true） | 与部署形态一致，且务必显式写出 | 主文件 | common.yml |
| mdp.system.verify-password | true / false | true | 生产 true；开发可 false 快速登录 | 主文件 | common.yml |
| mdp.system.verify-captcha | true / false | true | 生产 true；本地调试可 false | 主文件 | common.yml |
| mdp.system.def-pwd | 任意字符串 | 123456 | 改为复杂值并只告知管理员 | 主文件 | common.yml |
| mdp.system.record-log | true / false | false | true（记录接口操作日志） | 主文件 | common.yml |
| mdp.system.record-args | true / false | true | true | 主文件 | common.yml |
| mdp.system.record-result | true / false | true | true | 主文件 | common.yml |
| mdp.system.enum-package | 包路径 | - | 保持默认。枚举扫描包路径。 | 主文件 | common.yml |
| mdp.system.forget-password-url | url | - | 指向 web-workbench 忘记密码页 | 主文件 | common.yml |
mode 的实际作用是决定用户上下文通过 TokenContextFilter 还是 HeaderThreadLocalInterceptor 获取：
mdp.system.mode | 注册的拦截器 | 行为 |
|---|---|---|
boot | TokenContextFilter | 本进程内解析 token：StpUtil.getSession() 取会话，按 mdp.ignore 跳过免登录接口，再把 userId、公司、部门等写入 ContextUtil（ThreadLocal）与 MDC |
cloud | HeaderThreadLocalInterceptor | 不解析 token，只把 inner-gateway 鉴权后透传下来的请求头读进 ContextUtil 与 MDC |
跨模块调用走本地方法还是 OpenFeign，与 mode 无关
那是编译期由 pom 引入的 impl 模块决定的：boot-server 引 workbench-boot-impl / console-boot-impl / open-boot-impl（进程内直调），workbench-server 引 console-cloud-impl / open-cloud-impl（经 OpenFeign 调用 web 层接口），详见架构介绍。
另外前端也有一个类似参数 VITE_GLOB_MODE，它只决定开发代理转发到 23455 还是 23450（见前端配置）。两者互相独立、各自都要与部署形态一致，配错哪一个现象都是接口层面不通，注意区分。
2. mdp.ignore —— 鉴权放行配置
绑定类：IgnoreProperties。
| 配置项 | 可选值 | 默认值 | 建议值 | 单体版 | 微服务版 |
|---|---|---|---|---|---|
| mdp.ignore.auth-enabled | true / false | true | true（生产严禁 false） | 主文件 | inner-gateway-server.yml |
| mdp.ignore.case-sensitive | true / false | false | false | 主文件 | inner-gateway-server.yml |
| mdp.ignore.anyone.ALL | Ant 路径列表 | 空 | /anyone/ | 主文件 | inner-gateway-server.yml |
| mdp.ignore.any-user.ALL | Ant 路径列表 | 空 | /anyUser/、/sso/、/oauth2/ | 主文件 | inner-gateway-server.yml |
三个放行级别的语义：
| 级别 | 是否需要登录（携带token） | 是否鉴权 uri | 能否取到当前用户 |
|---|---|---|---|
| any-user | 否 | 否 | 否 |
| anyone | 是 | 否 | 是 |
单体版在 boot-server 内校验，微服务版统一收敛到 inner-gateway（各后端服务自己的
authEnabled: false）。给微服务新增免登录接口时，改 Nacos 上的inner-gateway-server.yml。
3. mdp.database —— 数据库与 ID 生成
绑定类：DatabaseProperties。单体版在主文件，微服务版在 Nacos db.yml。
| 配置项 | 可选值 | 默认值 | 建议值 | 说明 |
|---|---|---|---|---|
| mdp.database.id-type | HU_TOOL / DEFAULT / CACHE | HU_TOOL | CACHE | ID 生成策略 |
| mdp.database.hutool-id.worker-id | 0~31 | 0 | 集群部署时各实例不同 | HU_TOOL 雪花算法机器号 |
| mdp.database.hutool-id.data-center-id | 0~31 | 0 | 集群部署时各实例不同 | HU_TOOL 雪花算法数据中心号 |
| mdp.database.cache-id.time-bits | 正整数 | 31 | 31 | CACHE 模式可用年限（31≈68 年） |
| mdp.database.cache-id.worker-bits | 正整数 | 23 | 22~23 | 支持的重启次数 |
| mdp.database.cache-id.seq-bits | 正整数 | 9 | 10 | 每秒并发量（10≈1024/s） |
| mdp.database.cache-id.epoch-str | 日期字符串 | 2020-09-15 | 项目启动日期 | 时间基点 |
| mdp.database.flex.audit | true / false | false | true | SQL 审计 |
| mdp.database.flex.audit-collector | 枚举 | DEFAULTS | DEFAULTS | 审计收集器 |
| mdp.database.flex.logic-delete-processor | 枚举 | TIME_STAMP_DEL_BY_LOGIC_DELETE_PROCESSOR | 默认 | 逻辑删除处理器 |
| mdp.database.flex.deleted-by-column | 字段名 | deleted_by | 默认 | 逻辑删除人字段 |
id-type 选择注意事项：
- HU_TOOL：单机或固定数量集群，配置最简单；
- DEFAULT / CACHE：集群动态扩容场景（UidGenerator，CACHE 为 RingBuffer 优化版，约 600 万/s 吞吐）。三者位数参数总和须 ≤ 64。
4. mdp.cache —— 缓存
绑定类：CustomCacheProperties。单体版在主文件，微服务版在 Nacos redis.yml。
| 配置项 | 可选值 | 默认值 | 建议值 | 说明 |
|---|---|---|---|---|
| mdp.cache.serializer-type | jack_son / ProtoStuff 等 | ProtoStuff | jack_son | 缓存值序列化方式，多语言/可读性场景建议 jack_son |
| mdp.cache.cache-prefix | 字符串 | - | mdp | 缓存 key 前缀，共用 Redis 时用于隔离（可配合不同 database） |
5. mdp.echo —— 远程数据回显
绑定类：EchoProperties。单体版在主文件，微服务版在 common.yml。
| 配置项 | 可选值 | 默认值 | 建议值 | 说明 |
|---|---|---|---|---|
| mdp.echo.aop-enabled | true / false | true | true | 启用 @EchoResult 注解 AOP 注入 |
| mdp.echo.dict-separator | 字符串 | ### | 默认 | 字典类型与 code 的分隔符 |
| mdp.echo.dict-item-separator | 字符串 | , | 默认 | 多个字典 code 的分隔符 |
| mdp.echo.max-depth | 正整数 | 3 | 3 | 递归回显最大深度 |
| mdp.echo.guava-cache.enabled | true / false | false | 生产 false | 本地缓存有短暂不一致，生产慎用 |
6. mdp.log —— 操作日志
绑定类：OptLogProperties。单体版在主文件，微服务版在 common.yml。
| 配置项 | 可选值 | 默认值 | 建议值 | 说明 |
|---|---|---|---|---|
| mdp.log.enabled | true / false | true | true | 开启操作日志 |
| mdp.log.type | DB / LOGGER | DB | DB（可查询）/LOGGER（文件） | 存储位置 |
| mdp.log.ipv4.xdb-path | classpath:/file:/路径 | - | file:./docs/ip2region_v4.xdb | IP 归属地库，支持 classpath:、file: 绝对/相对路径。xdb文件比较大，不建议放在jar中。 |
7. mdp.xss —— XSS 过滤
绑定类：XssProperties。单体版在主文件，微服务版在 common.yml。
| 配置项 | 可选值 | 默认值 | 建议值 | 说明 |
|---|---|---|---|---|
| mdp.xss.enabled | true / false | true | true | XSS 过滤器开关 |
| mdp.xss.request-body-enabled | true / false | false | 按需 | RequestBody 参数反序列化时过滤 |
| mdp.xss.ignore-param-values | 参数名列表 | [noxss] | 默认 | 忽略过滤的参数名 |
8. mdp.captcha —— 验证码
绑定类：GraphicCaptchaProperties / SliderCaptchaProperties。单体版在主文件，微服务版在 common.yml。
| 配置项 | 可选值 | 默认值 | 说明 |
|---|---|---|---|
| mdp.captcha.slider.enabled | true / false | true | 行为验证码（滑块）开关 |
| mdp.captcha.slider.cache-type | redis / DEFAULT | DEFAULT | 生产多实例必须 redis（本地缓存会校验失败） |
| mdp.captcha.graphic.enabled | true / false | true | 图形验证码开关 |
| mdp.captcha.graphic.length | 4~8 | 4 | 验证码长度 |
| mdp.captcha.graphic.width / height | 像素 | 111 / 36 | 图片尺寸 |
9. mdp.msg / mdp.async / mdp.swagger / mdp.file
绑定类：MsgProperties（@RefreshScope）、AsyncProperties、SwaggerProperties、FileProperties（@RefreshScope）。
位置：mdp.msg 、 mdp.async、mdp.swagger 在 common.yml（单体在主文件）；mdp.file 微服务版在 console-server.yml（单体在主文件）。
| 配置项 | 可选值 | 默认值 | 说明 |
|---|---|---|---|
| mdp.msg.sms.length / type | 数字 / number|string | 6 / number | 短信验证码长度与类型 |
| mdp.msg.email.length / type | 数字 / number|string | 6 / string | 邮件验证码长度与类型 |
| mdp.async.core-pool-size | 正整数 | 2 | 异步线程池核心线程数 |
| mdp.async.max-pool-size | 正整数 | 50 | 最大线程数 |
| mdp.async.queue-capacity | 正整数 | 10000 | 队列容量 |
| mdp.async.keep-alive-seconds | 秒 | 300 | 线程存活时间 |
| mdp.swagger.version | 字符串 | 1.0 | 文档版本，通常用 @project.version@ |
| mdp.file.suffix | 后缀列表 | 见主文件 | 上传文件后缀白名单（逗号分隔） |
| mdp.file.del-file | true / false | false | 删附件记录时是否物理删文件 |
| mdp.file.chunk-size | MB | 5 | 分片上传的片大小 |
| mdp.file.temp-storage-path | 目录 | - | 分片临时目录（生产改到磁盘充裕的路径） |
| mdp.file.public-bucket | 桶名集合 | 空 | 公开桶（富文本等 url 永久可访问的场景） |
10. sa-token.* —— 认证与会话
sa-token 官方配置（官方文档），单体版在主文件，微服务版在 common.yml + workbench-server.yml。
| 配置项 | 常用值 | 默认值 | 建议值 | 说明 |
|---|---|---|---|---|
| sa-token.token-name | 字符串 | satoken | Token | token 名称（也是 cookie 名、请求头名） |
| sa-token.token-prefix | 字符串 | 空 | 空 | token 前缀（如 Bearer ） |
| sa-token.timeout | 秒，-1 永不过期 | 2592000（30 天） | 按安全要求 | token 有效期 |
| sa-token.active-timeout | 秒，-1 不冻结 | -1 | 按需 | 无操作冻结期 |
| sa-token.is-concurrent | true / false | true | true | 是否允许同账号并发登录 |
| sa-token.is-share | true / false | false | false | 并发登录是否共用 token |
| sa-token.token-style | uuid 等 | uuid | uuid | token 风格 |
| sa-token.is-log | true / false | - | 开发 true，生产 false | 是否输出操作日志 |
| sa-token.sso-server.ticket-timeout | 秒 | 300 | 300 | ticket 有效期（分钟级，不宜长） |
| sa-token.sso-server.is-http | true / false | false | false | 是否模式三（跨域） |
| sa-token.sso-server.allow-anon-client | true / false | false | false | 关闭匿名 client，强制携带应用信息 |
| sa-token.sso-server.secret-key | 字符串 | - | 强随机串 | 全局 SSO 接口调用秘钥 |
| sa-token.sso-client.* | 见单点登录客户端配置 | - | - | 客户端接入配置 |
微服务版中
sa-token.sso-clients（MDP 对 sa-token 的增强，一个后端服务对应多个前端应用）只在 workbench-server.yml 中维护；单体版在主文件。
11. dromara.x-file-storage —— 文件存储
x-file-storage 官方配置（官方文档），单体版在主文件，微服务版在 console-server.yml / api-server.yml（两处都提供文件能力）。
dromara:
x-file-storage:
default-platform: localPlusExt # 默认存储平台
thumbnail-suffix: ".min.jpg" # 缩略图后缀
local-plus:
- platform: localPlus
domain: http://127.0.0.1:23451/preview/ # 访问域名，以 / 结尾
base-path: local-plus/ # 基础路径
path-patterns: /preview/** # 访问路径
storage-path: /your/path/mdp/ # 存储目录（生产改为磁盘充裕路径）
enableStorage: true
enableAccess: true要点：
default-platform: localPlusExt是 MDP 增强的本地存储平台；如需切换 OSS/MinIO 等，参考 x-file-storage 官方文档追加对应平台配置并改default-platform；domain要与path-patterns对应（domain + 文件路径即下载地址），本地存储建议用相对域名方便后期换域名；- 微服务版 console 与 api 服务都配置了文件存储，生产环境务必保证两个服务指向同一个 storage-path（或都改为同一外部存储平台），否则上传与读取会落空。
12. springdoc.* 与 knife4j.* —— 接口文档
单体版在主文件，微服务版基础项在 common.yml、group-configs 在各服务 yml。
| 配置项 | 常用值 | 说明 |
|---|---|---|
| knife4j.enable | true / false | 生产环境建议 false（关闭文档入口） |
| springdoc.default-flat-param-object | true | 平铺参数对象（保持 true，否则 GET 对象参数解析异常） |
| springdoc.swagger-ui.path | /swagger-ui.html | swagger-ui 地址 |
| springdoc.api-docs.path | /v3/api-docs | openapi 描述文件地址 |
| springdoc.group-configs | 分组列表 | 每组：group / displayName / paths-to-match / packages-to-scan；单体版一组应用一个分组 |
访问入口：http://服务地址/doc.html（knife4j 增强界面）。生产环境建议通过 knife4j.enable=false 或网关屏蔽文档路径，避免接口结构泄露。
13. mybatis-flex.* —— ORM
绑定方式：mybatis-flex 官方配置，单体版在主文件，微服务版在 Nacos db.yml。
| 配置项 | 建议值 | 说明 |
|---|---|---|
| mybatis-flex.mapper-locations | classpath*:/mapper/**/*.xml | XML 扫描位置，保持默认 |
| mybatis-flex.configuration.log-impl | StdOutImpl / 不配置 | 开发期打印 SQL，生产删掉 |
| mybatis-flex.configuration.map-underscore-to-camel-case | true | 下划线转驼峰，保持 true |
| mybatis-flex.configuration.cache-enabled | false | 二级缓存，保持 false |
| mybatis-flex.global-config.logic-delete-column | deleted_at | 全局逻辑删除字段 |
| mybatis-flex.global-config.key-config.value | uid | 主键生成器（对接 mdp.database.id-type） |
14. spring.datasource.* —— 数据源（Druid）
单体版在 env 文件（application-{dev|test|prod}.yml），微服务版在 Nacos db.yml。
| 配置项 | 建议值 | 说明 |
|---|---|---|
| spring.datasource.druid.url | 生产连接串 | 含时区与编码参数，保持模板中的参数组合 |
| spring.datasource.druid.username / password | 强密码 | 通过环境变量注入，勿明文入库/入库提交 |
| spring.datasource.druid.initial-size / min-idle | 10 | 初始/最小连接数 |
| spring.datasource.druid.max-active | 200 | 最大连接数，按数据库承受能力调整 |
| spring.datasource.druid.max-wait | 60000 | 获取连接超时（毫秒） |
| spring.datasource.druid.test-while-idle | true | 空闲检测，保持 true |
| spring.datasource.druid.filter.wall.enabled | true | SQL 防火墙 |
| spring.datasource.druid.filter.slf4j.statement-executable-sql-log-enable | true | 可执行 SQL 日志，生产可关 |
| spring.datasource.druid.stat-view-servlet.enabled | true / false | Druid 监控页 /druid/*，生产必须设置强账号密码或关闭 |
安全提示：
stat-view-servlet默认login-username/password为空，等于监控页无密码。生产环境要么关闭，要么配置强账号密码并限制 allow 来源 IP。这是认证相关配置，修改时注意安全影响。
15. spring.servlet.multipart —— 上传大小
单体版在主文件，微服务版在 common.yml（网关侧单独配置，见开放平台网关配置）。
| 配置项 | 默认值（MDP） | 说明 |
|---|---|---|
| spring.servlet.multipart.max-file-size | 10MB（boot）/ 60MB（sop-gateway） | 单文件上限 |
| spring.servlet.multipart.max-request-size | 50MB（boot）/ 200MB（sop-gateway） | 单请求上限 |
| spring.servlet.multipart.resolve-lazily | false | 懒加载（true 可提前拒绝超大请求） |
调大上传限制时的完整链条：业务限制（mdp.upload）< 容器限制（本节）< RPC 限制（dubbo.protocol.payload），详见开放平台网关配置第 2.3 节。
16. 其他常见配置速查
| 配置项 | 单体版位置 | 微服务版位置 | 说明 |
|---|---|---|---|
| server.port | 主文件 23455 | 各服务 yml | 服务端口 |
| server.shutdown | GRACEFUL | common.yml | 优雅停机（配合 spring.lifecycle.timeout-per-shutdown-phase: 30s） |
| management.endpoints.web.exposure.include | * | common.yml | 生产建议收敛为 health,info |
| management.endpoint.health.show-details | when_authorized | common.yml | 健康详情仅授权可见，保持 |
| logging.file.path / logging.level.* | 主文件 | common.yml | 日志路径与级别 |
| spring.data.redis.* | env 文件 | redis.yml | Redis 连接（database：单体 6、微服务 7，避免互相干扰） |
| spring.cache.type | GENERIC | common.yml | 缓存抽象类型 |
| spring.freemarker.* | 主文件 | common.yml | 模板引擎（消息模板渲染用） |
| sms.config-type | 主文件 | console-server.yml | 短信实现方式（INTERFACE 为接口对接） |
| dubbo.* / powerjob.* | 主文件 + env 文件 | 各服务 yml | RPC 与定时任务，含两个能力开关，见第 17 节 |
17. dubbo.* 与 powerjob.worker.* —— RPC 与定时任务
本节单独列出，是因为里面藏着两个能力开关：dubbo.enabled 决定这个进程要不要提供开放接口，powerjob.worker.enabled 决定它要不要当定时任务执行器。两者配合起来裁剪 worker-server 的职责，原理见架构介绍 §3.3。
17.1 dubbo.* —— RPC 与开放接口
| 配置项 | 可选值 | 默认值 | 建议值 |
|---|---|---|---|
| dubbo.enabled | true / false | 不配即 true（@ConditionalOnProperty 的 matchIfMissing=true） | boot-server 必须 false；微服务版 worker-server 建议 false |
| dubbo.protocol.name | dubbo / rest / … | dubbo | 保持 dubbo |
| dubbo.protocol.port | 端口 / -1（随机可用端口） | - | -1，交给 Dubbo 选端口 |
| dubbo.application.qos-enable | true / false | 未配时 Dubbo 默认开 | false（否则 22222 端口会随进程数冲突） |
| dubbo.consumer.timeout | 毫秒 | Dubbo 默认 1000 | MDP 统一 30000 |
| dubbo.consumer.retries | 次数 | Dubbo 默认 2 | 必须 0——超时重试会让服务端重复处理同一请求 |
| dubbo.consumer.check | true / false | 未配时 Dubbo 默认 true | false（启动时不强制要求 provider 已存在） |
| dubbo.provider.validation | jvalidationNew / true / false | - | jvalidationNew（JSR-303 校验） |
| dubbo.provider.filter | 过滤器名，逗号分隔 | - | 保持 globalExceptionFilter,exception，去掉会导致远程异常丢失 |
| dubbo.registry.address | zookeeper://ip:2181 / nacos://user:pwd@ip:port?namespace=xxx | - | dev 可用 zookeeper；test/prod 必须 nacos |
| dubbo.registry.check | true / false | 未配时 Dubbo 默认 true | false（注册中心抖动不阻塞启动） |
17.2 powerjob.worker.* —— 定时任务执行器
绑定类：PowerJobProperties。全仓只有 worker-server 引入该 starter。
| 配置项 | 可选值 | 代码默认值 | 实际值 / 建议 |
|---|---|---|---|
| powerjob.worker.enabled | true / false | true | true；application-dev.yml:25 覆盖为 false |
| powerjob.worker.app-name | 任意字符串，无默认 | - | MDP，必须与 PowerJob 控制台里已注册的应用名完全一致，否则 worker 注册被拒 |
| powerjob.worker.server-address | ip:port，多值逗号分隔，无默认 | - | 127.0.0.1:17700；填的是调度中心地址，不是 worker 自己的端口。 |
| powerjob.worker.protocol | AKKA / HTTP | AKKA | http，保持不动；注意 server 与 worker 两端都要放通端口 |
| powerjob.worker.store-strategy | DISK / DB | DISK | DISK（Map/MapReduce 类任务走磁盘，避免 OOM） |
| powerjob.worker.max-result-length | 字节数 | 8192 | 4096，超出部分被截断 |
| powerjob.worker.max-appended-wf-context-length | 字节数 | 8192 | 4096，超出直接丢弃 |
| powerjob.worker.max-lightweight-task-num | 并发数 | 1024 | 同默认；执行器 CPU 核数少时可调低 |
| powerjob.worker.max-heavyweight-task-num | 并发数 | 64 | 同默认。 |
| powerjob.worker.allow-lazy-connect-server | true / false | false | false；"本地没有调度中心也要启动项目"，不能当作关闭执行器的替代手段 |
| powerjob.worker.health-report-interval | 秒 | 10 | 保持默认 |
| powerjob.worker.port / akka-port | 端口 | port 为空时回落到 akka-port，后者 ≤ 0 则随机端口 | 单实例随机即可；同一台机器跑多个 worker 实例时显式指定，方便放通防火墙 |
微服务版部署 worker-server 的推荐写法（否则它会与 api-server 同时注册为开放接口 provider，被网关轮询到）：
# worker-server/src/main/resources/application-prod.yml 追加
dubbo:
enabled: false # 只做执行器，不承接开放接口
powerjob:
worker:
enabled: true # 显式打开执行器（test/prod 出厂即为 true，写出来更直观）