wms/.qoder/repowiki/zh/content/部署运维/部署运维.md

# 部署运维

<cite>
**本文引用的文件**
- [pom.xml](file://pom.xml)
- [readme.md](file://readme.md)
- [GatewayApplication.java](file://nflg-wms-gateway/src/main/java/com/nflg/wms/gateway/GatewayApplication.java)
- [AdminApplication.java](file://nflg-wms-admin/src/main/java/com/nflg/wms/admin/AdminApplication.java)
- [AuthApplication.java](file://nflg-wms-auth/src/main/java/com/nflg/wms/auth/AuthApplication.java)
- [application.yml（网关）](file://nflg-wms-gateway/src/main/resources/application.yml)
- [application.yml（认证）](file://nflg-wms-auth/src/main/resources/application.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-prod.yml（管理端）](file://nflg-wms-admin/src/main/resources/application-prod.yml)
- [application-dev.yml（网关）](file://nflg-wms-gateway/src/main/resources/application-dev.yml)
- [application-dev.yml（认证）](file://nflg-wms-auth/src/main/resources/application-dev.yml)
- [DeploySitTest.java（管理端）](file://nflg-wms-admin/src/test/java/com/nflg/wms/admin/DeploySitTest.java)
</cite>

## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构总览](#架构总览)
5. [详细组件分析](#详细组件分析)
6. [依赖分析](#依赖分析)
7. [性能考虑](#性能考虑)
8. [故障排除指南](#故障排除指南)
9. [结论](#结论)
10. [附录](#附录)

## 简介
本指南面向NFGL WMS系统的运维与开发团队，提供从部署架构、微服务拆分、容器化与集群配置，到负载均衡与高可用、监控与日志、性能指标与基准测试、故障排查、备份与恢复、日常巡检与自动化部署的完整实践说明。系统采用Spring Boot 3与Spring Cloud生态，结合Nacos服务注册与配置中心、Sa-Token统一认证、Actuator健康监控、Loki日志推送等技术栈。

## 项目结构
- 多模块Maven聚合工程，包含网关、认证中心、管理端、定时任务、SRM收货、发货、仓储、公共模块与启动器等。
- 核心运行时依赖：Spring Boot 3.2.4、Spring Cloud 2023.0.1、Spring Cloud Alibaba 2023.0.1.0、PostgreSQL驱动、Actuator、Sa-Token、Redisson、PowerJob等。
- 应用通过@EnableDiscoveryClient接入Nacos进行服务注册与发现；通过spring.config.import引入Nacos配置；Actuator暴露健康检查与指标端点；日志通过Loki appender推送至Loki。

```mermaid
graph TB
subgraph "网关层"
GW["网关应用<br/>GatewayApplication"]
end
subgraph "业务服务"
AUTH["认证应用<br/>AuthApplication"]
ADMIN["管理端应用<br/>AdminApplication"]
end
subgraph "基础设施"
NACOS["Nacos 服务注册与配置"]
LOBI["Loki 日志收集"]
PROM["Prometheus 监控"]
REDIS["Redis 缓存"]
DB["PostgreSQL 数据库"]
end
GW --> AUTH
GW --> ADMIN
AUTH --> NACOS
ADMIN --> NACOS
GW --> NACOS
AUTH --> DB
ADMIN --> DB
AUTH --> REDIS
ADMIN --> REDIS
GW --> PROM
AUTH --> PROM
ADMIN --> PROM
AUTH --> LOBI
ADMIN --> LOBI
```

图表来源
- [GatewayApplication.java:1-21](file://nflg-wms-gateway/src/main/java/com/nflg/wms/gateway/GatewayApplication.java#L1-L21)
- [AdminApplication.java:1-27](file://nflg-wms-admin/src/main/java/com/nflg/wms/admin/AdminApplication.java#L1-L27)
- [AuthApplication.java:1-24](file://nflg-wms-auth/src/main/java/com/nflg/wms/auth/AuthApplication.java#L1-L24)
- [application.yml（网关）:1-43](file://nflg-wms-gateway/src/main/resources/application.yml#L1-L43)
- [application.yml（认证）:1-50](file://nflg-wms-auth/src/main/resources/application.yml#L1-L50)
- [application.yml（管理端）:1-48](file://nflg-wms-admin/src/main/resources/application.yml#L1-L48)

章节来源
- [pom.xml:17-28](file://pom.xml#L17-L28)
- [pom.xml:54-193](file://pom.xml#L54-L193)
- [application.yml（网关）:1-43](file://nflg-wms-gateway/src/main/resources/application.yml#L1-L43)
- [application.yml（认证）:1-50](file://nflg-wms-auth/src/main/resources/application.yml#L1-L50)
- [application.yml（管理端）:1-48](file://nflg-wms-admin/src/main/resources/application.yml#L1-L48)

## 核心组件
- 网关服务（gateway）
  - 启动类启用服务发现与组件扫描，集成Nacos配置与发现，开启Spring Cloud Gateway自动路由与负载均衡。
  - 端口与健康检查、指标暴露均在配置中定义。
- 认证服务（auth）
  - 启动类启用服务发现与组件扫描，集成Nacos配置与发现，内置Sa-Token SSO配置。
- 管理端服务（admin）
  - 启动类启用服务发现、调度与重试注解，集成Nacos配置与发现，支持大文件上传与多部分请求配置。
- 公共与启动器模块
  - 提供通用常量、异常、工具、基础控制器与拦截器等，被各业务模块复用。

章节来源
- [GatewayApplication.java:1-21](file://nflg-wms-gateway/src/main/java/com/nflg/wms/gateway/GatewayApplication.java#L1-L21)
- [AuthApplication.java:1-24](file://nflg-wms-auth/src/main/java/com/nflg/wms/auth/AuthApplication.java#L1-L24)
- [AdminApplication.java:1-27](file://nflg-wms-admin/src/main/java/com/nflg/wms/admin/AdminApplication.java#L1-L27)
- [application.yml（网关）:1-43](file://nflg-wms-gateway/src/main/resources/application.yml#L1-L43)
- [application.yml（认证）:1-50](file://nflg-wms-auth/src/main/resources/application.yml#L1-L50)
- [application.yml（管理端）:1-48](file://nflg-wms-admin/src/main/resources/application.yml#L1-L48)

## 架构总览
- 微服务拆分
  - 网关层：统一入口、路由、鉴权转发。
  - 认证中心：SSO统一认证与票据管理。
  - 业务服务：管理端负责业务功能与前端交互。
- 容器化与集群
  - 建议使用Docker镜像化每个服务，结合Kubernetes进行部署与扩缩容，使用Ingress/Nginx或云厂商LB实现外部流量接入。
  - 使用Deployment/Service/ConfigMap/Secret等资源对象管理服务与配置。
- 高可用与弹性
  - 多副本部署，结合Nacos实现服务注册与发现，利用Spring Cloud LoadBalancer进行客户端负载均衡。
  - 结合Redisson与数据库连接池参数优化，提升并发与稳定性。

```mermaid
graph TB
LB["负载均衡/反向代理"]
subgraph "K8s 集群"
subgraph "命名空间 wms"
SVC_GW["Service 网关"]
POD_GW["Pod 网关 xN"]
SVC_AUTH["Service 认证"]
POD_AUTH["Pod 认证 xN"]
SVC_ADMIN["Service 管理端"]
POD_ADMIN["Pod 管理端 xN"]
end
end
NACOS["Nacos 服务注册与配置"]
REDIS["Redis 集群"]
DB["PostgreSQL 集群"]
LB --> SVC_GW
SVC_GW --> POD_GW
POD_GW --> SVC_AUTH
POD_GW --> SVC_ADMIN
POD_AUTH --> REDIS
POD_ADMIN --> REDIS
POD_AUTH --> DB
POD_ADMIN --> DB
POD_GW --> NACOS
POD_AUTH --> NACOS
POD_ADMIN --> NACOS
```

图表来源
- [application.yml（网关）:10-26](file://nflg-wms-gateway/src/main/resources/application.yml#L10-L26)
- [application.yml（认证）:10-19](file://nflg-wms-auth/src/main/resources/application.yml#L10-L19)
- [application.yml（管理端）:12-23](file://nflg-wms-admin/src/main/resources/application.yml#L12-L23)

## 详细组件分析

### 网关服务（gateway）
- 启动与发现
  - 启用@EnableDiscoveryClient，组件扫描覆盖网关与仓库模块。
- 路由与负载均衡
  - 开启基于服务名的自动路由定位与小写服务ID，启用客户端负载均衡。
- 配置与监控
  - 通过Nacos导入共享配置，暴露Actuator端点，开启数据库与Redis健康探测。

```mermaid
sequenceDiagram
participant U as "客户端"
participant GW as "网关"
participant N as "Nacos"
participant S as "后端服务"
U->>GW : 请求 /api/...
GW->>N : 查询服务列表
N-->>GW : 返回服务实例
GW->>S : 转发请求带负载均衡
S-->>GW : 返回响应
GW-->>U : 返回响应
```

图表来源
- [GatewayApplication.java:10-12](file://nflg-wms-gateway/src/main/java/com/nflg/wms/gateway/GatewayApplication.java#L10-L12)
- [application.yml（网关）:20-26](file://nflg-wms-gateway/src/main/resources/application.yml#L20-L26)

章节来源
- [GatewayApplication.java:1-21](file://nflg-wms-gateway/src/main/java/com/nflg/wms/gateway/GatewayApplication.java#L1-L21)
- [application.yml（网关）:1-43](file://nflg-wms-gateway/src/main/resources/application.yml#L1-L43)

### 认证服务（auth）
- 启动与SSO
  - 启用@EnableDiscoveryClient，组件扫描覆盖认证与启动器、仓库模块。
  - 内置Sa-Token SSO配置，包含票据超时、回调地址与JWT密钥。
- 配置与监控
  - 通过Nacos导入共享配置，暴露Actuator端点，开启数据库与Redis健康探测。

```mermaid
sequenceDiagram
participant C as "浏览器/客户端"
participant GW as "网关"
participant AUTH as "认证中心"
participant N as "Nacos"
C->>GW : 访问受保护资源
GW->>AUTH : 重定向至登录页
AUTH-->>C : 登录并签发票据
C->>GW : 携带票据访问
GW->>AUTH : 校验票据
AUTH-->>GW : 校验通过
GW-->>C : 放行业务请求
```

图表来源
- [AuthApplication.java:10-13](file://nflg-wms-auth/src/main/java/com/nflg/wms/auth/AuthApplication.java#L10-L13)
- [application.yml（认证）:20-33](file://nflg-wms-auth/src/main/resources/application.yml#L20-L33)

章节来源
- [AuthApplication.java:1-24](file://nflg-wms-auth/src/main/java/com/nflg/wms/auth/AuthApplication.java#L1-L24)
- [application.yml（认证）:1-50](file://nflg-wms-auth/src/main/resources/application.yml#L1-L50)

### 管理端服务（admin）
- 启动与能力
  - 启用@EnableDiscoveryClient、@EnableScheduling、@EnableRetry，组件扫描覆盖管理端与启动器、仓库模块。
- 配置与监控
  - 通过Nacos导入共享配置，暴露Actuator端点，开启数据库与Redis健康探测与链路追踪采样。
- 日志与追踪
  - 配置Loki推送地址与OTLP追踪端点，便于集中日志与分布式追踪。

```mermaid
flowchart TD
Start(["应用启动"]) --> Reg["注册到 Nacos"]
Reg --> Cfg["拉取配置Nacos"]
Cfg --> Health["健康检查与指标暴露"]
Health --> Loki["日志推送 Loki"]
Health --> Tracing["链路追踪 OTLP"]
Loki --> End(["正常运行"])
Tracing --> End
```

图表来源
- [AdminApplication.java:12-17](file://nflg-wms-admin/src/main/java/com/nflg/wms/admin/AdminApplication.java#L12-L17)
- [application.yml（管理端）:31-48](file://nflg-wms-admin/src/main/resources/application.yml#L31-L48)
- [application-dev.yml（管理端）:1-34](file://nflg-wms-admin/src/main/resources/application-dev.yml#L1-L34)

章节来源
- [AdminApplication.java:1-27](file://nflg-wms-admin/src/main/java/com/nflg/wms/admin/AdminApplication.java#L1-L27)
- [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-prod.yml（管理端）:1-30](file://nflg-wms-admin/src/main/resources/application-prod.yml#L1-L30)

## 依赖分析
- 版本与依赖管理
  - Spring Boot 3.2.4、Spring Cloud 2023.0.1、Spring Cloud Alibaba 2023.0.1.0统一版本。
  - Actuator、Sa-Token、Redisson、PowerJob、ZXing、Loki Logback Appender等关键依赖集中管理。
- 模块耦合
  - 网关依赖于Nacos配置与发现；业务服务同样依赖Nacos；日志与追踪分别对接Loki与OTLP；缓存与数据库作为基础设施被多个服务复用。

```mermaid
graph LR
POM["父POM 依赖管理"]
SB["Spring Boot"]
SC["Spring Cloud"]
SCA["Spring Cloud Alibaba"]
ACT["Actuator"]
ST["Sa-Token"]
RDS["Redisson"]
PJ["PowerJob"]
LG["Loki Appender"]
POM --> SB
POM --> SC
POM --> SCA
POM --> ACT
POM --> ST
POM --> RDS
POM --> PJ
POM --> LG
```

图表来源
- [pom.xml:54-193](file://pom.xml#L54-L193)

章节来源
- [pom.xml:1-260](file://pom.xml#L1-L260)

## 性能考虑
- 连接池与缓存
  - Hikari连接池参数（最大池大小、空闲超时、最大生存时间、连接超时、泄漏检测阈值）在各环境配置文件中设置，建议根据峰值QPS与事务时长调优。
- 负载均衡与限流
  - 客户端负载均衡已启用；可结合Sentinel或Spring Cloud Gateway限流规则实现入口级防护。
- 监控与追踪
  - Actuator暴露JVM与业务指标；OTEL采样概率可按环境调整；Loki集中日志便于快速定位性能瓶颈。
- 基准测试
  - 建议使用JMeter或Gatling对关键路径（登录、查询、导入导出）进行压测，关注P95/P99延迟、错误率与资源占用。

章节来源
- [application-dev.yml（管理端）:26-34](file://nflg-wms-admin/src/main/resources/application-dev.yml#L26-L34)
- [application-dev.yml（网关）:11-20](file://nflg-wms-gateway/src/main/resources/application-dev.yml#L11-L20)
- [application-dev.yml（认证）:11-20](file://nflg-wms-auth/src/main/resources/application-dev.yml#L11-L20)
- [application.yml（管理端）:45-48](file://nflg-wms-admin/src/main/resources/application.yml#L45-L48)

## 故障排除指南
- 启动与连通性
  - 确认Nacos地址与命名空间正确，服务是否成功注册；检查Actuator健康端点与数据库/Redis连通性。
- 认证与SSO
  - 若登录跳转异常，检查认证中心的SSO配置与回调地址；确认JWT密钥一致性。
- 日志与追踪
  - Loki推送地址与OTLP端点需可达；若日志缺失，检查Loki Appender与日志级别配置。
- 文件上传与表单限制
  - 管理端对文件大小与请求大小进行了上限配置，上传失败时核对客户端与服务端配置。
- 自动化部署
  - 测试用例展示了基于SSH/SFTP的部署流程，包括MD5校验与远程执行脚本，可用于验证部署流程。

章节来源
- [application.yml（网关）:11-19](file://nflg-wms-gateway/src/main/resources/application.yml#L11-L19)
- [application.yml（认证）:10-19](file://nflg-wms-auth/src/main/resources/application.yml#L10-L19)
- [application.yml（管理端）:12-27](file://nflg-wms-admin/src/main/resources/application.yml#L12-L27)
- [application-dev.yml（管理端）:1-34](file://nflg-wms-admin/src/main/resources/application-dev.yml#L1-L34)
- [DeploySitTest.java（管理端）:28-41](file://nflg-wms-admin/src/test/java/com/nflg/wms/admin/DeploySitTest.java#L28-L41)

## 结论
NFGL WMS系统具备清晰的微服务边界与完善的基础设施依赖，结合Nacos、Loki、Prometheus与Actuator，可实现稳定可观测的生产部署。建议在现有基础上完善容器化与Kubernetes编排、引入入口限流与熔断、强化备份与灾备演练，并持续优化连接池与追踪采样策略以满足生产性能要求。

## 附录

### Docker部署指南（步骤要点）
- 镜像构建
  - 使用多阶段构建，先在构建镜像中执行Maven打包，再将产物复制到精简运行镜像，减少体积。
- 容器编排
  - 使用Compose或Kubernetes Deployment/Service/ConfigMap/Secret管理服务与配置；为每个服务设置健康检查探针。
- 网络配置
  - 将网关置于Ingress/Nginx之后，内部服务间通过ClusterIP访问；Nacos与数据库、Redis置于内网或同VPC。
- 环境变量
  - 通过ConfigMap注入Nacos地址、命名空间、组名与数据库连接串；敏感信息使用Secret。

### 负载均衡与高可用
- 服务发现与注册
  - 各服务启用@EnableDiscoveryClient并接入Nacos；网关开启自动路由与小写服务ID。
- 客户端负载均衡
  - 启用Spring Cloud LoadBalancer；结合K8s Service实现多副本横向扩展。
- 熔断与降级
  - 建议引入Spring Cloud Circuit Breaker与Resilience4j，对下游依赖进行熔断与超时控制。
- 故障转移
  - 通过K8s滚动更新与就绪探针，确保零停机切换；网关侧可配置重试与超时策略。

### 监控与日志
- Prometheus
  - 通过Actuator暴露指标，Prometheus定期抓取；自定义指标可结合Micrometer。
- Loki
  - 各服务配置Loki Appender，统一推送至Loki；结合Grafana进行可视化。
- 告警
  - 在Prometheus Alertmanager中配置阈值告警；结合企业微信/钉钉通知。

### 性能监控指标与基准测试
- 指标建议
  - JVM：堆内存、GC频率、线程数；数据库：连接池活跃数、等待时间；网关：请求速率、错误率、响应时间。
- 基准测试
  - 对登录、查询、导入导出等关键路径进行压力测试，记录P95/P99延迟与错误率，评估扩容阈值。

### 备份与恢复策略
- 数据备份
  - PostgreSQL使用逻辑备份（如pg_dump）定期归档；备份保留周期与异地存储策略应明确。
- 配置备份
  - Nacos配置导出与版本化管理；K8s ConfigMap/Secret纳入GitOps管理。
- 灾难恢复
  - 制定RTO/RPO目标，演练跨可用区/跨地域恢复流程；验证服务注册与发现、日志与监控链路恢复。

### 日常维护与巡检清单
- 每日
  - 检查服务健康状态、关键指标阈值、磁盘与内存使用率、日志量与错误率。
- 每周
  - 清理临时文件与旧日志；核对数据库连接池与慢查询；验证Nacos配置同步。
- 每月
  - 复盘告警与故障，优化采样与阈值；进行备份恢复演练。

### 自动化部署与CI/CD
- CI/CD流水线建议
  - 触发条件：合并请求或打Tag；步骤：代码检查、单元测试、打包、镜像构建与推送、Kubernetes部署与回滚策略。
- 部署脚本参考
  - 参考测试用例中的SSH/SFTP部署流程，封装为可重复的部署脚本，支持MD5校验与远程执行。

章节来源
- [DeploySitTest.java（管理端）:66-81](file://nflg-wms-admin/src/test/java/com/nflg/wms/admin/DeploySitTest.java#L66-L81)
- [readme.md:1-10](file://readme.md#L1-L10)