Главная Обзор Помощь
Регистрация Вход
vectorSeek
/
zsjz-ai
5
0
Ответвить 0
Файлы Задачи 0 Запросы на слияние 0 Вики
Дерево: fc3daa8d0f
Ветки Метки
zsjz-ai
/
.qoder
/
repowiki
/
knowledge
/
zh
/
AI 多模块聚合工程根
/
configuration_system.md

configuration_system.md 5.5 KB
История Исходник

总体方案

仓库采用 Spring Boot 3.5 的原生配置机制：以 application.yaml 为默认配置，按 spring.profiles.active=dev|pro 加载 application-dev.yaml / application-pro.yaml 进行覆盖；业务域配置通过 @ConfigurationProperties(prefix = "...") 绑定到独立 POJO（EmbeddingProperties、GatewayProperties、InsightProperties、AiCleanVectorProperties、EtlProperties、ChatAttachmentProperties、ArtifactProperties、DuckdbBudgetProperties、KnowledgeProperties 等），零散开关则用 @Value。两个子模块各自维护独立的配置文件集合，无共享的公共配置中心。

关键文件与分层

  • ai-server
    • src/main/resources/application.yaml — 默认配置入口，定义 server.*、spring.*、zsjz.*（insight/duckdb/file-ai/embedding/ai-clean/electl）、mybatis-plus.* 等核心段。
    • application-dev.yaml / application-pro.yaml — 分别覆盖数据库连接（PostgreSQL + pgvector）、Redis、Elasticsearch、storage.local.*、sa-token.*、Neo4j、以及 zsjz.embedding.enabled/model-path 等环境差异项。
    • common/config/CorsConfig.java — 基于 @ConditionalOnProperty("app.cors.enabled") 与 @Value("${app.cors.allowed-origin-patterns:*}") 动态注册全局 CORS Filter。
    • 各 module/*/config/*Properties.java — 领域级配置 POJO。
  • ai-gateway
    • src/main/resources/application.yaml — 网关基础配置（Spring Cloud Gateway、Sa-Token、gateway.admin/health-check/cors/services）。
    • application-dev.yaml / application-pro.yaml — 仅覆盖 PostgreSQL 与 Redis 连接，生产版使用 ${PG_URL} / ${PG_USER} / ${PG_PASSWORD} / ${REDIS_HOST} / ${REDIS_PASSWORD} 环境变量注入。
    • config/GatewayProperties.java — gateway.* 类型安全映射。

架构约定与设计决策

  1. Profile 隔离环境：spring.profiles.active=dev 是默认值；开发用内网地址（192.168.0.x），生产用 localhost 或环境变量。两套 YAML 结构完全对齐，便于新增 profile 时对照。
  2. 类型安全优先于字符串取值：复杂配置段（zsjz.embedding、gateway.services[*].nodes[*] 等）统一用 Lombok @Data + @ConfigurationProperties 绑定 POJO，避免散落多处 @Value。
  3. 跨模块配置同步由注释约束：application.yaml 中显式注释“Sa-Token 配置必须与 ai-server 的 application.yaml 逐项一致”，因为网关只读 Redis 中的 token->loginId，键名由配置拼接；application-dev.yaml 也注释“与 ai-server 的同库同 Redis”。
  4. 敏感信息走环境变量：生产环境的 PG 和 Redis 凭据全部通过 ${...} 占位符注入，YAML 中仅保留默认回退值。
  5. 功能开关集中在 zsjz.* 命名空间：insight、duckdb、file-ai、embedding、ai-clean/vector、chat-attachment、etl.rag 等能力均作为 zsjz 下的子树，便于统一启停。
  6. CORS 默认开启但可关闭：CorsConfig 使用 @ConditionalOnProperty(name = "app.cors.enabled", havingValue = "true", matchIfMissing = true)，并允许 app.cors.allowed-origin-patterns 通配收敛到具体来源。
  7. 启动期 DDL 幂等：网关通过 spring.sql.init.mode=always + schema-locations: classpath:db/gateway.sql 在每次启动执行幂等建表；服务侧 MyBatis-Plus 禁用二级缓存，mapper XML 走 classpath*:mappers/**/*.xml。
  8. 运行时持久化配置：gateway.services 仅在 gateway_service 表为空时播种，之后由 /gateway/admin/** 管理，YAML 不再覆盖。

观察到的约定与规则

  • 规则：每个模块的默认配置文件位于 src/main/resources/application.yaml，环境变体命名为 application-{profile}.yaml，并通过 spring.profiles.active 激活（来源：两模块的 application.yaml 顶部）。
  • 规则：spring.application.name 明确区分两个服务（ai-server / ai-gateway），用于 Spring 上下文标识（来源：两模块 application.yaml）。
  • 规则：Sa-Token 的 token-name、timeout、active-timeout、is-concurrent、replaced-range 等字段在 ai-server 与 ai-gateway 的配置中保持逐项一致（来源：两模块 application.yaml 及 dev/pro 文件的注释说明）。
  • 规则：生产环境数据库与 Redis 连接信息通过 ${PG_URL}、${PG_USER}、${PG_PASSWORD}、${REDIS_HOST}、${REDIS_PASSWORD} 环境变量注入，YAML 仅提供默认值（来源：ai-gateway/src/main/resources/application-pro.yaml）。
  • 规则：动态数据源使用 dynamic-datasource，strict=true，写错 @DS key 直接报错而非静默回退主库（来源：application-dev.yaml 中文注释）。
  • 约定：领域配置集中放在 module/<domain>/config/<Domain>Properties.java，对应 application.yaml 中 zsjz.<domain> 或模块自管前缀（如 gateway.*、storage.*、neo4j.*）。
  • 约定：可选能力通过 @ConditionalOnProperty 控制装配（如 CORS Filter 默认 matchIfMissing = true 开启）。
  • 约定：本地文件存储路径 storage.local.root-path=./data/files，对外访问基址 storage.local.base-url 需与 server.port + context-path 保持一致（来源：两处 YAML 注释）。

Electron 前端配置（补充）

Electron 应用另有独立的桌面端配置：electron/config/{config.default,config.local,config.prod}.ts 与窗口选项 windowOptions.ts，以及用户级 data/codex-home/config.toml、local-settings.json，与 Java 后端的 Spring Boot 配置体系相互独立。