rakor
/
wms
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
wms/.qoder/repowiki/zh/content/配置管理/配置管理.md

348 lines
18 KiB
Markdown
Raw Permalink Normal View History

docs(api): 新增完整API接口文档 - 覆盖仓储管理、物料管理、订单处理等业务域接口设计与规范 - 介绍统一返回体、状态码体系、认证授权机制及错误处理策略 - 详细描述接口清单管理及二维码内容生成机制 - 提供架构总览、依赖分析和性能考虑建议 - 包含故障排查指南及Postman集合和curl示例说明 docs(biz): 新增业务功能文档详解 - 系统化梳理仓储、物料、订单、生产、采购销售和质量管理业务流程 - 按功能划分控制层模块，明确数据模型和持久化结构 - 详细描述核心业务组件及关键操作流程图和时序图 - 分析业务依赖与耦合点，强调事务一致性和并发锁机制 - 提供故障排查和性能优化建议，支持批量操作分批处理
2026-04-14 08:26:07 +08:00
# 配置管理
<cite>
**本文引用的文件**
- [application.yml](file://nflg-qms-admin/src/main/resources/application.yml)
- [application-dev.yml](file://nflg-qms-admin/src/main/resources/application-dev.yml)
- [application-sit.yml](file://nflg-qms-admin/src/main/resources/application-sit.yml)
- [application-prod.yml](file://nflg-qms-admin/src/main/resources/application-prod.yml)
- [application.yml](file://nflg-wms-admin/src/main/resources/application.yml)
- [application-dev.yml](file://nflg-wms-admin/src/main/resources/application-dev.yml)
- [application-sit.yml](file://nflg-wms-admin/src/main/resources/application-sit.yml)
- [application-prod.yml](file://nflg-wms-admin/src/main/resources/application-prod.yml)
- [application.yml](file://nflg-wms-auth/src/main/resources/application.yml)
- [application-dev.yml](file://nflg-wms-auth/src/main/resources/application-dev.yml)
- [application-sit.yml](file://nflg-wms-auth/src/main/resources/application-sit.yml)
- [application-prod.yml](file://nflg-wms-auth/src/main/resources/application-prod.yml)
- [application.yml](file://nflg-wms-shipment/src/main/resources/application.yml)
- [application-dev.yml](file://nflg-wms-shipment/src/main/resources/application-dev.yml)
- [application-sit.yml](file://nflg-wms-shipment/src/main/resources/application-sit.yml)
- [application-prod.yml](file://nflg-wms-shipment/src/main/resources/application-prod.yml)
- [application.yml](file://nflg-wms-srm-receive/src/main/resources/application.yml)
- [application-dev.yml](file://nflg-wms-srm-receive/src/main/resources/application-dev.yml)
- [application-sit.yml](file://nflg-wms-srm-receive/src/main/resources/application-sit.yml)
- [application-prod.yml](file://nflg-wms-srm-receive/src/main/resources/application-prod.yml)
- [application.yml](file://nflg-wms-gateway/src/main/resources/application.yml)
- [application.yml](file://nflg-wms-scheduled/src/main/resources/application.yml)
- [application.yml](file://nflg-wms-starter/src/main/resources/application.yml)
- [LdapConfig.java](file://nflg-wms-admin/src/main/java/com/nflg/wms/admin/config/LdapConfig.java)
- [pom.xml](file://nflg-wms-starter/pom.xml)
</cite>
## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构总览](#架构总览)
5. [详细组件分析](#详细组件分析)
6. [依赖分析](#依赖分析)
7. [性能考虑](#性能考虑)
8. [故障排除指南](#故障排除指南)
9. [结论](#结论)
10. [附录](#附录)
## 简介
本文件面向NFLG WMS系统运维与开发团队，系统化阐述多环境配置策略与管理方法，覆盖开发(dev)、测试(sit)、生产(prod)三类环境的配置差异与落地实践；明确核心配置项（数据库连接、Redis、Nacos动态配置、日志与链路追踪、LDAP等）的作用与设置要点；解释配置文件优先级与覆盖机制（环境变量、命令行参数与配置文件的组合），并提供配置热更新与动态配置管理方案、配置安全策略（敏感信息保护、文件权限控制）、配置验证与故障排除方法，以及部署与变更管理指南与模板。
## 项目结构
WMS采用多模块结构，每个业务模块均包含标准Spring Boot配置文件，按环境拆分：
- 公共基础配置：application.yml（定义端口、Nacos导入、健康监控、日志级别等）
- 环境差异化配置：application-{env}.yml（dev/sit/prod）
- 模块示例：admin、auth、qms-admin、shipment、srm-receive、gateway、scheduled、starter
```mermaid
graph TB
subgraph "模块"
A["nflg-wms-admin<br/>应用配置"]
B["nflg-wms-auth<br/>应用配置"]
C["nflg-qms-admin<br/>应用配置"]
D["nflg-wms-shipment<br/>应用配置"]
E["nflg-wms-srm-receive<br/>应用配置"]
F["nflg-wms-gateway<br/>应用配置"]
G["nflg-wms-scheduled<br/>应用配置"]
H["nflg-wms-starter<br/>公共依赖"]
end
subgraph "配置文件"
Y1["application.yml"]
Y2["application-dev.yml"]
Y3["application-sit.yml"]
Y4["application-prod.yml"]
end
A --- Y1
A --- Y2
A --- Y3
A --- Y4
B --- Y1
B --- Y2
B --- Y3
B --- Y4
C --- Y1
C --- Y2
C --- Y3
C --- Y4
D --- Y1
D --- Y2
D --- Y3
D --- Y4
E --- Y1
E --- Y2
E --- Y3
E --- Y4
F --- Y1
G --- Y1
H --- Y1
```
图表来源
- [application.yml:1-48](file://nflg-wms-admin/src/main/resources/application.yml#L1-L48)
- [application-dev.yml:1-34](file://nflg-wms-admin/src/main/resources/application-dev.yml#L1-L34)
- [application-sit.yml:1-40](file://nflg-wms-admin/src/main/resources/application-sit.yml#L1-L40)
- [application-prod.yml:1-30](file://nflg-wms-admin/src/main/resources/application-prod.yml#L1-L30)
章节来源
- [application.yml:1-48](file://nflg-wms-admin/src/main/resources/application.yml#L1-L48)
- [application.yml:1-50](file://nflg-wms-auth/src/main/resources/application.yml#L1-L50)
- [application.yml:1-48](file://nflg-qms-admin/src/main/resources/application.yml#L1-L48)
## 核心组件
- 多环境激活与动态配置
- 通过profiles.active选择环境，结合Nacos动态配置中心进行集中管理与热更新。
- Nacos配置导入语法统一，按环境分组，支持刷新开关。
- 日志与可观测性
- 统一配置日志级别、健康检查端点暴露、链路追踪采样率与导出目标。
- 数据库连接池
- HikariCP在各环境差异化配置连接池大小、空闲超时、生命周期与泄漏检测阈值。
- 安全与认证
- Sa-Token令牌名称、有效期、SSO相关参数在auth模块集中配置。
- LDAP集成
- 通过LdapConfig读取spring.ldap.*配置，构建LDAP上下文源。
章节来源
- [application.yml:1-48](file://nflg-wms-admin/src/main/resources/application.yml#L1-L48)
- [application-dev.yml:25-34](file://nflg-wms-admin/src/main/resources/application-dev.yml#L25-L34)
- [application-sit.yml:31-40](file://nflg-wms-admin/src/main/resources/application-sit.yml#L31-L40)
- [application.yml:20-34](file://nflg-wms-auth/src/main/resources/application.yml#L20-L34)
- [LdapConfig.java:1-42](file://nflg-wms-admin/src/main/java/com/nflg/wms/admin/config/LdapConfig.java#L1-L42)
## 架构总览
下图展示配置加载与动态更新的整体流程，强调环境选择、Nacos导入、本地覆盖与热更新的关系。
```mermaid
sequenceDiagram
participant Boot as "Spring Boot 应用"
participant Env as "环境变量/命令行"
participant Local as "application.yml"
participant EnvYml as "application-{env}.yml"
participant Nacos as "Nacos 动态配置"
participant App as "业务组件"
Boot->>Env : 读取环境变量/命令行参数
Boot->>Local : 加载基础配置
Boot->>EnvYml : 按profiles.active合并环境配置
Boot->>Nacos : 导入shared.properties(按group=env)
Nacos-->>Boot : 返回配置键值
Boot->>App : 注入配置并初始化组件
note over Boot,Nacos : 当配置变更时，若开启refreshEnabled则触发动态刷新
```
图表来源
- [application.yml:10-13](file://nflg-wms-admin/src/main/resources/application.yml#L10-L13)
- [application.yml:10-13](file://nflg-qms-admin/src/main/resources/application.yml#L10-L13)
- [application.yml:6-9](file://nflg-wms-auth/src/main/resources/application.yml#L6-L9)
## 详细组件分析
### 多环境配置策略与差异
- 环境激活
- 通过profiles.active指定当前环境，模块间保持一致的命名约定（dev/sit/prod）。
- 日志与链路追踪
- 开发与测试环境提高日志与Nacos调试级别，生产环境收敛日志级别以降低开销。
- 统一配置OTLP追踪端点，便于跨环境观测。
- 数据库连接池
- 各环境对最大池大小、最小空闲、连接超时等参数差异化配置，以适配资源与负载。
- 安全与认证
- auth模块集中配置Sa-Token令牌名称、有效期、SSO服务端参数，确保跨模块一致性。
- LDAP集成
- 通过LdapConfig从spring.ldap.*注入属性，构建LDAP上下文源，便于统一管理。
章节来源
- [application-dev.yml:1-34](file://nflg-wms-admin/src/main/resources/application-dev.yml#L1-L34)
- [application-sit.yml:1-40](file://nflg-wms-admin/src/main/resources/application-sit.yml#L1-L40)
- [application-prod.yml:1-30](file://nflg-wms-admin/src/main/resources/application-prod.yml#L1-L30)
- [application-dev.yml:1-30](file://nflg-qms-admin/src/main/resources/application-dev.yml#L1-L30)
- [application-sit.yml:1-30](file://nflg-qms-admin/src/main/resources/application-sit.yml#L1-L30)
- [application-prod.yml:1-30](file://nflg-qms-admin/src/main/resources/application-prod.yml#L1-L30)
- [application.yml:20-34](file://nflg-wms-auth/src/main/resources/application.yml#L20-L34)
- [LdapConfig.java:14-25](file://nflg-wms-admin/src/main/java/com/nflg/wms/admin/config/LdapConfig.java#L14-L25)
### 核心配置项与设置方法
- 服务器与上传
- server.port、Tomcat表单大小限制、Servlet上传大小限制，用于控制访问端口与文件上传能力。
- Nacos动态配置
- spring.config.import引入Nacos共享配置，按环境分组，支持动态刷新开关。
- cloud.nacos.config/discovery配置服务地址、命名空间与分组，确保注册与配置一致性。
- 健康检查与可观测性
- management.endpoints/web.exposure.include、endpoint.health.show-details、health.db/redis启用，tracing采样概率与导出端点统一配置。
- 数据库连接池（HikariCP）
- pool-name、maximum-pool-size、minimum-idle、idle-timeout、max-lifetime、connection-timeout、leak-detection-threshold，按环境调优。
- 安全与认证（Sa-Token）
- token-name、timeout、SSO服务端ticket有效期、允许回调地址、JWT密钥，确保令牌安全与SSO连通。
- LDAP
- spring.ldap.urls/base/username/password，由LdapConfig注入并构建上下文源。
章节来源
- [application.yml:1-48](file://nflg-wms-admin/src/main/resources/application.yml#L1-L48)
- [application.yml:1-48](file://nflg-qms-admin/src/main/resources/application.yml#L1-L48)
- [application.yml:1-50](file://nflg-wms-auth/src/main/resources/application.yml#L1-L50)
- [LdapConfig.java:14-25](file://nflg-wms-admin/src/main/java/com/nflg/wms/admin/config/LdapConfig.java#L14-L25)
### 配置优先级与覆盖机制
- 命令行参数 > 环境变量 > application-{env}.yml > application.yml
- Nacos动态配置作为外部配置源，与本地配置文件共同参与覆盖，最终以运行时生效为准。
- 建议：将敏感或环境差异较大的配置置于Nacos，本地仅保留通用默认值。
章节来源
- [application.yml:10-13](file://nflg-wms-admin/src/main/resources/application.yml#L10-L13)
- [application.yml:10-13](file://nflg-qms-admin/src/main/resources/application.yml#L10-L13)
- [application.yml:6-9](file://nflg-wms-auth/src/main/resources/application.yml#L6-L9)
### 配置热更新与动态配置管理
- 启用方式
- 在Nacos导入URL中开启refreshEnabled参数，实现配置变更后的自动刷新。
- 生效范围
- 对于非@RefreshScope注解的组件，需确保配置项被Spring管理且可重新绑定；对于需要立即生效的关键配置，建议配合注解或事件监听。
- 变更流程
- 在Nacos控制台修改对应group的配置项，观察应用日志确认刷新成功；必要时触发手动刷新接口或重启实例。
章节来源
- [application.yml:12-13](file://nflg-wms-admin/src/main/resources/application.yml#L12-L13)
- [application.yml:12-13](file://nflg-qms-admin/src/main/resources/application.yml#L12-L13)
- [application.yml:8-9](file://nflg-wms-auth/src/main/resources/application.yml#L8-L9)
### 配置安全策略
- 敏感信息加密
- 将数据库密码、JWT密钥、LDAP凭据等放入Nacos并启用加密存储；避免明文写入版本库。
- 文件权限控制
- 仅授予运行账户读取权限；禁止将配置文件纳入CI缓存或制品仓库。
- 最小暴露原则
- 仅开放必要的管理端点；生产环境收敛端点暴露范围。
- 审计与回滚
- 记录每次配置变更；建立快速回滚预案与灰度发布策略。
（本节为通用安全建议，不直接分析具体文件）
### 配置验证与故障排除
- 常见问题定位
- 端口冲突：检查server.port是否与其他实例重复。
- Nacos连接失败：核对nacos.server-addr、namespace、group与环境一致。
- 数据库连接异常：核对HikariCP参数与数据库实例状态。
- LDAP认证失败：核对spring.ldap.*配置与域控连通性。
- 排查步骤
- 查看启动日志中的配置导入与合并过程；确认management端点可访问；使用健康检查端点验证DB/Redis可用性。
- 快速修复
- 临时降级日志级别；切换到稳定环境配置；回滚最近一次Nacos变更。
章节来源
- [application.yml:31-48](file://nflg-wms-admin/src/main/resources/application.yml#L31-L48)
- [application.yml:28-48](file://nflg-qms-admin/src/main/resources/application.yml#L28-L48)
- [application.yml:37-50](file://nflg-wms-auth/src/main/resources/application.yml#L37-L50)
- [LdapConfig.java:27-41](file://nflg-wms-admin/src/main/java/com/nflg/wms/admin/config/LdapConfig.java#L27-L41)
### 运维部署与变更管理指南
- 部署前准备
- 明确目标环境（dev/sit/prod），准备对应application-{env}.yml与Nacos group。
- 准备数据库初始化脚本与Redis/消息队列等基础设施。
- 部署流程
- 通过CI流水线打包并推送镜像/制品；在目标环境启动应用，观察启动日志与健康检查。
- 若使用Nacos，先在对应group创建或更新配置，再启动应用。
- 变更管理
- 重大变更走灰度发布；记录变更内容、影响面与回滚计划；变更后进行冒烟测试与回归测试。
章节来源
- [application.yml:10-13](file://nflg-wms-admin/src/main/resources/application.yml#L10-L13)
- [application.yml:10-13](file://nflg-qms-admin/src/main/resources/application.yml#L10-L13)
- [application.yml:6-9](file://nflg-wms-auth/src/main/resources/application.yml#L6-L9)
### 配置模板与最佳实践
- 配置模板
- application.yml：基础端口、Nacos导入、健康监控、日志与追踪配置。
- application-{env}.yml：日志级别、数据库连接池、LDAP与SSO参数等环境差异项。
- 最佳实践
- 将环境无关的默认值放在application.yml，环境相关与敏感信息放在Nacos。
- 为关键配置添加注释说明用途与取值范围；定期审计配置有效性。
- 使用统一的命名规范与分组策略，避免配置散乱与冲突。
章节来源
- [application.yml:1-48](file://nflg-wms-admin/src/main/resources/application.yml#L1-L48)
- [application-dev.yml:1-34](file://nflg-wms-admin/src/main/resources/application-dev.yml#L1-L34)
- [application-sit.yml:1-40](file://nflg-wms-admin/src/main/resources/application-sit.yml#L1-L40)
- [application-prod.yml:1-30](file://nflg-wms-admin/src/main/resources/application-prod.yml#L1-L30)
## 依赖分析
- Nacos依赖
- starter模块引入spring-cloud-starter-alibaba-nacos-config与nacos-discovery，支撑动态配置与服务发现。
- Redis依赖
- starter模块引入spring-boot-starter-data-redis，为缓存与会话提供基础能力。
- 组件耦合
- 各业务模块共享同一套配置加载与动态更新机制，耦合度低、扩展性强。
```mermaid
graph LR
Starter["nflg-wms-starter"] --> NacosCfg["Nacos Config 依赖"]
Starter --> NacosDis["Nacos Discovery 依赖"]
Starter --> RedisStarter["Redis Starter 依赖"]
Admin["nflg-wms-admin"] --> Starter
Auth["nflg-wms-auth"] --> Starter
Qms["nflg-qms-admin"] --> Starter
Ship["nflg-wms-shipment"] --> Starter
Srm["nflg-wms-srm-receive"] --> Starter
Gate["nflg-wms-gateway"] --> Starter
Sch["nflg-wms-scheduled"] --> Starter
```
图表来源
- [pom.xml:34-64](file://nflg-wms-starter/pom.xml#L34-L64)
章节来源
- [pom.xml:34-64](file://nflg-wms-starter/pom.xml#L34-L64)
## 性能考虑
- 日志级别
- 生产环境收敛日志级别，减少IO与CPU消耗；开发/测试环境适度放宽以便排查。
- 连接池参数
- 根据并发与响应时间目标调整最大池大小、空闲超时与生命周期，避免连接泄露与抖动。
- 追踪采样
- 控制tracing采样概率，平衡可观测性与性能开销。
（本节为通用性能建议，不直接分析具体文件）
## 故障排除指南
- 启动失败
- 检查端口占用与网络连通；核对Nacos地址与命名空间；确认数据库与Redis可达。
- 配置未生效
- 确认profiles.active与Nacos group一致；检查refreshEnabled是否开启；查看配置导入日志。
- LDAP/SSO异常
- 核对spring.ldap.*与SSO服务端地址；检查网络策略与证书配置。
章节来源
- [application.yml:1-48](file://nflg-wms-admin/src/main/resources/application.yml#L1-L48)
- [application.yml:1-48](file://nflg-qms-admin/src/main/resources/application.yml#L1-L48)
- [application.yml:1-50](file://nflg-wms-auth/src/main/resources/application.yml#L1-L50)
- [LdapConfig.java:14-25](file://nflg-wms-admin/src/main/java/com/nflg/wms/admin/config/LdapConfig.java#L14-L25)
## 结论
通过统一的多环境配置策略与Nacos动态配置中心，WMS实现了配置的标准化、可维护性与可演进性。建议在后续实践中持续完善配置模板、强化安全与审计、优化性能参数，并建立完善的变更与回滚机制，以保障系统在不同环境下的稳定性与可靠性。
## 附录
- 关键配置清单
- 服务器端口与上传限制：server.port、multipart.max-file/request-size
- Nacos动态配置：spring.config.import、cloud.nacos.config.server-addr/namespace/group
- 健康检查与可观测性：management端点与tracing
- 数据库连接池：HikariCP各项参数
- 安全与认证：Sa-Token令牌与SSO参数
- LDAP：spring.ldap.urls/base/username/password
章节来源
- [application.yml:1-48](file://nflg-wms-admin/src/main/resources/application.yml#L1-L48)
- [application.yml:1-48](file://nflg-qms-admin/src/main/resources/application.yml#L1-L48)
- [application.yml:1-50](file://nflg-wms-auth/src/main/resources/application.yml#L1-L50)
- [LdapConfig.java:14-25](file://nflg-wms-admin/src/main/java/com/nflg/wms/admin/config/LdapConfig.java#L14-L25)