## 总体方案 仓库采用 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//config/Properties.java`,对应 `application.yaml` 中 `zsjz.` 或模块自管前缀(如 `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 配置体系相互独立。