aury-boot 0.0.28__py3-none-any.whl → 0.0.30__py3-none-any.whl

aury/boot/commands/templates/project/aury_docs/17-alerting.md.tpl

@@ -0,0 +1,210 @@
+# 告警系统
+
+本文档介绍 {project_name} 项目中的告警系统配置和使用方法。
+
+## 快速开始（简版配置）
+
+所有告警发送到同一个飞书群：
+
+```bash
+# .env
+ALERT__ENABLED=true
+ALERT__NOTIFIERS__DEFAULT__TYPE=feishu
+ALERT__NOTIFIERS__DEFAULT__WEBHOOK=https://open.feishu.cn/open-apis/bot/v2/hook/xxx
+```
+
+框架会自动创建默认规则，检测慢请求、慢 SQL、异常并发送告警。
+
+---
+
+## 完整版配置（分群告警）
+
+不同类型的告警发送到不同的飞书群，避免一个群接收所有消息。
+
+### 1. 环境变量
+
+```bash
+# .env
+
+# ============ 告警系统 ============
+ALERT__ENABLED=true
+ALERT__RULES_FILE=alert_rules.yaml
+
+# 性能群（慢请求、慢SQL）
+ALERT__NOTIFIERS__PERF_GROUP__TYPE=feishu
+ALERT__NOTIFIERS__PERF_GROUP__WEBHOOK=https://open.feishu.cn/open-apis/bot/v2/hook/perf-xxx
+ALERT__NOTIFIERS__PERF_GROUP__SECRET=your-secret  # 可选
+
+# 错误群（异常）
+ALERT__NOTIFIERS__ERROR_GROUP__TYPE=feishu
+ALERT__NOTIFIERS__ERROR_GROUP__WEBHOOK=https://open.feishu.cn/open-apis/bot/v2/hook/error-xxx
+
+# 运维群（任务失败、超时）
+ALERT__NOTIFIERS__OPS_GROUP__TYPE=feishu
+ALERT__NOTIFIERS__OPS_GROUP__WEBHOOK=https://open.feishu.cn/open-apis/bot/v2/hook/ops-xxx
+
+# 慢操作阈值
+ALERT__SLOW_REQUEST_THRESHOLD=1.0
+ALERT__SLOW_SQL_THRESHOLD=0.5
+```
+
+### 2. 规则文件
+
+生成规则模板：`aury docs alert-rules`
+
+```yaml
+# alert_rules.yaml
+defaults:
+  slow_request_threshold: 1.0
+  slow_sql_threshold: 0.5
+  aggregate_window: 10
+  suppress_seconds: 300
+
+rules:
+  # 慢请求 → 性能群
+  - name: slow_request
+    event_types: [slow_request]
+    aggregate_threshold: 5
+    notifiers: [perf_group]
+
+  # 慢 SQL → 性能群
+  - name: slow_sql
+    event_types: [slow_sql]
+    aggregate_threshold: 10
+    notifiers: [perf_group]
+
+  # 异常 → 错误群（立即告警）
+  - name: exception
+    event_types: [exception]
+    aggregate_threshold: 1
+    suppress_seconds: 60
+    notifiers: [error_group]
+
+  # 任务失败/超时 → 运维群
+  - name: task_issues
+    event_types: [task_failure, task_timeout]
+    aggregate_threshold: 1
+    notifiers: [ops_group]
+```
+
+### 3. 效果
+
+| 事件类型 | 目标群 | 触发条件 |
+|---------|--------|----------|
+| 慢请求（>1s） | 性能群 | 60秒内累计5次 |
+| 慢 SQL（>0.5s） | 性能群 | 60秒内累计10次 |
+| 异常 | 错误群 | 立即告警 |
+| 任务失败/超时 | 运维群 | 立即告警 |
+
+---
+
+## 代码中手动发送告警
+
+```python
+from aury.boot.infrastructure.monitoring.alerting import emit_alert, AlertEventType, AlertSeverity
+
+# 发送自定义告警
+await emit_alert(
+    AlertEventType.CUSTOM,
+    "订单支付超时",
+    severity=AlertSeverity.WARNING,
+    order_id="12345",
+    user_id="u001",
+)
+
+# 发送慢 SQL 告警（通常由框架自动触发）
+await emit_alert(
+    AlertEventType.SLOW_SQL,
+    "慢查询告警",
+    duration=2.5,
+    sql="SELECT * FROM orders WHERE ...",
+)
+```
+
+---
+
+## 通知器类型
+
+### 飞书（feishu）
+
+```bash
+ALERT__NOTIFIERS__XXX__TYPE=feishu
+ALERT__NOTIFIERS__XXX__WEBHOOK=https://open.feishu.cn/open-apis/bot/v2/hook/xxx
+ALERT__NOTIFIERS__XXX__SECRET=xxx  # 可选，签名密钥
+```
+
+### 通用 Webhook
+
+```bash
+ALERT__NOTIFIERS__XXX__TYPE=webhook
+ALERT__NOTIFIERS__XXX__URL=https://your-system.com/alert
+ALERT__NOTIFIERS__XXX__METHOD=POST
+ALERT__NOTIFIERS__XXX__HEADERS='{{"Authorization": "Bearer xxx"}}'
+```
+
+### 自定义通知器
+
+```python
+from aury.boot.infrastructure.monitoring.alerting import AlertNotifier, AlertManager
+
+class DingTalkNotifier(AlertNotifier):
+    @classmethod
+    def from_config(cls, config: dict) -> "DingTalkNotifier":
+        return cls(webhook=config["webhook"])
+
+    async def send(self, notification) -> bool:
+        # 实现发送逻辑
+        ...
+
+# 注册
+AlertManager.register_notifier_class("dingtalk", DingTalkNotifier)
+```
+
+然后在环境变量中使用：
+
+```bash
+ALERT__NOTIFIERS__DING__TYPE=dingtalk
+ALERT__NOTIFIERS__DING__WEBHOOK=https://oapi.dingtalk.com/robot/send?access_token=xxx
+```
+
+---
+
+## 告警事件类型
+
+| 类型 | 说明 | 自动触发 |
+|-----|------|----------|
+| `slow_request` | 慢 HTTP 请求 | 框架自动检测 |
+| `slow_sql` | 慢 SQL 查询 | 框架自动检测 |
+| `exception` | 异常/错误 | 框架自动检测 |
+| `task_failure` | 任务执行失败 | 任务系统触发 |
+| `task_timeout` | 任务执行超时 | 任务系统触发 |
+| `custom` | 自定义告警 | 手动调用 emit_alert |
+
+---
+
+## 告警抑制与聚合
+
+- **聚合窗口**：在窗口时间内累计触发次数，达到阈值才发送告警
+- **抑制时间**：同一告警在抑制时间内不会重复发送
+- **示例**：`aggregate_window=60, aggregate_threshold=5` 表示 60 秒内触发 5 次才告警
+
+这样可以避免告警风暴，同时不遗漏重要问题。
+
+---
+
+## 环境变量参考
+
+| 变量 | 说明 | 默认值 |
+|------|------|--------|
+| `ALERT__ENABLED` | 是否启用告警 | `false` |
+| `ALERT__RULES_FILE` | 规则文件路径 | - |
+| `ALERT__SLOW_REQUEST_THRESHOLD` | 慢请求阈值（秒） | `1.0` |
+| `ALERT__SLOW_SQL_THRESHOLD` | 慢 SQL 阈值（秒） | `0.5` |
+| `ALERT__ALERT_ON_SLOW_REQUEST` | 是否对慢请求告警 | `true` |
+| `ALERT__ALERT_ON_SLOW_SQL` | 是否对慢 SQL 告警 | `true` |
+| `ALERT__ALERT_ON_ERROR` | 是否对异常告警 | `true` |
+| `ALERT__AGGREGATE_WINDOW` | 聚合窗口（秒） | `10` |
+| `ALERT__SLOW_REQUEST_AGGREGATE` | 慢请求触发阈值（窗口内次数） | `5` |
+| `ALERT__SLOW_SQL_AGGREGATE` | 慢 SQL 触发阈值 | `10` |
+| `ALERT__EXCEPTION_AGGREGATE` | 异常触发阈值 | `1` |
+| `ALERT__SUPPRESS_SECONDS` | 抑制时间（秒） | `300` |

aury/boot/commands/templates/project/env_templates/monitoring.tpl

@@ -0,0 +1,61 @@
+# =============================================================================
+# 监控与告警配置
+# =============================================================================
+
+# ---------- OpenTelemetry 遥测 ----------
+# 启用后自动 instrument FastAPI、SQLAlchemy、httpx
+TELEMETRY__ENABLED=false
+# TELEMETRY__SAMPLING_RATE=1.0
+
+# OTLP 导出（可选）
+# TELEMETRY__TRACES_ENDPOINT=http://jaeger:4317
+# TELEMETRY__LOGS_ENDPOINT=http://loki:3100
+# TELEMETRY__METRICS_ENDPOINT=http://prometheus:9090
+
+# ---------- 告警系统 ----------
+ALERT__ENABLED=false
+# 慢操作阈值
+ALERT__SLOW_REQUEST_THRESHOLD=1.0
+ALERT__SLOW_SQL_THRESHOLD=0.5
+# 告警开关
+ALERT__ALERT_ON_SLOW_REQUEST=true
+ALERT__ALERT_ON_SLOW_SQL=true
+ALERT__ALERT_ON_ERROR=true
+# 聚合与抑制
+ALERT__AGGREGATE_WINDOW=10
+ALERT__SLOW_REQUEST_AGGREGATE=5
+ALERT__SLOW_SQL_AGGREGATE=10
+ALERT__EXCEPTION_AGGREGATE=1
+ALERT__SUPPRESS_SECONDS=300
+
+# ---------- 告警通知器（简版：单群）----------
+# 所有告警发到同一个飞书群，取消注释并填写 Webhook 即可
+# ALERT__NOTIFIERS__DEFAULT__TYPE=feishu
+# ALERT__NOTIFIERS__DEFAULT__WEBHOOK=https://open.feishu.cn/open-apis/bot/v2/hook/your-webhook-id
+# ALERT__NOTIFIERS__DEFAULT__SECRET=your-secret
+
+# ---------- 告警通知器（完整版：分群告警）----------
+# 不同类型告警发到不同群，需配合 alert_rules.yaml 使用
+# 生成规则模板：aury docs alert-rules
+# ALERT__RULES_FILE=alert_rules.yaml
+
+# 性能群（慢请求、慢SQL）
+# ALERT__NOTIFIERS__PERF_GROUP__TYPE=feishu
+# ALERT__NOTIFIERS__PERF_GROUP__WEBHOOK=https://open.feishu.cn/open-apis/bot/v2/hook/perf-webhook-id
+# ALERT__NOTIFIERS__PERF_GROUP__SECRET=perf-secret
+
+# 错误群（异常）
+# ALERT__NOTIFIERS__ERROR_GROUP__TYPE=feishu
+# ALERT__NOTIFIERS__ERROR_GROUP__WEBHOOK=https://open.feishu.cn/open-apis/bot/v2/hook/error-webhook-id
+# ALERT__NOTIFIERS__ERROR_GROUP__SECRET=error-secret
+
+# 运维群（任务失败、超时）
+# ALERT__NOTIFIERS__OPS_GROUP__TYPE=feishu
+# ALERT__NOTIFIERS__OPS_GROUP__WEBHOOK=https://open.feishu.cn/open-apis/bot/v2/hook/ops-webhook-id
+# ALERT__NOTIFIERS__OPS_GROUP__SECRET=ops-secret
+
+# 通用 Webhook（自定义系统）
+# ALERT__NOTIFIERS__CUSTOM__TYPE=webhook
+# ALERT__NOTIFIERS__CUSTOM__URL=https://your-system.com/api/alert
+# ALERT__NOTIFIERS__CUSTOM__METHOD=POST
+# ALERT__NOTIFIERS__CUSTOM__HEADERS={{"Authorization": "Bearer your-token"}}

aury/boot/common/logging/context.py

@@ -58,8 +58,24 @@ def set_service_context(context: ServiceContext | str) -> None:
 def get_trace_id() -> str:
     """获取当前链路追踪ID。
 
-    如果尚未设置，则生成一个新的随机 ID。
+    优先从 OpenTelemetry 获取（如果已启用），否则使用内置 trace_id。
+    如果都没有设置，则生成一个新的随机 ID。
     """
+    # 优先从 OTel 获取
+    try:
+        from opentelemetry import trace
+        
+        span = trace.get_current_span()
+        if span and span.is_recording():
+            otel_trace_id = span.get_span_context().trace_id
+            if otel_trace_id:
+                return format(otel_trace_id, "032x")
+    except ImportError:
+        pass
+    except Exception:
+        pass
+    
+    # 回退到内置实现
     trace_id = _trace_id_var.get()
     if not trace_id:
         trace_id = str(uuid.uuid4())

aury/boot/common/logging/format.py

@@ -309,7 +309,11 @@ def log_exception(
 
 __all__ = [
     "create_console_sink",
+    "format_exception_compact",
     "format_exception_java_style",
     "format_message",
     "log_exception",
 ]
+
+# 别名导出（保持内部使用 _ 前缀）
+format_exception_compact = _format_exception_compact

aury/boot/domain/transaction/__init__.py

@@ -390,11 +390,68 @@ def requires_transaction(func: Callable) -> Callable:
     return wrapper
 
 
+def isolated_task[T](func: Callable[..., T]) -> Callable[..., T]:
+    """后台任务隔离装饰器。
+    
+    重置事务上下文，避免从父协程继承 _transaction_depth 导致 auto_commit 失效。
+    
+    问题背景：
+        asyncio.create_task() 会继承父协程的 contextvars。如果父协程在 @transactional 中，
+        _transaction_depth > 0，子任务的 auto_commit 和 transactional_context 都会认为
+        "在事务中" 而跳过 commit，导致 session 关闭时 rollback。
+    
+    用法：
+        @isolated_task
+        async def upload_cover(space_id: int, cover_url: str):
+            async with db.session() as session:
+                async with transactional_context(session):
+                    repo = SpaceRepository(session, Space)
+                    space = await repo.get(space_id)
+                    await repo.update(space, {"cover": cover_url})
+                # 现在会正常 commit
+        
+        # 在 Service 中 spawn
+        asyncio.create_task(upload_cover(space.id, url))
+    """
+    @wraps(func)
+    async def wrapper(*args, **kwargs):
+        # 重置事务深度，让当前任务成为独立的事务上下文
+        token = _transaction_depth.set(0)
+        try:
+            return await func(*args, **kwargs)
+        finally:
+            _transaction_depth.reset(token)
+    
+    return wrapper
+
+
+@asynccontextmanager
+async def isolated_context() -> AsyncGenerator[None]:
+    """后台任务隔离上下文管理器。
+    
+    与 @isolated_task 作用相同，但用于上下文管理器形式。
+    
+    用法：
+        async def background_job():
+            async with isolated_context():
+                async with db.session() as session:
+                    async with transactional_context(session):
+                        ...
+    """
+    token = _transaction_depth.set(0)
+    try:
+        yield
+    finally:
+        _transaction_depth.reset(token)
+
+
 __all__ = [
     "TransactionManager",
     "TransactionRequiredError",
     "_transaction_depth",  # 内部使用，不对外文档化
     "ensure_transaction",
+    "isolated_context",
+    "isolated_task",
     "on_commit",
     "requires_transaction",
     "transactional",

aury/boot/infrastructure/channel/base.py

@@ -31,7 +31,10 @@ class ChannelMessage:
     timestamp: datetime = field(default_factory=datetime.now)
 
     def to_sse(self) -> str:
-        """转换为 SSE 格式。"""
+        """转换为 SSE 格式。
+        
+        SSE 规范要求每个消息以双换行符结束。
+        """
         lines = []
         if self.id:
             lines.append(f"id: {self.id}")
@@ -42,7 +45,8 @@ class ChannelMessage:
         for line in data_str.split("\n"):
             lines.append(f"data: {line}")
         lines.append("")  # 空行结束
-        return "\n".join(lines)
+        # SSE 规范要求消息以双换行符结束
+        return "\n".join(lines) + "\n"
 
 
 class IChannel(ABC):

aury/boot/infrastructure/database/query_tools/__init__.py

@@ -12,8 +12,8 @@ import time
 
 from aury.boot.common.logging import logger
 
-# 查询性能监控配置
-QUERY_SLOW_THRESHOLD = 1.0  # 慢查询阈值（秒）
+# 默认慢查询阈值（秒）
+DEFAULT_SLOW_QUERY_THRESHOLD = 1.0
 
 
 def cache_query(
@@ -86,7 +86,7 @@ def cache_query(
 
 
 def monitor_query(
-    slow_threshold: float = QUERY_SLOW_THRESHOLD,
+    slow_threshold: float = DEFAULT_SLOW_QUERY_THRESHOLD,
     enable_explain: bool = False,
 ) -> Callable:
     """查询性能监控装饰器。
@@ -104,7 +104,6 @@ def monitor_query(
             async def list(self, **filters):
                 return await super().list(**filters)
     """
-    
     def decorator(func: Callable) -> Callable:
         @wraps(func)
         async def wrapper(self, *args, **kwargs):
@@ -154,7 +153,6 @@ def monitor_query(
     
     return decorator
 
-
 __all__ = [
     "cache_query",
     "monitor_query",