aury-boot 0.0.4__py3-none-any.whl → 0.0.7__py3-none-any.whl

aury/boot/application/config/settings.py

@@ -9,23 +9,33 @@
 from __future__ import annotations
 
 from pathlib import Path
-from typing import Literal
+from typing import Any, Literal
 
 from dotenv import load_dotenv
-from pydantic import Field
+from pydantic import BaseModel, Field
 from pydantic_settings import BaseSettings, SettingsConfigDict
 
+from .multi_instance import MultiInstanceConfigLoader, MultiInstanceSettings
+
 
 def _load_env_file(env_file: str | Path) -> bool:
     """加载 .env 文件到环境变量。"""
     return load_dotenv(env_file, override=True)
 
 
-class DatabaseSettings(BaseSettings):
-    """数据库配置。
+# =============================================================================
+# 多实例配置基类
+# =============================================================================
+
+
+class DatabaseInstanceConfig(MultiInstanceSettings):
+    """数据库实例配置。
     
-    环境变量前缀: DATABASE_
-    示例: DATABASE_URL, DATABASE_ECHO, DATABASE_POOL_SIZE
+    环境变量格式: DATABASE__{INSTANCE}__{FIELD}
+    示例:
+        DATABASE__DEFAULT__URL=postgresql://main...
+        DATABASE__DEFAULT__POOL_SIZE=10
+        DATABASE__ANALYTICS__URL=postgresql://analytics...
     """
     
     url: str = Field(
@@ -56,23 +66,170 @@ class DatabaseSettings(BaseSettings):
         default=True,
         description="是否在获取连接前进行 PING"
     )
+
+
+class CacheInstanceConfig(MultiInstanceSettings):
+    """缓存实例配置。
     
-    model_config = SettingsConfigDict(
-        env_prefix="DATABASE_",
-        case_sensitive=False,
+    环境变量格式: CACHE__{INSTANCE}__{FIELD}
+    示例:
+        CACHE__DEFAULT__BACKEND=redis
+        CACHE__DEFAULT__URL=redis://localhost:6379/0
+        CACHE__LOCAL__BACKEND=memory
+        CACHE__LOCAL__MAX_SIZE=5000
+    """
+    
+    backend: str = Field(
+        default="memory",
+        description="缓存后端 (memory/redis/memcached)"
+    )
+    url: str | None = Field(
+        default=None,
+        description="缓存服务 URL"
+    )
+    max_size: int = Field(
+        default=1000,
+        description="内存缓存最大大小"
+    )
+
+
+class StorageInstanceConfig(MultiInstanceSettings):
+    """对象存储实例配置。
+    
+    环境变量格式: STORAGE__{INSTANCE}__{FIELD}
+    示例:
+        STORAGE__DEFAULT__BACKEND=s3
+        STORAGE__DEFAULT__BUCKET=main-bucket
+        STORAGE__BACKUP__BACKEND=local
+        STORAGE__BACKUP__BASE_PATH=/backup
+    """
+    
+    backend: Literal["local", "s3", "oss", "cos"] = Field(
+        default="local",
+        description="存储后端"
+    )
+    # S3 配置
+    access_key_id: str | None = Field(default=None)
+    access_key_secret: str | None = Field(default=None)
+    endpoint: str | None = Field(default=None)
+    region: str | None = Field(default=None)
+    bucket_name: str | None = Field(default=None)
+    # 本地存储
+    base_path: str = Field(default="./storage")
+
+
+class ChannelInstanceConfig(MultiInstanceSettings):
+    """通道实例配置。
+    
+    环境变量格式: CHANNEL__{INSTANCE}__{FIELD}
+    示例:
+        CHANNEL__DEFAULT__BACKEND=memory
+        CHANNEL__SHARED__BACKEND=redis
+        CHANNEL__SHARED__URL=redis://localhost:6379/3
+    """
+    
+    backend: str = Field(
+        default="memory",
+        description="通道后端 (memory/redis)"
+    )
+    url: str | None = Field(
+        default=None,
+        description="Redis URL（当 backend=redis 时需要）"
+    )
+
+
+class MQInstanceConfig(MultiInstanceSettings):
+    """消息队列实例配置。
+    
+    环境变量格式: MQ__{INSTANCE}__{FIELD}
+    示例:
+        MQ__DEFAULT__BACKEND=redis
+        MQ__DEFAULT__URL=redis://localhost:6379/4
+    """
+    
+    backend: str = Field(
+        default="redis",
+        description="消息队列后端 (redis/rabbitmq)"
+    )
+    url: str | None = Field(
+        default=None,
+        description="连接 URL"
+    )
+
+
+class EventInstanceConfig(MultiInstanceSettings):
+    """事件总线实例配置。
+    
+    环境变量格式: EVENT__{INSTANCE}__{FIELD}
+    示例:
+        EVENT__DEFAULT__BACKEND=memory
+        EVENT__DISTRIBUTED__BACKEND=redis
+        EVENT__DISTRIBUTED__URL=redis://localhost:6379/5
+    """
+    
+    backend: str = Field(
+        default="memory",
+        description="事件后端 (memory/redis/rabbitmq)"
+    )
+    url: str | None = Field(
+        default=None,
+        description="连接 URL"
     )
 
 
-class CacheSettings(BaseSettings):
+# =============================================================================
+# 单实例配置
+# =============================================================================
+
+
+class DatabaseSettings(BaseModel):
+    """数据库配置（单实例）。
+    
+    环境变量格式: DATABASE__{FIELD}
+    示例: DATABASE__URL, DATABASE__POOL_SIZE
+    多实例格式: DATABASE__{INSTANCE}__{FIELD}
+    """
+    
+    url: str = Field(
+        default="sqlite+aiosqlite:///./app.db",
+        description="数据库连接字符串"
+    )
+    echo: bool = Field(
+        default=False,
+        description="是否输出 SQL 语句"
+    )
+    pool_size: int = Field(
+        default=5,
+        description="数据库连接池大小"
+    )
+    max_overflow: int = Field(
+        default=10,
+        description="连接池最大溢出连接数"
+    )
+    pool_recycle: int = Field(
+        default=3600,
+        description="连接回收时间（秒）"
+    )
+    pool_timeout: int = Field(
+        default=30,
+        description="获取连接超时时间（秒）"
+    )
+    pool_pre_ping: bool = Field(
+        default=True,
+        description="是否在获取连接前进行 PING"
+    )
+
+
+class CacheSettings(BaseModel):
     """缓存配置。
     
-    环境变量前缀: CACHE_
-    示例: CACHE_TYPE, CACHE_URL, CACHE_MAX_SIZE
+    环境变量格式: CACHE__{FIELD}
+    示例: CACHE__TYPE, CACHE__URL, CACHE__MAX_SIZE
     
     支持的缓存类型：
     - memory: 内存缓存（默认，无需 URL）
-    - redis: Redis 缓存（需要设置 CACHE_URL）
-    - memcached: Memcached 缓存（需要设置 CACHE_URL）
+    - redis: Redis 缓存（需要设置 CACHE__URL）
+    - memcached: Memcached 缓存（需要设置 CACHE__URL）
     """
     
     cache_type: str = Field(
@@ -87,22 +244,14 @@ class CacheSettings(BaseSettings):
         default=1000,
         description="内存缓存最大大小"
     )
-    
-    model_config = SettingsConfigDict(
-        env_prefix="CACHE_",
-        case_sensitive=False,
-    )
 
 
-class StorageSettings(BaseSettings):
+class StorageSettings(BaseModel):
     """对象存储组件接入配置（Application 层）。
 
-说明：
-- Application 层负责从 env/.env 读取配置（快速接入组件）
-- Infrastructure 层的 storage 仅接受 Pydantic(BaseModel) 的配置对象，不读取 env
-
-环境变量前缀：STORAGE_
-"""
+    环境变量格式: STORAGE__{FIELD}
+    示例: STORAGE__TYPE, STORAGE__BUCKET_NAME
+    """
 
     enabled: bool = Field(default=True, description="是否启用存储组件")
 
@@ -129,22 +278,16 @@ class StorageSettings(BaseSettings):
     # local
     base_path: str = Field(default="./storage", description="本地存储基础目录")
 
-    model_config = SettingsConfigDict(
-        env_prefix="STORAGE_",
-        case_sensitive=False,
-        extra="ignore",
-    )
-
 
-class ServerSettings(BaseSettings):
+class ServerSettings(BaseModel):
     """服务器配置。
     
-    环境变量前缀: SERVER_
-    示例: SERVER_HOST, SERVER_PORT, SERVER_RELOAD
+    环境变量格式: SERVER__{FIELD}
+    示例: SERVER__HOST, SERVER__PORT, SERVER__RELOAD
     """
     
     host: str = Field(
-        default="127.0.0.1",
+        default="0.0.0.0",
         description="服务器监听地址"
     )
     port: int = Field(
@@ -159,18 +302,13 @@ class ServerSettings(BaseSettings):
         default=1,
         description="工作进程数"
     )
-    
-    model_config = SettingsConfigDict(
-        env_prefix="SERVER_",
-        case_sensitive=False,
-    )
 
 
-class CORSSettings(BaseSettings):
+class CORSSettings(BaseModel):
     """CORS配置。
     
-    环境变量前缀: CORS_
-    示例: CORS_ORIGINS, CORS_ALLOW_CREDENTIALS, CORS_ALLOW_METHODS
+    环境变量格式: CORS__{FIELD}
+    示例: CORS__ORIGINS, CORS__ALLOW_CREDENTIALS, CORS__ALLOW_METHODS
     """
     
     origins: list[str] = Field(
@@ -189,18 +327,13 @@ class CORSSettings(BaseSettings):
         default=["*"],
         description="允许的CORS头"
     )
-    
-    model_config = SettingsConfigDict(
-        env_prefix="CORS_",
-        case_sensitive=False,
-    )
 
 
-class LogSettings(BaseSettings):
+class LogSettings(BaseModel):
     """日志配置。
     
-    环境变量前缀: LOG_
-    示例: LOG_LEVEL, LOG_DIR, LOG_ROTATION_TIME, LOG_RETENTION_DAYS
+    环境变量格式: LOG__{FIELD}
+    示例: LOG__LEVEL, LOG__DIR, LOG__ROTATION_TIME, LOG__RETENTION_DAYS
     """
     
     level: str = Field(
@@ -239,24 +372,19 @@ class LogSettings(BaseSettings):
         default=False,
         description="是否记录 WebSocket 消息内容（注意性能和敏感数据）"
     )
-    
-    model_config = SettingsConfigDict(
-        env_prefix="LOG_",
-        case_sensitive=False,
-    )
 
 
-class ServiceSettings(BaseSettings):
+class ServiceSettings(BaseModel):
     """服务配置。
 
-    环境变量前缀: SERVICE_
-    示例: SERVICE_NAME, SERVICE_TYPE
+    环境变量格式: SERVICE__{FIELD}
+    示例: SERVICE__NAME, SERVICE__TYPE
 
     服务类型说明：
-    - api: 运行 API 服务（SCHEDULER_ENABLED 决定是否同时运行调度器）
+    - api: 运行 API 服务（SCHEDULER__ENABLED 决定是否同时运行调度器）
     - worker: 运行任务队列 Worker（处理异步任务）
 
-    独立调度器通过 `aury scheduler` 命令运行，不需要配置 SERVICE_TYPE。
+    独立调度器通过 `aury scheduler` 命令运行，不需要配置 SERVICE__TYPE。
     """
 
     name: str = Field(
@@ -268,21 +396,16 @@ class ServiceSettings(BaseSettings):
         description="服务类型（api/worker）"
     )
 
-    model_config = SettingsConfigDict(
-        env_prefix="SERVICE_",
-        case_sensitive=False,
-    )
-
 
-class SchedulerSettings(BaseSettings):
+class SchedulerSettings(BaseModel):
     """调度器配置。
     
-    环境变量前缀: SCHEDULER_
-    示例: SCHEDULER_ENABLED, SCHEDULER_SCHEDULE_MODULES
+    环境变量格式: SCHEDULER__{FIELD}
+    示例: SCHEDULER__ENABLED, SCHEDULER__SCHEDULE_MODULES
     
-    仅在 SERVICE_TYPE=api 时有效：
-    - SCHEDULER_ENABLED=true: API 服务同时运行内嵌调度器（默认）
-    - SCHEDULER_ENABLED=false: 只运行 API，不启动调度器
+    仅在 SERVICE__TYPE=api 时有效：
+    - SCHEDULER__ENABLED=true: API 服务同时运行内嵌调度器（默认）
+    - SCHEDULER__ENABLED=false: 只运行 API，不启动调度器
     
     独立调度器通过 `aury scheduler` 命令运行，不需要此配置。
     """
@@ -295,18 +418,13 @@ class SchedulerSettings(BaseSettings):
         default_factory=list,
         description="定时任务模块列表。为空时自动发现 schedules 模块"
     )
-    
-    model_config = SettingsConfigDict(
-        env_prefix="SCHEDULER_",
-        case_sensitive=False,
-    )
 
 
-class TaskSettings(BaseSettings):
+class TaskSettings(BaseModel):
     """任务队列配置。
     
-    环境变量前缀: TASK_
-    示例: TASK_BROKER_URL, TASK_MAX_RETRIES
+    环境变量格式: TASK__{FIELD}
+    示例: TASK__BROKER_URL, TASK__MAX_RETRIES
     """
     
     broker_url: str | None = Field(
@@ -321,18 +439,13 @@ class TaskSettings(BaseSettings):
         default=3600,
         description="任务超时时间（秒）"
     )
-    
-    model_config = SettingsConfigDict(
-        env_prefix="TASK_",
-        case_sensitive=False,
-    )
 
 
-class EventSettings(BaseSettings):
+class EventSettings(BaseModel):
     """事件总线配置。
     
-    环境变量前缀: EVENT_
-    示例: EVENT_BROKER_URL, EVENT_EXCHANGE_NAME
+    环境变量格式: EVENT__{FIELD}
+    示例: EVENT__BROKER_URL, EVENT__EXCHANGE_NAME
     """
     
     broker_url: str | None = Field(
@@ -343,18 +456,51 @@ class EventSettings(BaseSettings):
         default="aury.events",
         description="事件交换机名称"
     )
+
+
+class MessageQueueSettings(BaseModel):
+    """消息队列配置。
     
-    model_config = SettingsConfigDict(
-        env_prefix="EVENT_",
-        case_sensitive=False,
+    环境变量格式: MQ__{FIELD}
+    示例: MQ__BROKER_URL, MQ__DEFAULT_QUEUE, MQ__SERIALIZER
+    
+    与 Task（任务队列）的区别：
+    - Task: 基于 Dramatiq，用于异步任务处理（API + Worker 模式）
+    - MQ: 通用消息队列，用于服务间通信、事件驱动架构
+    
+    支持的后端（通过 Kombu）：
+    - Redis: redis://localhost:6379/0
+    - RabbitMQ: amqp://guest:guest@localhost:5672//
+    - Amazon SQS: sqs://
+    """
+    
+    enabled: bool = Field(
+        default=False,
+        description="是否启用消息队列组件"
+    )
+    broker_url: str | None = Field(
+        default=None,
+        description="消息队列代理 URL"
+    )
+    default_queue: str = Field(
+        default="default",
+        description="默认队列名称"
+    )
+    serializer: str = Field(
+        default="json",
+        description="序列化方式（json/pickle/msgpack）"
+    )
+    prefetch_count: int = Field(
+        default=1,
+        description="预取消息数量"
     )
 
 
-class MigrationSettings(BaseSettings):
+class MigrationSettings(BaseModel):
     """数据库迁移配置。
     
-    环境变量前缀: MIGRATION_
-    示例: MIGRATION_CONFIG_PATH, MIGRATION_SCRIPT_LOCATION, MIGRATION_MODEL_MODULES
+    环境变量格式: MIGRATION__{FIELD}
+    示例: MIGRATION__CONFIG_PATH, MIGRATION__SCRIPT_LOCATION, MIGRATION__MODEL_MODULES
     """
     
     config_path: str = Field(
@@ -377,20 +523,15 @@ class MigrationSettings(BaseSettings):
         default=True,
         description="是否自动创建迁移配置和目录"
     )
-    
-    model_config = SettingsConfigDict(
-        env_prefix="MIGRATION_",
-        case_sensitive=False,
-    )
 
 
-class RPCClientSettings(BaseSettings):
+class RPCClientSettings(BaseModel):
     """RPC 客户端调用配置。
     
     用于配置客户端调用其他服务时的行为。
     
-    环境变量前缀: RPC_CLIENT_
-    示例: RPC_CLIENT_SERVICES, RPC_CLIENT_TIMEOUT, RPC_CLIENT_RETRY_TIMES, RPC_CLIENT_DNS_SCHEME
+    环境变量格式: RPC_CLIENT__{FIELD}
+    示例: RPC_CLIENT__SERVICES, RPC_CLIENT__TIMEOUT, RPC_CLIENT__RETRY_TIMES
     """
     
     services: dict[str, str] = Field(
@@ -417,20 +558,15 @@ class RPCClientSettings(BaseSettings):
         default=True,
         description="是否在配置中找不到时使用 DNS 解析（K8s/Docker Compose 自动 DNS）"
     )
-    
-    model_config = SettingsConfigDict(
-        env_prefix="RPC_CLIENT_",
-        case_sensitive=False,
-    )
 
 
-class RPCServiceSettings(BaseSettings):
+class RPCServiceSettings(BaseModel):
     """RPC 服务注册配置。
     
     用于配置当前服务注册到服务注册中心时的信息。
     
-    环境变量前缀: RPC_SERVICE_
-    示例: RPC_SERVICE_NAME, RPC_SERVICE_URL, RPC_SERVICE_HEALTH_CHECK_URL
+    环境变量格式: RPC_SERVICE__{FIELD}
+    示例: RPC_SERVICE__NAME, RPC_SERVICE__URL, RPC_SERVICE__HEALTH_CHECK_URL
     """
     
     name: str | None = Field(
@@ -453,21 +589,16 @@ class RPCServiceSettings(BaseSettings):
         default=None,
         description="服务注册中心地址（如果使用外部注册中心）"
     )
-    
-    model_config = SettingsConfigDict(
-        env_prefix="RPC_SERVICE_",
-        case_sensitive=False,
-    )
 
 
-class HealthCheckSettings(BaseSettings):
+class HealthCheckSettings(BaseModel):
     """健康检查配置。
     
     用于配置 Aury 框架的默认健康检查端点。
     注意：此配置仅用于框架内置的健康检查端点，不影响服务自身的健康检查端点。
     
-    环境变量前缀: HEALTH_CHECK_
-    示例: HEALTH_CHECK_PATH, HEALTH_CHECK_ENABLED
+    环境变量格式: HEALTH_CHECK__{FIELD}
+    示例: HEALTH_CHECK__PATH, HEALTH_CHECK__ENABLED
     """
     
     path: str = Field(
@@ -478,22 +609,17 @@ class HealthCheckSettings(BaseSettings):
         default=True,
         description="是否启用 Aury 默认健康检查端点"
     )
-    
-    model_config = SettingsConfigDict(
-        env_prefix="HEALTH_CHECK_",
-        case_sensitive=False,
-    )
 
 
-class AdminAuthSettings(BaseSettings):
+class AdminAuthSettings(BaseModel):
     """管理后台认证配置。
 
-    环境变量前缀: ADMIN_AUTH_
-    示例: ADMIN_AUTH_MODE, ADMIN_AUTH_SECRET_KEY, ADMIN_AUTH_BASIC_USERNAME
+    作为 ADMIN 配置的子配置，环境变量格式: ADMIN__AUTH__{FIELD}
+    示例: ADMIN__AUTH__MODE, ADMIN__AUTH__SECRET_KEY, ADMIN__AUTH__BASIC_USERNAME
 
     说明：
     - 内置模式仅保证 basic / bearer 开箱即用
-    - jwt/custom 推荐由用户自定义 backend 实现（见 ADMIN_AUTH_BACKEND）
+    - jwt/custom 推荐由用户自定义 backend 实现
     """
 
     mode: Literal["none", "basic", "bearer", "jwt", "custom"] = Field(
@@ -520,17 +646,13 @@ class AdminAuthSettings(BaseSettings):
         description='自定义认证后端导入路径，如 "yourpkg.admin_auth:backend"',
     )
 
-    model_config = SettingsConfigDict(
-        env_prefix="ADMIN_AUTH_",
-        case_sensitive=False,
-    )
 
-
-class AdminConsoleSettings(BaseSettings):
+class AdminConsoleSettings(BaseModel):
     """SQLAdmin 管理后台配置。
 
-    环境变量前缀: ADMIN_
-    示例: ADMIN_ENABLED, ADMIN_PATH, ADMIN_DATABASE_URL
+    环境变量格式: ADMIN__{FIELD}
+    示例: ADMIN__ENABLED, ADMIN__PATH, ADMIN__DATABASE_URL
+    嵌套配置: ADMIN__AUTH__{FIELD}
     """
 
     enabled: bool = Field(default=False, description="是否启用管理后台")
@@ -554,11 +676,6 @@ class AdminConsoleSettings(BaseSettings):
 
     auth: AdminAuthSettings = Field(default_factory=AdminAuthSettings, description="管理后台认证配置")
 
-    model_config = SettingsConfigDict(
-        env_prefix="ADMIN_",
-        case_sensitive=False,
-    )
-
 
 class BaseConfig(BaseSettings):
     """基础配置类。
@@ -566,9 +683,34 @@ class BaseConfig(BaseSettings):
     所有应用配置的基类，提供通用配置项。
     初始化时自动从 .env 文件加载环境变量，然后由 pydantic-settings 读取环境变量。
     
+    环境变量格式:
+    使用双下划线 (__) 作为层级分隔符：
+        {SECTION}__{FIELD}=value
+        {SECTION}__{NESTED}__{FIELD}=value
+    
+    单实例示例:
+        SERVER__HOST=0.0.0.0
+        SERVER__PORT=8000
+        DATABASE__URL=postgresql://...
+        LOG__LEVEL=INFO
+    
+    多实例示例:
+        DATABASE__DEFAULT__URL=postgresql://main...
+        DATABASE__ANALYTICS__URL=postgresql://analytics...
+        CACHE__DEFAULT__BACKEND=redis
+        CACHE__REDIS__URL=redis://localhost:6379/1
+    
     注意：Application 层配置完全独立，不依赖 Infrastructure 层。
     """
     
+    # 多实例配置缓存
+    _databases: dict[str, DatabaseInstanceConfig] | None = None
+    _caches: dict[str, CacheInstanceConfig] | None = None
+    _storages: dict[str, StorageInstanceConfig] | None = None
+    _channels: dict[str, ChannelInstanceConfig] | None = None
+    _mqs: dict[str, MQInstanceConfig] | None = None
+    _events: dict[str, EventInstanceConfig] | None = None
+    
     def __init__(self, _env_file: str | Path = ".env", **kwargs) -> None:
         """初始化配置。
         
@@ -597,13 +739,8 @@ class BaseConfig(BaseSettings):
     admin: AdminConsoleSettings = Field(default_factory=AdminConsoleSettings)
     
     # ========== 数据与缓存 ==========
-    # 数据库配置
     database: DatabaseSettings = Field(default_factory=DatabaseSettings)
-    
-    # 缓存配置
     cache: CacheSettings = Field(default_factory=CacheSettings)
-
-    # 对象存储配置（接入用；storage SDK 本身不读取 env）
     storage: StorageSettings = Field(default_factory=StorageSettings)
     
     # 迁移配置
@@ -617,10 +754,7 @@ class BaseConfig(BaseSettings):
     scheduler: SchedulerSettings = Field(default_factory=SchedulerSettings)
     
     # ========== 异步与事件 ==========
-    # 任务队列配置
     task: TaskSettings = Field(default_factory=TaskSettings)
-    
-    # 事件总线配置
     event: EventSettings = Field(default_factory=EventSettings)
     
     # ========== 微服务通信 ==========
@@ -633,8 +767,114 @@ class BaseConfig(BaseSettings):
     model_config = SettingsConfigDict(
         case_sensitive=False,
         extra="ignore",
+        env_nested_delimiter="__",
     )
     
+    # ========== 多实例配置访问方法 ==========
+    
+    def get_databases(self) -> dict[str, DatabaseInstanceConfig]:
+        """获取所有数据库实例配置。
+        
+        从环境变量解析 DATABASE__{INSTANCE}__{FIELD} 格式的配置。
+        如果没有配置多实例，返回从单实例配置转换的 default 实例。
+        """
+        if self._databases is None:
+            loader = MultiInstanceConfigLoader("DATABASE", DatabaseInstanceConfig)
+            self._databases = loader.load()
+            if not self._databases:
+                self._databases = {
+                    "default": DatabaseInstanceConfig(
+                        url=self.database.url,
+                        echo=self.database.echo,
+                        pool_size=self.database.pool_size,
+                        max_overflow=self.database.max_overflow,
+                        pool_recycle=self.database.pool_recycle,
+                        pool_timeout=self.database.pool_timeout,
+                        pool_pre_ping=self.database.pool_pre_ping,
+                    )
+                }
+        return self._databases
+    
+    def get_caches(self) -> dict[str, CacheInstanceConfig]:
+        """获取所有缓存实例配置。
+        
+        从环境变量解析 CACHE__{INSTANCE}__{FIELD} 格式的配置。
+        如果没有配置多实例，返回从单实例配置转换的 default 实例。
+        """
+        if self._caches is None:
+            loader = MultiInstanceConfigLoader("CACHE", CacheInstanceConfig)
+            self._caches = loader.load()
+            if not self._caches:
+                self._caches = {
+                    "default": CacheInstanceConfig(
+                        backend=self.cache.cache_type,
+                        url=self.cache.url,
+                        max_size=self.cache.max_size,
+                    )
+                }
+        return self._caches
+    
+    def get_storages(self) -> dict[str, StorageInstanceConfig]:
+        """获取所有存储实例配置。
+        
+        从环境变量解析 STORAGE__{INSTANCE}__{FIELD} 格式的配置。
+        如果没有配置多实例，返回从单实例配置转换的 default 实例。
+        """
+        if self._storages is None:
+            loader = MultiInstanceConfigLoader("STORAGE", StorageInstanceConfig)
+            self._storages = loader.load()
+            if not self._storages:
+                self._storages = {
+                    "default": StorageInstanceConfig(
+                        backend=self.storage.type,
+                        access_key_id=self.storage.access_key_id,
+                        access_key_secret=self.storage.access_key_secret,
+                        endpoint=self.storage.endpoint,
+                        region=self.storage.region,
+                        bucket_name=self.storage.bucket_name,
+                        base_path=self.storage.base_path,
+                    )
+                }
+        return self._storages
+    
+    def get_channels(self) -> dict[str, ChannelInstanceConfig]:
+        """获取所有通道实例配置。
+        
+        从环境变量解析 CHANNEL__{INSTANCE}__{FIELD} 格式的配置。
+        """
+        if self._channels is None:
+            loader = MultiInstanceConfigLoader("CHANNEL", ChannelInstanceConfig)
+            self._channels = loader.load()
+        return self._channels
+    
+    def get_mqs(self) -> dict[str, MQInstanceConfig]:
+        """获取所有消息队列实例配置。
+        
+        从环境变量解析 MQ__{INSTANCE}__{FIELD} 格式的配置。
+        """
+        if self._mqs is None:
+            loader = MultiInstanceConfigLoader("MQ", MQInstanceConfig)
+            self._mqs = loader.load()
+        return self._mqs
+    
+    def get_events(self) -> dict[str, EventInstanceConfig]:
+        """获取所有事件总线实例配置。
+        
+        从环境变量解析 EVENT__{INSTANCE}__{FIELD} 格式的配置。
+        如果没有配置多实例，返回从单实例配置转换的 default 实例。
+        """
+        if self._events is None:
+            loader = MultiInstanceConfigLoader("EVENT", EventInstanceConfig)
+            self._events = loader.load()
+            if not self._events and self.event.broker_url:
+                self._events = {
+                    "default": EventInstanceConfig(
+                        backend="redis" if "redis" in (self.event.broker_url or "") else "rabbitmq",
+                        url=self.event.broker_url,
+                    )
+                }
+        return self._events
+    
     @property
     def is_production(self) -> bool:
         """是否为生产环境。"""
@@ -642,21 +882,30 @@ class BaseConfig(BaseSettings):
 
 
 __all__ = [
+    # 配置类
     "AdminAuthSettings",
     "AdminConsoleSettings",
     "BaseConfig",
     "CORSSettings",
+    # 多实例配置类
+    "CacheInstanceConfig",
     "CacheSettings",
+    "ChannelInstanceConfig",
+    "DatabaseInstanceConfig",
     "DatabaseSettings",
+    "EventInstanceConfig",
     "EventSettings",
     "HealthCheckSettings",
     "LogSettings",
+    "MQInstanceConfig",
+    "MessageQueueSettings",
     "MigrationSettings",
     "RPCClientSettings",
     "RPCServiceSettings",
     "SchedulerSettings",
     "ServerSettings",
     "ServiceSettings",
+    "StorageInstanceConfig",
     "StorageSettings",
     "TaskSettings",
 ]