aury-boot 0.0.35__py3-none-any.whl → 0.0.37__py3-none-any.whl

aury/boot/_version.py

@@ -28,7 +28,7 @@ version_tuple: VERSION_TUPLE
 commit_id: COMMIT_ID
 __commit_id__: COMMIT_ID
 
-__version__ = version = '0.0.35'
-__version_tuple__ = version_tuple = (0, 0, 35)
+__version__ = version = '0.0.37'
+__version_tuple__ = version_tuple = (0, 0, 37)
 
 __commit_id__ = commit_id = None

aury/boot/application/config/settings.py

@@ -147,13 +147,13 @@ class MQInstanceConfig(MultiInstanceSettings):
     
     环境变量格式: MQ__{INSTANCE}__{FIELD}
     示例:
-        MQ__DEFAULT__BACKEND=redis
+        MQ__DEFAULT__BACKEND=redis_stream
         MQ__DEFAULT__URL=redis://localhost:6379/4
     """
     
     backend: str = Field(
-        default="redis",
-        description="消息队列后端 (redis/rabbitmq)"
+        default="redis_stream",
+        description="消息队列后端 (redis/redis_stream/rabbitmq)"
     )
     url: str | None = Field(
         default=None,
@@ -530,24 +530,25 @@ class MessageQueueSettings(BaseModel):
     """消息队列配置。
     
     环境变量格式: MQ__{FIELD}
-    示例: MQ__BROKER_URL, MQ__DEFAULT_QUEUE, MQ__SERIALIZER
+    示例: MQ__BACKEND, MQ__URL, MQ__BROKER_URL
     
     与 Task（任务队列）的区别：
     - Task: 基于 Dramatiq，用于异步任务处理（API + Worker 模式）
     - MQ: 通用消息队列，用于服务间通信、事件驱动架构
     
     支持的后端：
-    - Redis: redis://localhost:6379/0
-    - RabbitMQ: amqp://guest:guest@localhost:5672//
+    - redis: redis://localhost:6379/0
+    - redis_stream: redis://localhost:6379/0
+    - rabbitmq: amqp://guest:guest@localhost:5672//
     """
     
-    enabled: bool = Field(
-        default=False,
-        description="是否启用消息队列组件"
+    backend: str = Field(
+        default="",
+        description="消息队列后端 (redis/redis_stream/rabbitmq)，空字符串表示不启用"
     )
-    broker_url: str | None = Field(
+    url: str | None = Field(
         default=None,
-        description="消息队列代理 URL"
+        description="连接 URL"
     )
     default_queue: str = Field(
         default="default",
@@ -714,7 +715,7 @@ class AlertSettings(BaseModel):
     
     # 抑制配置
     suppress_seconds: int = Field(
-        default=10,
+        default=300,
         description="告警抑制时间（秒），相同告警在此时间内不重复发送"
     )
     
@@ -1001,6 +1002,7 @@ class BaseConfig(BaseSettings):
     # ========== 异步与事件 ==========
     task: TaskSettings = Field(default_factory=TaskSettings)
     event: EventSettings = Field(default_factory=EventSettings)
+    mq: MessageQueueSettings = Field(default_factory=MessageQueueSettings)
     
     # ========== 微服务通信 ==========
     # RPC 客户端配置（调用其他服务）
@@ -1108,10 +1110,18 @@ class BaseConfig(BaseSettings):
         """获取所有消息队列实例配置。
         
         从环境变量解析 MQ__{INSTANCE}__{FIELD} 格式的配置。
+        如果没有配置多实例，返回从单实例配置转换的 default 实例。
         """
         if self._mqs is None:
             loader = MultiInstanceConfigLoader("MQ", MQInstanceConfig)
             self._mqs = loader.load()
+            if not self._mqs and self.mq.backend:
+                self._mqs = {
+                    "default": MQInstanceConfig(
+                        backend=self.mq.backend,
+                        url=self.mq.url,
+                    )
+                }
         return self._mqs
     
     def get_events(self) -> dict[str, EventInstanceConfig]:

aury/boot/commands/init.py

@@ -707,8 +707,8 @@ def init(
         console.print(f"  [cyan]uv add \"{deps[0]}\"[/cyan]")
         console.print()
     else:
-        # 非交互模式：默认启用 Admin Console
-        with_admin_console = True
+        # 非交互模式：默认禁用 Admin Console
+        with_admin_console = False
         if package_name == ".":
             package_name_snake = None
         elif package_name:

aury/boot/commands/server/app.py

@@ -9,6 +9,7 @@ import sys
 from typing import TYPE_CHECKING
 
 import typer
+import uvicorn
 
 if TYPE_CHECKING:
     from aury.boot.application.app.base import FoundationApp
@@ -416,7 +417,6 @@ def dev(
         os_module.environ["AURIMYTH_RELOAD"] = "1"
         
         # 热重载模式下，直接使用 uvicorn，传递 app 字符串路径
-        import uvicorn
         uvicorn.run(
             app=app_module_path,
             host=server_host,
@@ -500,19 +500,22 @@ def prod(
     typer.echo("   热重载: ❌")
     typer.echo("   调试模式: ❌")
     
+    # 获取 app 模块路径（多进程模式需要字符串格式）
+    app_module_path = app_path or _detect_app_module()
+    typer.echo(f"   应用模块: {app_module_path}")
+    
     try:
-        server = ApplicationServer(
-            app=app_instance,
+        # 多进程模式必须使用字符串路径，否则子进程无法重新加载应用
+        uvicorn.run(
+            app=app_module_path,
             host=server_host,
             port=server_port,
             workers=server_workers,
             reload=False,
             loop="auto",
             http="auto",
-            debug=False,
             access_log=True,
         )
-        server.run()
     except KeyboardInterrupt:
         typer.echo("\n👋 服务器已停止")
     except Exception as e:

aury/boot/commands/templates/project/AGENTS.md.tpl

@@ -169,7 +169,7 @@ class BaseConfig(BaseSettings):
     )
 ```
 
-**环境变量命名规则**：`{SECTION}__{FIELD}`
+**环境变量命名规则**：`{{SECTION}}__{{FIELD}}`
 
 ```bash
 # 示例

aury/boot/commands/templates/project/aury_docs/14-mq.md.tpl

@@ -1,6 +1,6 @@
 # 消息队列（MQ）
 
-支持 `redis` 和 `rabbitmq` 后端的消息队列，用于异步任务解耦。
+支持 `redis`、`redis_stream` 和 `rabbitmq` 后端的消息队列，用于异步任务解耦。
 
 ## 14.1 基本用法
 
@@ -10,93 +10,143 @@ from aury.boot.infrastructure.mq import MQManager
 # 获取实例
 mq = MQManager.get_instance()
 
-# Redis 后端
+# Redis List 后端（简单队列）
 await mq.initialize(backend="redis", url="redis://localhost:6379/0")
 
+# Redis Stream 后端（推荐，支持消费者组）
+await mq.initialize(backend="redis_stream", url="redis://localhost:6379/0")
+
 # RabbitMQ 后端
 await mq.initialize(backend="rabbitmq", url="amqp://guest:guest@localhost:5672/")
 ```
 
-## 14.2 生产者
+## 14.2 后端对比
+
+**Redis List (redis)**:
+- 简单的 FIFO 队列（LPUSH/BRPOP）
+- 适合单消费者场景
+- 消息不持久化（除非开启 AOF）
+
+**Redis Stream (redis_stream)** ⭐ 推荐:
+- 支持消费者组，多实例可并行消费
+- 消息持久化（配合 AOF）
+- 支持消息确认（ACK）和重试
+- 支持消息回放和历史查询
+
+**RabbitMQ (rabbitmq)**:
+- 功能最完整的消息队列
+- 支持多种交换机类型
+- 适合复杂的消息路由场景
+
+## 14.3 生产者
 
 ```python
+from aury.boot.infrastructure.mq import MQMessage
+
 # 发送消息
-await mq.publish(
+await mq.send(
     queue="orders",
     message={{"order_id": "123", "action": "created"}}
 )
 
-# 批量发送
-await mq.publish_batch(
-    queue="orders",
-    messages=[
-        {{"order_id": "1", "action": "created"}},
-        {{"order_id": "2", "action": "updated"}},
-    ]
+# 使用 MQMessage 对象（可设置 headers）
+msg = MQMessage(
+    body={{"order_id": "123"}},
+    headers={{"priority": "high"}}
 )
+await mq.send("orders", msg)
 ```
 
-## 14.3 消费者
+## 14.4 消费者
 
 **文件**: `{package_name}/workers/order_worker.py`
 
 ```python
-from aury.boot.infrastructure.mq import MQManager
+from aury.boot.infrastructure.mq import MQManager, MQMessage
 from aury.boot.common.logging import logger
 
 mq = MQManager.get_instance()
 
 
-async def process_order(message: dict):
+async def process_order(message: MQMessage):
     \"\"\"处理订单消息。\"\"\"
-    logger.info(f"处理订单: {{message['order_id']}}")
+    logger.info(f"处理订单: {{message.body}}")
     # 业务逻辑...
 
 
 async def start_consumer():
     \"\"\"启动消费者。\"\"\"
+    # consume 会自动处理 ACK/NACK
     await mq.consume("orders", process_order)
+```
+
+## 14.5 Redis Stream 特性
 
+```python
+from aury.boot.infrastructure.mq.backends.redis_stream import RedisStreamMQ
+
+# 初始化时指定消费者组
+mq = MQManager.get_instance()
+await mq.initialize(
+    backend="redis_stream",
+    url="redis://localhost:6379/0"
+)
+
+# 获取底层 RedisStreamMQ 实例使用高级特性
+stream_mq: RedisStreamMQ = mq.backend
 
-# 带确认的消费
-async def process_with_ack(message: dict, ack, nack):
-    try:
-        await process_order(message)
-        await ack()
-    except Exception:
-        await nack(requeue=True)
+# 读取所有历史消息（用于重放）
+messages = await stream_mq.read_all("orders", count=100)
 
-await mq.consume("orders", process_with_ack, auto_ack=False)
+# 阻塞读取新消息（用于 SSE/实时推送）
+messages = await stream_mq.read_blocking(
+    "orders",
+    last_id="$",  # 从最新消息开始
+    count=10,
+    block_ms=5000  # 阻塞 5 秒
+)
+
+# 裁剪 Stream（保留最新 1000 条）
+await stream_mq.trim("orders", maxlen=1000)
+
+# 获取 Stream 信息
+info = await stream_mq.stream_info("orders")
 ```
 
-## 14.4 多实例
+## 14.6 多实例配置
+
+框架支持命名多实例，适合不同业务场景使用不同的 MQ：
 
 ```python
-# 不同用途的 MQ 实例
+# 代码中使用命名实例
 orders_mq = MQManager.get_instance("orders")
 notifications_mq = MQManager.get_instance("notifications")
 
 # 分别初始化
-await orders_mq.initialize(backend="rabbitmq", url="amqp://localhost:5672/orders")
-await notifications_mq.initialize(backend="redis", url="redis://localhost:6379/5")
+await orders_mq.initialize(backend="redis_stream", url="redis://localhost:6379/1")
+await notifications_mq.initialize(backend="redis", url="redis://localhost:6379/2")
 ```
 
-## 14.5 环境变量
+**环境变量配置**（自动初始化）:
 
 ```bash
-# 默认实例
-MQ__BACKEND=redis
+# 单实例配置
+MQ__BACKEND=redis_stream
 MQ__URL=redis://localhost:6379/0
 
-# 多实例（格式：MQ__{{INSTANCE}}__{{FIELD}}）
-MQ__DEFAULT__BACKEND=redis
+# 多实例配置（格式：MQ__{{INSTANCE}}__{{FIELD}}）
+MQ__DEFAULT__BACKEND=redis_stream
 MQ__DEFAULT__URL=redis://localhost:6379/4
 MQ__ORDERS__BACKEND=rabbitmq
 MQ__ORDERS__URL=amqp://guest:guest@localhost:5672/
-MQ__ORDERS__PREFETCH_COUNT=10
 ```
 
-## 14.6 与异步任务（Dramatiq）的区别
+## 14.7 与异步任务（Dramatiq）的区别
+
+- **MQ**：轻量级消息传递，适合简单的生产者-消费者模式、实时通知、多实例消费
+- **Dramatiq（TaskManager）**：功能更丰富，支持重试、延迟、优先级、Actor 模式
 
-- **MQ**：轻量级消息传递，适合简单的生产者-消费者模式
-- **Dramatiq（TaskManager）**：功能更丰富，支持重试、延迟、优先级等
+选择建议：
+- 简单的异步解耦 → MQ (redis_stream)
+- 需要重试/延迟/优先级 → Dramatiq
+- 多服务实例并行消费 → MQ (redis_stream) 或 RabbitMQ

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

@@ -19,19 +19,27 @@
 # =============================================================================
 # 消息队列配置 (MQ__)
 # =============================================================================
+# 支持后端: redis | redis_stream (推荐) | rabbitmq
+#
 # 单实例配置:
-# MQ__ENABLED=false
-# MQ__BROKER_URL=redis://localhost:6379/4
-
+# MQ__BACKEND=redis_stream
+# MQ__URL=redis://localhost:6379/4
+#
 # 多实例配置 (格式: MQ__{{INSTANCE}}__{{FIELD}}):
-# MQ__DEFAULT__BACKEND=redis
+# MQ__DEFAULT__BACKEND=redis_stream
 # MQ__DEFAULT__URL=redis://localhost:6379/4
-# MQ__DEFAULT__MAX_CONNECTIONS=10
 #
-# RabbitMQ 后端:
+# Redis List 后端 (简单 FIFO 队列):
+# MQ__SIMPLE__BACKEND=redis
+# MQ__SIMPLE__URL=redis://localhost:6379/4
+#
+# Redis Stream 后端 (推荐，支持消费者组/多实例消费):
+# MQ__TASKS__BACKEND=redis_stream
+# MQ__TASKS__URL=redis://localhost:6379/4
+#
+# RabbitMQ 后端 (复杂消息路由):
 # MQ__ORDERS__BACKEND=rabbitmq
 # MQ__ORDERS__URL=amqp://guest:guest@localhost:5672/orders
-# MQ__ORDERS__PREFETCH_COUNT=10
 
 # =============================================================================
 # 事件总线配置 (EVENT__)

aury/boot/infrastructure/monitoring/alerting/rules.py

@@ -107,14 +107,14 @@ class AlertRule:
         # 检查路径
         if self._path_regex:
             endpoint = event.metadata.get("endpoint", "")
-            if not self._path_regex.match(endpoint):
+            if not self._path_regex.fullmatch(endpoint):
                 return False
         
         # 检查排除路径
         if self._exclude_regexes:
             endpoint = event.metadata.get("endpoint", "")
             for exclude_regex in self._exclude_regexes:
-                if exclude_regex.match(endpoint):
+                if exclude_regex.fullmatch(endpoint):
                     return False  # 匹配到排除规则，不触发告警
         
         # 检查阈值（对于 slow_* 类型）

aury/boot/infrastructure/monitoring/tracing/processor.py

@@ -181,7 +181,23 @@ class AlertingSpanProcessor:
             or name
         )
         
-        return any(regex.match(path) for regex in self._exclude_regexes)
+        # 检查所有可能的路径来源
+        paths_to_check = [path]
+        
+        # 也检查 span name 中的路径（可能包含 HTTP 方法和后缀）
+        # 例如 "GET /api/v1/spaces/{space_id}/subscribe http receive"
+        if name and name != path:
+            # 尝试提取 span name 中的路径部分
+            parts = name.split()
+            for part in parts:
+                if part.startswith("/"):
+                    paths_to_check.append(part)
+        
+        for p in paths_to_check:
+            if any(regex.fullmatch(p) for regex in self._exclude_regexes):
+                return True
+        
+        return False
     
     def _emit_slow_alert(
         self,

aury/boot/infrastructure/mq/backends/__init__.py

@@ -2,8 +2,10 @@
 
 from .rabbitmq import RabbitMQ
 from .redis import RedisMQ
+from .redis_stream import RedisStreamMQ
 
 __all__ = [
     "RabbitMQ",
     "RedisMQ",
+    "RedisStreamMQ",
 ]

aury/boot/infrastructure/mq/backends/redis_stream.py

@@ -0,0 +1,428 @@
+"""Redis Stream 消息队列后端。
+
+使用 Redis Stream 实现支持消费者组的消息队列。
+相比 Redis List，提供更强的持久化和消费保证。
+"""
+
+from __future__ import annotations
+
+import asyncio
+from collections.abc import Callable
+import json
+from typing import TYPE_CHECKING, Any
+
+from aury.boot.common.logging import logger
+
+from ..base import IMQ, MQMessage
+
+if TYPE_CHECKING:
+    from aury.boot.infrastructure.clients.redis import RedisClient
+
+
+class RedisStreamMQ(IMQ):
+    """Redis Stream 消息队列实现。
+
+    使用 Redis Stream (XADD/XREADGROUP/XACK) 实现可靠的消息队列。
+    
+    特性:
+    - 消费者组支持多实例消费
+    - 消息持久化 (配合 AOF)
+    - 消息确认机制
+    - 支持消息重放
+    """
+
+    def __init__(
+        self,
+        url: str | None = None,
+        *,
+        redis_client: RedisClient | None = None,
+        prefix: str = "stream:",
+        consumer_group: str = "default",
+        consumer_name: str | None = None,
+        max_len: int | None = None,
+    ) -> None:
+        """初始化 Redis Stream 消息队列。
+
+        Args:
+            url: Redis 连接 URL（当 redis_client 为 None 时必须提供）
+            redis_client: RedisClient 实例（可选，优先使用）
+            prefix: 队列名称前缀
+            consumer_group: 消费者组名称
+            consumer_name: 消费者名称（默认自动生成）
+            max_len: Stream 最大长度（可选，用于自动裁剪）
+        
+        Raises:
+            ValueError: 当 url 和 redis_client 都为 None 时
+        """
+        if redis_client is None and url is None:
+            raise ValueError("Redis Stream 消息队列需要提供 url 或 redis_client 参数")
+        
+        self._url = url
+        self._client = redis_client
+        self._prefix = prefix
+        self._consumer_group = consumer_group
+        self._consumer_name = consumer_name or f"consumer-{id(self)}"
+        self._max_len = max_len
+        self._consuming = False
+        self._owns_client = False
+    
+    async def _ensure_client(self) -> None:
+        """确保 Redis 客户端已初始化。"""
+        if self._client is None and self._url:
+            from aury.boot.infrastructure.clients.redis import RedisClient
+            # 创建独立实例（不使用 get_instance 避免和全局实例冲突）
+            self._client = RedisClient(name=f"mq-{id(self)}")
+            self._client.configure(url=self._url)
+            await self._client.initialize()
+            self._owns_client = True
+
+    def _stream_key(self, queue: str) -> str:
+        """获取 Stream 的 Redis key。"""
+        return f"{self._prefix}{queue}"
+
+    async def _ensure_group(self, queue: str) -> None:
+        """确保消费者组存在。"""
+        stream_key = self._stream_key(queue)
+        try:
+            await self._client.connection.xgroup_create(
+                stream_key,
+                self._consumer_group,
+                id="0",
+                mkstream=True,
+            )
+            logger.debug(f"创建消费者组: {self._consumer_group} on {stream_key}")
+        except Exception as e:
+            # 组已存在，忽略
+            if "BUSYGROUP" not in str(e):
+                raise
+
+    async def send(self, queue: str, message: MQMessage) -> str:
+        """发送消息到 Stream。
+        
+        使用 XADD 命令，支持 MAXLEN 自动裁剪。
+        """
+        await self._ensure_client()
+        message.queue = queue
+        
+        # 序列化消息
+        data = {
+            "payload": json.dumps(message.to_dict()),
+        }
+        
+        stream_key = self._stream_key(queue)
+        
+        # XADD with optional MAXLEN
+        if self._max_len:
+            msg_id = await self._client.connection.xadd(
+                stream_key,
+                data,
+                maxlen=self._max_len,
+                approximate=True,  # ~ 近似裁剪，性能更好
+            )
+        else:
+            msg_id = await self._client.connection.xadd(stream_key, data)
+        
+        logger.debug(f"发送消息到 Stream: {stream_key}, id={msg_id}")
+        return message.id
+
+    async def receive(
+        self,
+        queue: str,
+        timeout: float | None = None,
+    ) -> MQMessage | None:
+        """从 Stream 接收消息（不使用消费者组）。
+        
+        用于简单场景，直接 XREAD 读取最新消息。
+        """
+        await self._ensure_client()
+        
+        stream_key = self._stream_key(queue)
+        timeout_ms = int(timeout * 1000) if timeout else 0
+        
+        result = await self._client.connection.xread(
+            streams={stream_key: "$"},
+            count=1,
+            block=timeout_ms,
+        )
+        
+        if not result:
+            return None
+        
+        # 解析结果: [[stream_key, [(msg_id, data)]]]
+        for stream, messages in result:
+            for msg_id, data in messages:
+                try:
+                    payload = data.get(b"payload") or data.get("payload")
+                    if isinstance(payload, bytes):
+                        payload = payload.decode()
+                    msg_dict = json.loads(payload)
+                    message = MQMessage.from_dict(msg_dict)
+                    message._stream_id = msg_id  # 保存 stream ID 用于 ACK
+                    return message
+                except (json.JSONDecodeError, KeyError) as e:
+                    logger.error(f"解析消息失败: {e}")
+                    return None
+        
+        return None
+
+    async def receive_group(
+        self,
+        queue: str,
+        timeout: float | None = None,
+    ) -> MQMessage | None:
+        """从 Stream 接收消息（使用消费者组）。
+        
+        使用 XREADGROUP 从消费者组读取，支持多实例消费。
+        """
+        await self._ensure_client()
+        await self._ensure_group(queue)
+        
+        stream_key = self._stream_key(queue)
+        timeout_ms = int(timeout * 1000) if timeout else 0
+        
+        result = await self._client.connection.xreadgroup(
+            groupname=self._consumer_group,
+            consumername=self._consumer_name,
+            streams={stream_key: ">"},  # > 表示只读取新消息
+            count=1,
+            block=timeout_ms,
+        )
+        
+        if not result:
+            return None
+        
+        # 解析结果
+        for stream, messages in result:
+            for msg_id, data in messages:
+                try:
+                    payload = data.get(b"payload") or data.get("payload")
+                    if isinstance(payload, bytes):
+                        payload = payload.decode()
+                    msg_dict = json.loads(payload)
+                    message = MQMessage.from_dict(msg_dict)
+                    message._stream_id = msg_id  # 保存用于 ACK
+                    message.queue = queue
+                    return message
+                except (json.JSONDecodeError, KeyError) as e:
+                    logger.error(f"解析消息失败: {e}")
+                    # ACK 损坏的消息，防止阻塞
+                    await self._client.connection.xack(
+                        stream_key, self._consumer_group, msg_id
+                    )
+                    return None
+        
+        return None
+
+    async def ack(self, message: MQMessage) -> None:
+        """确认消息已处理。"""
+        if not message.queue:
+            return
+        
+        stream_id = getattr(message, "_stream_id", None)
+        if stream_id:
+            stream_key = self._stream_key(message.queue)
+            await self._client.connection.xack(
+                stream_key, self._consumer_group, stream_id
+            )
+            logger.debug(f"ACK 消息: {stream_id}")
+
+    async def nack(self, message: MQMessage, requeue: bool = True) -> None:
+        """拒绝消息。
+        
+        Redis Stream 没有原生 NACK，通过重新发送实现。
+        """
+        if not message.queue:
+            return
+        
+        stream_id = getattr(message, "_stream_id", None)
+        if stream_id:
+            stream_key = self._stream_key(message.queue)
+            # 先 ACK 原消息
+            await self._client.connection.xack(
+                stream_key, self._consumer_group, stream_id
+            )
+            
+            if requeue and message.retry_count < message.max_retries:
+                # 重新发送
+                message.retry_count += 1
+                await self.send(message.queue, message)
+                logger.debug(f"NACK 重新入队: {message.id}, retry={message.retry_count}")
+
+    async def consume(
+        self,
+        queue: str,
+        handler: Callable[[MQMessage], Any],
+        *,
+        prefetch: int = 1,
+    ) -> None:
+        """消费队列消息（使用消费者组）。"""
+        self._consuming = True
+        await self._ensure_group(queue)
+        logger.info(f"开始消费 Stream: {queue}, group={self._consumer_group}")
+
+        while self._consuming:
+            try:
+                message = await self.receive_group(queue, timeout=1.0)
+                if message is None:
+                    continue
+
+                try:
+                    result = handler(message)
+                    if asyncio.iscoroutine(result):
+                        await result
+                    await self.ack(message)
+                except Exception as e:
+                    logger.error(f"处理消息失败: {e}")
+                    await self.nack(message, requeue=True)
+
+            except Exception as e:
+                logger.error(f"消费消息异常: {e}")
+                await asyncio.sleep(1)
+
+    async def read_all(
+        self,
+        queue: str,
+        start: str = "-",
+        end: str = "+",
+        count: int | None = None,
+    ) -> list[MQMessage]:
+        """读取 Stream 中的所有消息（用于 compaction）。
+        
+        使用 XRANGE 读取指定范围的消息。
+        
+        Args:
+            queue: 队列名称
+            start: 起始 ID（"-" 表示最早）
+            end: 结束 ID（"+" 表示最新）
+            count: 最大数量
+            
+        Returns:
+            消息列表
+        """
+        await self._ensure_client()
+        stream_key = self._stream_key(queue)
+        
+        result = await self._client.connection.xrange(
+            stream_key,
+            min=start,
+            max=end,
+            count=count,
+        )
+        
+        messages = []
+        for msg_id, data in result:
+            try:
+                payload = data.get(b"payload") or data.get("payload")
+                if isinstance(payload, bytes):
+                    payload = payload.decode()
+                msg_dict = json.loads(payload)
+                message = MQMessage.from_dict(msg_dict)
+                message._stream_id = msg_id
+                messages.append(message)
+            except (json.JSONDecodeError, KeyError) as e:
+                logger.warning(f"跳过损坏的消息 {msg_id}: {e}")
+        
+        return messages
+
+    async def read_blocking(
+        self,
+        queue: str,
+        last_id: str = "$",
+        count: int = 10,
+        block_ms: int = 100,
+    ) -> list[MQMessage]:
+        """阻塞读取 Stream 中的新消息（使用 XREAD BLOCK）。
+        
+        Args:
+            queue: 队列名称
+            last_id: 起始 ID（"$" 表示只等待新消息，"0" 表示从开头）
+            count: 最大读取数量
+            block_ms: 阻塞等待超时（毫秒），0 表示不阻塞
+            
+        Returns:
+            消息列表
+        """
+        await self._ensure_client()
+        stream_key = self._stream_key(queue)
+        
+        result = await self._client.connection.xread(
+            streams={stream_key: last_id},
+            count=count,
+            block=block_ms,
+        )
+        
+        if not result:
+            return []
+        
+        messages = []
+        for stream, stream_messages in result:
+            for msg_id, data in stream_messages:
+                try:
+                    payload = data.get(b"payload") or data.get("payload")
+                    if isinstance(payload, bytes):
+                        payload = payload.decode()
+                    msg_dict = json.loads(payload)
+                    message = MQMessage.from_dict(msg_dict)
+                    message._stream_id = msg_id
+                    messages.append(message)
+                except (json.JSONDecodeError, KeyError) as e:
+                    logger.warning(f"跳过损坏的消息 {msg_id}: {e}")
+        
+        return messages
+
+    async def trim(
+        self,
+        queue: str,
+        *,
+        maxlen: int | None = None,
+        minid: str | None = None,
+    ) -> int:
+        """裁剪 Stream。
+        
+        Args:
+            queue: 队列名称
+            maxlen: 保留的最大长度
+            minid: 保留此 ID 之后的消息
+            
+        Returns:
+            删除的消息数量
+        """
+        await self._ensure_client()
+        stream_key = self._stream_key(queue)
+        
+        if minid:
+            return await self._client.connection.xtrim(
+                stream_key, minid=minid, approximate=False
+            )
+        elif maxlen is not None:
+            # maxlen=0 也应该生效（清空 stream）
+            return await self._client.connection.xtrim(
+                stream_key, maxlen=maxlen, approximate=False
+            )
+        return 0
+
+    async def delete_stream(self, queue: str) -> bool:
+        """删除整个 Stream。"""
+        await self._ensure_client()
+        stream_key = self._stream_key(queue)
+        return await self._client.connection.delete(stream_key) > 0
+
+    async def stream_info(self, queue: str) -> dict[str, Any]:
+        """获取 Stream 信息。"""
+        await self._ensure_client()
+        stream_key = self._stream_key(queue)
+        try:
+            return await self._client.connection.xinfo_stream(stream_key)
+        except Exception:
+            return {}
+
+    async def close(self) -> None:
+        """关闭连接。"""
+        self._consuming = False
+        if self._owns_client and self._client:
+            await self._client.close()
+            self._client = None
+        logger.debug("Redis Stream 消息队列已关闭")
+
+
+__all__ = ["RedisStreamMQ"]

aury/boot/infrastructure/mq/base.py

@@ -18,6 +18,7 @@ class MQBackend(Enum):
     """消息队列后端类型。"""
 
     REDIS = "redis"
+    REDIS_STREAM = "redis_stream"
     RABBITMQ = "rabbitmq"
 
 

aury/boot/infrastructure/mq/manager.py

@@ -12,6 +12,7 @@ from aury.boot.common.logging import logger
 
 from .backends.rabbitmq import RabbitMQ
 from .backends.redis import RedisMQ
+from .backends.redis_stream import RedisStreamMQ
 from .base import IMQ, MQBackend, MQMessage
 
 if TYPE_CHECKING:
@@ -127,6 +128,8 @@ class MQManager:
         # 根据后端类型创建实例，参数校验由后端自己处理
         if backend == MQBackend.REDIS:
             self._backend = RedisMQ(url=url, redis_client=redis_client, prefix=prefix)
+        elif backend == MQBackend.REDIS_STREAM:
+            self._backend = RedisStreamMQ(url=url, redis_client=redis_client, prefix=prefix)
         elif backend == MQBackend.RABBITMQ:
             self._backend = RabbitMQ(url=url)
         else:

{aury_boot-0.0.35.dist-info → aury_boot-0.0.37.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: aury-boot
-Version: 0.0.35
+Version: 0.0.37
 Summary: Aury Boot - 基于 FastAPI 生态的企业级 API 开发框架
 Requires-Python: >=3.13
 Requires-Dist: alembic>=1.17.2

{aury_boot-0.0.35.dist-info → aury_boot-0.0.37.dist-info}/RECORD

@@ -1,5 +1,5 @@
 aury/boot/__init__.py,sha256=pCno-EInnpIBa1OtxNYF-JWf9j95Cd2h6vmu0xqa_-4,1791
-aury/boot/_version.py,sha256=w77E3DIE0tp22UaCyYn9461JfWMpEPhsv91t-4n4Bjw,706
+aury/boot/_version.py,sha256=BV1Ma7idHU0hCvzfaqU-vGA4N-4x9mQtKafasKpzadA,706
 aury/boot/application/__init__.py,sha256=I2KqNVdYg2q5nlOXr0TtFGyHmhj4oWdaR6ZB73Mwg7Y,3041
 aury/boot/application/adapter/__init__.py,sha256=e1bcSb1bxUMfofTwiCuHBZJk5-STkMCWPF2EJXHQ7UU,3976
 aury/boot/application/adapter/base.py,sha256=Ar_66fiHPDEmV-1DKnqXKwc53p3pozG31bgTJTEUriY,15763
@@ -14,7 +14,7 @@ aury/boot/application/app/middlewares.py,sha256=BXe2H14FHzJUVpQM6DZUm-zfZRXSXIi1
 aury/boot/application/app/startup.py,sha256=DHKt3C2G7V5XfFr1SQMl14tNzcuDd9MqUVAxi274HDQ,7873
 aury/boot/application/config/__init__.py,sha256=Dd-myRSBCM18DXXsi863h0cJG5VFrI10xMRtjnvelGo,1894
 aury/boot/application/config/multi_instance.py,sha256=RXSp-xP8-bKMDEhq3SeL7T3lS8-vpRlvBEVBuZVjVK4,6475
-aury/boot/application/config/settings.py,sha256=XGPoA8qFYxmnStmsboCBRHn1OAuniXCWzH7jAtrq4ho,37517
+aury/boot/application/config/settings.py,sha256=JZuLVKH13cuBdlHdtrt7ZZ4d7KD8as5DWBv0d9enHDk,38026
 aury/boot/application/constants/__init__.py,sha256=DCXs13_VVaQWHqO-qpJoZwRd7HIexiirtw_nu8msTXE,340
 aury/boot/application/constants/components.py,sha256=I4SlsF2DpSzMiLsi1wVrEmdHn4yV5J2h3ikMQqufPmM,1120
 aury/boot/application/constants/scheduler.py,sha256=S77FBIvHlyruvlabRWZJ2J1YAs2xWXPQI2yuGdGUDNA,471
@@ -47,7 +47,7 @@ aury/boot/commands/config.py,sha256=gPkG_jSWrXidjpyVdzABH7uRhoCgX5yrOcdKabtX5wY,
 aury/boot/commands/docker.py,sha256=7mKorZCPZgxH1XFslzo6W-uzpe61hGXz86JKOhOeBlo,9006
 aury/boot/commands/docs.py,sha256=Hz1W-2TW8DzaPxARqEF4UncPhGMI9h97jJ962dlox3U,14327
 aury/boot/commands/generate.py,sha256=WZieSXuofxJOC7NBiVGpBigB9NZ4GMcF2F1ReTNun1I,44420
-aury/boot/commands/init.py,sha256=W_eCL3wydWaMSLqTpadREDnzC0w-LGgNnj3IBjuQAfA,32348
+aury/boot/commands/init.py,sha256=6reBpZ5jS4O9QTfXHKt4MCXPn3WcubjUfOtB5tKdy0s,32349
 aury/boot/commands/pkg.py,sha256=bw0QPptKscNgQ4I1SfSehTio9Q5KrvxgvkYx4tbZ7Vs,14495
 aury/boot/commands/scheduler.py,sha256=XO3Gq7PqNxXNz5Gw0xNUHa_bEnAKZ9AkzLc062QJ3j8,3669
 aury/boot/commands/worker.py,sha256=OEvfDiiM_pV3Mj73HKhSm1RNqFPuS125iNM0qNCTHFY,4316
@@ -55,13 +55,13 @@ aury/boot/commands/migrate/__init__.py,sha256=W9OhkX8ILdolySofgdP2oYoJGG9loQd5Fe
 aury/boot/commands/migrate/app.py,sha256=phCMKW6cuFYW2wr6PSMSCq0K2uUCiYo3UiFd0_UvA_o,1327
 aury/boot/commands/migrate/commands.py,sha256=892htS_pTtpejLGqRP8bc3xXJPG92WwAejHlY74oI3o,9950
 aury/boot/commands/server/__init__.py,sha256=aP3bPNGn6wT8dHa_OmKw1Dexnxuvf0BhrGA6pEUcsVM,319
-aury/boot/commands/server/app.py,sha256=-A52dLgerab98IM50a-_ptFb0xlMvbdbhYjqoJIIIpU,15795
+aury/boot/commands/server/app.py,sha256=9QQs7PHOw-CBxm9-soccB5v-mElO3G4-WZDWJQebpp0,16010
 aury/boot/commands/templates/generate/api.py.tpl,sha256=xTbk9uzn5IMtJ-SPMadjmOUNHoM3WoE6g-TIEsGHFUA,3153
 aury/boot/commands/templates/generate/model.py.tpl,sha256=knFwMyGZ7wMpzH4_bQD_V1hFTvmCb2H04G8p3s2xvyA,312
 aury/boot/commands/templates/generate/repository.py.tpl,sha256=Uj9jNEI9Zn8W061FGFlRaIfAy9IhdassYH6noEjG0z0,662
 aury/boot/commands/templates/generate/schema.py.tpl,sha256=HIaY5B0UG_S188nQLrZDEJ0q73WPdb7BmCdc0tseZA4,545
 aury/boot/commands/templates/generate/service.py.tpl,sha256=2hwQ8e4a5d_bIMx_jGDobdmKPMFLBlfQrQVQH4Ym5k4,1842
-aury/boot/commands/templates/project/AGENTS.md.tpl,sha256=sp5qyzU-SGhgQCobpMW4EXRzpGsEsVdmJvspnKAP4AQ,10059
+aury/boot/commands/templates/project/AGENTS.md.tpl,sha256=KdCqZJeI6cRwjTxX0B2u9fcGQKUi2fJrIjTJBkm3c4U,10063
 aury/boot/commands/templates/project/README.md.tpl,sha256=oCeBiukk6Pa3hrCKybkfM2sIRHsPZ15nlwuFTUSFDwY,2459
 aury/boot/commands/templates/project/admin_console_init.py.tpl,sha256=K81L14thyEhRA8lFCQJVZL_NU22-sBz0xS68MJPeoCo,1541
 aury/boot/commands/templates/project/alert_rules.example.yaml.tpl,sha256=QZH6SC5TcUhgX_2JRXk0k0g26wJf9xNwsdquiEIgg-I,2492
@@ -83,7 +83,7 @@ aury/boot/commands/templates/project/aury_docs/10-storage.md.tpl,sha256=mhe0j0S5
 aury/boot/commands/templates/project/aury_docs/11-logging.md.tpl,sha256=bwxFCGQsO9cTEbwqJF1xcjsZKP82HRWhIMRUS0c9_ZI,2435
 aury/boot/commands/templates/project/aury_docs/12-admin.md.tpl,sha256=6z3mN54qP2jtpTFOJBLVexvEv0ZHXYKjncvpZG4yOdw,1883
 aury/boot/commands/templates/project/aury_docs/13-channel.md.tpl,sha256=aGpf2phQBMRs6Uh1DfjNl06pC_niea91Sm8sTq_NFec,4443
-aury/boot/commands/templates/project/aury_docs/14-mq.md.tpl,sha256=4bxLQBbCi0Fue0VQWOPt6acZ5P00BoLkCoLPQe_8k4U,2396
+aury/boot/commands/templates/project/aury_docs/14-mq.md.tpl,sha256=irrKal6y8pPAjifntnOLfRzzllvBQinKMjIjKd-_ANc,4016
 aury/boot/commands/templates/project/aury_docs/15-events.md.tpl,sha256=a4wQRgVPuYUGTGmw_lX1HJH_yFTbD30mBz7Arc4zgfs,3361
 aury/boot/commands/templates/project/aury_docs/16-adapter.md.tpl,sha256=pkmJkZw2Ca6_uYk2jZvAb8DozjBa2tWq_t3gtq1lFSk,11456
 aury/boot/commands/templates/project/aury_docs/17-alerting.md.tpl,sha256=2MosApSAuGerBw7SOO-ihk4NTp2qEkgOUyu6pS2m0UY,5709
@@ -93,7 +93,7 @@ aury/boot/commands/templates/project/env_templates/admin.tpl,sha256=wWt3iybOpBHt
 aury/boot/commands/templates/project/env_templates/cache.tpl,sha256=_sK-p_FECj4mVvggNvgb4Wu0yGii0Ocz560syG7DU2c,498
 aury/boot/commands/templates/project/env_templates/database.tpl,sha256=2lWzTKt4X0SpeBBCkrDV90Di4EfoAuqYzhVsh74vTUI,907
 aury/boot/commands/templates/project/env_templates/log.tpl,sha256=x5rkrEFJISH0gaCcr-wTCbDYtyFnlLNJpY789fqjZgc,754
-aury/boot/commands/templates/project/env_templates/messaging.tpl,sha256=SzPRKwN0wO5e1kpjkSwpPJfVmiUDzZkK4Qm-qNsCvVE,2178
+aury/boot/commands/templates/project/env_templates/messaging.tpl,sha256=AgfsXTRnvDySFERoCVop89jsC_h8hzj1sPeq5MczSXM,2462
 aury/boot/commands/templates/project/env_templates/monitoring.tpl,sha256=Zq0xQzDrCRtbeLCQB3pkEE2p8FFED6IjQo4TqMyd_P8,2584
 aury/boot/commands/templates/project/env_templates/rpc.tpl,sha256=FhweCFakawGLSs01a_BkmZo11UhWax2-VCBudHj68WA,1163
 aury/boot/commands/templates/project/env_templates/scheduler.tpl,sha256=c8Grcs1rgBB58RHlxqmDMPHQl8BnbcqNW473ctmsojU,752
@@ -173,7 +173,7 @@ aury/boot/infrastructure/monitoring/alerting/__init__.py,sha256=UvUsMhSZeGJOjZy0
 aury/boot/infrastructure/monitoring/alerting/aggregator.py,sha256=fiI-lBSqWxXv1eVPfaDNjcigX-81w41fcmhD_vN_XSs,5805
 aury/boot/infrastructure/monitoring/alerting/events.py,sha256=zJvTevQ-9JflIDyYVo1BRzOVyAGhdgEfRlMsD0NcBgM,4056
 aury/boot/infrastructure/monitoring/alerting/manager.py,sha256=vdWox9Pnjl_0IIE6w-Ne9R17IUrqtF9CPhZHwZvke6E,16044
-aury/boot/infrastructure/monitoring/alerting/rules.py,sha256=XcXJXWVrPpdZKKz63BiVWmwkKitIaNQWBfJATrSzG1M,6116
+aury/boot/infrastructure/monitoring/alerting/rules.py,sha256=FdyGOolQJF31fN_9mqRGi9i_x2JqtoHEOkNOcPyO07o,6124
 aury/boot/infrastructure/monitoring/alerting/notifiers/__init__.py,sha256=dsfxThPHO_Ofb3Wo_dYlL8HvP_N63pb_S_UXm_qSxF8,321
 aury/boot/infrastructure/monitoring/alerting/notifiers/base.py,sha256=_RXZMzWX-YeTG0Up1U8CwK8ADfX34dd0Sh56ugfqOWM,1462
 aury/boot/infrastructure/monitoring/alerting/notifiers/feishu.py,sha256=JAMJiCNRYoDeJrYn29ew_ZVXDGq8OLgiFApRWd4iPY0,7134
@@ -182,15 +182,16 @@ aury/boot/infrastructure/monitoring/health/__init__.py,sha256=nqwFFXl6J9yTfQa1JL
 aury/boot/infrastructure/monitoring/tracing/__init__.py,sha256=YizkpnhY-bcUUcd8YaDzUsluMflhNOH1dAKdVtkW05U,1287
 aury/boot/infrastructure/monitoring/tracing/context.py,sha256=s_k2MzNl4LDDpei9xUP6TFW5BwZneoQg44RPaw95jac,978
 aury/boot/infrastructure/monitoring/tracing/logging.py,sha256=gzuKa1ZiyY4z06fHNTbjgZasS6mLftSEaZQQ-Z6J_RE,2041
-aury/boot/infrastructure/monitoring/tracing/processor.py,sha256=qc37YmS8rslpwqAYHrBDzVvNWmXRIFEwpld34NMmByk,12640
+aury/boot/infrastructure/monitoring/tracing/processor.py,sha256=36hoiyQ25sk55k7D4vDAKXt7l9d4wCNkZMTpwlPwg_Y,13224
 aury/boot/infrastructure/monitoring/tracing/provider.py,sha256=AnPHUDHnfrCB48WHjp9vLBhCh9BpyfWb3DHGRh6Din4,11553
 aury/boot/infrastructure/monitoring/tracing/tracing.py,sha256=BeWL-FYtlQ05r05wGJ6qjTSpypgCp-7OzdNnZ3uunB0,6890
 aury/boot/infrastructure/mq/__init__.py,sha256=Q7kBk_GeQnxnqkyp29Bh1yFH3Q8xxxjs8oDYLeDj8C0,498
-aury/boot/infrastructure/mq/base.py,sha256=kHrWUysWflMj3qyOnioLZ90it8d9Alq1Wb4PYhpBW4k,3396
-aury/boot/infrastructure/mq/manager.py,sha256=DVXOQhoqx9dz9INajWiAxLnKjLaP-otKmdiBUzxgsAY,7502
-aury/boot/infrastructure/mq/backends/__init__.py,sha256=YRByNFWv0VFibslQR5v4h5XxfSX-HIveCfb6W1jXM54,139
+aury/boot/infrastructure/mq/base.py,sha256=ld4wtzhO_6y8wJRXL1DagqJiwhd0VQ6MJlJGDQoL6A8,3430
+aury/boot/infrastructure/mq/manager.py,sha256=Bu4E1Tgz0CzFvJuCS9_fBMj9eAqmXcZp8aFIYhvNUl4,7692
+aury/boot/infrastructure/mq/backends/__init__.py,sha256=10nggw2V-AzuZ1vvzq_ksoXR4FI3e4BR36EfY49Pek4,200
 aury/boot/infrastructure/mq/backends/rabbitmq.py,sha256=0NWgPKEwtbmI63EVvKINdfXXDNyOvuOOP9LlBzqH91E,5493
 aury/boot/infrastructure/mq/backends/redis.py,sha256=i8KECToIFEZ6CnHyNCk34_xdff5ioK172_knOy6EeUU,5279
+aury/boot/infrastructure/mq/backends/redis_stream.py,sha256=hbSX03d0BLshE10GryjyvqybtjDBOS4pQUsNHhQFB-Q,14420
 aury/boot/infrastructure/scheduler/__init__.py,sha256=eTRJ5dSPcKvyFvLVtraoQteXTTDDGwIrmw06J2hoNdA,323
 aury/boot/infrastructure/scheduler/exceptions.py,sha256=ROltrhSctVWA-6ulnjuYeHAk3ZF-sykDoesuierYzew,634
 aury/boot/infrastructure/scheduler/manager.py,sha256=OHQOHQlcoN8yFnky4kfuhsEIk39qX6nLZ7xJ51tfg68,23130
@@ -209,7 +210,7 @@ aury/boot/testing/client.py,sha256=KOg1EemuIVsBG68G5y0DjSxZGcIQVdWQ4ASaHE3o1R0,4
 aury/boot/testing/factory.py,sha256=8GvwX9qIDu0L65gzJMlrWB0xbmJ-7zPHuwk3eECULcg,5185
 aury/boot/toolkit/__init__.py,sha256=AcyVb9fDf3CaEmJPNkWC4iGv32qCPyk4BuFKSuNiJRQ,334
 aury/boot/toolkit/http/__init__.py,sha256=zIPmpIZ9Qbqe25VmEr7jixoY2fkRbLm7NkCB9vKpg6I,11039
-aury_boot-0.0.35.dist-info/METADATA,sha256=fyQTvIB-zPVWMQblf2xQC-bPoTyALLCe5Snkc9WG1fA,8694
-aury_boot-0.0.35.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-aury_boot-0.0.35.dist-info/entry_points.txt,sha256=f9KXEkDIGc0BGkgBvsNx_HMz9VhDjNxu26q00jUpDwQ,49
-aury_boot-0.0.35.dist-info/RECORD,,
+aury_boot-0.0.37.dist-info/METADATA,sha256=8Kgz7a5fhou-Ki53QzjfwAfv68cE8iu83UWQ8aR6BOI,8694
+aury_boot-0.0.37.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+aury_boot-0.0.37.dist-info/entry_points.txt,sha256=f9KXEkDIGc0BGkgBvsNx_HMz9VhDjNxu26q00jUpDwQ,49
+aury_boot-0.0.37.dist-info/RECORD,,