# 配置管理 **本文引用的文件** - [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) ## 目录 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)