refactor(#774): 统一配置管理，消除重复定义和默认值不一致 #784

Merged

xiaoxia merged 3 commits from refactor/unified-config-management into develop 2026-07-23 22:17:51 +08:00

Conversation 2 Commits 3 Files Changed 5

+1078 -111

xiaoxia commented 2026-07-23 21:33:09 +08:00

Owner

Copy Link

Copy Source

代码质量专项 P0 第一单：统一配置管理

问题

• 三套独立配置系统（API / Worker / Shared），20+ 字段重复定义
• 数据库连接池默认值不一致：API max_overflow=10，Worker/Shared=40
• Redis 主机默认值不一致：API用localhost，Worker用redis
• 命名风格不统一：API大写 vs Worker/Shared小写
• 三套各自实现单例模式 + env 文件加载逻辑

修复方案

SharedSettings 作为统一配置基类，API和Worker都继承，只追加特有字段。

packages/shared/config.py — 统一配置入口

• 新增 oss_direct_upload_max_mb / oss_direct_upload_expire_seconds
• database_max_overflow 默认值统一为 10（API端合理值）
• 所有通用配置集中管理：DB / Redis / Celery / OSS / CosyVoice / 豆包

apps/api/app/config.py — 继承 SharedSettings

• 删除重复定义的 20+ 通用字段
• 只保留 API 特有字段：JWT / SMTP / CORS / 渲染引擎 / 邮件等
• 保留 UPPER_CASE property 别名，100% 向后兼容

apps/worker/worker_app/core/config.py — 继承 SharedSettings

• 删除重复定义的 10+ 通用字段
• 只保留 Worker 特有字段：worker_name / concurrency / max_tasks_per_child
• broker_url / result_backend 改为 property 别名指向继承字段

测试

• 全量单测：4305 passed, 8 skipped
• 配置相关 149 个单测全部通过

收益

• 消除重复定义，新增通用配置只需改一处
• 彻底解决默认值不一致问题
• 命名风格逐步统一（新代码用 snake_case）
• 向后兼容，零破坏性改动

## 代码质量专项 P0 第一单：统一配置管理 ### 问题 - 三套独立配置系统（API / Worker / Shared），20+ 字段重复定义 - 数据库连接池默认值不一致：API max_overflow=10，Worker/Shared=40 - Redis 主机默认值不一致：API用localhost，Worker用redis - 命名风格不统一：API大写 vs Worker/Shared小写 - 三套各自实现单例模式 + env 文件加载逻辑 ### 修复方案 **SharedSettings 作为统一配置基类**，API和Worker都继承，只追加特有字段。 **packages/shared/config.py** — 统一配置入口 - 新增 oss_direct_upload_max_mb / oss_direct_upload_expire_seconds - database_max_overflow 默认值统一为 10（API端合理值） - 所有通用配置集中管理：DB / Redis / Celery / OSS / CosyVoice / 豆包 **apps/api/app/config.py** — 继承 SharedSettings - 删除重复定义的 20+ 通用字段 - 只保留 API 特有字段：JWT / SMTP / CORS / 渲染引擎 / 邮件等 - 保留 UPPER_CASE property 别名，100% 向后兼容 **apps/worker/worker_app/core/config.py** — 继承 SharedSettings - 删除重复定义的 10+ 通用字段 - 只保留 Worker 特有字段：worker_name / concurrency / max_tasks_per_child - broker_url / result_backend 改为 property 别名指向继承字段 ### 测试 - 全量单测：**4305 passed, 8 skipped** - 配置相关 149 个单测全部通过 ### 收益 - 消除重复定义，新增通用配置只需改一处 - 彻底解决默认值不一致问题 - 命名风格逐步统一（新代码用 snake_case） - 向后兼容，零破坏性改动

xiaoxia added 3 commits 2026-07-23 21:33:09 +08:00

test(p3-1): wave30 Project领域模型+UseCase单测39个 ... 99330d723b

- Project领域模型：create/is_owner/is_shared_with/can_access 共14个
- ListProjectsUseCase：空校验/空格清理/空列表 共5个
- GetProjectUseCase：正常/不存在/空校验 共5个
- CreateProjectUseCase：正常/默认描述/空名称 共3个
- ShareProjectUseCase：正常/幂等/不存在/非所有者 共4个
- UnshareProjectUseCase：正常/幂等/不存在/非所有者 共4个
- DeleteProjectUseCase：正常/不存在/非所有者/共享用户 共4个
合计39个单测全部通过

test(p3-1): wave31 素材库+素材UseCase单测20个 a0b3f63b8a

refactor(#774): 统一配置管理，消除重复定义和默认值不一致 ... 2f0cc3899e

核心改动：
- SharedSettings 作为统一配置基类，所有通用配置只定义一次
- API Settings 继承 SharedSettings，只保留 API 特有字段（JWT/SMTP/CORS/渲染引擎等）
- Worker Settings 继承 SharedSettings，只保留 Worker 特有字段（并发数等）
- 统一数据库连接池默认值：max_overflow=10（API端合理值，两端一致）
- 统一 OSS 直传配置：max_mb/expire_seconds 从 API 提到 SharedSettings
- 新增 CosyVoice/豆包等 AI 配置的统一管理
- 保留 UPPER_CASE property 别名，100% 向后兼容

收益：
- 消除 3 套配置系统的重复定义（DB/Redis/Celery/OSS 等 20+ 字段）
- 彻底解决默认值不一致问题
- 新增通用配置只需改 SharedSettings 一处
- 全量 4305 单测通过

auto-approve-bot commented 2026-07-23 21:39:28 +08:00

Collaborator

Copy Link

Copy Source

代码审查结果 - PR #784

⚠️ 问题（2个需要修改）

1. packages/shared/config.py 第16行：Worker 数据库连接池配置被错误缩小。

   • 原因：原 apps/worker/ 配置中 database_max_overflow 为 40（最大连接数 60），现统一到 SharedSettings 中改为 10（最大连接数 30）。Worker 服务通常处理高并发后台任务（如视频渲染、AI处理），连接池过小可能导致任务阻塞或数据库获取连接超时。
   • 后果：生产环境 Worker 服务性能下降，任务堆积。

2. packages/shared/config.py 第65行：环境文件加载逻辑可能失效。

   • 原因：model_config 中硬编码了 env_file=".env"，而 get_shared_settings 函数中读取了 APP_ENV 试图加载 .env.{env}。如果在实例化 SharedSettings() 时未显式传递 _env_file 参数，model_config 中的硬编码将生效，导致 APP_ENV 环境切换逻辑失效，始终只加载 .env。
   • 后果：无法根据环境变量切换开发/测试/生产环境配置，导致服务连接错误的数据库或资源。

💡 建议（2个可选）

1. apps/api/app/config.py 第123行：属性映射代码冗长。

   • 内容：使用了大量的 @property 来做 UPPER_CASE 到 snake_case 的兼容。虽然可行，但增加了大量样板代码。建议利用 Pydantic 的 populate_by_name = True 配合 Field(alias=...) 来自动处理别名，或使用 pydantic.AliasChoices，减少维护成本。

2. apps/api/app/config.py 第94行：校验逻辑中的环境变量读取方式不一致。

   • 内容：validate_oss_access_key_id 中使用 os.getenv("APP_ENV") 判断环境。由于配置类中已经定义了 environment 字段，建议在校验器中尽量依赖 Pydantic 模型自身的字段值（需注意 mode="before" 时模型尚未初始化），或者确保 APP_ENV 与 environment 字段含义严格一致，避免两套环境变量逻辑混淆。

---

✅ 格式检查通过 | ❌ 逻辑审查需修改 | ⚠️ 建议关注性能

---

_{🤖 由 AI 代码审查机器人自动生成 | 2026-07-23 13:39:28 | 模型:}

## 代码审查结果 - PR #784 ### ⚠️ 问题（2个需要修改） 1. **packages/shared/config.py 第16行**：Worker 数据库连接池配置被错误缩小。 - **原因**：原 `apps/worker/` 配置中 `database_max_overflow` 为 40（最大连接数 60），现统一到 `SharedSettings` 中改为 10（最大连接数 30）。Worker 服务通常处理高并发后台任务（如视频渲染、AI处理），连接池过小可能导致任务阻塞或数据库获取连接超时。 - **后果**：生产环境 Worker 服务性能下降，任务堆积。 2. **packages/shared/config.py 第65行**：环境文件加载逻辑可能失效。 - **原因**：`model_config` 中硬编码了 `env_file=".env"`，而 `get_shared_settings` 函数中读取了 `APP_ENV` 试图加载 `.env.{env}`。如果在实例化 `SharedSettings()` 时未显式传递 `_env_file` 参数，`model_config` 中的硬编码将生效，导致 `APP_ENV` 环境切换逻辑失效，始终只加载 `.env`。 - **后果**：无法根据环境变量切换开发/测试/生产环境配置，导致服务连接错误的数据库或资源。 ### 💡 建议（2个可选） 1. **apps/api/app/config.py 第123行**：属性映射代码冗长。 - **内容**：使用了大量的 `@property` 来做 UPPER_CASE 到 snake_case 的兼容。虽然可行，但增加了大量样板代码。建议利用 Pydantic 的 `populate_by_name = True` 配合 `Field(alias=...)` 来自动处理别名，或使用 `pydantic.AliasChoices`，减少维护成本。 2. **apps/api/app/config.py 第94行**：校验逻辑中的环境变量读取方式不一致。 - **内容**：`validate_oss_access_key_id` 中使用 `os.getenv("APP_ENV")` 判断环境。由于配置类中已经定义了 `environment` 字段，建议在校验器中尽量依赖 Pydantic 模型自身的字段值（需注意 `mode="before"` 时模型尚未初始化），或者确保 `APP_ENV` 与 `environment` 字段含义严格一致，避免两套环境变量逻辑混淆。 --- ✅ 格式检查通过 | ❌ 逻辑审查需修改 | ⚠️ 建议关注性能 --- _{🤖 由 AI 代码审查机器人自动生成 | 2026-07-23 13:39:28 | 模型:} <!-- AI_CODE_REVIEW_AUTO_COMMENT -->

xiaoxia merged commit 956d90c5c2 into develop 2026-07-23 22:17:51 +08:00

xiaoxia deleted branch refactor/unified-config-management 2026-07-23 22:17:51 +08:00

gitea-actions bot commented 2026-07-23 22:22:16 +08:00

Copy Link

Copy Source

🗑️ 预览环境已清理

PR #784 已关闭或合并，对应的预览环境已被清理。

如有需要，可以重新打开 PR 来重新生成预览环境。

🗑️ **预览环境已清理** PR #784 已关闭或合并，对应的预览环境已被清理。 > 如有需要，可以重新打开 PR 来重新生成预览环境。

Sign in to join this conversation.

Reviewers

No Reviewers

Labels

Clear labels

P0

阻塞性，必须立即处理

P1

高优先级

P2

中优先级

P3

低优先级/后考虑

architecture

架构设计

backend

后端相关

blocked

阻塞中

bug

Bug修复

ci-bug

CI本身的bug

ci-optimization

CI优化类任务

ci-pipeline

CI流水线/workflow相关

cleanup

代码清理

devops

运维/部署/CI

documentation

文档相关

feature

新功能

frontend

前端相关

question

需要讨论确认

ready

PR CI通过，可合并

refactor

代码重构

No Label

Milestone

No items

No Milestone

Projects

Clear projects

No project

Assignees

Clear assignees

auto-approve-bot xiaoxia

No Assignees

3 Participants

Notifications

Subscribe

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: xiaoxia/xiaoxia-saas#784