0 Fork 0

Files

T

oneao f4c7413dc6 20260823210241

2026-08-23 21:02:41 +08:00

18 KiB

Raw Blame History

配置管理

**本文引用的文件** - [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)

简介

本文件面向FMS配置管理系统，系统性说明前后端配置体系与最佳实践。内容覆盖：

前端Vite构建配置、环境变量管理、主题配置（主色、深浅色模式）
后端应用配置（application.yaml）、多租户数据库连接配置、文件存储配置
多环境配置策略（开发、测试、生产）
运行时配置热更新机制与配置校验规则
安全建议（敏感信息加密、配置审计）

项目结构

本项目采用前后端分离的多模块结构：

fms-vue：前端工程，基于Vite + Vue，提供主题系统与UI设计令牌
fms-api：后端Spring Boot服务，提供API与多租户数据库、文件存储等能力
共享配置与迁移脚本位于fms-api/config下

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

图表来源

章节来源

核心组件

前端构建与代理：Vite配置定义别名、开发服务器端口与API代理
前端主题系统：通过CSS变量与JS动态切换主色与深浅色模式
后端应用配置：统一入口application.yaml，包含服务端口、上下文路径、JWT、数据库池、文件存储等
多租户数据库配置：按机构码加载独立.properties配置文件，并进行严格校验
文件存储配置：支持本地与OSS两种模式

章节来源

架构总览

下图展示前后端配置在运行时的交互关系：前端通过Vite启动并代理API请求到后端；后端读取application.yaml与多租户数据库配置，提供API服务。

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 : "返回业务数据"

图表来源

详细组件分析

前端Vite构建配置

别名设置：将@指向src目录，便于模块导入
开发服务器：host为true，端口固定，strictPort避免冲突
API代理：开发时将/api请求转发至后端地址，便于联调
插件：启用Vue插件

章节来源

前端环境变量管理

当前工程未使用.env或Vite环境变量注入方式，所有运行时行为通过主题与状态管理控制
若需接入环境变量，可参考通用工具对.env文件的解析与合并逻辑（如查找优先级、注释处理、引号处理等），以便后续扩展

章节来源

fms-vue/package.json:6-19

前端主题配置

主色写入：通过JS在根节点设置CSS变量--fms-primary
深浅色模式：通过切换html的dark class实现
预设色板：集中维护主题色列表与默认值
设计令牌：tokens.css集中定义浅色与深色两套变量，主色派生通过color-mix计算

flowchart TD
Start(["应用启动"]) --> LoadPresets["加载预设主色"]
LoadPresets --> ApplyPrimary["写入 --fms-primary"]
ApplyPrimary --> ToggleDark{"是否深色模式?"}
ToggleDark --> |是| AddClass["添加 .dark 类"]
ToggleDark --> |否| RemoveClass["移除 .dark 类"]
AddClass --> Render["渲染界面(使用 tokens.css)"]
RemoveClass --> Render

图表来源

章节来源

后端应用配置（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

多租户数据库配置

配置目录：fms.database.config-dir指定存放机构数据库配置的目录
配置格式：每个机构一个{ORG_ID}.properties文件，包含url、username、password、driver
配置加载：启动后根据机构码规范化并读取对应文件，缺失或非法则抛出异常
驱动默认：未指定driver时使用SQL Server驱动
校验规则：机构码必须匹配正则，必填项检查（url、username、password）

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 : "生成"

图表来源

章节来源

文件存储配置

类型选择：storage-type=local或oss
本地存储：storage-dir指定物理目录，url-prefix用于静态访问前缀
OSS存储：g3oss-url指定远端对象存储地址

章节来源

fms-api/src/main/resources/application.yaml:27-34

多环境配置管理策略

开发环境：
- 前端：Vite server端口5082，/api代理到http://127.0.0.1:8088
- 后端：application.yaml中server.port=8088，context-path=/api
测试/生产环境：
- 可通过环境变量覆盖敏感配置（如JWT密钥）
- 多租户数据库配置以外部文件形式部署，避免入库
- 文件存储可在不同环境切换local/oss

章节来源

运行时配置的热更新机制

前端主题：通过JS动态修改CSS变量与DOM class，无需刷新即可生效
后端配置：
- application.yaml为静态资源，重启生效
- 多租户数据库配置以文件形式存在，建议在配置变更时重启服务以确保一致性
- 如需热更新，可在服务内增加监听配置目录变化并重新加载配置的能力（当前仓库未实现）

章节来源

配置验证规则

机构码规范化与校验：仅允许大写英文字母、数字、下划线、连字符，长度限制
必填字段校验：url、username、password必须存在且非空
驱动读取：未提供driver时回退到SQL Server驱动
错误提示：缺失配置或非法输入会抛出明确异常

章节来源

fms-api/src/main/java/cn/g3soft/fmsapi/database/OrgDatabaseConfigLoader.java:22-103

依赖关系分析

前端依赖：Vite、Vue插件、Pinia、Axios等（见package.json）
后端依赖：Spring Boot、JDBC驱动（SQL Server）、自定义数据库配置加载器
配置耦合：
- 前端通过Vite代理与后端解耦，便于独立开发与联调
- 后端通过application.yaml与外部.properties文件解耦，支持多租户与多环境

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"]

图表来源

章节来源

性能考虑

前端：
- 使用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是否存在且包含必填字段
- 检查机构码是否规范（大小写、字符集）
- 查看日志中关于缺少配置或格式错误的异常信息

章节来源

结论

本配置管理体系通过清晰的前后端职责划分与模块化配置，实现了：

灵活的主题与多环境支持
多租户数据库连接的标准化与强校验
可扩展的文件存储方案建议在生产环境中：
使用环境变量管理敏感配置（如JWT密钥）
将多租户数据库配置文件纳入安全管控（权限、备份、审计）
建立配置变更流程与回滚机制

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

附录

多租户数据库配置示例与说明参见dbconfigs/README.md
前端脚本命令与依赖版本参见package.json
主题设计与令牌定义参见theme目录下的JS与CSS文件

章节来源

18 KiB Raw Blame History Unescape Escape

配置管理

目录

简介

项目结构

核心组件

架构总览

详细组件分析

前端Vite构建配置

前端环境变量管理

前端主题配置

后端应用配置（application.yaml）

多租户数据库配置

文件存储配置

多环境配置管理策略

运行时配置的热更新机制

配置验证规则

依赖关系分析

性能考虑

故障排查指南

结论

附录

18 KiB

Raw Blame History