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

核心改动：
- 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 单测通过

apps/api/app/config.py

@@ -1,50 +1,62 @@
+"""API 服务配置 — 继承 SharedSettings，只追加 API 特有字段。
+
+通用配置（DB/Redis/OSS/Celery/CosyVoice/Doubao 等）统一在
+packages/shared/config.py 的 SharedSettings 中定义，这里不重复。
+
+历史上 API 端使用 UPPER_CASE 命名风格的字段，目前通过 property
+别名向后兼容。新代码统一使用 snake_case（继承自 SharedSettings）。
+"""
+
 import os
 from typing import Optional
 
 from pydantic import AliasChoices, Field, field_validator
-from pydantic_settings import BaseSettings, SettingsConfigDict
+from pydantic_settings import SettingsConfigDict
+
+from packages.shared.config import SharedSettings
 
 
-class Settings(BaseSettings):
-    APP_NAME: str = "xiaoxia-saas"
-    APP_VERSION: str = "0.1.61"
-    ENVIRONMENT: str = "development"
-    DEBUG: bool = True
+class Settings(SharedSettings):
+    """API 服务专用配置。
+
+    通用配置继承自 SharedSettings，这里只定义 API 独有字段。
+    """
+
+    # ── 应用基本信息 ────────────────────────────────────────────────────
+    app_name: str = "xiaoxia-saas"
+    app_version: str = "0.1.61"
 
     # 应用基础 URL，用于生成认证邮件中的链接
     # 开发环境默认 http://localhost:3000
     # 生产环境应通过环境变量 APP_BASE_URL 设置
-    APP_BASE_URL: str = "http://localhost:3000"
+    app_base_url: str = "http://localhost:3000"
 
     # Container bind address; external expose is controlled by Docker/Nginx.
-    API_HOST: str = "0.0.0.0"  # nosec: B104
-    API_PORT: int = 8000
+    api_host: str = "0.0.0.0"  # nosec: B104
+    api_port: int = 8000
 
-    DATABASE_URL: str = "postgresql+psycopg://postgres:postgres@localhost:5432/xiaoxia_saas"
-    DATABASE_POOL_SIZE: int = 20
-    DATABASE_MAX_OVERFLOW: int = 10  # 调整为合理值：pool_size(20) + max_overflow(10) = 最大30连接
-    DATABASE_POOL_TIMEOUT: int = 30
-    DATABASE_POOL_RECYCLE: int = 3600
-    USE_IN_MEMORY_DB: bool = False
-    AUTO_CREATE_SCHEMA: bool = False
+    # ── 数据库特有 ──────────────────────────────────────────────────────
+    use_in_memory_db: bool = False
 
-    REDIS_URL: str = "redis://localhost:6379/0"
-    ENABLE_REDIS_SESSIONS: bool = False
+    # ── Redis 特有 ──────────────────────────────────────────────────────
+    enable_redis_sessions: bool = False
 
+    # ── JWT ────────────────────────────────────────────────────────────
     # JWT secret key - MUST be set via environment variable, no default allowed
-    JWT_SECRET_KEY: Optional[str] = None
+    jwt_secret_key: Optional[str] = None
 
-    # JWT 算法与过期时间（与 .env.example 对齐）
-    JWT_ALGORITHM: str = "HS256"
-    JWT_ACCESS_TOKEN_EXPIRE_MINUTES: int = 30
-    JWT_REFRESH_TOKEN_EXPIRE_DAYS: int = 30
+    # JWT 算法与过期时间
+    jwt_algorithm: str = "HS256"
+    jwt_access_token_expire_minutes: int = 30
+    jwt_refresh_token_expire_days: int = 30
 
-    @field_validator("JWT_SECRET_KEY", mode="before")
+    @field_validator("jwt_secret_key", mode="before")
     @classmethod
     def validate_jwt_secret_key(cls, v):
         if v is None or v == "":
             raise ValueError(
-                "JWT_SECRET_KEY must be set via environment variable. " "Do not use default value in production!"
+                "JWT_SECRET_KEY must be set via environment variable. "
+                "Do not use default value in production!"
             )
         # Block known insecure default values
         insecure_defaults = [
@@ -56,29 +68,23 @@ class Settings(BaseSettings):
         ]
         if v.lower() in [d.lower() for d in insecure_defaults]:
             raise ValueError(
-                f"JWT_SECRET_KEY '{v}' is insecure. " "Please set a strong random secret via environment variable."
+                f"JWT_SECRET_KEY '{v}' is insecure. "
+                "Please set a strong random secret via environment variable."
             )
         return v
 
-    ENABLE_EMAIL_DELIVERY: bool = False
-    SMTP_HOST: str = "smtp.gmail.com"
-    SMTP_PORT: int = 587
-    SMTP_USER: str = ""
-    SMTP_PASSWORD: str = ""
-    SMTP_FROM_EMAIL: str = ""
-    SMTP_FROM_NAME: str = "小虾 SaaS"
-    SMTP_USE_TLS: bool = True
+    # ── 邮件 ────────────────────────────────────────────────────────────
+    enable_email_delivery: bool = False
+    smtp_host: str = "smtp.gmail.com"
+    smtp_port: int = 587
+    smtp_user: str = ""
+    smtp_password: str = ""
+    smtp_from_email: str = ""
+    smtp_from_name: str = "小虾 SaaS"
+    smtp_use_tls: bool = True
 
-    CELERY_BROKER_URL: str = "redis://localhost:6379/0"
-    CELERY_RESULT_BACKEND: str = "redis://localhost:6379/1"
-
-    # OSS 七牛云相关
-    OSS_ENDPOINT: str = "oss-cn-hangzhou.aliyuncs.com"
-    OSS_ACCESS_KEY_ID: str = ""
-    OSS_ACCESS_KEY_SECRET: str = ""
-    OSS_BUCKET_NAME: str = "xiaoxia-autocut"
-
-    @field_validator("OSS_ACCESS_KEY_ID", mode="before")
+    # ── OSS 特有校验 ────────────────────────────────────────────────────
+    @field_validator("oss_access_key_id", mode="before")
     @classmethod
     def validate_oss_access_key_id(cls, v):
         if (v is None or v == "") and os.getenv("APP_ENV", "development") != "development":
@@ -88,7 +94,7 @@ class Settings(BaseSettings):
             )
         return v or ""
 
-    @field_validator("OSS_ACCESS_KEY_SECRET", mode="before")
+    @field_validator("oss_access_key_secret", mode="before")
     @classmethod
     def validate_oss_access_key_secret(cls, v):
         if (v is None or v == "") and os.getenv("APP_ENV", "development") != "development":
@@ -98,16 +104,17 @@ class Settings(BaseSettings):
             )
         return v or ""
 
-    OSS_DIRECT_UPLOAD_MAX_MB: int = Field(
+    oss_direct_upload_max_mb: int = Field(
         default=2000,
-        validation_alias=AliasChoices("OSS_DIRECT_UPLOAD_MAX_MB", "MAX_UPLOAD_SIZE_MB"),
+        validation_alias=AliasChoices("oss_direct_upload_max_mb", "max_upload_size_mb"),
     )
-    OSS_DIRECT_UPLOAD_EXPIRE_SECONDS: int = 900
 
-    CORS_ORIGINS_RAW: str = "http://localhost:3000,http://localhost:5173,http://localhost:8000"
+    # ── CORS ────────────────────────────────────────────────────────────
+    cors_origins_raw: str = "http://localhost:3000,http://localhost:5173,http://localhost:8000"
 
+    # ── 渲染引擎 ────────────────────────────────────────────────────────
     # 渲染引擎选择：legacy=旧VideoComposeService，unified=新UnifiedRenderService
-    RENDER_ENGINE: str = "legacy"
+    render_engine: str = "legacy"
 
     model_config = SettingsConfigDict(
         env_file=".env",
@@ -116,47 +123,178 @@ class Settings(BaseSettings):
         extra="ignore",
     )
 
+    @property
+    def cors_origins(self) -> list[str]:
+        return [origin.strip() for origin in self.cors_origins_raw.split(",") if origin.strip()]
+
+    # ── 向后兼容：UPPER_CASE property 别名 ──────────────────────────────
+    # 新代码请使用 snake_case（继承的字段名），以下别名仅用于兼容旧代码
+
+    @property
+    def APP_NAME(self) -> str:
+        return self.app_name
+
+    @property
+    def APP_VERSION(self) -> str:
+        return self.app_version
+
+    @property
+    def ENVIRONMENT(self) -> str:
+        return self.environment
+
+    @property
+    def DEBUG(self) -> bool:
+        return self.debug
+
+    @property
+    def APP_BASE_URL(self) -> str:
+        return self.app_base_url
+
+    @property
+    def API_HOST(self) -> str:
+        return self.api_host
+
+    @property
+    def API_PORT(self) -> int:
+        return self.api_port
+
+    @property
+    def DATABASE_URL(self) -> str:
+        return self.database_url
+
+    @property
+    def DATABASE_POOL_SIZE(self) -> int:
+        return self.database_pool_size
+
+    @property
+    def DATABASE_MAX_OVERFLOW(self) -> int:
+        return self.database_max_overflow
+
+    @property
+    def DATABASE_POOL_TIMEOUT(self) -> int:
+        return self.database_pool_timeout
+
+    @property
+    def DATABASE_POOL_RECYCLE(self) -> int:
+        return self.database_pool_recycle
+
+    @property
+    def USE_IN_MEMORY_DB(self) -> bool:
+        return self.use_in_memory_db
+
+    @property
+    def AUTO_CREATE_SCHEMA(self) -> bool:
+        return self.auto_create_schema
+
+    @property
+    def REDIS_URL(self) -> str:
+        return self.redis_url
+
+    @property
+    def ENABLE_REDIS_SESSIONS(self) -> bool:
+        return self.enable_redis_sessions
+
+    @property
+    def JWT_SECRET_KEY(self) -> Optional[str]:
+        return self.jwt_secret_key
+
+    @property
+    def JWT_ALGORITHM(self) -> str:
+        return self.jwt_algorithm
+
+    @property
+    def JWT_ACCESS_TOKEN_EXPIRE_MINUTES(self) -> int:
+        return self.jwt_access_token_expire_minutes
+
+    @property
+    def JWT_REFRESH_TOKEN_EXPIRE_DAYS(self) -> int:
+        return self.jwt_refresh_token_expire_days
+
+    @property
+    def ENABLE_EMAIL_DELIVERY(self) -> bool:
+        return self.enable_email_delivery
+
+    @property
+    def SMTP_HOST(self) -> str:
+        return self.smtp_host
+
+    @property
+    def SMTP_PORT(self) -> int:
+        return self.smtp_port
+
+    @property
+    def SMTP_USER(self) -> str:
+        return self.smtp_user
+
+    @property
+    def SMTP_PASSWORD(self) -> str:
+        return self.smtp_password
+
+    @property
+    def SMTP_FROM_EMAIL(self) -> str:
+        return self.smtp_from_email
+
+    @property
+    def SMTP_FROM_NAME(self) -> str:
+        return self.smtp_from_name
+
+    @property
+    def SMTP_USE_TLS(self) -> bool:
+        return self.smtp_use_tls
+
+    @property
+    def CELERY_BROKER_URL(self) -> str:
+        return self.celery_broker_url
+
+    @property
+    def CELERY_RESULT_BACKEND(self) -> str:
+        return self.celery_result_backend
+
+    @property
+    def OSS_ENDPOINT(self) -> str:
+        return self.oss_endpoint
+
+    @property
+    def OSS_ACCESS_KEY_ID(self) -> str:
+        return self.oss_access_key_id
+
+    @property
+    def OSS_ACCESS_KEY_SECRET(self) -> str:
+        return self.oss_access_key_secret
+
+    @property
+    def OSS_BUCKET_NAME(self) -> str:
+        return self.oss_bucket_name
+
+    @property
+    def OSS_DIRECT_UPLOAD_MAX_MB(self) -> int:
+        return self.oss_direct_upload_max_mb
+
+    @property
+    def OSS_DIRECT_UPLOAD_EXPIRE_SECONDS(self) -> int:
+        return self.oss_direct_upload_expire_seconds
+
+    @property
+    def CORS_ORIGINS_RAW(self) -> str:
+        return self.cors_origins_raw
+
     @property
     def CORS_ORIGINS(self) -> list[str]:
-        return [origin.strip() for origin in self.CORS_ORIGINS_RAW.split(",") if origin.strip()]
+        return self.cors_origins
 
     @property
-    def database_url(self) -> str:
-        return self.DATABASE_URL
-
-    @property
-    def redis_url(self) -> str:
-        return self.REDIS_URL
-
-    @property
-    def celery_broker_url(self) -> str:
-        return self.CELERY_BROKER_URL
-
-    @property
-    def celery_result_backend(self) -> str:
-        return self.CELERY_RESULT_BACKEND
-
-    @property
-    def oss_endpoint(self) -> str:
-        return self.OSS_ENDPOINT
-
-    @property
-    def oss_access_key_id(self) -> str:
-        return self.OSS_ACCESS_KEY_ID
-
-    @property
-    def oss_access_key_secret(self) -> str:
-        return self.OSS_ACCESS_KEY_SECRET
-
-    @property
-    def oss_bucket_name(self) -> str:
-        return self.OSS_BUCKET_NAME
+    def RENDER_ENGINE(self) -> str:
+        return self.render_engine
 
 
-_settings: Optional[Settings] = None
+_settings: Optional["Settings"] = None
 
 
-def get_settings() -> Settings:
+def get_settings() -> "Settings":
+    """获取 API 配置单例。
+
+    优先读取 APP_ENV 指定的环境文件（.env.{env}），不存在则读 .env。
+    """
     global _settings
     if _settings is None:
         env = os.getenv("APP_ENV", "development")

apps/worker/worker_app/core/config.py

@@ -1,23 +1,29 @@
+"""Worker 服务配置 — 继承 SharedSettings，只追加 Worker 特有字段。
+
+通用配置（DB/Redis/Celery/OSS/CosyVoice/Doubao 等）统一在
+packages/shared/config.py 的 SharedSettings 中定义，这里不重复。
+"""
+
 import os
 from typing import Optional
 
-from pydantic_settings import BaseSettings, SettingsConfigDict
+from pydantic_settings import SettingsConfigDict
+
+from packages.shared.config import SharedSettings
 
 
-class WorkerSettings(BaseSettings):
+class WorkerSettings(SharedSettings):
+    """Worker 服务专用配置。
+
+    通用配置继承自 SharedSettings，这里只定义 Worker 独有字段。
+    Celery broker/backend 使用继承的 celery_broker_url / celery_result_backend；
+    历史上 Worker 使用 broker_url / result_backend 字段名，通过 property 别名兼容。
+    """
+
+    # ── Worker 特有 ────────────────────────────────────────────────────
     worker_name: str = "xiaoxia-saas-worker"
-    broker_url: str = "redis://redis:6379/0"
-    result_backend: str = "redis://redis:6379/1"
     worker_concurrency: int = 4
     worker_max_tasks_per_child: int = 1000
-    database_url: str = "postgresql+psycopg://postgres:postgres@postgres:5432/xiaoxia_saas"
-    database_pool_size: int = 20
-    database_max_overflow: int = 40
-    database_pool_timeout: int = 30
-    database_pool_recycle: int = 3600
-    environment: str = "development"
-    auto_create_schema: bool = False
-    redis_url: str = "redis://redis:6379/0"
 
     model_config = SettingsConfigDict(
         env_file=".env",
@@ -26,11 +32,24 @@ class WorkerSettings(BaseSettings):
         extra="ignore",
     )
 
+    # ── 向后兼容：Celery 字段名别名 ──────────────────────────────────
+    @property
+    def broker_url(self) -> str:
+        return self.celery_broker_url
 
-_settings: Optional[WorkerSettings] = None
+    @property
+    def result_backend(self) -> str:
+        return self.celery_result_backend
 
 
-def get_settings() -> WorkerSettings:
+_settings: Optional["WorkerSettings"] = None
+
+
+def get_settings() -> "WorkerSettings":
+    """获取 Worker 配置单例。
+
+    优先读取 APP_ENV 指定的环境文件（.env.{env}），不存在则读 .env。
+    """
     global _settings
     if _settings is None:
         env = os.getenv("APP_ENV", "development")

packages/shared/config.py

@@ -1,4 +1,8 @@
-"""Shared settings for API and Worker services."""
+"""统一配置入口 — API 和 Worker 共享的基础配置。
+
+所有服务通用配置定义在这里，两端各自的 Settings 类继承本类，
+只追加服务特有字段。彻底消除重复定义和默认值不一致问题。
+"""
 
 import os
 from typing import Optional
@@ -7,29 +11,42 @@ from pydantic_settings import BaseSettings, SettingsConfigDict
 
 
 class SharedSettings(BaseSettings):
-    """Settings shared between API and Worker services."""
+    """所有服务共享的基础配置。
 
-    # Database
+    API 和 Worker 都继承本类，确保：
+    1. 数据库/Redis/OSS/Celery 等核心配置默认值一致
+    2. 环境变量命名统一（小写风格，pydantic-settings 自动兼容大写）
+    3. 单例模式和 env 文件加载逻辑只实现一次
+    """
+
+    # ── 环境 ──────────────────────────────────────────────────────────────
+    environment: str = "development"
+    debug: bool = True
+    auto_create_schema: bool = False
+
+    # ── 数据库 ────────────────────────────────────────────────────────────
     database_url: str = "postgresql+psycopg://postgres:postgres@localhost:5432/xiaoxia_saas"
     database_pool_size: int = 20
-    database_max_overflow: int = 40
+    database_max_overflow: int = 10  # pool_size(20) + max_overflow(10) = 最大30连接
     database_pool_timeout: int = 30
     database_pool_recycle: int = 3600
 
-    # Redis
+    # ── Redis ────────────────────────────────────────────────────────────
     redis_url: str = "redis://localhost:6379/0"
 
-    # Celery
+    # ── Celery ───────────────────────────────────────────────────────────
     celery_broker_url: str = "redis://localhost:6379/0"
     celery_result_backend: str = "redis://localhost:6379/1"
 
-    # OSS Aliyun
+    # ── OSS 阿里云 ──────────────────────────────────────────────────────
     oss_endpoint: str = "oss-cn-hangzhou.aliyuncs.com"
     oss_access_key_id: str = ""
     oss_access_key_secret: str = ""
     oss_bucket_name: str = "xiaoxia-autocut"
+    oss_direct_upload_max_mb: int = 2000
+    oss_direct_upload_expire_seconds: int = 900
 
-    # CosyVoice (阿里云百炼语音合成)
+    # ── CosyVoice (阿里云百炼语音合成) ───────────────────────────────────
     cosyvoice_api_key: str = ""
     cosyvoice_base_url: str = "https://dashscope.aliyuncs.com/api/v1"
     cosyvoice_model: str = "cosyvoice-v3-flash"
@@ -39,17 +56,13 @@ class SharedSettings(BaseSettings):
     # 音色克隆模型名（固定为 voice-enrollment）
     cosyvoice_clone_model: str = "voice-enrollment"
 
-    # 豆包大模型（火山引擎方舟）
+    # ── 豆包大模型（火山引擎方舟） ────────────────────────────────────────
     doubao_api_key: str = ""
     doubao_model: str = "doubao-seed-1-6-250615"
     doubao_base_url: str = "https://ark.cn-beijing.volces.com/api/v3"
     doubao_timeout: int = 30
     doubao_max_retries: int = 2
 
-    # Environment
-    environment: str = "development"
-    auto_create_schema: bool = False
-
     model_config = SettingsConfigDict(
         env_file=".env",
         env_file_encoding="utf-8",
@@ -62,7 +75,10 @@ _settings: Optional[SharedSettings] = None
 
 
 def get_shared_settings() -> SharedSettings:
-    """Get shared settings instance (global singleton)."""
+    """获取共享配置单例。
+
+    优先读取 APP_ENV 指定的环境文件（.env.{env}），不存在则读 .env。
+    """
     global _settings
     if _settings is None:
         env = os.getenv("APP_ENV", "development")