# 部署运维

<cite>
**本文引用的文件**
- [fms-api/pom.xml](file://fms-api/pom.xml)
- [fms-api/src/main/resources/application.yaml](file://fms-api/src/main/resources/application.yaml)
- [fms-api/start.cmd](file://fms-api/start.cmd)
- [fms-api/config/dbconfigs/README.md](file://fms-api/config/dbconfigs/README.md)
- [fms-api/config/dbconfigs/G3HD.properties](file://fms-api/config/dbconfigs/G3HD.properties)
- [fms-api/config/dbconfigs/G3HY2025.properties](file://fms-api/config/dbconfigs/G3HY2025.properties)
- [fms-vue/package.json](file://fms-vue/package.json)
- [fms-vue/vite.config.js](file://fms-vue/vite.config.js)
- [fms-api/src/main/java/cn/g3soft/fmsapi/utils/JwtUtils.java](file://fms-api/src/main/java/cn/g3soft/fmsapi/utils/JwtUtils.java)
</cite>

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

## 简介
本文件面向生产环境的FMS系统，提供端到端的部署与运维指南。内容涵盖：
- Docker容器化部署方案、服务器环境要求与网络配置
- 前后端构建流程与发布策略（静态资源优化、CDN与缓存）
- 监控与日志收集（应用性能监控、错误日志、告警）
- 数据库备份恢复与数据迁移流程
- 日常运维操作（服务启停、配置更新、故障排查）
- 性能调优与安全加固最佳实践

## 项目结构
FMS由前后端两个主要子系统构成：
- 后端：Spring Boot API服务（Java 21），使用Maven构建，默认端口8088，上下文路径/api
- 前端：Vue 3 + Vite应用，开发时通过代理访问后端API，生产构建为静态资源

```mermaid
graph TB
subgraph "前端"
FE["fms-vue<br/>Vite 构建"]
end
subgraph "后端"
BE["fms-api<br/>Spring Boot Web MVC"]
end
DB["SQL Server"]
OSS["对象存储(可选)"]
FE --> |"HTTP /api/*"| BE
BE --> DB
BE --> OSS
```

图表来源
- [fms-vue/vite.config.js:11-21](file://fms-vue/vite.config.js#L11-L21)
- [fms-api/src/main/resources/application.yaml:1-4](file://fms-api/src/main/resources/application.yaml#L1-L4)

章节来源
- [fms-api/src/main/resources/application.yaml:1-34](file://fms-api/src/main/resources/application.yaml#L1-L34)
- [fms-vue/vite.config.js:1-25](file://fms-vue/vite.config.js#L1-L25)
- [fms-vue/package.json:6-19](file://fms-vue/package.json#L6-L19)
- [fms-api/pom.xml:29-96](file://fms-api/pom.xml#L29-L96)

## 核心组件
- 后端服务：基于Spring Boot Web MVC，内置Tomcat，暴露REST接口；使用Druid连接池与SQL Server JDBC驱动；JWT鉴权；支持本地或OSS文件存储
- 前端应用：Vue 3 + Vite，开发模式代理/api到后端；生产模式输出静态资源供Web服务器或CDN托管
- 数据库：SQL Server，按组织隔离的配置文件管理多库连接
- 安全：JWT签名与校验，密钥长度与有效期强制校验

章节来源
- [fms-api/pom.xml:32-96](file://fms-api/pom.xml#L32-L96)
- [fms-api/src/main/resources/application.yaml:10-34](file://fms-api/src/main/resources/application.yaml#L10-L34)
- [fms-api/config/dbconfigs/README.md:1-28](file://fms-api/config/dbconfigs/README.md#L1-L28)
- [fms-api/src/main/java/cn/g3soft/fmsapi/utils/JwtUtils.java:18-81](file://fms-api/src/main/java/cn/g3soft/fmsapi/utils/JwtUtils.java#L18-L81)

## 架构总览
生产环境推荐拓扑：
- Nginx/反向代理对外暴露HTTPS入口，将静态资源请求指向CDN或本地静态目录，将/api转发至后端
- 后端以Docker容器运行，挂载外部卷用于文件存储与配置
- 数据库独立部署，仅对后端开放端口

```mermaid
graph TB
Client["浏览器/客户端"]
CDN["CDN(可选)"]
Nginx["Nginx/反向代理"]
FEStatic["前端静态资源(dist)"]
BE["fms-api 容器"]
DB["SQL Server"]
OSS["对象存储(可选)"]
Client --> |HTTPS /| Nginx
Nginx --> |静态资源| CDN
Nginx --> |静态资源| FEStatic
Nginx --> |/api/*| BE
BE --> DB
BE --> OSS
```

图表来源
- [fms-vue/vite.config.js:11-21](file://fms-vue/vite.config.js#L11-L21)
- [fms-api/src/main/resources/application.yaml:1-4](file://fms-api/src/main/resources/application.yaml#L1-L4)
- [fms-api/src/main/resources/application.yaml:27-34](file://fms-api/src/main/resources/application.yaml#L27-L34)

## 详细组件分析

### 后端服务（fms-api）
- 技术栈与依赖：Spring Boot Web MVC、JDBC、Druid连接池、SQL Server JDBC驱动、JWT、Jackson、UA解析、IP定位等
- 启动方式：Maven spring-boot:run（开发脚本），生产建议打包为可执行JAR并容器化运行
- 配置要点：
  - 服务端口与上下文路径
  - JWT密钥与有效期
  - 数据库连接池参数
  - 文件存储类型（本地/OSS）及路径/URL前缀

```mermaid
classDiagram
class JwtUtils {
+init() void
+generateToken(userId, orgId, sessionId) String
+parseToken(token) TokenClaims
+getOrgId(token) String
}
class AuthProperties {
+jwtSecret String
+jwtExpiration Duration
}
class ApplicationConfig {
+server.port int
+server.servlet.context-path String
+fms.auth.jwt-secret String
+fms.auth.jwt-expiration Duration
+fms.database.pool.* ...
+fms.file.storage-type String
+fms.file.local.storage-dir String
+fms.file.local.url-prefix String
+fms.file.oss.g3oss-url String
}
JwtUtils --> AuthProperties : "读取配置"
ApplicationConfig ..> JwtUtils : "影响鉴权行为"
```

图表来源
- [fms-api/src/main/java/cn/g3soft/fmsapi/utils/JwtUtils.java:18-81](file://fms-api/src/main/java/cn/g3soft/fmsapi/utils/JwtUtils.java#L18-L81)
- [fms-api/src/main/resources/application.yaml:1-34](file://fms-api/src/main/resources/application.yaml#L1-L34)

章节来源
- [fms-api/pom.xml:29-96](file://fms-api/pom.xml#L29-L96)
- [fms-api/src/main/resources/application.yaml:1-34](file://fms-api/src/main/resources/application.yaml#L1-L34)
- [fms-api/start.cmd:1-8](file://fms-api/start.cmd#L1-L8)

### 前端应用（fms-vue）
- 构建与预览：vite build生成dist静态资源；vite preview本地预览
- 开发代理：开发时将/api请求代理到后端8088端口
- 发布产物：dist目录包含HTML、JS、CSS等资源，适合放置于Nginx或CDN

```mermaid
flowchart TD
Start(["开始"]) --> Build["执行 vite build"]
Build --> Dist["产出 dist 静态资源"]
Dist --> Deploy["部署至 Nginx/CDN"]
Deploy --> End(["完成"])
```

图表来源
- [fms-vue/package.json:6-19](file://fms-vue/package.json#L6-L19)
- [fms-vue/vite.config.js:11-21](file://fms-vue/vite.config.js#L11-L21)

章节来源
- [fms-vue/package.json:6-19](file://fms-vue/package.json#L6-L19)
- [fms-vue/vite.config.js:1-25](file://fms-vue/vite.config.js#L1-L25)

### 数据库与多租户配置
- 多组织数据库：每个组织一个properties文件，命名规则与示例见文档
- 连接信息：url、username、password、driver
- 开发兼容：旧版SQL Server需TLS兼容参数

```mermaid
flowchart TD
A["选择组织ID"] --> B{"是否存在对应 .properties ?"}
B --> |是| C["加载连接参数"]
B --> |否| D["报错/回退"]
C --> E["建立数据库连接"]
```

图表来源
- [fms-api/config/dbconfigs/README.md:1-28](file://fms-api/config/dbconfigs/README.md#L1-L28)
- [fms-api/config/dbconfigs/G3HD.properties:1-5](file://fms-api/config/dbconfigs/G3HD.properties#L1-L5)
- [fms-api/config/dbconfigs/G3HY2025.properties:1-5](file://fms-api/config/dbconfigs/G3HY2025.properties#L1-L5)

章节来源
- [fms-api/config/dbconfigs/README.md:1-28](file://fms-api/config/dbconfigs/README.md#L1-L28)
- [fms-api/config/dbconfigs/G3HD.properties:1-5](file://fms-api/config/dbconfigs/G3HD.properties#L1-L5)
- [fms-api/config/dbconfigs/G3HY2025.properties:1-5](file://fms-api/config/dbconfigs/G3HY2025.properties#L1-L5)

### 登录鉴权流程（JWT）
```mermaid
sequenceDiagram
participant C as "客户端"
participant S as "fms-api"
participant J as "JwtUtils"
C->>S : "POST /api/auth/login (账号/密码)"
S->>S : "验证凭据"
S->>J : "generateToken(userId, orgId, sessionId)"
J-->>S : "返回JWT字符串"
S-->>C : "返回{token}"
C->>S : "后续请求携带 Authorization : Bearer <token>"
S->>J : "parseToken(token)"
J-->>S : "解析出userId/orgId/sessionId"
S-->>C : "业务响应"
```

图表来源
- [fms-api/src/main/java/cn/g3soft/fmsapi/utils/JwtUtils.java:45-66](file://fms-api/src/main/java/cn/g3soft/fmsapi/utils/JwtUtils.java#L45-L66)
- [fms-api/src/main/resources/application.yaml:10-13](file://fms-api/src/main/resources/application.yaml#L10-L13)

章节来源
- [fms-api/src/main/java/cn/g3soft/fmsapi/utils/JwtUtils.java:18-81](file://fms-api/src/main/java/cn/g3soft/fmsapi/utils/JwtUtils.java#L18-L81)
- [fms-api/src/main/resources/application.yaml:10-13](file://fms-api/src/main/resources/application.yaml#L10-L13)

## 依赖关系分析
- 后端依赖：Spring Boot、JDBC、Druid、SQL Server驱动、JWT、Jackson、UA Parser、IP2Region
- 前端依赖：Vue 3、Vue Router、Pinia、Axios、Dayjs、UI组件库等
- 运行时依赖：JDK 21、Node.js（构建期）、Nginx/CDN（生产）

```mermaid
graph LR
FE["fms-vue"] --> |"构建产物"| DIST["dist 静态资源"]
DIST --> |"托管"| WEB["Nginx/CDN"]
WEB --> |"HTTP /api/*"| BE["fms-api"]
BE --> |"JDBC"| DB["SQL Server"]
BE --> |"可选"| OSS["对象存储"]
```

图表来源
- [fms-vue/package.json:21-45](file://fms-vue/package.json#L21-L45)
- [fms-api/pom.xml:32-96](file://fms-api/pom.xml#L32-L96)

章节来源
- [fms-vue/package.json:21-45](file://fms-vue/package.json#L21-L45)
- [fms-api/pom.xml:32-96](file://fms-api/pom.xml#L32-L96)

## 性能考虑
- 连接池调优：根据并发与延迟调整初始大小、最小空闲、最大活跃、等待超时、空闲检测间隔等
- 静态资源优化：启用Gzip/Brotli压缩、长缓存（带版本哈希）、按需懒加载路由与组件
- CDN与缓存：静态资源上CDN，设置合理的Cache-Control与ETag；API层避免过度缓存敏感数据
- 数据库：索引优化、慢查询治理、连接池上限与超时合理配置
- 容器资源：限制CPU/内存，预留堆外内存给JVM与连接池

[本节为通用指导，不直接分析具体文件]

## 故障排查指南
- 启动失败
  - 检查JDK版本与环境变量（参考开发启动脚本）
  - 确认端口占用与上下文路径
- 鉴权异常
  - 校验JWT密钥长度与有效期配置
  - 检查令牌是否过期或缺失必要声明
- 数据库连接问题
  - 核对组织数据库配置文件格式与连通性
  - 关注连接池耗尽与超时
- 文件上传/访问
  - 本地存储：确认目录存在且可写，URL前缀正确
  - OSS：确认地址与权限

章节来源
- [fms-api/start.cmd:1-8](file://fms-api/start.cmd#L1-L8)
- [fms-api/src/main/java/cn/g3soft/fmsapi/utils/JwtUtils.java:28-42](file://fms-api/src/main/java/cn/g3soft/fmsapi/utils/JwtUtils.java#L28-L42)
- [fms-api/config/dbconfigs/README.md:1-28](file://fms-api/config/dbconfigs/README.md#L1-L28)
- [fms-api/src/main/resources/application.yaml:27-34](file://fms-api/src/main/resources/application.yaml#L27-L34)

## 结论
FMS采用前后端分离架构，后端以Spring Boot提供服务，前端以Vite构建静态资源。生产部署建议通过反向代理统一入口，结合CDN加速静态资源，数据库独立部署并按组织隔离。配合合理的连接池、缓存与监控策略，可获得稳定高效的运行体验。

[本节为总结性内容，不直接分析具体文件]

## 附录

### 生产部署方案（Docker化）
- 镜像构建
  - 后端：基于JDK 21基础镜像，复制打包后的JAR，暴露端口8088
  - 前端：基于Nginx镜像，复制dist目录，配置静态资源与反向代理
- 环境变量与配置
  - 后端：通过环境变量注入JWT密钥、数据库连接池参数、文件存储配置
  - 前端：通过Nginx环境变量或构建时替换API基址
- 数据持久化
  - 挂载文件存储目录（本地模式）
  - 数据库与对象存储独立部署
- 网络与安全
  - 仅开放443端口，内部端口不暴露
  - 启用HTTPS，配置强加密套件与HSTS
  - 限制跨域与源白名单

[本节为通用指导，不直接分析具体文件]

### 服务器环境要求
- 后端：JDK 21，建议4核8GB起（视并发与负载调整）
- 前端：构建阶段需要Node.js（版本与包管理器依pnpm-lock为准）
- 数据库：SQL Server（版本与TLS策略需与驱动匹配）
- 存储：本地磁盘或对象存储（按配置）

章节来源
- [fms-api/pom.xml:29-31](file://fms-api/pom.xml#L29-L31)
- [fms-api/config/dbconfigs/README.md:18-28](file://fms-api/config/dbconfigs/README.md#L18-L28)

### 前后端构建流程与发布策略
- 前端
  - 开发：vite dev，自动代理/api到后端
  - 构建：vite build，产出dist
  - 发布：将dist部署至Nginx或CDN，配置缓存头与压缩
- 后端
  - 构建：mvn package（Spring Boot Maven插件）
  - 运行：java -jar 或容器运行
  - 配置：application.yaml与组织数据库配置文件

章节来源
- [fms-vue/package.json:6-19](file://fms-vue/package.json#L6-L19)
- [fms-vue/vite.config.js:11-21](file://fms-vue/vite.config.js#L11-L21)
- [fms-api/pom.xml:98-105](file://fms-api/pom.xml#L98-L105)
- [fms-api/src/main/resources/application.yaml:1-34](file://fms-api/src/main/resources/application.yaml#L1-L34)

### 静态资源优化、CDN与缓存策略
- 启用Gzip/Brotli压缩
- 为静态资源设置长期缓存（带内容哈希）
- 使用CDN分发静态资源，配置边缘缓存与回源策略
- API响应按需缓存，敏感数据不缓存

[本节为通用指导，不直接分析具体文件]

### 监控与日志收集
- 应用性能监控
  - 接入APM（如SkyWalking/Pinpoint）采集JVM指标、接口耗时、错误率
- 日志收集
  - 应用日志：统一输出JSON格式，集中收集（ELK/Loki）
  - 访问日志：Nginx访问日志结构化，便于审计与分析
- 告警机制
  - 基于指标阈值（CPU/内存/错误率/慢查询）配置告警
  - 关键链路失败即时通知

[本节为通用指导，不直接分析具体文件]

### 数据库备份恢复与数据迁移
- 备份策略
  - 全量+增量备份，异地容灾
  - 定期演练恢复流程
- 恢复流程
  - 停机窗口评估与回滚预案
  - 校验备份完整性后恢复
- 数据迁移
  - 使用版本化脚本与工具进行增量迁移
  - 迁移前后进行一致性校验与回滚方案

[本节为通用指导，不直接分析具体文件]

### 日常运维操作
- 服务启停
  - 后端：systemd或容器编排管理生命周期
  - 前端：Nginx重载配置或滚动更新
- 配置更新
  - 后端：热更新或灰度发布（注意状态与连接池）
  - 前端：静态资源版本升级，CDN刷新
- 故障排查
  - 查看应用日志、访问日志、数据库慢查询
  - 检查连接池、磁盘空间、证书有效期

[本节为通用指导，不直接分析具体文件]

### 性能调优与安全加固
- 性能调优
  - JVM参数优化（堆大小、GC策略）
  - 连接池与线程池容量调优
  - 静态资源压缩与缓存
- 安全加固
  - HTTPS强制与强加密套件
  - JWT密钥轮换与最小权限原则
  - 输入校验、防注入、限流与防重放
  - 敏感配置外置与加密存储

[本节为通用指导，不直接分析具体文件]