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 Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 配置管理
<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)
Reference in New Issue View Git Blame Copy Permalink