20260823210241
This commit is contained in:
oneao committed
1 parent
5ff4583aeb
commit
f4c7413dc6
2766 files changed
+1836409
-94689
No files matched your search
@@ -0,0 +1,378 @@
|
||||
# 前端配置
|
||||
|
||||
<cite>
|
||||
**本文引用的文件**
|
||||
- [vite.config.js](file://fms-vue/vite.config.js)
|
||||
- [package.json](file://fms-vue/package.json)
|
||||
- [vitest.config.js](file://fms-vue/vitest.config.js)
|
||||
- [index.html](file://fms-vue/index.html)
|
||||
- [main.js](file://fms-vue/src/main.js)
|
||||
- [http.js](file://fms-vue/src/services/http.js)
|
||||
- [tokens.css](file://fms-vue/src/theme/tokens.css)
|
||||
- [index.js](file://fms-vue/src/theme/index.js)
|
||||
- [presets.js](file://fms-vue/src/theme/presets.js)
|
||||
- [app.js](file://fms-vue/src/stores/app.js)
|
||||
- [index.css](file://fms-vue/src/styles/index.css)
|
||||
</cite>
|
||||
|
||||
## 目录
|
||||
1. [简介](#简介)
|
||||
2. [项目结构](#项目结构)
|
||||
3. [核心组件](#核心组件)
|
||||
4. [架构总览](#架构总览)
|
||||
5. [详细组件分析](#详细组件分析)
|
||||
6. [依赖关系分析](#依赖关系分析)
|
||||
7. [性能考量](#性能考量)
|
||||
8. [故障排查指南](#故障排查指南)
|
||||
9. [结论](#结论)
|
||||
10. [附录](#附录)
|
||||
|
||||
## 简介
|
||||
本文件面向 FMS 前端（基于 Vite + Vue 3）的配置系统，聚焦以下目标：
|
||||
- 全面说明 Vite 构建与开发服务器配置：端口、主机、代理、路径别名等。
|
||||
- 详解主题系统：颜色变量、样式令牌、深浅色切换与主色动态替换机制。
|
||||
- 环境变量管理策略：开发/测试/生产环境的差异与最佳实践。
|
||||
- 插件与构建优化选项：当前已启用能力与可扩展点。
|
||||
- 给出可操作的最佳实践：性能优化、代码分割、资源加载策略。
|
||||
- 提供常见问题定位与解决方案。
|
||||
|
||||
## 项目结构
|
||||
FMS 前端位于 fms-vue 子工程，关键配置与运行时入口如下：
|
||||
- 构建与开发服务器：vite.config.js
|
||||
- 脚本与依赖：package.json
|
||||
- 测试配置：vitest.config.js
|
||||
- 应用入口与启动流程：src/main.js、index.html
|
||||
- HTTP 客户端与环境变量使用：src/services/http.js
|
||||
- 主题系统与样式：src/theme/*、src/styles/index.css
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
A["index.html<br/>首屏与加载屏"] --> B["src/main.js<br/>应用初始化"]
|
||||
B --> C["vite.config.js<br/>Vite 构建/开发配置"]
|
||||
B --> D["src/services/http.js<br/>HTTP 客户端与环境变量"]
|
||||
B --> E["src/stores/app.js<br/>主题状态与持久化"]
|
||||
E --> F["src/theme/index.js<br/>写入 CSS 变量/切换深色类"]
|
||||
F --> G["src/theme/tokens.css<br/>设计令牌与深浅色覆盖"]
|
||||
E --> H["src/theme/presets.js<br/>预设主色"]
|
||||
B --> I["src/styles/index.css<br/>引入 tokens 与字体"]
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [index.html:1-295](file://fms-vue/index.html#L1-L295)
|
||||
- [main.js:1-78](file://fms-vue/src/main.js#L1-L78)
|
||||
- [vite.config.js:1-25](file://fms-vue/vite.config.js#L1-L25)
|
||||
- [http.js:1-111](file://fms-vue/src/services/http.js#L1-L111)
|
||||
- [app.js:1-123](file://fms-vue/src/stores/app.js#L1-L123)
|
||||
- [index.js:1-16](file://fms-vue/src/theme/index.js#L1-L16)
|
||||
- [tokens.css:1-152](file://fms-vue/src/theme/tokens.css#L1-L152)
|
||||
- [presets.js:1-16](file://fms-vue/src/theme/presets.js#L1-L16)
|
||||
- [index.css:1-17](file://fms-vue/src/styles/index.css#L1-L17)
|
||||
|
||||
章节来源
|
||||
- [vite.config.js:1-25](file://fms-vue/vite.config.js#L1-L25)
|
||||
- [package.json:1-48](file://fms-vue/package.json#L1-L48)
|
||||
- [vitest.config.js:1-34](file://fms-vue/vitest.config.js#L1-L34)
|
||||
- [index.html:1-295](file://fms-vue/index.html#L1-L295)
|
||||
- [main.js:1-78](file://fms-vue/src/main.js#L1-L78)
|
||||
|
||||
## 核心组件
|
||||
- Vite 构建与开发服务器
|
||||
- 路径别名：将 @ 指向 src，便于统一导入。
|
||||
- 开发服务器：host 为 true，port 固定为 5082，strictPort 确保端口独占；/api 请求代理到后端 http://127.0.0.1:8088。
|
||||
- 插件：仅启用 @vitejs/plugin-vue。
|
||||
- 主题系统
|
||||
- 设计令牌：集中定义在 tokens.css，浅色 :root，深色 .dark 覆盖同一批变量；主色 --fms-primary 由 JS 注入，衍生色通过 color-mix 派生。
|
||||
- 主题切换：通过 app store 的 darkMode 与 primaryColor 驱动 index.js 中的 applyDarkMode 与 applyPrimaryColor，实时修改 DOM。
|
||||
- 预设色板：presets.js 提供多套主色，默认主色与 store 初始值一致。
|
||||
- 环境变量与网络
|
||||
- 基础 URL：http.js 使用 import.meta.env.VITE_API_BASE_URL，未设置时回退到 /api（开发期走 Vite 代理）。
|
||||
- 鉴权与错误处理：拦截器统一处理 401/40101 会话失效并跳转登录；网络异常或 5xx 统一提示。
|
||||
- 应用启动与加载体验
|
||||
- index.html 内嵌脚本在模块加载前读取本地存储的主题偏好，给 html 添加 boot-dark 类，避免首屏闪烁。
|
||||
- main.js 在挂载前初始化主题同步，路由就绪后挂载应用，并以过渡动画隐藏加载屏。
|
||||
|
||||
章节来源
|
||||
- [vite.config.js:5-23](file://fms-vue/vite.config.js#L5-L23)
|
||||
- [tokens.css:7-151](file://fms-vue/src/theme/tokens.css#L7-L151)
|
||||
- [index.js:5-15](file://fms-vue/src/theme/index.js#L5-L15)
|
||||
- [presets.js:1-16](file://fms-vue/src/theme/presets.js#L1-L16)
|
||||
- [app.js:6-123](file://fms-vue/src/stores/app.js#L6-L123)
|
||||
- [http.js:8-10](file://fms-vue/src/services/http.js#L8-L10)
|
||||
- [index.html:8-19](file://fms-vue/index.html#L8-L19)
|
||||
- [main.js:21-58](file://fms-vue/src/main.js#L21-L58)
|
||||
|
||||
## 架构总览
|
||||
下图展示从浏览器加载到主题生效、网络请求代理的关键链路。
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant U as "用户"
|
||||
participant H as "index.html"
|
||||
participant M as "main.js"
|
||||
participant S as "stores/app.js"
|
||||
participant T as "theme/index.js"
|
||||
participant C as "theme/tokens.css"
|
||||
participant V as "vite.config.js"
|
||||
participant API as "后端服务(8088)"
|
||||
U->>H : 打开页面
|
||||
H-->>U : 显示加载屏根据本地存储决定是否加 boot-dark
|
||||
H->>M : 执行入口脚本
|
||||
M->>S : initThemeSync(pinia)
|
||||
S->>T : applyDarkMode(darkMode)
|
||||
T->>C : 切换 .dark 类
|
||||
S->>T : applyPrimaryColor(primaryColor)
|
||||
T->>C : 写入 --fms-primary
|
||||
U->>M : 触发业务请求
|
||||
M->>V : 开发期 /api 请求
|
||||
V-->>API : 代理转发到 http : //127.0.0.1 : 8088
|
||||
API-->>U : 返回数据
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [index.html:8-19](file://fms-vue/index.html#L8-L19)
|
||||
- [main.js:21-58](file://fms-vue/src/main.js#L21-L58)
|
||||
- [app.js:104-123](file://fms-vue/src/stores/app.js#L104-L123)
|
||||
- [index.js:5-15](file://fms-vue/src/theme/index.js#L5-L15)
|
||||
- [tokens.css:7-151](file://fms-vue/src/theme/tokens.css#L7-L151)
|
||||
- [vite.config.js:11-21](file://fms-vue/vite.config.js#L11-L21)
|
||||
|
||||
## 详细组件分析
|
||||
|
||||
### Vite 构建与开发服务器配置
|
||||
- 路径别名
|
||||
- 将 @ 映射到 src，简化导入路径。
|
||||
- 开发服务器
|
||||
- host: true 允许局域网访问；port: 5082；strictPort: true 避免自动换端口。
|
||||
- 代理：/api -> http://127.0.0.1:8088，changeOrigin 开启以兼容后端跨域校验。
|
||||
- 插件
|
||||
- 仅启用 Vue 插件，保持轻量。
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Start(["启动 dev"]) --> Alias["解析路径别名 @ -> src"]
|
||||
Alias --> Server["启动开发服务器 5082"]
|
||||
Server --> Proxy{"请求是否匹配 /api ?"}
|
||||
Proxy --> |是| Forward["转发到 http://127.0.0.1:8088"]
|
||||
Proxy --> |否| Serve["本地静态资源/模块热更新"]
|
||||
Forward --> End(["响应"])
|
||||
Serve --> End
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [vite.config.js:6-21](file://fms-vue/vite.config.js#L6-L21)
|
||||
|
||||
章节来源
|
||||
- [vite.config.js:1-25](file://fms-vue/vite.config.js#L1-L25)
|
||||
|
||||
### 主题配置系统
|
||||
- 设计令牌
|
||||
- tokens.css 定义中性色、语义色、控件尺寸、阴影、层级等变量；浅色在 :root，深色通过 .dark 覆盖。
|
||||
- 主色 --fms-primary 由 JS 注入，hover/active 等衍生色通过 color-mix 计算，保证明暗对比。
|
||||
- 主题切换机制
|
||||
- app store 维护 darkMode 与 primaryColor，并通过 watch 调用 theme/index.js 的方法更新 DOM。
|
||||
- 持久化：pinia-plugin-persistedstate 仅持久化 darkMode、primaryColor、locale。
|
||||
- 预设色板
|
||||
- presets.js 提供多套主色，DEFAULT_PRIMARY 作为初始值。
|
||||
|
||||
```mermaid
|
||||
classDiagram
|
||||
class AppStore {
|
||||
+boolean darkMode
|
||||
+string primaryColor
|
||||
+setDark(value)
|
||||
+toggleDark()
|
||||
+setPrimary(color)
|
||||
}
|
||||
class ThemeAPI {
|
||||
+applyDarkMode(isDark)
|
||||
+applyPrimaryColor(color)
|
||||
}
|
||||
class TokensCSS {
|
||||
+" : root 变量"
|
||||
+".dark 覆盖变量"
|
||||
}
|
||||
class Presets {
|
||||
+PRESETS[]
|
||||
+DEFAULT_PRIMARY
|
||||
}
|
||||
AppStore --> ThemeAPI : "watch 驱动"
|
||||
ThemeAPI --> TokensCSS : "写入 CSS 变量/切换类"
|
||||
AppStore --> Presets : "读取默认主色"
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [app.js:6-123](file://fms-vue/src/stores/app.js#L6-L123)
|
||||
- [index.js:5-15](file://fms-vue/src/theme/index.js#L5-L15)
|
||||
- [tokens.css:7-151](file://fms-vue/src/theme/tokens.css#L7-L151)
|
||||
- [presets.js:1-16](file://fms-vue/src/theme/presets.js#L1-L16)
|
||||
|
||||
章节来源
|
||||
- [tokens.css:7-151](file://fms-vue/src/theme/tokens.css#L7-L151)
|
||||
- [index.js:5-15](file://fms-vue/src/theme/index.js#L5-L15)
|
||||
- [presets.js:1-16](file://fms-vue/src/theme/presets.js#L1-L16)
|
||||
- [app.js:6-123](file://fms-vue/src/stores/app.js#L6-L123)
|
||||
|
||||
### 环境变量管理与网络层
|
||||
- 环境变量
|
||||
- 使用 import.meta.env.VITE_API_BASE_URL 指定 API 基础地址；未设置时回退到 /api。
|
||||
- 开发期通过 Vite 代理将 /api 转发至后端；生产环境建议直接配置真实 API 地址。
|
||||
- 请求与错误处理
|
||||
- 请求拦截器注入 Authorization 头；响应拦截器统一封装 ApiResult，处理 401/40101 会话失效并跳转登录。
|
||||
- 网络异常或 5xx 统一提示，4xx 业务错误交由调用方处理。
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant UI as "业务组件"
|
||||
participant HTTP as "http.js"
|
||||
participant AUTH as "auth store"
|
||||
participant MSG as "Message"
|
||||
participant BE as "后端"
|
||||
UI->>HTTP : post(path, data)
|
||||
HTTP->>AUTH : 读取 token
|
||||
HTTP->>BE : 发送请求(带 Authorization)
|
||||
alt 成功
|
||||
BE-->>HTTP : 返回数据
|
||||
HTTP-->>UI : 透传结果
|
||||
else 鉴权失败(401/40101)
|
||||
BE-->>HTTP : 鉴权错误
|
||||
HTTP->>AUTH : 清除会话
|
||||
HTTP-->>UI : 抛出错误
|
||||
HTTP->>UI : 跳转登录页
|
||||
else 网络/服务端错误
|
||||
BE-->>HTTP : 无响应或 5xx
|
||||
HTTP->>MSG : 统一错误提示
|
||||
HTTP-->>UI : 抛出错误
|
||||
end
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [http.js:8-10](file://fms-vue/src/services/http.js#L8-L10)
|
||||
- [http.js:40-104](file://fms-vue/src/services/http.js#L40-L104)
|
||||
|
||||
章节来源
|
||||
- [http.js:1-111](file://fms-vue/src/services/http.js#L1-L111)
|
||||
|
||||
### 应用启动与加载体验
|
||||
- 首屏防闪烁
|
||||
- index.html 在模块加载前读取 localStorage 中 app 的 darkMode，若为真则给 html 添加 boot-dark，使加载屏与最终主题一致。
|
||||
- 启动流程
|
||||
- main.js 创建 Pinia 并启用持久化插件，先初始化主题同步，再等待路由就绪后挂载应用，最后以过渡动画隐藏加载屏。
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Boot["index.html 加载"] --> Check["读取本地存储主题偏好"]
|
||||
Check --> ApplyBoot{"是否需要深色?"}
|
||||
ApplyBoot --> |是| AddClass["html 添加 boot-dark"]
|
||||
ApplyBoot --> |否| Skip["保持浅色"]
|
||||
AddClass --> Main["执行 main.js"]
|
||||
Skip --> Main
|
||||
Main --> InitTheme["initThemeSync 恢复主题"]
|
||||
InitTheme --> Mount["挂载应用"]
|
||||
Mount --> HideBoot["淡出加载屏"]
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [index.html:8-19](file://fms-vue/index.html#L8-L19)
|
||||
- [main.js:14-58](file://fms-vue/src/main.js#L14-L58)
|
||||
|
||||
章节来源
|
||||
- [index.html:8-19](file://fms-vue/index.html#L8-L19)
|
||||
- [main.js:14-58](file://fms-vue/src/main.js#L14-L58)
|
||||
|
||||
### 测试配置
|
||||
- Vitest 使用 jsdom 环境，全局开关开启，setupFiles 指定初始化脚本。
|
||||
- 覆盖率统计排除入口与纯常量文件，阈值 60% 起步。
|
||||
|
||||
章节来源
|
||||
- [vitest.config.js:1-34](file://fms-vue/vitest.config.js#L1-L34)
|
||||
|
||||
## 依赖关系分析
|
||||
- 构建与运行
|
||||
- package.json 定义了 dev/build/preview/test/lint/fmt 等脚本，依赖 vite、@vitejs/plugin-vue、vue 等。
|
||||
- 运行时依赖
|
||||
- axios 用于网络请求；pinia 与 pinia-plugin-persistedstate 负责状态与持久化；stk-table-vue 提供表格能力。
|
||||
- 样式依赖
|
||||
- styles/index.css 引入 tokens.css、组件库样式与字体。
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
Pkg["package.json<br/>脚本与依赖"] --> Vite["vite.config.js"]
|
||||
Pkg --> Vue["Vue 3 生态"]
|
||||
Pkg --> Axios["axios"]
|
||||
Pkg --> Pinia["pinia + persistedstate"]
|
||||
Pkg --> Table["stk-table-vue"]
|
||||
Styles["styles/index.css"] --> Tokens["theme/tokens.css"]
|
||||
Styles --> Font["@fontsource/noto-sans-sc"]
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [package.json:1-48](file://fms-vue/package.json#L1-L48)
|
||||
- [index.css:1-17](file://fms-vue/src/styles/index.css#L1-L17)
|
||||
|
||||
章节来源
|
||||
- [package.json:1-48](file://fms-vue/package.json#L1-L48)
|
||||
- [index.css:1-17](file://fms-vue/src/styles/index.css#L1-L17)
|
||||
|
||||
## 性能考量
|
||||
- 构建与打包
|
||||
- 当前未启用额外插件，可通过按需引入、Tree Shaking、分包策略进一步优化。
|
||||
- 建议：对大体积第三方库进行按需引入或外部化；对路由级视图进行懒加载。
|
||||
- 开发体验
|
||||
- 严格端口与固定端口有助于 CI/CD 稳定性；代理配置减少跨域问题。
|
||||
- 主题渲染
|
||||
- 使用 CSS 变量与 color-mix 减少重复样式；在首屏前注入主题类避免闪烁。
|
||||
- 网络
|
||||
- 合理设置超时与统一错误提示；对鉴权失败做快速重定向，提升用户体验。
|
||||
|
||||
[本节为通用指导，不直接分析具体文件]
|
||||
|
||||
## 故障排查指南
|
||||
- 开发服务器端口占用
|
||||
- 现象：启动时报端口被占用。
|
||||
- 处理：确认 5082 端口未被占用，或调整 vite.config.js 中的 port。
|
||||
- 代理无效导致 404
|
||||
- 现象：请求 /api 返回 404。
|
||||
- 处理：检查 vite.config.js 的 proxy 配置与后端服务是否启动在 8088。
|
||||
- 主题闪烁
|
||||
- 现象：首次加载出现浅色闪屏。
|
||||
- 处理：确认 index.html 中读取本地存储并添加 boot-dark 的逻辑存在且正确。
|
||||
- 登录后仍频繁跳转
|
||||
- 现象：进入页面即跳转登录。
|
||||
- 处理：检查 http.js 的鉴权拦截逻辑与后端返回码是否为 401/40101。
|
||||
- 构建产物过大
|
||||
- 现象：包体积增长明显。
|
||||
- 处理：评估是否引入了未使用的依赖；考虑拆分与懒加载。
|
||||
|
||||
章节来源
|
||||
- [vite.config.js:11-21](file://fms-vue/vite.config.js#L11-L21)
|
||||
- [index.html:8-19](file://fms-vue/index.html#L8-L19)
|
||||
- [http.js:40-104](file://fms-vue/src/services/http.js#L40-L104)
|
||||
|
||||
## 结论
|
||||
本项目的前端配置以简洁、可维护为核心：
|
||||
- Vite 配置聚焦路径别名、开发服务器与代理，满足日常开发与联调需求。
|
||||
- 主题系统通过 CSS 变量与 JS 驱动实现灵活切换，支持深浅色与主色定制。
|
||||
- 环境变量与网络层解耦清晰，便于在不同环境部署。
|
||||
- 建议在后续迭代中逐步引入按需引入、路由懒加载、更细粒度的构建优化，进一步提升性能与可维护性。
|
||||
|
||||
[本节为总结，不直接分析具体文件]
|
||||
|
||||
## 附录
|
||||
- 常用命令
|
||||
- 开发：pnpm dev
|
||||
- 构建：pnpm build
|
||||
- 预览：pnpm preview
|
||||
- 测试：pnpm test
|
||||
- 覆盖率：pnpm test:coverage
|
||||
- 代码检查与格式化：pnpm lint / pnpm fmt
|
||||
- 环境变量约定
|
||||
- VITE_API_BASE_URL：API 基础地址（可选），未设置时默认 /api。
|
||||
- 主题扩展
|
||||
- 新增预设色：在 presets.js 中添加新条目。
|
||||
- 新增令牌：在 tokens.css 中补充变量，并在组件中使用对应变量。
|
||||
|
||||
章节来源
|
||||
- [package.json:6-19](file://fms-vue/package.json#L6-L19)
|
||||
- [http.js:8-10](file://fms-vue/src/services/http.js#L8-L10)
|
||||
- [presets.js:1-16](file://fms-vue/src/theme/presets.js#L1-L16)
|
||||
- [tokens.css:7-151](file://fms-vue/src/theme/tokens.css#L7-L151)
|
||||
@@ -0,0 +1,314 @@
|
||||
# 后端配置
|
||||
|
||||
<cite>
|
||||
**本文引用的文件**
|
||||
- [application.yaml](file://fms-api/src/main/resources/application.yaml)
|
||||
- [AuthProperties.java](file://fms-api/src/main/java/cn/g3soft/fmsapi/config/AuthProperties.java)
|
||||
- [FileStorageProperties.java](file://fms-api/src/main/java/cn/g3soft/fmsapi/config/FileStorageProperties.java)
|
||||
- [OrgDatabaseProperties.java](file://fms-api/src/main/java/cn/g3soft/fmsapi/database/OrgDatabaseProperties.java)
|
||||
- [OrgDataSourceFactory.java](file://fms-api/src/main/java/cn/g3soft/fmsapi/database/OrgDataSourceFactory.java)
|
||||
- [OrgDataSourceManager.java](file://fms-api/src/main/java/cn/g3soft/fmsapi/database/OrgDataSourceManager.java)
|
||||
- [OrgRoutingDataSource.java](file://fms-api/src/main/java/cn/g3soft/fmsapi/database/OrgRoutingDataSource.java)
|
||||
- [OrgDatabaseConfig.java](file://fms-api/src/main/java/cn/g3soft/fmsapi/database/OrgDatabaseConfig.java)
|
||||
- [README.md](file://fms-api/config/dbconfigs/README.md)
|
||||
</cite>
|
||||
|
||||
## 目录
|
||||
1. [简介](#简介)
|
||||
2. [项目结构](#项目结构)
|
||||
3. [核心组件](#核心组件)
|
||||
4. [架构总览](#架构总览)
|
||||
5. [详细组件分析](#详细组件分析)
|
||||
6. [依赖关系分析](#依赖关系分析)
|
||||
7. [性能考虑](#性能考虑)
|
||||
8. [故障排查指南](#故障排查指南)
|
||||
9. [结论](#结论)
|
||||
10. [附录](#附录)
|
||||
|
||||
## 简介
|
||||
本文件为 FMS 后端（Spring Boot）配置系统的权威文档，聚焦 application.yaml 的结构与各项参数，覆盖服务器、数据库连接池、多数据源切换、文件存储、安全设置等。同时说明第三方服务集成点、配置验证与默认值管理、以及可热更新的边界与机制。目标是帮助开发者快速理解并正确配置系统，保障生产环境的稳定性与可运维性。
|
||||
|
||||
## 项目结构
|
||||
FMS 后端采用 Spring Boot 工程组织，应用级配置集中在 resources/application.yaml；业务相关配置通过 @ConfigurationProperties 映射到 Java 类；多机构数据库配置以外部 properties 文件形式存放于 config/dbconfigs 目录，按机构 ID 命名加载。
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
A["application.yaml"] --> B["AuthProperties<br/>认证配置绑定"]
|
||||
A --> C["FileStorageProperties<br/>文件存储配置绑定"]
|
||||
A --> D["OrgDatabaseProperties<br/>数据库与连接池配置绑定"]
|
||||
D --> E["OrgDataSourceFactory<br/>创建Druid连接池"]
|
||||
E --> F["OrgDataSourceManager<br/>按机构ID缓存与管理DS"]
|
||||
F --> G["OrgRoutingDataSource<br/>基于上下文路由到具体DS"]
|
||||
H["config/dbconfigs/*.properties<br/>各机构DB连接信息"] --> E
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [application.yaml:1-34](file://fms-api/src/main/resources/application.yaml#L1-L34)
|
||||
- [AuthProperties.java:1-29](file://fms-api/src/main/java/cn/g3soft/fmsapi/config/AuthProperties.java#L1-L29)
|
||||
- [FileStorageProperties.java:1-69](file://fms-api/src/main/java/cn/g3soft/fmsapi/config/FileStorageProperties.java#L1-L69)
|
||||
- [OrgDatabaseProperties.java:1-120](file://fms-api/src/main/java/cn/g3soft/fmsapi/database/OrgDatabaseProperties.java#L1-L120)
|
||||
- [OrgDataSourceFactory.java:1-53](file://fms-api/src/main/java/cn/g3soft/fmsapi/database/OrgDataSourceFactory.java#L1-L53)
|
||||
- [OrgDataSourceManager.java:1-62](file://fms-api/src/main/java/cn/g3soft/fmsapi/database/OrgDataSourceManager.java#L1-L62)
|
||||
- [OrgRoutingDataSource.java:1-29](file://fms-api/src/main/java/cn/g3soft/fmsapi/database/OrgRoutingDataSource.java#L1-L29)
|
||||
- [README.md:1-28](file://fms-api/config/dbconfigs/README.md#L1-L28)
|
||||
|
||||
章节来源
|
||||
- [application.yaml:1-34](file://fms-api/src/main/resources/application.yaml#L1-L34)
|
||||
- [README.md:1-28](file://fms-api/config/dbconfigs/README.md#L1-L28)
|
||||
|
||||
## 核心组件
|
||||
- 服务器与应用基础配置：端口、上下文路径、应用名。
|
||||
- 认证配置：JWT 密钥与过期时间，支持环境变量注入与默认值。
|
||||
- 文件存储配置：本地存储与云存储（OSS）两种模式，支持 URL 前缀与存储根目录。
|
||||
- 多数据源配置：按机构维度加载外部 properties 文件，使用 Druid 连接池，并通过路由数据源在运行时根据上下文选择目标库。
|
||||
- 连接池与性能调优：初始大小、空闲最小数、最大活跃、等待超时、校验查询、空闲检测、驱逐策略、NAT/防火墙保活等。
|
||||
|
||||
章节来源
|
||||
- [application.yaml:1-34](file://fms-api/src/main/resources/application.yaml#L1-L34)
|
||||
- [AuthProperties.java:1-29](file://fms-api/src/main/java/cn/g3soft/fmsapi/config/AuthProperties.java#L1-L29)
|
||||
- [FileStorageProperties.java:1-69](file://fms-api/src/main/java/cn/g3soft/fmsapi/config/FileStorageProperties.java#L1-L69)
|
||||
- [OrgDatabaseProperties.java:1-120](file://fms-api/src/main/java/cn/g3soft/fmsapi/database/OrgDatabaseProperties.java#L1-L120)
|
||||
- [OrgDataSourceFactory.java:1-53](file://fms-api/src/main/java/cn/g3soft/fmsapi/database/OrgDataSourceFactory.java#L1-L53)
|
||||
|
||||
## 架构总览
|
||||
下图展示了配置加载与数据源路由的整体流程：应用启动时读取 application.yaml，绑定到对应 Properties 对象；请求进入后，通过 OrgContext 确定当前机构 ID，由 OrgRoutingDataSource 委托给 OrgDataSourceManager，后者从缓存或按需创建 Druid 数据源，最终返回连接。
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Client as "客户端"
|
||||
participant App as "Spring MVC"
|
||||
participant Router as "OrgRoutingDataSource"
|
||||
participant Manager as "OrgDataSourceManager"
|
||||
participant Factory as "OrgDataSourceFactory"
|
||||
participant DS as "DruidDataSource"
|
||||
participant DB as "数据库"
|
||||
Client->>App : HTTP 请求
|
||||
App->>Router : getConnection()
|
||||
Router->>Manager : getConnection(orgId from context)
|
||||
alt 首次访问该机构
|
||||
Manager->>Factory : create(orgId, config)
|
||||
Factory->>DS : 初始化连接池(属性+保活)
|
||||
DS-->>Manager : 已就绪
|
||||
end
|
||||
Manager-->>Router : Connection
|
||||
Router-->>App : Connection
|
||||
App->>DB : 执行SQL
|
||||
DB-->>App : 结果
|
||||
App-->>Client : 响应
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [OrgRoutingDataSource.java:1-29](file://fms-api/src/main/java/cn/g3soft/fmsapi/database/OrgRoutingDataSource.java#L1-L29)
|
||||
- [OrgDataSourceManager.java:1-62](file://fms-api/src/main/java/cn/g3soft/fmsapi/database/OrgDataSourceManager.java#L1-L62)
|
||||
- [OrgDataSourceFactory.java:1-53](file://fms-api/src/main/java/cn/g3soft/fmsapi/database/OrgDataSourceFactory.java#L1-L53)
|
||||
- [application.yaml:1-34](file://fms-api/src/main/resources/application.yaml#L1-L34)
|
||||
|
||||
## 详细组件分析
|
||||
|
||||
### 服务器与应用配置
|
||||
- 端口与上下文路径：用于暴露 API 的监听端口与统一前缀。
|
||||
- 应用名称：便于日志与监控标识。
|
||||
|
||||
章节来源
|
||||
- [application.yaml:1-8](file://fms-api/src/main/resources/application.yaml#L1-L8)
|
||||
|
||||
### 认证配置（JWT）
|
||||
- 密钥与过期时间：通过 fms.auth.* 绑定到 AuthProperties，支持环境变量覆盖与默认值。
|
||||
- 建议：生产环境务必通过环境变量注入强随机密钥，避免硬编码。
|
||||
|
||||
章节来源
|
||||
- [application.yaml:10-13](file://fms-api/src/main/resources/application.yaml#L10-L13)
|
||||
- [AuthProperties.java:1-29](file://fms-api/src/main/java/cn/g3soft/fmsapi/config/AuthProperties.java#L1-L29)
|
||||
|
||||
### 文件存储服务配置
|
||||
- 存储类型：local 或 oss，通过 fms.file.storage-type 控制。
|
||||
- 本地存储：存储根目录与静态资源 URL 前缀，便于直接挂载或反向代理。
|
||||
- 云存储（OSS）：提供 OSS 端点地址，便于后续扩展上传/下载能力。
|
||||
|
||||
章节来源
|
||||
- [application.yaml:27-34](file://fms-api/src/main/resources/application.yaml#L27-L34)
|
||||
- [FileStorageProperties.java:1-69](file://fms-api/src/main/java/cn/g3soft/fmsapi/config/FileStorageProperties.java#L1-L69)
|
||||
|
||||
### 多数据源配置与切换机制
|
||||
- 配置来源：每个机构一个 {ORG_ID}.properties 文件，包含 url、username、password、driver。
|
||||
- 配置加载：OrgDatabaseConfigLoader 负责读取与规范化机构 ID。
|
||||
- 数据源工厂：OrgDataSourceFactory 将配置转换为 DruidDataSource，并应用全局连接池参数。
|
||||
- 数据源管理：OrgDataSourceManager 维护 orgId -> DataSource 的并发缓存，懒加载与优雅关闭。
|
||||
- 路由数据源：OrgRoutingDataSource 作为 Primary 数据源，依据当前线程上下文中的机构 ID 动态选择连接。
|
||||
|
||||
```mermaid
|
||||
classDiagram
|
||||
class OrgDatabaseProperties {
|
||||
+Path configDir
|
||||
+Pool pool
|
||||
}
|
||||
class Pool {
|
||||
+int initialSize
|
||||
+int minIdle
|
||||
+int maxActive
|
||||
+long maxWait
|
||||
+String validationQuery
|
||||
+boolean testWhileIdle
|
||||
+boolean testOnBorrow
|
||||
+boolean testOnReturn
|
||||
+Duration timeBetweenEvictionRuns
|
||||
+Duration minEvictableIdleTime
|
||||
}
|
||||
class OrgDatabaseConfig {
|
||||
+String url
|
||||
+String username
|
||||
+String password
|
||||
+String driver
|
||||
}
|
||||
class OrgDataSourceFactory {
|
||||
+create(orgId, config) DruidDataSource
|
||||
}
|
||||
class OrgDataSourceManager {
|
||||
-ConcurrentMap dataSources
|
||||
+getDataSource(orgId)
|
||||
+getConnection(orgId)
|
||||
+closeAll()
|
||||
}
|
||||
class OrgRoutingDataSource {
|
||||
+getConnection()
|
||||
+getConnection(username,password)
|
||||
}
|
||||
OrgDatabaseProperties --> Pool
|
||||
OrgDataSourceFactory --> OrgDatabaseProperties : "读取池参数"
|
||||
OrgDataSourceFactory --> OrgDatabaseConfig : "读取连接信息"
|
||||
OrgDataSourceManager --> OrgDataSourceFactory : "创建DS"
|
||||
OrgRoutingDataSource --> OrgDataSourceManager : "委托获取连接"
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [OrgDatabaseProperties.java:1-120](file://fms-api/src/main/java/cn/g3soft/fmsapi/database/OrgDatabaseProperties.java#L1-L120)
|
||||
- [OrgDatabaseConfig.java:1-10](file://fms-api/src/main/java/cn/g3soft/fmsapi/database/OrgDatabaseConfig.java#L1-L10)
|
||||
- [OrgDataSourceFactory.java:1-53](file://fms-api/src/main/java/cn/g3soft/fmsapi/database/OrgDataSourceFactory.java#L1-L53)
|
||||
- [OrgDataSourceManager.java:1-62](file://fms-api/src/main/java/cn/g3soft/fmsapi/database/OrgDataSourceManager.java#L1-L62)
|
||||
- [OrgRoutingDataSource.java:1-29](file://fms-api/src/main/java/cn/g3soft/fmsapi/database/OrgRoutingDataSource.java#L1-L29)
|
||||
|
||||
章节来源
|
||||
- [application.yaml:14-26](file://fms-api/src/main/resources/application.yaml#L14-L26)
|
||||
- [OrgDatabaseProperties.java:1-120](file://fms-api/src/main/java/cn/g3soft/fmsapi/database/OrgDatabaseProperties.java#L1-L120)
|
||||
- [OrgDataSourceFactory.java:1-53](file://fms-api/src/main/java/cn/g3soft/fmsapi/database/OrgDataSourceFactory.java#L1-L53)
|
||||
- [OrgDataSourceManager.java:1-62](file://fms-api/src/main/java/cn/g3soft/fmsapi/database/OrgDataSourceManager.java#L1-L62)
|
||||
- [OrgRoutingDataSource.java:1-29](file://fms-api/src/main/java/cn/g3soft/fmsapi/database/OrgRoutingDataSource.java#L1-L29)
|
||||
- [README.md:1-28](file://fms-api/config/dbconfigs/README.md#L1-L28)
|
||||
|
||||
### 数据库连接池配置与性能调优
|
||||
- 关键参数
|
||||
- 初始大小/最小空闲/最大活跃：控制预热与容量上限。
|
||||
- 最大等待时间：防止请求堆积导致雪崩。
|
||||
- 校验查询：确保取出的连接有效。
|
||||
- 空闲检测与驱逐：定期清理僵尸连接，降低内存占用。
|
||||
- 保活：对抗云环境 NAT/防火墙回收空闲 TCP 会话。
|
||||
- 推荐实践
|
||||
- 开发环境：initial-size=0，按需增长。
|
||||
- 生产环境：适当提高 min-idle 与 max-active，结合压测确定阈值。
|
||||
- 高延迟网络：开启 keepAlive 与合理的 timeBetweenEvictionRuns。
|
||||
|
||||
章节来源
|
||||
- [application.yaml:16-26](file://fms-api/src/main/resources/application.yaml#L16-L26)
|
||||
- [OrgDatabaseProperties.java:26-118](file://fms-api/src/main/java/cn/g3soft/fmsapi/database/OrgDatabaseProperties.java#L26-L118)
|
||||
- [OrgDataSourceFactory.java:15-42](file://fms-api/src/main/java/cn/g3soft/fmsapi/database/OrgDataSourceFactory.java#L15-L42)
|
||||
|
||||
### 文件存储切换与静态资源访问
|
||||
- 切换方式：修改 fms.file.storage-type 为 local 或 oss。
|
||||
- 本地模式：配置 storage-dir 与 url-prefix，配合 Web 静态资源映射即可访问。
|
||||
- 云存储模式：配置 g3oss-url，后续可在文件服务中对接上传/下载逻辑。
|
||||
|
||||
章节来源
|
||||
- [application.yaml:27-34](file://fms-api/src/main/resources/application.yaml#L27-L34)
|
||||
- [FileStorageProperties.java:1-69](file://fms-api/src/main/java/cn/g3soft/fmsapi/config/FileStorageProperties.java#L1-L69)
|
||||
|
||||
### 第三方服务集成配置
|
||||
- 邮件服务：当前仓库未包含邮件相关配置项，可按需新增 fms.mail.* 并在 Properties 中绑定。
|
||||
- 消息队列：当前仓库未包含 MQ 相关配置项，可按需新增 fms.mq.* 并在 Properties 中绑定。
|
||||
- 建议：所有外部服务配置均通过环境变量注入，避免敏感信息入库。
|
||||
|
||||
[本节为通用指导，不直接分析具体文件]
|
||||
|
||||
### 配置验证、默认值管理与热更新
|
||||
- 配置验证
|
||||
- 通过 @ConfigurationProperties 自动绑定，建议在启动阶段对必填字段进行校验（例如 JWT 密钥非空）。
|
||||
- 数据库驱动与连接串格式应在加载时校验，失败时尽早抛出异常。
|
||||
- 默认值管理
|
||||
- 认证过期时间、连接池默认值已在 Properties 中定义，便于开箱即用。
|
||||
- 可通过 application.yaml 或环境变量覆盖默认值。
|
||||
- 热更新
|
||||
- 当前实现为启动时加载并缓存数据源，不支持运行时动态切换数据源或热重载配置文件。
|
||||
- 若需热更新，可在 Properties 上引入配置刷新机制，并在变更时重建或替换对应数据源。
|
||||
|
||||
章节来源
|
||||
- [application.yaml:10-34](file://fms-api/src/main/resources/application.yaml#L10-L34)
|
||||
- [AuthProperties.java:1-29](file://fms-api/src/main/java/cn/g3soft/fmsapi/config/AuthProperties.java#L1-L29)
|
||||
- [OrgDatabaseProperties.java:1-120](file://fms-api/src/main/java/cn/g3soft/fmsapi/database/OrgDatabaseProperties.java#L1-L120)
|
||||
- [OrgDataSourceManager.java:13-62](file://fms-api/src/main/java/cn/g3soft/fmsapi/database/OrgDataSourceManager.java#L13-L62)
|
||||
|
||||
## 依赖关系分析
|
||||
- 配置绑定：application.yaml → @ConfigurationProperties 类。
|
||||
- 数据源生命周期：Factory 创建 → Manager 缓存 → Routing 路由。
|
||||
- 外部依赖：Druid 连接池、SQL Server JDBC（示例驱动），外部 properties 文件。
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
YML["application.yaml"] --> AP["AuthProperties"]
|
||||
YML --> FP["FileStorageProperties"]
|
||||
YML --> DP["OrgDatabaseProperties"]
|
||||
DP --> DF["OrgDataSourceFactory"]
|
||||
DF --> DM["OrgDataSourceManager"]
|
||||
DM --> RD["OrgRoutingDataSource"]
|
||||
CFG["dbconfigs/*.properties"] --> DF
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [application.yaml:1-34](file://fms-api/src/main/resources/application.yaml#L1-L34)
|
||||
- [OrgDatabaseProperties.java:1-120](file://fms-api/src/main/java/cn/g3soft/fmsapi/database/OrgDatabaseProperties.java#L1-L120)
|
||||
- [OrgDataSourceFactory.java:1-53](file://fms-api/src/main/java/cn/g3soft/fmsapi/database/OrgDataSourceFactory.java#L1-L53)
|
||||
- [OrgDataSourceManager.java:1-62](file://fms-api/src/main/java/cn/g3soft/fmsapi/database/OrgDataSourceManager.java#L1-L62)
|
||||
- [OrgRoutingDataSource.java:1-29](file://fms-api/src/main/java/cn/g3soft/fmsapi/database/OrgRoutingDataSource.java#L1-L29)
|
||||
- [README.md:1-28](file://fms-api/config/dbconfigs/README.md#L1-L28)
|
||||
|
||||
章节来源
|
||||
- [application.yaml:1-34](file://fms-api/src/main/resources/application.yaml#L1-L34)
|
||||
- [OrgDataSourceManager.java:1-62](file://fms-api/src/main/java/cn/g3soft/fmsapi/database/OrgDataSourceManager.java#L1-L62)
|
||||
|
||||
## 性能考虑
|
||||
- 连接池规模：根据并发与平均响应时间估算 max-active，避免过大导致数据库压力。
|
||||
- 空闲检测：在高延迟或云环境中，保持合理的 timeBetweenEvictionRuns 与 keepAlive。
|
||||
- 等待超时：合理设置 max-wait，避免长事务拖垮连接池。
|
||||
- 预热策略：生产环境可适当提升 initial-size/min-idle，减少冷启动抖动。
|
||||
- 文件存储：本地模式注意磁盘 I/O 与空间配额；云存储关注带宽与限流。
|
||||
|
||||
[本节为通用指导，不直接分析具体文件]
|
||||
|
||||
## 故障排查指南
|
||||
- 无法连接数据库
|
||||
- 检查 dbconfigs/{ORG_ID}.properties 是否存在且内容正确。
|
||||
- 确认驱动类名与 JDBC URL 匹配数据库类型。
|
||||
- 查看连接池错误重试与保活配置是否生效。
|
||||
- 连接泄漏或耗尽
|
||||
- 检查业务代码是否正确释放连接。
|
||||
- 调整 max-wait 与 max-active，观察慢查询与锁竞争。
|
||||
- 静态文件无法访问
|
||||
- 核对 fms.file.local.url-prefix 与部署时的静态资源映射。
|
||||
- 认证失败
|
||||
- 确认环境变量 FMS_JWT_SECRET 已正确注入。
|
||||
- 检查 jwt-expiration 是否符合预期。
|
||||
|
||||
章节来源
|
||||
- [application.yaml:10-34](file://fms-api/src/main/resources/application.yaml#L10-L34)
|
||||
- [OrgDataSourceFactory.java:15-53](file://fms-api/src/main/java/cn/g3soft/fmsapi/database/OrgDataSourceFactory.java#L15-L53)
|
||||
- [README.md:1-28](file://fms-api/config/dbconfigs/README.md#L1-L28)
|
||||
|
||||
## 结论
|
||||
本配置体系通过 application.yaml 与 @ConfigurationProperties 完成集中式配置管理，结合外部 properties 文件实现多机构数据源隔离与按需加载。连接池参数可调、具备保活机制，适合云原生与混合部署场景。文件存储支持本地与云存储双模式，便于演进。建议在生产环境严格使用环境变量注入敏感配置，并结合压测优化连接池与超时参数。
|
||||
|
||||
[本节为总结，不直接分析具体文件]
|
||||
|
||||
## 附录
|
||||
- 多机构数据库配置示例位置与规范：参见 dbconfigs 目录下的 README。
|
||||
- 如需扩展第三方服务（邮件、MQ），建议新增独立配置段与 Properties 类，遵循环境变量优先原则。
|
||||
|
||||
章节来源
|
||||
- [README.md:1-28](file://fms-api/config/dbconfigs/README.md#L1-L28)
|
||||
@@ -0,0 +1,318 @@
|
||||
# 环境管理
|
||||
|
||||
<cite>
|
||||
**本文引用的文件**
|
||||
- [application.yaml](file://fms-api/src/main/resources/application.yaml)
|
||||
- [README.md](file://fms-api/config/dbconfigs/README.md)
|
||||
- [G3HD.properties](file://fms-api/config/dbconfigs/G3HD.properties)
|
||||
- [G3HY2025.properties](file://fms-api/config/dbconfigs/G3HY2025.properties)
|
||||
- [OrgDataSourceFactory.java](file://fms-api/src/main/java/cn/g3soft/fmsapi/database/OrgDataSourceFactory.java)
|
||||
- [OrgDatabaseConfigLoader.java](file://fms-api/src/main/java/cn/g3soft/fmsapi/database/OrgDatabaseConfigLoader.java)
|
||||
- [OrgRoutingDataSource.java](file://fms-api/src/main/java/cn/g3soft/fmsapi/database/OrgRoutingDataSource.java)
|
||||
- [OrgContext.java](file://fms-api/src/main/java/cn/g3soft/fmsapi/database/OrgContext.java)
|
||||
</cite>
|
||||
|
||||
## 目录
|
||||
1. [简介](#简介)
|
||||
2. [项目结构](#项目结构)
|
||||
3. [核心组件](#核心组件)
|
||||
4. [架构总览](#架构总览)
|
||||
5. [详细组件分析](#详细组件分析)
|
||||
6. [依赖关系分析](#依赖关系分析)
|
||||
7. [性能考虑](#性能考虑)
|
||||
8. [故障排查指南](#故障排查指南)
|
||||
9. [结论](#结论)
|
||||
10. [附录](#附录)
|
||||
|
||||
## 简介
|
||||
本文件面向FMS环境管理系统，聚焦多环境配置管理策略与数据库动态切换机制。内容涵盖开发、测试、预发布、生产环境的差异化管理方式；环境变量在不同环境中的定义与使用；按机构动态加载数据库连接；敏感信息的安全管理（密钥、密码、访问控制）；环境切换的最佳实践（配置校验、回滚策略、部署自动化）；以及环境特定的调试工具与监控配置建议。
|
||||
|
||||
## 项目结构
|
||||
后端服务基于Spring Boot，应用级配置集中在application.yaml中，包含服务器端口、上下文路径、JWT密钥来源、数据库连接池参数、文件存储类型等。数据库连接采用“按机构”的独立配置文件模式，位于config/dbconfigs目录下，每个机构一个properties文件，运行时由配置加载器读取并创建数据源。
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
A["应用配置<br/>application.yaml"] --> B["数据库连接池参数<br/>pool.*"]
|
||||
A --> C["JWT密钥来源<br/>环境变量注入"]
|
||||
A --> D["文件存储配置<br/>storage-type/local/oss"]
|
||||
E["机构数据库配置目录<br/>config/dbconfigs/*.properties"] --> F["配置加载器<br/>OrgDatabaseConfigLoader"]
|
||||
F --> G["数据源工厂<br/>OrgDataSourceFactory"]
|
||||
G --> H["路由数据源<br/>OrgRoutingDataSource"]
|
||||
H --> I["业务代码通过JDBC访问"]
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [application.yaml:1-34](file://fms-api/src/main/resources/application.yaml#L1-L34)
|
||||
- [OrgDatabaseConfigLoader.java:31-65](file://fms-api/src/main/java/cn/g3soft/fmsapi/database/OrgDatabaseConfigLoader.java#L31-L65)
|
||||
- [OrgDataSourceFactory.java:15-50](file://fms-api/src/main/java/cn/g3soft/fmsapi/database/OrgDataSourceFactory.java#L15-L50)
|
||||
- [OrgRoutingDataSource.java:11-27](file://fms-api/src/main/java/cn/g3soft/fmsapi/database/OrgRoutingDataSource.java#L11-L27)
|
||||
|
||||
章节来源
|
||||
- [application.yaml:1-34](file://fms-api/src/main/resources/application.yaml#L1-L34)
|
||||
- [README.md:1-28](file://fms-api/config/dbconfigs/README.md#L1-L28)
|
||||
|
||||
## 核心组件
|
||||
- 应用配置中心：application.yaml集中声明服务端口、上下文路径、JWT密钥来源、数据库连接池参数、文件存储策略等。
|
||||
- 机构数据库配置加载器：从指定目录读取{ORG_ID}.properties，校验并解析为连接信息。
|
||||
- 数据源工厂：根据配置创建Druid连接池，设置连接池参数与健康检查策略。
|
||||
- 路由数据源：将当前线程的机构上下文映射到对应数据源，实现多租户隔离。
|
||||
- 上下文管理：ThreadLocal维护当前请求的机构ID与用户ID，确保数据源路由正确。
|
||||
|
||||
章节来源
|
||||
- [application.yaml:10-34](file://fms-api/src/main/resources/application.yaml#L10-L34)
|
||||
- [OrgDatabaseConfigLoader.java:19-104](file://fms-api/src/main/java/cn/g3soft/fmsapi/database/OrgDatabaseConfigLoader.java#L19-L104)
|
||||
- [OrgDataSourceFactory.java:9-53](file://fms-api/src/main/java/cn/g3soft/fmsapi/database/OrgDataSourceFactory.java#L9-L53)
|
||||
- [OrgRoutingDataSource.java:11-27](file://fms-api/src/main/java/cn/g3soft/fmsapi/database/OrgRoutingDataSource.java#L11-L27)
|
||||
- [OrgContext.java:3-55](file://fms-api/src/main/java/cn/g3soft/fmsapi/database/OrgContext.java#L3-L55)
|
||||
|
||||
## 架构总览
|
||||
下图展示了从应用启动到按机构路由访问数据库的整体流程，包括配置加载、数据源创建与选择。
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant App as "应用"
|
||||
participant Loader as "配置加载器"
|
||||
participant Factory as "数据源工厂"
|
||||
participant Router as "路由数据源"
|
||||
participant DB as "SQL Server"
|
||||
App->>Loader : 初始化并扫描配置目录
|
||||
Loader-->>App : 提供按机构加载能力
|
||||
App->>Router : 发起数据库操作
|
||||
Router->>Router : 读取当前机构上下文
|
||||
Router->>Factory : 获取或创建机构数据源
|
||||
Factory-->>Router : DruidDataSource实例
|
||||
Router->>DB : 建立连接并执行SQL
|
||||
DB-->>Router : 返回结果
|
||||
Router-->>App : 返回查询结果
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [OrgDatabaseConfigLoader.java:31-65](file://fms-api/src/main/java/cn/g3soft/fmsapi/database/OrgDatabaseConfigLoader.java#L31-L65)
|
||||
- [OrgDataSourceFactory.java:15-50](file://fms-api/src/main/java/cn/g3soft/fmsapi/database/OrgDataSourceFactory.java#L15-L50)
|
||||
- [OrgRoutingDataSource.java:18-27](file://fms-api/src/main/java/cn/g3soft/fmsapi/database/OrgRoutingDataSource.java#L18-L27)
|
||||
- [application.yaml:10-34](file://fms-api/src/main/resources/application.yaml#L10-L34)
|
||||
|
||||
## 详细组件分析
|
||||
|
||||
### 多环境配置管理策略
|
||||
- 统一入口：application.yaml作为应用级配置入口，定义服务端口、上下文路径、JWT密钥来源、数据库连接池参数、文件存储策略等。
|
||||
- 环境变量注入：JWT密钥通过环境变量注入，便于不同环境差异化配置且避免硬编码。
|
||||
- 外部化数据库配置：机构数据库连接以独立properties文件存放于config/dbconfigs目录，支持按机构隔离，便于在测试、预发布、生产环境中分别准备不同的机构配置集。
|
||||
- 环境差异点示例：
|
||||
- 开发环境：本地或内网SQL Server地址、宽松的连接池参数、开启更多日志。
|
||||
- 测试环境：共享测试库、中等连接池规模、启用基础健康检查。
|
||||
- 预发布环境：接近生产的网络拓扑、严格连接池与超时参数、开启审计与告警。
|
||||
- 生产环境：高可用数据库集群、严格的连接池上限与等待时间、强安全策略与最小权限账号。
|
||||
|
||||
章节来源
|
||||
- [application.yaml:1-34](file://fms-api/src/main/resources/application.yaml#L1-L34)
|
||||
- [README.md:1-28](file://fms-api/config/dbconfigs/README.md#L1-L28)
|
||||
|
||||
### 环境变量在不同环境中的定义与使用
|
||||
- JWT密钥：通过环境变量注入，避免将敏感信息写入代码或仓库。
|
||||
- 使用方式：在application.yaml中以占位符形式引用环境变量，运行期由容器或平台注入实际值。
|
||||
- 最佳实践：
|
||||
- 为每个环境维护独立的密钥与凭据，禁止跨环境复用。
|
||||
- 使用平台提供的密钥管理服务（如Kubernetes Secrets、云平台KMS）进行注入与轮换。
|
||||
- 对关键变量增加格式校验与默认值保护，防止启动失败。
|
||||
|
||||
章节来源
|
||||
- [application.yaml:10-13](file://fms-api/src/main/resources/application.yaml#L10-L13)
|
||||
|
||||
### 数据库配置的动态切换机制（按机构）
|
||||
- 配置目录与命名规范：config/dbconfigs下每个机构一个{ORG_ID}.properties文件，组织ID规范化为大写字母、数字、下划线和连字符。
|
||||
- 加载与校验：
|
||||
- 加载器读取指定目录下的properties文件，校验URL必须为SQL Server驱动。
|
||||
- 必填字段包括url、username、password；driver可选，未提供时使用默认SQL Server驱动。
|
||||
- 对orgId进行规范化与格式校验，防止路径穿越与非法输入。
|
||||
- 数据源创建：
|
||||
- 工厂类根据配置创建DruidDataSource，设置连接池大小、等待时间、空闲检测、保活策略等。
|
||||
- 针对云NAT/防火墙回收空闲TCP会话，启用定期ping以保持连接活跃。
|
||||
- 路由选择：
|
||||
- 路由数据源根据当前线程的机构上下文选择对应数据源，实现多租户隔离。
|
||||
- 若未设置机构上下文，将抛出异常提示。
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Start(["开始"]) --> Normalize["规范化机构ID"]
|
||||
Normalize --> CheckPath{"路径合法?"}
|
||||
CheckPath -- 否 --> ErrPath["抛出路径不合法错误"]
|
||||
CheckPath -- 是 --> LoadProps["读取*.properties"]
|
||||
LoadProps --> ValidateUrl{"URL为SQL Server?"}
|
||||
ValidateUrl -- 否 --> ErrDriver["抛出非SQL Server错误"]
|
||||
ValidateUrl -- 是 --> CreateDS["创建Druid连接池"]
|
||||
CreateDS --> Route["根据上下文路由到数据源"]
|
||||
Route --> End(["结束"])
|
||||
ErrPath --> End
|
||||
ErrDriver --> End
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [OrgDatabaseConfigLoader.java:36-65](file://fms-api/src/main/java/cn/g3soft/fmsapi/database/OrgDatabaseConfigLoader.java#L36-L65)
|
||||
- [OrgDatabaseConfigLoader.java:67-77](file://fms-api/src/main/java/cn/g3soft/fmsapi/database/OrgDatabaseConfigLoader.java#L67-L77)
|
||||
- [OrgDataSourceFactory.java:15-50](file://fms-api/src/main/java/cn/g3soft/fmsapi/database/OrgDataSourceFactory.java#L15-L50)
|
||||
- [OrgRoutingDataSource.java:18-27](file://fms-api/src/main/java/cn/g3soft/fmsapi/database/OrgRoutingDataSource.java#L18-L27)
|
||||
|
||||
章节来源
|
||||
- [README.md:1-28](file://fms-api/config/dbconfigs/README.md#L1-L28)
|
||||
- [G3HD.properties:1-5](file://fms-api/config/dbconfigs/G3HD.properties#L1-L5)
|
||||
- [G3HY2025.properties:1-5](file://fms-api/config/dbconfigs/G3HY2025.properties#L1-L5)
|
||||
- [OrgDatabaseConfigLoader.java:19-104](file://fms-api/src/main/java/cn/g3soft/fmsapi/database/OrgDatabaseConfigLoader.java#L19-L104)
|
||||
- [OrgDataSourceFactory.java:9-53](file://fms-api/src/main/java/cn/g3soft/fmsapi/database/OrgDataSourceFactory.java#L9-L53)
|
||||
- [OrgRoutingDataSource.java:11-27](file://fms-api/src/main/java/cn/g3soft/fmsapi/database/OrgRoutingDataSource.java#L11-L27)
|
||||
|
||||
### 敏感信息的安全管理
|
||||
- 密钥管理：
|
||||
- JWT密钥通过环境变量注入，避免明文存储在代码或配置文件中。
|
||||
- 建议在CI/CD中使用平台密钥管理服务注入，并在各环境独立管理。
|
||||
- 密码加密与存储：
|
||||
- 机构数据库密码以明文存在于properties文件中，属于高风险项。建议后续引入加密存储（如KMS托管密钥、环境变量或配置中心加密）。
|
||||
- 在开发环境可保留明文以便快速验证，但在测试、预发布、生产环境应强制加密与最小权限账号。
|
||||
- 访问控制：
|
||||
- 限制config/dbconfigs目录的访问权限，仅允许运行账户读取。
|
||||
- 对数据库账号实施最小权限原则，仅授予必要表与视图的读写权限。
|
||||
- 对API层增加鉴权与审计，记录机构上下文与用户上下文变更。
|
||||
|
||||
章节来源
|
||||
- [application.yaml:10-13](file://fms-api/src/main/resources/application.yaml#L10-L13)
|
||||
- [README.md:16-17](file://fms-api/config/dbconfigs/README.md#L16-L17)
|
||||
- [G3HD.properties:1-5](file://fms-api/config/dbconfigs/G3HD.properties#L1-L5)
|
||||
- [G3HY2025.properties:1-5](file://fms-api/config/dbconfigs/G3HY2025.properties#L1-L5)
|
||||
|
||||
### 环境切换的最佳实践
|
||||
- 配置验证：
|
||||
- 启动时校验JWT密钥是否已注入，缺失则拒绝启动。
|
||||
- 校验机构配置文件的URL、用户名、密码等必填字段，缺失则抛出明确错误。
|
||||
- 对orgId进行规范化与正则校验，防止路径穿越与非法输入。
|
||||
- 回滚策略：
|
||||
- 每次发布前备份当前环境的application.yaml与机构配置集。
|
||||
- 支持热切换：通过替换config/dbconfigs下的properties文件并重启服务完成回滚。
|
||||
- 对数据库迁移脚本进行幂等设计，支持重复执行与回滚脚本。
|
||||
- 部署自动化：
|
||||
- CI/CD流水线中注入环境变量与密钥，生成最终配置后部署。
|
||||
- 使用容器镜像固化应用代码，外部化所有敏感配置。
|
||||
- 部署后自动执行健康检查与连通性测试（数据库、对象存储等）。
|
||||
|
||||
章节来源
|
||||
- [application.yaml:1-34](file://fms-api/src/main/resources/application.yaml#L1-L34)
|
||||
- [OrgDatabaseConfigLoader.java:36-65](file://fms-api/src/main/java/cn/g3soft/fmsapi/database/OrgDatabaseConfigLoader.java#L36-L65)
|
||||
- [README.md:16-28](file://fms-api/config/dbconfigs/README.md#L16-L28)
|
||||
|
||||
### 环境特定的调试工具与监控配置
|
||||
- 开发环境：
|
||||
- 使用legacy TLS兼容参数启动，以连接仅支持TLS 1.0的旧版SQL Server。
|
||||
- 开启更详细的日志与慢查询日志，便于定位问题。
|
||||
- 测试与预发布环境：
|
||||
- 启用连接池监控指标（Druid内置监控），关注连接数、等待时间与错误率。
|
||||
- 对关键接口增加调用链追踪与审计日志。
|
||||
- 生产环境：
|
||||
- 关闭调试开关，仅保留必要日志级别。
|
||||
- 接入APM与告警系统，对数据库连接池、错误率、响应时间进行监控与告警。
|
||||
- 定期演练回滚与故障恢复流程。
|
||||
|
||||
章节来源
|
||||
- [README.md:18-28](file://fms-api/config/dbconfigs/README.md#L18-L28)
|
||||
- [application.yaml:10-34](file://fms-api/src/main/resources/application.yaml#L10-L34)
|
||||
|
||||
## 依赖关系分析
|
||||
- 组件耦合：
|
||||
- OrgRoutingDataSource依赖OrgDataSourceManager（由框架装配）与OrgContext，负责按上下文路由。
|
||||
- OrgDataSourceFactory依赖OrgDatabaseProperties，负责创建Druid连接池。
|
||||
- OrgDatabaseConfigLoader依赖文件系统与正则校验，负责加载与验证机构配置。
|
||||
- 外部依赖：
|
||||
- Spring Boot与Druid连接池。
|
||||
- SQL Server JDBC驱动。
|
||||
- 潜在风险：
|
||||
- 若未设置机构上下文，路由将抛出异常，需确保网关或拦截器正确设置上下文。
|
||||
- 若properties文件缺失或格式错误，将导致认证或初始化失败。
|
||||
|
||||
```mermaid
|
||||
classDiagram
|
||||
class OrgContext {
|
||||
+setOrgId(orgId)
|
||||
+getOrgId() String
|
||||
+requireOrgId() String
|
||||
+setUserId(userId)
|
||||
+getUserId() String
|
||||
+requireUserId() String
|
||||
+clear()
|
||||
}
|
||||
class OrgDatabaseConfigLoader {
|
||||
+init()
|
||||
+load(orgId) OrgDatabaseConfig
|
||||
+normalizeOrgId(orgId) String
|
||||
+getConfigDir() Path
|
||||
}
|
||||
class OrgDataSourceFactory {
|
||||
+create(orgId, config) DruidDataSource
|
||||
}
|
||||
class OrgRoutingDataSource {
|
||||
+getConnection() Connection
|
||||
+getConnection(username, password) Connection
|
||||
}
|
||||
OrgRoutingDataSource --> OrgDataSourceFactory : "获取数据源"
|
||||
OrgRoutingDataSource --> OrgContext : "读取上下文"
|
||||
OrgDataSourceFactory --> OrgDatabaseConfigLoader : "使用配置"
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [OrgContext.java:3-55](file://fms-api/src/main/java/cn/g3soft/fmsapi/database/OrgContext.java#L3-L55)
|
||||
- [OrgDatabaseConfigLoader.java:19-104](file://fms-api/src/main/java/cn/g3soft/fmsapi/database/OrgDatabaseConfigLoader.java#L19-L104)
|
||||
- [OrgDataSourceFactory.java:9-53](file://fms-api/src/main/java/cn/g3soft/fmsapi/database/OrgDataSourceFactory.java#L9-L53)
|
||||
- [OrgRoutingDataSource.java:11-27](file://fms-api/src/main/java/cn/g3soft/fmsapi/database/OrgRoutingDataSource.java#L11-L27)
|
||||
|
||||
章节来源
|
||||
- [OrgContext.java:3-55](file://fms-api/src/main/java/cn/g3soft/fmsapi/database/OrgContext.java#L3-L55)
|
||||
- [OrgDatabaseConfigLoader.java:19-104](file://fms-api/src/main/java/cn/g3soft/fmsapi/database/OrgDatabaseConfigLoader.java#L19-L104)
|
||||
- [OrgDataSourceFactory.java:9-53](file://fms-api/src/main/java/cn/g3soft/fmsapi/database/OrgDataSourceFactory.java#L9-L53)
|
||||
- [OrgRoutingDataSource.java:11-27](file://fms-api/src/main/java/cn/g3soft/fmsapi/database/OrgRoutingDataSource.java#L11-L27)
|
||||
|
||||
## 性能考虑
|
||||
- 连接池调优：
|
||||
- initial-size、min-idle、max-active、max-wait等参数应根据负载与环境调整。
|
||||
- 启用test-while-idle与keepAlive，对抗云NAT/防火墙回收空闲连接。
|
||||
- 连接健康检查：
|
||||
- validation-query用于连接可用性检测，确保获取到的连接有效。
|
||||
- time-between-eviction-runs与min-evictable-idle-time控制空闲连接回收周期。
|
||||
- 资源隔离：
|
||||
- 按机构独立数据源，避免跨租户资源争用。
|
||||
- 对高频接口使用连接池预热与批量操作减少连接开销。
|
||||
|
||||
章节来源
|
||||
- [application.yaml:14-26](file://fms-api/src/main/resources/application.yaml#L14-L26)
|
||||
- [OrgDataSourceFactory.java:15-50](file://fms-api/src/main/java/cn/g3soft/fmsapi/database/OrgDataSourceFactory.java#L15-L50)
|
||||
|
||||
## 故障排查指南
|
||||
- 常见错误与处理：
|
||||
- 机构码为空或格式不正确：检查传入orgId并进行规范化与正则校验。
|
||||
- 配置文件缺失或路径不合法：确认config/dbconfigs目录下存在对应{ORG_ID}.properties，且路径未被篡改。
|
||||
- URL非SQL Server：确保url以jdbc:sqlserver:开头。
|
||||
- 缺少必填字段：检查url、username、password是否存在且非空。
|
||||
- 未设置机构上下文：确保在请求处理前设置OrgContext.orgId。
|
||||
- 诊断步骤：
|
||||
- 查看应用日志中的异常堆栈，定位具体失败阶段。
|
||||
- 验证环境变量是否正确注入（如JWT密钥）。
|
||||
- 检查数据库连通性与账号权限。
|
||||
- 对连接池指标进行监控，关注连接泄漏与等待时间。
|
||||
|
||||
章节来源
|
||||
- [OrgDatabaseConfigLoader.java:36-65](file://fms-api/src/main/java/cn/g3soft/fmsapi/database/OrgDatabaseConfigLoader.java#L36-L65)
|
||||
- [OrgDatabaseConfigLoader.java:67-77](file://fms-api/src/main/java/cn/g3soft/fmsapi/database/OrgDatabaseConfigLoader.java#L67-L77)
|
||||
- [OrgContext.java:13-30](file://fms-api/src/main/java/cn/g3soft/fmsapi/database/OrgContext.java#L13-L30)
|
||||
- [application.yaml:10-13](file://fms-api/src/main/resources/application.yaml#L10-L13)
|
||||
|
||||
## 结论
|
||||
FMS环境管理系统通过application.yaml集中管理与外部化配置，结合按机构的独立数据库配置文件，实现了灵活的多环境支持与多租户隔离。通过环境变量注入敏感信息、严格的配置校验与连接池调优，提升了安全性与稳定性。建议在生产环境中进一步强化密钥加密、访问控制与监控告警，并完善回滚与自动化部署流程，以确保高可用与可运维性。
|
||||
|
||||
## 附录
|
||||
- 环境清单与差异对照（示例）：
|
||||
- 开发：本地SQL Server、宽松连接池、详细日志。
|
||||
- 测试：共享测试库、中等连接池、基础监控。
|
||||
- 预发布：接近生产拓扑、严格参数、审计与告警。
|
||||
- 生产：高可用数据库、严格安全策略、全面监控与演练。
|
||||
- 部署检查清单：
|
||||
- 环境变量注入验证（JWT密钥等）。
|
||||
- 机构配置文件完整性与权限校验。
|
||||
- 数据库连通性与权限测试。
|
||||
- 连接池指标与错误率基线确认。
|
||||
- 回滚脚本与应急预案就绪。
|
||||
@@ -0,0 +1,360 @@
|
||||
# 配置管理
|
||||
|
||||
<cite>
|
||||
**本文引用的文件**
|
||||
- [fms-vue/vite.config.js](file://fms-vue/vite.config.js)
|
||||
- [fms-vue/package.json](file://fms-vue/package.json)
|
||||
- [fms-vue/src/theme/index.js](file://fms-vue/src/theme/index.js)
|
||||
- [fms-vue/src/theme/presets.js](file://fms-vue/src/theme/presets.js)
|
||||
- [fms-vue/src/theme/tokens.css](file://fms-vue/src/theme/tokens.css)
|
||||
- [fms-api/src/main/resources/application.yaml](file://fms-api/src/main/resources/application.yaml)
|
||||
- [fms-api/config/dbconfigs/README.md](file://fms-api/config/dbconfigs/README.md)
|
||||
- [fms-api/src/main/java/cn/g3soft/fmsapi/database/OrgDatabaseProperties.java](file://fms-api/src/main/java/cn/g3soft/fmsapi/database/OrgDatabaseProperties.java)
|
||||
- [fms-api/src/main/java/cn/g3soft/fmsapi/database/OrgDatabaseConfigLoader.java](file://fms-api/src/main/java/cn/g3soft/fmsapi/database/OrgDatabaseConfigLoader.java)
|
||||
- [fms-api/src/main/java/cn/g3soft/fmsapi/database/OrgDatabaseConfig.java](file://fms-api/src/main/java/cn/g3soft/fmsapi/database/OrgDatabaseConfig.java)
|
||||
</cite>
|
||||
|
||||
## 目录
|
||||
1. [简介](#简介)
|
||||
2. [项目结构](#项目结构)
|
||||
3. [核心组件](#核心组件)
|
||||
4. [架构总览](#架构总览)
|
||||
5. [详细组件分析](#详细组件分析)
|
||||
6. [依赖关系分析](#依赖关系分析)
|
||||
7. [性能考虑](#性能考虑)
|
||||
8. [故障排查指南](#故障排查指南)
|
||||
9. [结论](#结论)
|
||||
10. [附录](#附录)
|
||||
|
||||
## 简介
|
||||
本文件面向FMS配置管理系统，系统性说明前后端配置体系与最佳实践。内容覆盖：
|
||||
- 前端Vite构建配置、环境变量管理、主题配置（主色、深浅色模式）
|
||||
- 后端应用配置（application.yaml）、多租户数据库连接配置、文件存储配置
|
||||
- 多环境配置策略（开发、测试、生产）
|
||||
- 运行时配置热更新机制与配置校验规则
|
||||
- 安全建议（敏感信息加密、配置审计）
|
||||
|
||||
## 项目结构
|
||||
本项目采用前后端分离的多模块结构：
|
||||
- fms-vue：前端工程，基于Vite + Vue，提供主题系统与UI设计令牌
|
||||
- fms-api：后端Spring Boot服务，提供API与多租户数据库、文件存储等能力
|
||||
- 共享配置与迁移脚本位于fms-api/config下
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "前端 fms-vue"
|
||||
VCFG["vite.config.js"]
|
||||
THEMEJS["theme/index.js"]
|
||||
PRESETS["theme/presets.js"]
|
||||
TOKENSCSS["theme/tokens.css"]
|
||||
PKG["package.json"]
|
||||
end
|
||||
subgraph "后端 fms-api"
|
||||
APPYAML["application.yaml"]
|
||||
DBPROPS["OrgDatabaseProperties.java"]
|
||||
DBLOADER["OrgDatabaseConfigLoader.java"]
|
||||
DBCONFIG["OrgDatabaseConfig.java"]
|
||||
DBREADME["config/dbconfigs/README.md"]
|
||||
end
|
||||
VCFG --> PKG
|
||||
THEMEJS --> PRESETS
|
||||
THEMEJS --> TOKENSCSS
|
||||
APPYAML --> DBPROPS
|
||||
DBPROPS --> DBLOADER
|
||||
DBLOADER --> DBCONFIG
|
||||
DBREADME -.-> DBLOADER
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [fms-vue/vite.config.js:1-25](file://fms-vue/vite.config.js#L1-L25)
|
||||
- [fms-vue/src/theme/index.js:1-16](file://fms-vue/src/theme/index.js#L1-L16)
|
||||
- [fms-vue/src/theme/presets.js:1-16](file://fms-vue/src/theme/presets.js#L1-L16)
|
||||
- [fms-vue/src/theme/tokens.css:1-152](file://fms-vue/src/theme/tokens.css#L1-L152)
|
||||
- [fms-api/src/main/resources/application.yaml:1-34](file://fms-api/src/main/resources/application.yaml#L1-L34)
|
||||
- [fms-api/src/main/java/cn/g3soft/fmsapi/database/OrgDatabaseProperties.java:1-53](file://fms-api/src/main/java/cn/g3soft/fmsapi/database/OrgDatabaseProperties.java#L1-L53)
|
||||
- [fms-api/src/main/java/cn/g3soft/fmsapi/database/OrgDatabaseConfigLoader.java:1-103](file://fms-api/src/main/java/cn/g3soft/fmsapi/database/OrgDatabaseConfigLoader.java#L1-L103)
|
||||
- [fms-api/src/main/java/cn/g3soft/fmsapi/database/OrgDatabaseConfig.java:1-9](file://fms-api/src/main/java/cn/g3soft/fmsapi/database/OrgDatabaseConfig.java#L1-L9)
|
||||
- [fms-api/config/dbconfigs/README.md:1-28](file://fms-api/config/dbconfigs/README.md#L1-L28)
|
||||
|
||||
章节来源
|
||||
- [fms-vue/vite.config.js:1-25](file://fms-vue/vite.config.js#L1-L25)
|
||||
- [fms-api/src/main/resources/application.yaml:1-34](file://fms-api/src/main/resources/application.yaml#L1-L34)
|
||||
|
||||
## 核心组件
|
||||
- 前端构建与代理：Vite配置定义别名、开发服务器端口与API代理
|
||||
- 前端主题系统：通过CSS变量与JS动态切换主色与深浅色模式
|
||||
- 后端应用配置：统一入口application.yaml，包含服务端口、上下文路径、JWT、数据库池、文件存储等
|
||||
- 多租户数据库配置：按机构码加载独立.properties配置文件，并进行严格校验
|
||||
- 文件存储配置：支持本地与OSS两种模式
|
||||
|
||||
章节来源
|
||||
- [fms-vue/vite.config.js:1-25](file://fms-vue/vite.config.js#L1-L25)
|
||||
- [fms-vue/src/theme/index.js:1-16](file://fms-vue/src/theme/index.js#L1-L16)
|
||||
- [fms-vue/src/theme/presets.js:1-16](file://fms-vue/src/theme/presets.js#L1-L16)
|
||||
- [fms-vue/src/theme/tokens.css:1-152](file://fms-vue/src/theme/tokens.css#L1-L152)
|
||||
- [fms-api/src/main/resources/application.yaml:1-34](file://fms-api/src/main/resources/application.yaml#L1-L34)
|
||||
- [fms-api/src/main/java/cn/g3soft/fmsapi/database/OrgDatabaseProperties.java:1-53](file://fms-api/src/main/java/cn/g3soft/fmsapi/database/OrgDatabaseProperties.java#L1-L53)
|
||||
- [fms-api/src/main/java/cn/g3soft/fmsapi/database/OrgDatabaseConfigLoader.java:1-103](file://fms-api/src/main/java/cn/g3soft/fmsapi/database/OrgDatabaseConfigLoader.java#L1-L103)
|
||||
- [fms-api/src/main/java/cn/g3soft/fmsapi/database/OrgDatabaseConfig.java:1-9](file://fms-api/src/main/java/cn/g3soft/fmsapi/database/OrgDatabaseConfig.java#L1-L9)
|
||||
- [fms-api/config/dbconfigs/README.md:1-28](file://fms-api/config/dbconfigs/README.md#L1-L28)
|
||||
|
||||
## 架构总览
|
||||
下图展示前后端配置在运行时的交互关系：前端通过Vite启动并代理API请求到后端；后端读取application.yaml与多租户数据库配置，提供API服务。
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant FE as "前端(Vite)"
|
||||
participant BE as "后端(Spring Boot)"
|
||||
participant CFG as "application.yaml"
|
||||
participant DBP as "OrgDatabaseProperties"
|
||||
participant DBL as "OrgDatabaseConfigLoader"
|
||||
participant DB as "机构数据库(.properties)"
|
||||
FE->>BE : "HTTP /api/* (开发时由Vite代理)"
|
||||
BE->>CFG : "启动时加载基础配置"
|
||||
BE->>DBP : "绑定fms.database.*属性"
|
||||
BE->>DBL : "根据机构码加载配置"
|
||||
DBL->>DB : "读取{ORG_ID}.properties"
|
||||
DB-->>DBL : "url/username/password/driver"
|
||||
DBL-->>BE : "OrgDatabaseConfig"
|
||||
BE-->>FE : "返回业务数据"
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [fms-vue/vite.config.js:11-21](file://fms-vue/vite.config.js#L11-L21)
|
||||
- [fms-api/src/main/resources/application.yaml:1-34](file://fms-api/src/main/resources/application.yaml#L1-L34)
|
||||
- [fms-api/src/main/java/cn/g3soft/fmsapi/database/OrgDatabaseProperties.java:8-53](file://fms-api/src/main/java/cn/g3soft/fmsapi/database/OrgDatabaseProperties.java#L8-L53)
|
||||
- [fms-api/src/main/java/cn/g3soft/fmsapi/database/OrgDatabaseConfigLoader.java:19-103](file://fms-api/src/main/java/cn/g3soft/fmsapi/database/OrgDatabaseConfigLoader.java#L19-L103)
|
||||
- [fms-api/config/dbconfigs/README.md:1-28](file://fms-api/config/dbconfigs/README.md#L1-L28)
|
||||
|
||||
## 详细组件分析
|
||||
|
||||
### 前端Vite构建配置
|
||||
- 别名设置：将@指向src目录，便于模块导入
|
||||
- 开发服务器：host为true，端口固定，strictPort避免冲突
|
||||
- API代理：开发时将/api请求转发至后端地址，便于联调
|
||||
- 插件：启用Vue插件
|
||||
|
||||
章节来源
|
||||
- [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)
|
||||
|
||||
### 前端环境变量管理
|
||||
- 当前工程未使用.env或Vite环境变量注入方式，所有运行时行为通过主题与状态管理控制
|
||||
- 若需接入环境变量，可参考通用工具对.env文件的解析与合并逻辑（如查找优先级、注释处理、引号处理等），以便后续扩展
|
||||
|
||||
章节来源
|
||||
- [fms-vue/package.json:6-19](file://fms-vue/package.json#L6-L19)
|
||||
|
||||
### 前端主题配置
|
||||
- 主色写入：通过JS在根节点设置CSS变量--fms-primary
|
||||
- 深浅色模式：通过切换html的dark class实现
|
||||
- 预设色板：集中维护主题色列表与默认值
|
||||
- 设计令牌：tokens.css集中定义浅色与深色两套变量，主色派生通过color-mix计算
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Start(["应用启动"]) --> LoadPresets["加载预设主色"]
|
||||
LoadPresets --> ApplyPrimary["写入 --fms-primary"]
|
||||
ApplyPrimary --> ToggleDark{"是否深色模式?"}
|
||||
ToggleDark --> |是| AddClass["添加 .dark 类"]
|
||||
ToggleDark --> |否| RemoveClass["移除 .dark 类"]
|
||||
AddClass --> Render["渲染界面(使用 tokens.css)"]
|
||||
RemoveClass --> Render
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [fms-vue/src/theme/index.js:1-16](file://fms-vue/src/theme/index.js#L1-L16)
|
||||
- [fms-vue/src/theme/presets.js:1-16](file://fms-vue/src/theme/presets.js#L1-L16)
|
||||
- [fms-vue/src/theme/tokens.css:1-152](file://fms-vue/src/theme/tokens.css#L1-L152)
|
||||
|
||||
章节来源
|
||||
- [fms-vue/src/theme/index.js:1-16](file://fms-vue/src/theme/index.js#L1-L16)
|
||||
- [fms-vue/src/theme/presets.js:1-16](file://fms-vue/src/theme/presets.js#L1-L16)
|
||||
- [fms-vue/src/theme/tokens.css:1-152](file://fms-vue/src/theme/tokens.css#L1-L152)
|
||||
|
||||
### 后端应用配置（application.yaml）
|
||||
- 服务端口与上下文路径：server.port=8088，context-path=/api
|
||||
- 应用名称：spring.application.name=fms-api
|
||||
- JWT认证：jwt-secret支持从环境变量注入，过期时间24小时
|
||||
- 数据库连接池：fms.database.pool.* 控制连接池参数
|
||||
- 文件存储：fms.file.storage-type选择local或oss；local存储目录与URL前缀；oss端点配置
|
||||
|
||||
章节来源
|
||||
- [fms-api/src/main/resources/application.yaml:1-34](file://fms-api/src/main/resources/application.yaml#L1-L34)
|
||||
|
||||
### 多租户数据库配置
|
||||
- 配置目录：fms.database.config-dir指定存放机构数据库配置的目录
|
||||
- 配置格式：每个机构一个{ORG_ID}.properties文件，包含url、username、password、driver
|
||||
- 配置加载：启动后根据机构码规范化并读取对应文件，缺失或非法则抛出异常
|
||||
- 驱动默认：未指定driver时使用SQL Server驱动
|
||||
- 校验规则：机构码必须匹配正则，必填项检查（url、username、password）
|
||||
|
||||
```mermaid
|
||||
classDiagram
|
||||
class OrgDatabaseProperties {
|
||||
+Path configDir
|
||||
+Pool pool
|
||||
}
|
||||
class Pool {
|
||||
+int initialSize
|
||||
+int minIdle
|
||||
+int maxActive
|
||||
+long maxWait
|
||||
+String validationQuery
|
||||
+boolean testWhileIdle
|
||||
+boolean testOnBorrow
|
||||
+boolean testOnReturn
|
||||
+Duration timeBetweenEvictionRuns
|
||||
+Duration minEvictableIdleTime
|
||||
}
|
||||
class OrgDatabaseConfigLoader {
|
||||
+init()
|
||||
+load(orgId) OrgDatabaseConfig
|
||||
+normalizeOrgId(orgId) String
|
||||
}
|
||||
class OrgDatabaseConfig {
|
||||
+String url
|
||||
+String username
|
||||
+String password
|
||||
+String driver
|
||||
}
|
||||
OrgDatabaseProperties --> Pool : "包含"
|
||||
OrgDatabaseConfigLoader --> OrgDatabaseProperties : "读取"
|
||||
OrgDatabaseConfigLoader --> OrgDatabaseConfig : "生成"
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [fms-api/src/main/java/cn/g3soft/fmsapi/database/OrgDatabaseProperties.java:8-53](file://fms-api/src/main/java/cn/g3soft/fmsapi/database/OrgDatabaseProperties.java#L8-L53)
|
||||
- [fms-api/src/main/java/cn/g3soft/fmsapi/database/OrgDatabaseConfigLoader.java:19-103](file://fms-api/src/main/java/cn/g3soft/fmsapi/database/OrgDatabaseConfigLoader.java#L19-L103)
|
||||
- [fms-api/src/main/java/cn/g3soft/fmsapi/database/OrgDatabaseConfig.java:1-9](file://fms-api/src/main/java/cn/g3soft/fmsapi/database/OrgDatabaseConfig.java#L1-L9)
|
||||
|
||||
章节来源
|
||||
- [fms-api/src/main/java/cn/g3soft/fmsapi/database/OrgDatabaseProperties.java:1-53](file://fms-api/src/main/java/cn/g3soft/fmsapi/database/OrgDatabaseProperties.java#L1-L53)
|
||||
- [fms-api/src/main/java/cn/g3soft/fmsapi/database/OrgDatabaseConfigLoader.java:1-103](file://fms-api/src/main/java/cn/g3soft/fmsapi/database/OrgDatabaseConfigLoader.java#L1-L103)
|
||||
- [fms-api/src/main/java/cn/g3soft/fmsapi/database/OrgDatabaseConfig.java:1-9](file://fms-api/src/main/java/cn/g3soft/fmsapi/database/OrgDatabaseConfig.java#L1-L9)
|
||||
- [fms-api/config/dbconfigs/README.md:1-28](file://fms-api/config/dbconfigs/README.md#L1-L28)
|
||||
|
||||
### 文件存储配置
|
||||
- 类型选择：storage-type=local或oss
|
||||
- 本地存储：storage-dir指定物理目录，url-prefix用于静态访问前缀
|
||||
- OSS存储：g3oss-url指定远端对象存储地址
|
||||
|
||||
章节来源
|
||||
- [fms-api/src/main/resources/application.yaml:27-34](file://fms-api/src/main/resources/application.yaml#L27-L34)
|
||||
|
||||
### 多环境配置管理策略
|
||||
- 开发环境：
|
||||
- 前端：Vite server端口5082，/api代理到http://127.0.0.1:8088
|
||||
- 后端：application.yaml中server.port=8088，context-path=/api
|
||||
- 测试/生产环境：
|
||||
- 可通过环境变量覆盖敏感配置（如JWT密钥）
|
||||
- 多租户数据库配置以外部文件形式部署，避免入库
|
||||
- 文件存储可在不同环境切换local/oss
|
||||
|
||||
章节来源
|
||||
- [fms-vue/vite.config.js:11-21](file://fms-vue/vite.config.js#L11-L21)
|
||||
- [fms-api/src/main/resources/application.yaml:1-34](file://fms-api/src/main/resources/application.yaml#L1-L34)
|
||||
|
||||
### 运行时配置的热更新机制
|
||||
- 前端主题：通过JS动态修改CSS变量与DOM class，无需刷新即可生效
|
||||
- 后端配置：
|
||||
- application.yaml为静态资源，重启生效
|
||||
- 多租户数据库配置以文件形式存在，建议在配置变更时重启服务以确保一致性
|
||||
- 如需热更新，可在服务内增加监听配置目录变化并重新加载配置的能力（当前仓库未实现）
|
||||
|
||||
章节来源
|
||||
- [fms-vue/src/theme/index.js:1-16](file://fms-vue/src/theme/index.js#L1-L16)
|
||||
- [fms-api/src/main/java/cn/g3soft/fmsapi/database/OrgDatabaseConfigLoader.java:19-103](file://fms-api/src/main/java/cn/g3soft/fmsapi/database/OrgDatabaseConfigLoader.java#L19-L103)
|
||||
|
||||
### 配置验证规则
|
||||
- 机构码规范化与校验：仅允许大写英文字母、数字、下划线、连字符，长度限制
|
||||
- 必填字段校验：url、username、password必须存在且非空
|
||||
- 驱动读取：未提供driver时回退到SQL Server驱动
|
||||
- 错误提示：缺失配置或非法输入会抛出明确异常
|
||||
|
||||
章节来源
|
||||
- [fms-api/src/main/java/cn/g3soft/fmsapi/database/OrgDatabaseConfigLoader.java:22-103](file://fms-api/src/main/java/cn/g3soft/fmsapi/database/OrgDatabaseConfigLoader.java#L22-L103)
|
||||
|
||||
## 依赖关系分析
|
||||
- 前端依赖：Vite、Vue插件、Pinia、Axios等（见package.json）
|
||||
- 后端依赖：Spring Boot、JDBC驱动（SQL Server）、自定义数据库配置加载器
|
||||
- 配置耦合：
|
||||
- 前端通过Vite代理与后端解耦，便于独立开发与联调
|
||||
- 后端通过application.yaml与外部.properties文件解耦，支持多租户与多环境
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
FE["前端(fms-vue)"] --> |代理| BE["后端(fms-api)"]
|
||||
BE --> |读取| APP["application.yaml"]
|
||||
BE --> |加载| DBP["OrgDatabaseProperties"]
|
||||
DBP --> |绑定| POOL["Pool配置"]
|
||||
BE --> |实例化| DBL["OrgDatabaseConfigLoader"]
|
||||
DBL --> |读取| DBF["{ORG_ID}.properties"]
|
||||
DBL --> |输出| DBCFG["OrgDatabaseConfig"]
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [fms-vue/vite.config.js:11-21](file://fms-vue/vite.config.js#L11-L21)
|
||||
- [fms-api/src/main/resources/application.yaml:1-34](file://fms-api/src/main/resources/application.yaml#L1-L34)
|
||||
- [fms-api/src/main/java/cn/g3soft/fmsapi/database/OrgDatabaseProperties.java:8-53](file://fms-api/src/main/java/cn/g3soft/fmsapi/database/OrgDatabaseProperties.java#L8-L53)
|
||||
- [fms-api/src/main/java/cn/g3soft/fmsapi/database/OrgDatabaseConfigLoader.java:19-103](file://fms-api/src/main/java/cn/g3soft/fmsapi/database/OrgDatabaseConfigLoader.java#L19-L103)
|
||||
|
||||
章节来源
|
||||
- [fms-vue/package.json:21-46](file://fms-vue/package.json#L21-L46)
|
||||
- [fms-api/src/main/resources/application.yaml:1-34](file://fms-api/src/main/resources/application.yaml#L1-L34)
|
||||
|
||||
## 性能考虑
|
||||
- 前端：
|
||||
- 使用CSS变量与color-mix减少重复样式，提升主题切换性能
|
||||
- 开发代理减少跨域开销，提高联调效率
|
||||
- 后端：
|
||||
- 合理设置连接池参数（initial-size、min-idle、max-active、max-wait）以平衡响应时间与资源占用
|
||||
- 多租户数据库配置按需加载，避免不必要的I/O
|
||||
- 文件存储选择本地或OSS，依据吞吐与延迟需求调整
|
||||
|
||||
[本节为通用指导，不直接分析具体文件]
|
||||
|
||||
## 故障排查指南
|
||||
- 前端代理失败：
|
||||
- 检查Vite server代理目标地址是否正确
|
||||
- 确认后端服务已启动且端口一致
|
||||
- 主题不生效：
|
||||
- 确认JS已写入--fms-primary变量
|
||||
- 检查HTML是否包含正确的class（light/dark）
|
||||
- 后端启动失败：
|
||||
- 检查application.yaml中的端口与上下文路径
|
||||
- 检查JWT密钥是否通过环境变量正确注入
|
||||
- 多租户数据库连接失败：
|
||||
- 确认{ORG_ID}.properties是否存在且包含必填字段
|
||||
- 检查机构码是否规范（大小写、字符集）
|
||||
- 查看日志中关于缺少配置或格式错误的异常信息
|
||||
|
||||
章节来源
|
||||
- [fms-vue/vite.config.js:11-21](file://fms-vue/vite.config.js#L11-L21)
|
||||
- [fms-vue/src/theme/index.js:1-16](file://fms-vue/src/theme/index.js#L1-L16)
|
||||
- [fms-api/src/main/resources/application.yaml:1-34](file://fms-api/src/main/resources/application.yaml#L1-L34)
|
||||
- [fms-api/src/main/java/cn/g3soft/fmsapi/database/OrgDatabaseConfigLoader.java:67-103](file://fms-api/src/main/java/cn/g3soft/fmsapi/database/OrgDatabaseConfigLoader.java#L67-L103)
|
||||
|
||||
## 结论
|
||||
本配置管理体系通过清晰的前后端职责划分与模块化配置，实现了：
|
||||
- 灵活的主题与多环境支持
|
||||
- 多租户数据库连接的标准化与强校验
|
||||
- 可扩展的文件存储方案
|
||||
建议在生产环境中：
|
||||
- 使用环境变量管理敏感配置（如JWT密钥）
|
||||
- 将多租户数据库配置文件纳入安全管控（权限、备份、审计）
|
||||
- 建立配置变更流程与回滚机制
|
||||
|
||||
[本节为总结性内容，不直接分析具体文件]
|
||||
|
||||
## 附录
|
||||
- 多租户数据库配置示例与说明参见dbconfigs/README.md
|
||||
- 前端脚本命令与依赖版本参见package.json
|
||||
- 主题设计与令牌定义参见theme目录下的JS与CSS文件
|
||||
|
||||
章节来源
|
||||
- [fms-api/config/dbconfigs/README.md:1-28](file://fms-api/config/dbconfigs/README.md#L1-L28)
|
||||
- [fms-vue/package.json:6-46](file://fms-vue/package.json#L6-L46)
|
||||
- [fms-vue/src/theme/index.js:1-16](file://fms-vue/src/theme/index.js#L1-L16)
|
||||
- [fms-vue/src/theme/presets.js:1-16](file://fms-vue/src/theme/presets.js#L1-L16)
|
||||
- [fms-vue/src/theme/tokens.css:1-152](file://fms-vue/src/theme/tokens.css#L1-L152)
|
||||
Reference in new issue
Block a user