aury-boot 0.0.39__tar.gz → 0.0.41__tar.gz

{aury_boot-0.0.39 → aury_boot-0.0.41}/PKG-INFO

@@ -1,8 +1,9 @@
 Metadata-Version: 2.4
 Name: aury-boot
-Version: 0.0.39
+Version: 0.0.41
 Summary: Aury Boot - 基于 FastAPI 生态的企业级 API 开发框架
 Requires-Python: >=3.13
+Requires-Dist: aiohttp>=3.11.0
 Requires-Dist: alembic>=1.17.2
 Requires-Dist: aury-sdk-storage[aws]>=0.0.6
 Requires-Dist: babel>=2.17.0
@@ -10,7 +11,6 @@ Requires-Dist: broadcaster[redis]>=0.3.1
 Requires-Dist: faker>=38.2.0
 Requires-Dist: fastapi>=0.122.0
 Requires-Dist: greenlet>=3.2.4
-Requires-Dist: httpx>=0.28.1
 Requires-Dist: loguru>=0.7.3
 Requires-Dist: pydantic-settings>=2.12.0
 Requires-Dist: pydantic>=2.12.5
@@ -28,12 +28,18 @@ Requires-Dist: aiosqlite>=0.21.0; extra == 'all'
 Requires-Dist: apscheduler>=3.11.1; extra == 'all'
 Requires-Dist: asyncpg>=0.31.0; extra == 'all'
 Requires-Dist: aury-sdk-storage[aws]>=0.0.1; extra == 'all'
+Requires-Dist: coredis>=5.6.0; extra == 'all'
 Requires-Dist: dramatiq>=1.18.0; extra == 'all'
 Requires-Dist: pika>=1.3.2; extra == 'all'
+Requires-Dist: psutil>=7.0.0; extra == 'all'
+Requires-Dist: pyroscope-io>=0.8.7; extra == 'all'
 Requires-Dist: redis>=7.1.0; extra == 'all'
 Provides-Extra: broadcaster
 Requires-Dist: broadcaster[redis]>=0.3.1; extra == 'broadcaster'
+Provides-Extra: channel-cluster
+Requires-Dist: coredis>=5.6.0; extra == 'channel-cluster'
 Provides-Extra: dev
+Requires-Dist: httpx>=0.28.1; extra == 'dev'
 Requires-Dist: mypy>=1.19.0; extra == 'dev'
 Requires-Dist: pytest-asyncio>=1.3.0; extra == 'dev'
 Requires-Dist: pytest-cov>=7.0.0; extra == 'dev'
@@ -47,14 +53,17 @@ Provides-Extra: mysql
 Requires-Dist: aiomysql>=0.3.2; extra == 'mysql'
 Provides-Extra: otel
 Requires-Dist: opentelemetry-api>=1.25.0; extra == 'otel'
+Requires-Dist: opentelemetry-instrumentation-aiohttp-client>=0.46b0; extra == 'otel'
 Requires-Dist: opentelemetry-instrumentation-fastapi>=0.46b0; extra == 'otel'
-Requires-Dist: opentelemetry-instrumentation-httpx>=0.46b0; extra == 'otel'
 Requires-Dist: opentelemetry-instrumentation-sqlalchemy>=0.46b0; extra == 'otel'
 Requires-Dist: opentelemetry-sdk>=1.25.0; extra == 'otel'
 Provides-Extra: otel-exporter
 Requires-Dist: opentelemetry-exporter-otlp>=1.25.0; extra == 'otel-exporter'
 Provides-Extra: postgres
 Requires-Dist: asyncpg>=0.31.0; extra == 'postgres'
+Provides-Extra: profiling
+Requires-Dist: psutil>=7.0.0; extra == 'profiling'
+Requires-Dist: pyroscope-io>=0.8.7; extra == 'profiling'
 Provides-Extra: rabbitmq
 Requires-Dist: amqp>=5.3.1; extra == 'rabbitmq'
 Provides-Extra: recommended
@@ -62,10 +71,11 @@ Requires-Dist: aiosqlite>=0.21.0; extra == 'recommended'
 Requires-Dist: apscheduler>=3.11.1; extra == 'recommended'
 Requires-Dist: asyncpg>=0.31.0; extra == 'recommended'
 Requires-Dist: aury-sdk-storage[aws]>=0.0.1; extra == 'recommended'
+Requires-Dist: coredis>=5.6.0; extra == 'recommended'
 Requires-Dist: dramatiq>=1.18.0; extra == 'recommended'
 Requires-Dist: opentelemetry-api>=1.25.0; extra == 'recommended'
+Requires-Dist: opentelemetry-instrumentation-aiohttp-client>=0.46b0; extra == 'recommended'
 Requires-Dist: opentelemetry-instrumentation-fastapi>=0.46b0; extra == 'recommended'
-Requires-Dist: opentelemetry-instrumentation-httpx>=0.46b0; extra == 'recommended'
 Requires-Dist: opentelemetry-instrumentation-sqlalchemy>=0.46b0; extra == 'recommended'
 Requires-Dist: opentelemetry-sdk>=1.25.0; extra == 'recommended'
 Requires-Dist: redis>=7.1.0; extra == 'recommended'

{aury_boot-0.0.39 → aury_boot-0.0.41}/aury/boot/_version.py

@@ -28,7 +28,7 @@ version_tuple: VERSION_TUPLE
 commit_id: COMMIT_ID
 __commit_id__: COMMIT_ID
 
-__version__ = version = '0.0.39'
-__version_tuple__ = version_tuple = (0, 0, 39)
+__version__ = version = '0.0.41'
+__version_tuple__ = version_tuple = (0, 0, 41)
 
 __commit_id__ = commit_id = None

{aury_boot-0.0.39 → aury_boot-0.0.41}/aury/boot/application/adapter/http.py

@@ -25,10 +25,14 @@ from __future__ import annotations
 
 from typing import Any
 
-import httpx
-
 from aury.boot.common.logging import get_trace_id, logger
-from aury.boot.toolkit.http import HttpClient, RetryConfig
+from aury.boot.toolkit.http import (
+    HttpClient,
+    HttpNetworkError,
+    HttpStatusError,
+    HttpTimeoutError,
+    RetryConfig,
+)
 
 from .base import BaseAdapter
 from .config import AdapterSettings
@@ -185,7 +189,7 @@ class HttpAdapter(BaseAdapter):
             json: JSON 请求体
             data: 表单数据
             files: 上传文件
-            **kwargs: 其他 httpx 参数
+            **kwargs: 其他 aiohttp 参数
             
         Returns:
             dict: 响应 JSON
@@ -228,7 +232,7 @@ class HttpAdapter(BaseAdapter):
                     "content": response.text,
                 }
         
-        except httpx.TimeoutException as exc:
+        except HttpTimeoutError as exc:
             raise AdapterTimeoutError(
                 f"请求超时: {method} {path}",
                 adapter_name=self.name,
@@ -236,7 +240,7 @@ class HttpAdapter(BaseAdapter):
                 cause=exc,
             ) from exc
         
-        except httpx.HTTPStatusError as exc:
+        except HttpStatusError as exc:
             # HTTP 错误状态码
             response = exc.response
             try:
@@ -255,6 +259,13 @@ class HttpAdapter(BaseAdapter):
                 cause=exc,
             ) from exc
         
+        except HttpNetworkError as exc:
+            raise AdapterError(
+                f"网络错误: {method} {path} - {exc}",
+                adapter_name=self.name,
+                cause=exc,
+            ) from exc
+        
         except Exception as exc:
             raise AdapterError(
                 f"请求失败: {method} {path} - {type(exc).__name__}: {exc}",

{aury_boot-0.0.39 → aury_boot-0.0.41}/aury/boot/application/app/base.py

@@ -313,6 +313,7 @@ class FoundationApp(FastAPI):
             enable_file_rotation=config.log.enable_file_rotation,
             enable_console=config.log.enable_console,
             logger_levels=logger_levels,
+            enqueue=config.log.enqueue,
         )
         
         # 注册 access 日志（HTTP 请求日志）

{aury_boot-0.0.39 → aury_boot-0.0.41}/aury/boot/application/app/components.py

@@ -318,13 +318,37 @@ class SchedulerComponent(Component):
         # jobstores: 根据 URL 自动选择存储后端
         if scheduler_config.jobstore_url:
             url = scheduler_config.jobstore_url
-            if url.startswith("redis://"):
+            if url.startswith("redis-cluster://"):
+                # Redis Cluster 模式
                 try:
+                    from aury.boot.infrastructure.scheduler.jobstores import RedisClusterJobStore
+                    
+                    scheduler_kwargs["jobstores"] = {
+                        "default": RedisClusterJobStore(url=url)
+                    }
+                    logger.info(f"调度器使用 Redis Cluster 存储: {url.split('@')[-1].split('/')[0]}")
+                except ImportError:
+                    logger.warning("Redis Cluster jobstore 需要安装 redis[cluster]: pip install 'redis[cluster]'")
+            elif url.startswith("redis://"):
+                try:
+                    from urllib.parse import urlparse
                     from apscheduler.jobstores.redis import RedisJobStore
+                    
+                    # 解析 Redis URL
+                    parsed = urlparse(url)
+                    redis_kwargs: dict = {
+                        "host": parsed.hostname or "localhost",
+                        "port": parsed.port or 6379,
+                    }
+                    if parsed.password:
+                        redis_kwargs["password"] = parsed.password
+                    if parsed.path and parsed.path != "/":
+                        redis_kwargs["db"] = int(parsed.path.lstrip("/") or 0)
+                    
                     scheduler_kwargs["jobstores"] = {
-                        "default": RedisJobStore.from_url(url)
+                        "default": RedisJobStore(**redis_kwargs)
                     }
-                    logger.info(f"调度器使用 Redis 存储: {url.split('@')[-1]}")
+                    logger.info(f"调度器使用 Redis 存储: {parsed.hostname}:{parsed.port}")
                 except ImportError:
                     logger.warning("Redis jobstore 需要安装 redis: pip install redis")
             else:
@@ -766,6 +790,70 @@ class AlertComponent(Component):
         pass
 
 
+class ProfilingComponent(Component):
+    """Profiling 组件。
+    
+    提供持续性能分析和事件循环阻塞检测：
+    - Pyroscope：持续采样生成火焰图
+    - 阻塞检测：检测同步代码阻塞事件循环
+    """
+
+    name = "profiling"
+    enabled = True
+    depends_on: ClassVar[list[str]] = ["alert"]  # 告警依赖
+
+    def can_enable(self, config: BaseConfig) -> bool:
+        """当启用 Pyroscope 或阻塞检测时启用。"""
+        return self.enabled and (
+            config.profiling.enabled or config.profiling.blocking_detector_enabled
+        )
+
+    async def setup(self, app: FoundationApp, config: BaseConfig) -> None:
+        """初始化 Profiling 组件。"""
+        try:
+            from aury.boot.infrastructure.monitoring.profiling import (
+                ProfilingConfig,
+                ProfilingManager,
+            )
+            
+            profiling_config = ProfilingConfig(
+                enabled=config.profiling.enabled,
+                pyroscope_endpoint=config.profiling.pyroscope_endpoint,
+                pyroscope_auth_token=config.profiling.pyroscope_auth_token,
+                service_name=config.service.name,
+                environment=config.service.environment,
+                blocking_detector_enabled=config.profiling.blocking_detector_enabled,
+                blocking_check_interval_ms=config.profiling.blocking_check_interval_ms,
+                blocking_threshold_ms=config.profiling.blocking_threshold_ms,
+                blocking_severe_threshold_ms=config.profiling.blocking_severe_threshold_ms,
+                blocking_alert_enabled=config.profiling.blocking_alert_enabled,
+                blocking_alert_cooldown_seconds=config.profiling.blocking_alert_cooldown_seconds,
+                blocking_max_history=config.profiling.blocking_max_history,
+                tags=config.profiling.pyroscope_tags,
+            )
+            
+            manager = ProfilingManager.get_instance()
+            manager.configure(profiling_config)
+            await manager.start()
+            
+            # 保存到 app.state
+            app.state.profiling_manager = manager
+            
+        except ImportError as e:
+            logger.warning(f"Profiling 依赖未安装，跳过初始化: {e}")
+        except Exception as e:
+            logger.warning(f"Profiling 初始化失败（非关键）: {e}")
+
+    async def teardown(self, app: FoundationApp) -> None:
+        """停止 Profiling 组件。"""
+        try:
+            manager = getattr(app.state, "profiling_manager", None)
+            if manager:
+                await manager.stop()
+        except Exception as e:
+            logger.warning(f"Profiling 关闭失败: {e}")
+
+
 class EventBusComponent(Component):
     """事件总线组件。
     
@@ -815,6 +903,7 @@ FoundationApp.plugins = [
 # 设置默认组件
 FoundationApp.components = [
     AlertComponent,  # 最先初始化告警管理器
+    ProfilingComponent,  # Profiling 依赖告警
     DatabaseComponent,
     MigrationComponent,
     AdminConsoleComponent,
@@ -837,6 +926,7 @@ __all__ = [
     "EventBusComponent",
     "MessageQueueComponent",
     "MigrationComponent",
+    "ProfilingComponent",
     "SchedulerComponent",
     "StorageComponent",
     "TaskComponent",

{aury_boot-0.0.39 → aury_boot-0.0.41}/aury/boot/application/config/settings.py

@@ -263,15 +263,19 @@ class ChannelSettings(BaseModel):
     支持的后端类型：
     - memory: 内存后端（默认，单进程）
     - redis: Redis Pub/Sub（多进程/分布式）
+    - redis_cluster: Redis Cluster Sharded Pub/Sub（Redis 7.0+）
+    
+    注意：URL 的 scheme 会自动决定后端类型：
+    - redis-cluster://... 自动使用 redis_cluster 后端
     """
     
     backend: str = Field(
         default="",
-        description="通道后端 (memory/redis)，空字符串表示不启用"
+        description="通道后端 (memory/redis/redis_cluster)，空字符串表示不启用"
     )
     url: str | None = Field(
         default=None,
-        description="Redis URL（当 backend=redis 时需要）"
+        description="连接 URL（redis://... 或 redis-cluster://...）"
     )
 
 
@@ -401,6 +405,14 @@ class LogSettings(BaseModel):
         default=False,
         description="是否记录 WebSocket 消息内容（注意性能和敏感数据）"
     )
+    enqueue: bool = Field(
+        default=False,
+        description=(
+            "是否启用多进程安全队列。"
+            "启用后日志通过 multiprocessing.Queue 传输，"
+            "可能导致事件循环阻塞。建议在 asyncio 应用中保持 False"
+        )
+    )
 
 
 class ServiceSettings(BaseModel):
@@ -464,6 +476,7 @@ class SchedulerSettings(BaseModel):
         default=None,
         description=(
             "任务存储 URL。支持：\n"
+            "- redis-cluster://password@host:port（Redis Cluster 存储）\n"
             "- redis://localhost:6379/0（Redis 存储）\n"
             "- sqlite:///jobs.db（SQLite 存储）\n"
             "- postgresql://user:pass@host/db（PostgreSQL 存储）\n"
@@ -741,6 +754,70 @@ class AlertSettings(BaseModel):
         return self._notifiers
 
 
+class ProfilingSettings(BaseModel):
+    """Profiling 配置。
+    
+    环境变量格式: PROFILING__{FIELD}
+    示例: PROFILING__ENABLED, PROFILING__PYROSCOPE_ENDPOINT
+    
+    功能说明：
+    - Pyroscope：持续采样生成火焰图（需安装 pyroscope-io）
+    - 阻塞检测：检测同步代码阻塞事件循环（需安装 psutil）
+    """
+    
+    # Pyroscope 持续 Profiling
+    enabled: bool = Field(
+        default=False,
+        description="是否启用 Pyroscope 持续 profiling"
+    )
+    pyroscope_endpoint: str | None = Field(
+        default=None,
+        description="Pyroscope 服务端点（如 http://pyroscope:4040）"
+    )
+    pyroscope_auth_token: str | None = Field(
+        default=None,
+        description="Pyroscope 认证 token（可选）"
+    )
+    pyroscope_sample_rate: int = Field(
+        default=100,
+        description="Pyroscope 采样率 (Hz)，降低可减少开销"
+    )
+    pyroscope_tags: dict[str, str] = Field(
+        default_factory=dict,
+        description="Pyroscope 自定义标签"
+    )
+    
+    # 事件循环阻塞检测
+    blocking_detector_enabled: bool = Field(
+        default=False,
+        description="是否启用事件循环阻塞检测"
+    )
+    blocking_check_interval_ms: float = Field(
+        default=100,
+        description="阻塞检测间隔 (ms)"
+    )
+    blocking_threshold_ms: float = Field(
+        default=100,
+        description="阻塞阈值 (ms)，超过此时间记录阻塞事件"
+    )
+    blocking_severe_threshold_ms: float = Field(
+        default=500,
+        description="严重阻塞阈值 (ms)，超过此时间触发严重告警"
+    )
+    blocking_alert_enabled: bool = Field(
+        default=True,
+        description="检测到阻塞时是否发送告警"
+    )
+    blocking_alert_cooldown_seconds: float = Field(
+        default=60,
+        description="阻塞告警冷却时间 (秒)，避免告警风暴"
+    )
+    blocking_max_history: int = Field(
+        default=50,
+        description="保留的阻塞事件历史数量"
+    )
+
+
 class MigrationSettings(BaseModel):
     """数据库迁移配置。
     
@@ -1014,6 +1091,7 @@ class BaseConfig(BaseSettings):
     # ========== 监控告警 ==========
     telemetry: TelemetrySettings = Field(default_factory=TelemetrySettings)
     alert: AlertSettings = Field(default_factory=AlertSettings)
+    profiling: ProfilingSettings = Field(default_factory=ProfilingSettings)
     
     model_config = SettingsConfigDict(
         case_sensitive=False,

{aury_boot-0.0.39 → aury_boot-0.0.41}/aury/boot/commands/init.py

@@ -542,6 +542,18 @@ def _collect_interactive_config() -> dict:
 
     config["features"] = features
 
+    # 5.5 监控配置
+    console.print()
+    console.print("[bold]📊 监控配置[/bold]")
+    config["with_otel"] = Confirm.ask(
+        "  启用 OpenTelemetry 链路追踪",
+        default=True,
+    )
+    config["with_profiling"] = Confirm.ask(
+        "  启用 Profiling (火焰图/阻塞检测)",
+        default=False,
+    )
+
     # 6. 开发工具
     console.print()
     config["with_dev"] = Confirm.ask(
@@ -589,6 +601,12 @@ def _build_dependency_list(config: dict) -> list[str]:
     if config.get("with_admin_console", True):
         extras.add("admin")
 
+    # 监控
+    if config.get("with_otel", True):
+        extras.add("otel")
+    if config.get("with_profiling", False):
+        extras.add("profiling")
+
     # 开发工具
     if config.get("with_dev"):
         extras.add("dev")
@@ -616,6 +634,8 @@ def _show_config_summary(config: dict) -> None:
         ("服务模式", config.get("service_mode", "api")),
         ("管理后台", "是" if config.get("with_admin_console", True) else "否"),
         ("可选功能", ", ".join(config.get("features", [])) or "无"),
+        ("OpenTelemetry", "是" if config.get("with_otel", True) else "否"),
+        ("Profiling", "是" if config.get("with_profiling", False) else "否"),
         ("开发工具", "是" if config.get("with_dev") else "否"),
         ("Docker", "是" if config.get("with_docker") else "否"),
     ]

{aury_boot-0.0.39 → aury_boot-0.0.41}/aury/boot/commands/pkg.py

@@ -45,6 +45,7 @@ class Category(str, Enum):
     SCHEDULER = "scheduler"
     ADMIN = "admin"
     STORAGE = "storage"
+    MONITORING = "monitoring"
     ECOSYSTEM = "ecosystem"
 
 
@@ -132,6 +133,29 @@ MODULES: dict[str, ModuleInfo] = {
         category=Category.STORAGE,
         deps=["aury-sdk-storage[aws]"],
     ),
+    # 监控
+    "otel": ModuleInfo(
+        name="otel",
+        desc="OpenTelemetry 链路追踪",
+        usage="启用 TELEMETRY__ENABLED 自动 instrument FastAPI/SQLAlchemy/httpx",
+        category=Category.MONITORING,
+        deps=["opentelemetry-api", "opentelemetry-sdk", "opentelemetry-instrumentation-fastapi",
+              "opentelemetry-instrumentation-sqlalchemy", "opentelemetry-instrumentation-httpx"],
+    ),
+    "otel-exporter": ModuleInfo(
+        name="otel-exporter",
+        desc="OpenTelemetry OTLP 导出器",
+        usage="导出 Traces/Metrics/Logs 到 Jaeger/Prometheus/Loki",
+        category=Category.MONITORING,
+        deps=["opentelemetry-exporter-otlp"],
+    ),
+    "profiling": ModuleInfo(
+        name="profiling",
+        desc="Profiling 性能分析",
+        usage="Pyroscope 火焰图 + 事件循环阻塞检测",
+        category=Category.MONITORING,
+        deps=["pyroscope-io", "psutil"],
+    ),
     # 生态包
     "storage-aws": ModuleInfo(
         name="storage-aws",
@@ -182,7 +206,12 @@ PRESETS: dict[str, PresetInfo] = {
     "full": PresetInfo(
         name="full",
         desc="完整功能（所有模块）",
-        modules=["postgres", "redis", "tasks", "rabbitmq", "scheduler", "admin", "storage-cos"],
+        modules=["postgres", "redis", "tasks", "rabbitmq", "scheduler", "admin", "storage-cos", "otel", "profiling"],
+    ),
+    "monitoring": PresetInfo(
+        name="monitoring",
+        desc="完整监控（OTel + Profiling）",
+        modules=["otel", "otel-exporter", "profiling"],
     ),
 }
 
@@ -195,6 +224,7 @@ CATEGORY_NAMES: dict[Category, str] = {
     Category.SCHEDULER: "📦 定时调度",
     Category.ADMIN: "📦 管理后台",
     Category.STORAGE: "📦 对象存储",
+    Category.MONITORING: "📊 监控分析",
     Category.ECOSYSTEM: "🌐 生态包",
 }
 

{aury_boot-0.0.39 → aury_boot-0.0.41}/aury/boot/commands/templates/project/aury_docs/00-overview.md.tpl

@@ -60,3 +60,4 @@ CLI 命令参考请查看 [99-cli.md](./99-cli.md)。
 
 ### 监控与告警
 - [17-alerting.md](./17-alerting.md) - 告警系统（慢请求/慢SQL/异常 → 飞书）
+- [18-monitoring-profiling.md](./18-monitoring-profiling.md) - 监控与 Profiling（火焰图/阻塞检测）