# 部署方案

<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-vue/package.json](file://fms-vue/package.json)
- [fms-vue/vite.config.js](file://fms-vue/vite.config.js)
</cite>

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

## 简介
本部署方案面向FMS系统生产环境，覆盖服务器硬件与操作系统要求、JDK与Node.js版本、前后端构建流程、Docker容器化与编排、Nginx反向代理（静态资源托管、API网关、SSL）、多环境差异化配置、以及负载均衡与高可用设计。文档基于仓库中后端Spring Boot应用、前端Vite工程及现有配置文件进行说明，确保可落地执行。

## 项目结构
FMS系统采用前后端分离架构：
- 后端：Spring Boot API服务（端口8088，上下文/api），使用SQL Server数据库，支持本地或OSS文件存储。
- 前端：Vue 3 + Vite工程，开发时通过Vite代理将/api请求转发至后端；生产环境由Nginx统一提供静态资源并反向代理API。

```mermaid
graph TB
Client["浏览器/客户端"] --> Nginx["Nginx 反向代理"]
Nginx --> |静态资源| FE["fms-vue 构建产物(dist)"]
Nginx --> |/api/*| BE["fms-api Spring Boot(8088)"]
BE --> DB["SQL Server"]
BE --> FS["文件存储<br/>本地/OSS"]
```

图表来源
- [fms-api/src/main/resources/application.yaml:1-34](file://fms-api/src/main/resources/application.yaml#L1-L34)
- [fms-vue/vite.config.js:11-22](file://fms-vue/vite.config.js#L11-L22)

章节来源
- [fms-api/src/main/resources/application.yaml:1-34](file://fms-api/src/main/resources/application.yaml#L1-L34)
- [fms-vue/vite.config.js:11-22](file://fms-vue/vite.config.js#L11-L22)

## 核心组件
- 后端服务：Spring Boot Web MVC + JDBC + Druid连接池 + JWT鉴权 + SQL Server驱动。
- 前端应用：Vue 3 + Vite + Pinia + Axios等。
- 数据存储：SQL Server（多机构properties配置）。
- 文件存储：本地目录或OSS（可通过配置切换）。

章节来源
- [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-vue/package.json:21-46](file://fms-vue/package.json#L21-L46)

## 架构总览
生产环境推荐拓扑：
- 入口层：Nginx对外暴露HTTPS，负责静态资源缓存、Gzip/Brotli压缩、限流、WAF（可选）和API路由。
- 应用层：fms-api以无状态方式运行，建议多实例横向扩展，配合会话共享或无状态JWT。
- 数据层：SQL Server主备或集群；文件存储建议使用对象存储（OSS）以提升可扩展性。

```mermaid
sequenceDiagram
participant U as "用户"
participant N as "Nginx"
participant F as "fms-vue 静态资源"
participant B as "fms-api 服务"
participant D as "SQL Server"
U->>N : HTTPS GET /index.html
N-->>U : 返回静态页面
U->>N : HTTPS POST /api/login
N->>B : 转发 /api/*
B->>D : 查询用户信息
D-->>B : 返回结果
B-->>N : JSON响应
N-->>U : 返回登录结果
```

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

## 详细组件分析

### 后端构建与运行（Maven + Spring Boot）
- JDK版本：Java 21（由POM属性指定）。
- Maven插件：spring-boot-maven-plugin打包为可执行JAR。
- 启动命令：Windows下start.cmd设置JAVA_HOME与MAVEN_HOME后执行spring-boot:run；生产环境直接java -jar运行。
- 关键依赖：Spring Web MVC、JDBC、Druid连接池、JWT、SQL Server驱动。

章节来源
- [fms-api/pom.xml:29-31](file://fms-api/pom.xml#L29-L31)
- [fms-api/pom.xml:98-105](file://fms-api/pom.xml#L98-L105)
- [fms-api/start.cmd:1-8](file://fms-api/start.cmd#L1-L8)

### 后端配置与环境变量
- 服务端口与上下文：server.port=8088，server.servlet.context-path=/api。
- 应用名：spring.application.name=fms-api。
- 认证：JWT密钥通过环境变量注入（FMS_JWT_SECRET），过期时间默认24小时。
- 数据库：连接池参数（初始大小、最小空闲、最大活跃、等待超时、健康检查等）在application.yaml中定义；多机构数据库连接通过config/dbconfigs/*.properties加载。
- 文件存储：默认local模式，本地目录./data/files，URL前缀/api/file/static；也可切换至OSS。

章节来源
- [fms-api/src/main/resources/application.yaml:1-34](file://fms-api/src/main/resources/application.yaml#L1-L34)
- [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)

### 前端构建与优化（Vite）
- 脚本命令：dev/build/preview/test/lint/fmt等。
- 开发代理：/api代理到http://127.0.0.1:8088，便于联调。
- 构建产物：vite build输出dist目录，适合Nginx托管。
- 依赖：Vue 3、Pinia、Axios、Vitest等。

章节来源
- [fms-vue/package.json:6-19](file://fms-vue/package.json#L6-L19)
- [fms-vue/vite.config.js:11-22](file://fms-vue/vite.config.js#L11-L22)
- [fms-vue/package.json:21-46](file://fms-vue/package.json#L21-L46)

### Docker容器化部署
- 后端镜像：基于OpenJDK 21基础镜像，复制fms-api打包的JAR，暴露8088端口，设置环境变量（如FMS_JWT_SECRET、数据库连接等）。
- 前端镜像：基于Nginx镜像，复制fms-vue/dist到/usr/share/nginx/html，并通过nginx.conf将/api反向代理到后端服务。
- 编排：使用docker-compose或Kubernetes管理多实例、滚动更新、健康检查、日志收集与监控。

（本节为通用实践说明，不直接引用具体代码文件）

### Nginx反向代理与静态资源托管
- 静态资源：将fms-vue/dist映射到根路径，启用缓存、Gzip/Brotli压缩、HTTP/2。
- API网关：将/api/*转发到后端服务集群（多个upstream节点实现负载均衡）。
- SSL证书：配置HTTPS监听、证书路径、强制HTTPS跳转、安全头（HSTS、CSP等）。
- 安全与限流：结合Nginx模块或外部WAF实现访问控制与速率限制。

（本节为通用实践说明，不直接引用具体代码文件）

### 多环境差异化配置
- 开发环境：
  - 前端：vite dev，/api代理到本地8088。
  - 后端：start.cmd或mvn spring-boot:run，读取本地dbconfigs与默认application.yaml。
- 测试环境：
  - 独立数据库与文件存储路径；JWT密钥与数据库连接通过环境变量注入。
- 生产环境：
  - 多实例后端+Nginx负载均衡；文件存储建议切换至OSS；严格的安全策略与监控告警。

章节来源
- [fms-vue/vite.config.js:15-21](file://fms-vue/vite.config.js#L15-L21)
- [fms-api/src/main/resources/application.yaml:10-34](file://fms-api/src/main/resources/application.yaml#L10-L34)

### 负载均衡与高可用
- 后端多实例：同一服务多副本，Nginx upstream轮询或加权策略。
- 会话无状态：使用JWT，避免服务端会话绑定。
- 数据库高可用：SQL Server主备或Always On；连接重试与熔断。
- 文件存储：对象存储（OSS）天然具备高可用与弹性扩容能力。
- 健康检查：Nginx主动探测后端存活，异常节点自动摘除。

（本节为通用实践说明，不直接引用具体代码文件）

## 依赖关系分析
- 后端依赖：Spring Web MVC、JDBC、Druid、JWT、SQL Server驱动。
- 前端依赖：Vue 3、Pinia、Axios、Vite、Vitest等。
- 运行时依赖：JDK 21、Node.js（与Vite兼容的版本）、Nginx（生产静态托管与反向代理）。

```mermaid
graph LR
A["fms-vue(package.json)"] --> V["Vite"]
A --> P["Vue 3"]
A --> X["Axios"]
B["fms-api(pom.xml)"] --> S["Spring Boot Web MVC"]
B --> J["JDBC + Druid"]
B --> W["JWT"]
B --> D["SQL Server Driver"]
```

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

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

## 性能与容量规划
- 服务器硬件（参考值）：
  - 后端：4核8GB起步，生产建议8核16GB以上；根据并发与SQL复杂度调整。
  - 前端/Nginx：2核4GB即可，主要承担静态资源与反向代理。
  - 数据库：按业务规模评估CPU/内存/IO，建议专用主机或云数据库。
- 操作系统：Linux发行版（CentOS/RHEL/Ubuntu/Debian）或Windows Server（若沿用Windows部署）。
- 网络与安全：开放443/80端口，关闭不必要端口；启用防火墙与访问白名单。
- 缓存与压缩：Nginx开启Gzip/Brotli、静态资源缓存；后端连接池与SQL优化。
- 监控与日志：集中日志采集（ELK/云日志）、指标监控（Prometheus+Grafana）、链路追踪（可选）。

（本节为通用实践说明，不直接引用具体代码文件）

## 故障排查指南
- 后端无法启动：
  - 检查JDK版本是否为21；确认spring-boot-maven-plugin已正确打包。
  - 验证application.yaml中的端口、上下文路径与数据库连接是否正确。
- 数据库连接失败：
  - 核对config/dbconfigs下的*.properties是否包含正确的url/username/password/driver。
  - 注意SQL Server TLS版本与加密选项（legacy环境需特殊JVM参数）。
- 前端代理问题：
  - 开发环境确认vite.config.js中/api代理目标地址可达。
  - 生产环境确认Nginx对/api的反向代理规则与后端服务端口一致。
- 文件访问异常：
  - 本地模式检查./data/files目录权限与磁盘空间。
  - OSS模式检查g3oss-url与鉴权配置。

章节来源
- [fms-api/start.cmd:1-8](file://fms-api/start.cmd#L1-L8)
- [fms-api/src/main/resources/application.yaml:1-34](file://fms-api/src/main/resources/application.yaml#L1-L34)
- [fms-api/config/dbconfigs/README.md:18-28](file://fms-api/config/dbconfigs/README.md#L18-L28)
- [fms-vue/vite.config.js:15-21](file://fms-vue/vite.config.js#L15-L21)

## 结论
本方案基于现有后端与前端工程，明确了生产环境的软硬件要求、构建与部署流程、容器化与编排思路、Nginx反向代理与安全配置、多环境差异化管理，以及负载均衡与高可用设计。按此方案实施，可实现稳定、可扩展且易维护的FMS系统生产部署。

## 附录
- 环境变量清单（示例）：
  - FMS_JWT_SECRET：JWT签名密钥（生产必须替换默认值）。
  - 数据库连接：通过config/dbconfigs/*.properties注入（敏感信息不入库）。
  - 文件存储：storage-type=local或oss；OSS模式下配置g3oss-url。
- 构建与发布步骤（概览）：
  - 前端：pnpm install -> pnpm build -> 产出dist。
  - 后端：mvn clean package -> 生成可执行JAR。
  - 部署：Nginx托管dist，/api反向代理到后端服务；配置HTTPS与缓存策略。

（本节为通用实践说明，不直接引用具体代码文件）