17 KiB
17 KiB
后端配置
**本文引用的文件** - [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)目录
简介
本文件为 FMS 后端（Spring Boot）配置系统的权威文档，聚焦 application.yaml 的结构与各项参数，覆盖服务器、数据库连接池、多数据源切换、文件存储、安全设置等。同时说明第三方服务集成点、配置验证与默认值管理、以及可热更新的边界与机制。目标是帮助开发者快速理解并正确配置系统，保障生产环境的稳定性与可运维性。
项目结构
FMS 后端采用 Spring Boot 工程组织，应用级配置集中在 resources/application.yaml；业务相关配置通过 @ConfigurationProperties 映射到 Java 类；多机构数据库配置以外部 properties 文件形式存放于 config/dbconfigs 目录，按机构 ID 命名加载。
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
- AuthProperties.java:1-29
- FileStorageProperties.java:1-69
- OrgDatabaseProperties.java:1-120
- OrgDataSourceFactory.java:1-53
- OrgDataSourceManager.java:1-62
- OrgRoutingDataSource.java:1-29
- README.md:1-28
章节来源
核心组件
- 服务器与应用基础配置：端口、上下文路径、应用名。
- 认证配置：JWT 密钥与过期时间，支持环境变量注入与默认值。
- 文件存储配置：本地存储与云存储（OSS）两种模式，支持 URL 前缀与存储根目录。
- 多数据源配置：按机构维度加载外部 properties 文件，使用 Druid 连接池，并通过路由数据源在运行时根据上下文选择目标库。
- 连接池与性能调优：初始大小、空闲最小数、最大活跃、等待超时、校验查询、空闲检测、驱逐策略、NAT/防火墙保活等。
章节来源
- application.yaml:1-34
- AuthProperties.java:1-29
- FileStorageProperties.java:1-69
- OrgDatabaseProperties.java:1-120
- OrgDataSourceFactory.java:1-53
架构总览
下图展示了配置加载与数据源路由的整体流程：应用启动时读取 application.yaml，绑定到对应 Properties 对象；请求进入后，通过 OrgContext 确定当前机构 ID，由 OrgRoutingDataSource 委托给 OrgDataSourceManager，后者从缓存或按需创建 Druid 数据源，最终返回连接。
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
- OrgDataSourceManager.java:1-62
- OrgDataSourceFactory.java:1-53
- application.yaml:1-34
详细组件分析
服务器与应用配置
- 端口与上下文路径：用于暴露 API 的监听端口与统一前缀。
- 应用名称：便于日志与监控标识。
章节来源
认证配置（JWT）
- 密钥与过期时间：通过 fms.auth.* 绑定到 AuthProperties，支持环境变量覆盖与默认值。
- 建议：生产环境务必通过环境变量注入强随机密钥，避免硬编码。
章节来源
文件存储服务配置
- 存储类型：local 或 oss，通过 fms.file.storage-type 控制。
- 本地存储：存储根目录与静态资源 URL 前缀，便于直接挂载或反向代理。
- 云存储（OSS）：提供 OSS 端点地址，便于后续扩展上传/下载能力。
章节来源
多数据源配置与切换机制
- 配置来源：每个机构一个 {ORG_ID}.properties 文件，包含 url、username、password、driver。
- 配置加载：OrgDatabaseConfigLoader 负责读取与规范化机构 ID。
- 数据源工厂：OrgDataSourceFactory 将配置转换为 DruidDataSource，并应用全局连接池参数。
- 数据源管理：OrgDataSourceManager 维护 orgId -> DataSource 的并发缓存，懒加载与优雅关闭。
- 路由数据源：OrgRoutingDataSource 作为 Primary 数据源，依据当前线程上下文中的机构 ID 动态选择连接。
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
- OrgDatabaseConfig.java:1-10
- OrgDataSourceFactory.java:1-53
- OrgDataSourceManager.java:1-62
- OrgRoutingDataSource.java:1-29
章节来源
- application.yaml:14-26
- OrgDatabaseProperties.java:1-120
- OrgDataSourceFactory.java:1-53
- OrgDataSourceManager.java:1-62
- OrgRoutingDataSource.java:1-29
- README.md:1-28
数据库连接池配置与性能调优
- 关键参数
- 初始大小/最小空闲/最大活跃：控制预热与容量上限。
- 最大等待时间：防止请求堆积导致雪崩。
- 校验查询：确保取出的连接有效。
- 空闲检测与驱逐：定期清理僵尸连接，降低内存占用。
- 保活：对抗云环境 NAT/防火墙回收空闲 TCP 会话。
- 推荐实践
- 开发环境：initial-size=0，按需增长。
- 生产环境：适当提高 min-idle 与 max-active，结合压测确定阈值。
- 高延迟网络：开启 keepAlive 与合理的 timeBetweenEvictionRuns。
章节来源
文件存储切换与静态资源访问
- 切换方式：修改 fms.file.storage-type 为 local 或 oss。
- 本地模式：配置 storage-dir 与 url-prefix，配合 Web 静态资源映射即可访问。
- 云存储模式：配置 g3oss-url，后续可在文件服务中对接上传/下载逻辑。
章节来源
第三方服务集成配置
- 邮件服务：当前仓库未包含邮件相关配置项，可按需新增 fms.mail.* 并在 Properties 中绑定。
- 消息队列：当前仓库未包含 MQ 相关配置项，可按需新增 fms.mq.* 并在 Properties 中绑定。
- 建议：所有外部服务配置均通过环境变量注入，避免敏感信息入库。
[本节为通用指导，不直接分析具体文件]
配置验证、默认值管理与热更新
- 配置验证
- 通过 @ConfigurationProperties 自动绑定，建议在启动阶段对必填字段进行校验（例如 JWT 密钥非空）。
- 数据库驱动与连接串格式应在加载时校验，失败时尽早抛出异常。
- 默认值管理
- 认证过期时间、连接池默认值已在 Properties 中定义，便于开箱即用。
- 可通过 application.yaml 或环境变量覆盖默认值。
- 热更新
- 当前实现为启动时加载并缓存数据源，不支持运行时动态切换数据源或热重载配置文件。
- 若需热更新，可在 Properties 上引入配置刷新机制，并在变更时重建或替换对应数据源。
章节来源
- application.yaml:10-34
- AuthProperties.java:1-29
- OrgDatabaseProperties.java:1-120
- OrgDataSourceManager.java:13-62
依赖关系分析
- 配置绑定：application.yaml → @ConfigurationProperties 类。
- 数据源生命周期：Factory 创建 → Manager 缓存 → Routing 路由。
- 外部依赖：Druid 连接池、SQL Server JDBC（示例驱动），外部 properties 文件。
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
- OrgDatabaseProperties.java:1-120
- OrgDataSourceFactory.java:1-53
- OrgDataSourceManager.java:1-62
- OrgRoutingDataSource.java:1-29
- README.md:1-28
章节来源
性能考虑
- 连接池规模：根据并发与平均响应时间估算 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 与 @ConfigurationProperties 完成集中式配置管理，结合外部 properties 文件实现多机构数据源隔离与按需加载。连接池参数可调、具备保活机制，适合云原生与混合部署场景。文件存储支持本地与云存储双模式，便于演进。建议在生产环境严格使用环境变量注入敏感配置，并结合压测优化连接池与超时参数。
[本节为总结，不直接分析具体文件]
附录
- 多机构数据库配置示例位置与规范：参见 dbconfigs 目录下的 README。
- 如需扩展第三方服务（邮件、MQ），建议新增独立配置段与 Properties 类，遵循环境变量优先原则。
章节来源