cancan-microstack 0.0.1__py3-none-any.whl

cancan_microstack/public/const/error.py

@@ -0,0 +1,56 @@
+import http
+from enum import StrEnum
+
+
+class ErrorCode(StrEnum):
+    SUCCESS = "0"
+    INVALID_PARAM = "4000"
+    USER_UNLOGIN = "4001"
+    HANDLER_NOT_FOUND = "4004"
+    REGISTRATION_REJECTED = "4009"
+    SYSTEM_ERROR = "5000"
+    SERVICE_MANAGEMENT_ERROR = "5001"
+    MISSING_REQUIRED_PARAM = "4002"
+    NETWORK_ERROR = "5100"
+
+    @classmethod
+    def http_status_to_error_code(cls, http_status_code: int) -> str:
+        d = {
+            http.HTTPStatus.OK.value: cls.SUCCESS,
+            http.HTTPStatus.BAD_REQUEST.value: cls.INVALID_PARAM,
+            http.HTTPStatus.UNAUTHORIZED.value: cls.USER_UNLOGIN,
+            http.HTTPStatus.NOT_FOUND.value: cls.HANDLER_NOT_FOUND,
+            http.HTTPStatus.INTERNAL_SERVER_ERROR.value: cls.SYSTEM_ERROR,
+            http.HTTPStatus.GATEWAY_TIMEOUT.value: cls.NETWORK_ERROR,
+        }
+        return d.get(http_status_code, cls.SUCCESS)
+
+
+class ErrorMsg(StrEnum):
+    SUCCESS = "success"
+    COMMON_ERROR = "system error"
+    INVALID_PARAM = "params error"
+    USER_UNLOGIN = "user not login"
+    HANDLER_NOT_FOUND = "not found"
+    SERVICE_MANAGEMENT_ERROR = "service management operation failed"
+    MISSING_REQUIRED_PARAM = "missing required parameter"
+    NETWORK_ERROR = "network error"
+
+    @classmethod
+    def get_msg(cls, code: str | int) -> str:
+        if code is None or code == "":
+            return cls.SUCCESS
+        if isinstance(code, int):
+            code = str(code)
+        d = {
+            ErrorCode.SUCCESS: cls.COMMON_ERROR,
+            ErrorCode.INVALID_PARAM: cls.INVALID_PARAM,
+            ErrorCode.USER_UNLOGIN: cls.USER_UNLOGIN,
+            ErrorCode.HANDLER_NOT_FOUND: cls.HANDLER_NOT_FOUND,
+            ErrorCode.NETWORK_ERROR: cls.NETWORK_ERROR,
+        }
+        if code in d:
+            return d[code]
+        elif code.isdigit() and int(code) in http.HTTPStatus:
+            return http.HTTPStatus(int(code)).phrase
+        return cls.COMMON_ERROR

cancan_microstack/public/const/health_consts.py

@@ -0,0 +1,52 @@
+from enum import StrEnum
+
+
+class HealthCheckResult(StrEnum):
+    """
+    健康检查结果枚举
+    Enum for health check result values
+    """
+    PASS = "PASS"
+    FAIL = "FAIL"
+
+
+class HealthOverallStatus(StrEnum):
+    """
+    服务整体状态枚举
+    Enum for overall service status used in overviews
+    """
+    UP = "UP"
+    PARTIAL = "PARTIAL"
+    DOWN = "DOWN"
+
+
+# 更多健康状态，用于实例级别标记
+class InstanceHealthStatus(StrEnum):
+    UNKNOWN = "unknown"
+    HEALTHY = "healthy"
+    DEGRADED = "degraded"
+    UNHEALTHY = "unhealthy"
+    EXEMPTED = "exempted"
+    EXPECTED_STOPPED = "expected_stopped"
+
+
+class ServiceRuntimeStatus(StrEnum):
+    """
+    服务运行时状态（用于概览的 expected/actual）
+    Runtime service status for overview expected/actual fields
+    """
+
+    RUNNING = "running"
+    STOPPED = "stopped"
+    DEGRADED = "degraded"
+
+
+class ServiceExpectedStatusAlias(StrEnum):
+    """
+    期望状态别名（用于标准化输入）
+    Expected status aliases for normalization
+    """
+
+    STOP = "stop"
+    STOPPED = "stopped"
+    DOWN = "down"

cancan_microstack/public/const/hook_enums.py

@@ -0,0 +1,56 @@
+"""
+Hook-related enums.
+"""
+from enum import StrEnum, IntEnum
+
+
+class HookResult(StrEnum):
+    """钩子执行结果枚举"""
+    SUCCESS = "success"           # 成功
+    FAILURE = "failure"           # 失败
+    SKIP = "skip"                 # 跳过
+    RETRY = "retry"               # 重试
+    TERMINATE = "terminate"       # 终止
+
+
+class HookType(StrEnum):
+    """钩子类型枚举 / Hook type enum"""
+    PRE_REGISTER = "pre_register"           # 注册前钩子
+    POST_REGISTER = "post_register"         # 注册后钩子
+    PRE_DEREGISTER = "pre_deregister"       # 注销前钩子
+    POST_DEREGISTER = "post_deregister"     # 注销后钩子
+
+
+class HookPriority(IntEnum):
+    """钩子优先级枚举"""
+    HIGHEST = 0
+    HIGH = 25
+    MEDIUM = 50
+    NORMAL = 50
+    LOW = 75
+    LOWEST = 100
+
+
+class HookLogAction(StrEnum):
+    """
+    钩子日志行为类型枚举
+    Hook log action type enum
+    """
+    REGISTERED = "registered"                  # 钩子已注册
+    DEREGISTERED = "deregistered"              # 钩子已注销
+    EXECUTION_STARTED = "execution_started"    # 执行开始
+    EXECUTION_SUCCESS = "execution_success"    # 执行成功
+    EXECUTION_FAILURE = "execution_failure"    # 执行失败
+    REJECTION = "rejection"                    # 拒绝注册
+    MODIFICATION = "modification"              # 修改服务信息
+
+
+class SensitiveFieldKey(StrEnum):
+    """
+    敏感字段名枚举（用于日志脱敏）
+    Sensitive field key enum (for log sanitization)
+    """
+    PASSWORD = "password"
+    TOKEN = "token"
+    SECRET = "secret"
+    CREDENTIAL = "credential"

cancan_microstack/public/const/logging_enums.py

@@ -0,0 +1,13 @@
+"""
+Logging-related enums.
+"""
+from enum import StrEnum
+
+
+class LogLevel(StrEnum):
+    """日志级别枚举"""
+    DEBUG = "debug"
+    INFO = "info"
+    WARNING = "warning"
+    ERROR = "error"
+    CRITICAL = "critical"

cancan_microstack/public/const/metrics_enums.py

@@ -0,0 +1,36 @@
+"""
+Metrics-related enums.
+"""
+from enum import StrEnum
+
+
+class MetricType(StrEnum):
+    """指标类型枚举"""
+    COUNTER = "counter"
+    GAUGE = "gauge"
+    HISTOGRAM = "histogram"
+    SUMMARY = "summary"
+
+
+class HookMetricName(StrEnum):
+    """钩子指标名称枚举"""
+    EXECUTIONS_TOTAL = "hook_executions_total"
+    EXECUTION_DURATION_SECONDS = "hook_execution_duration_seconds"
+    FAILURES_TOTAL = "hook_failures_total"
+    ACTIVE_HOOKS = "active_hooks"
+    REJECTIONS_TOTAL = "hook_rejections_total"
+
+
+class HookMetricLabel(StrEnum):
+    """钩子指标标签枚举"""
+    HOOK_NAME = "hook_name"
+    HOOK_TYPE = "hook_type"
+    RESULT = "result"
+    ERROR_TYPE = "error_type"
+    REASON = "reason"
+
+
+class HookMetricResult(StrEnum):
+    """钩子指标结果枚举"""
+    SUCCESS = "success"
+    FAILURE = "failure"

cancan_microstack/public/const/monitor_enums.py

@@ -0,0 +1,26 @@
+"""
+Monitor-related enums.
+"""
+from enum import StrEnum
+
+
+class ContainerStatus(StrEnum):
+    """容器状态枚举"""
+    RUNNING = "running"
+    STOPPED = "stopped"
+    PAUSED = "paused"
+    RESTARTING = "restarting"
+    STARTING = "starting"
+    REMOVING = "removing"
+    EXITED = "exited"
+    DEAD = "dead"
+    CREATED = "created"
+    UNKNOWN = "unknown"
+
+
+class CleanupPolicy(StrEnum):
+    """清理策略枚举"""
+    NEVER = "never"           # 从不清理
+    ON_FAILURE = "failure"    # 失败时清理
+    ON_EXIT = "exit"          # 退出时清理
+    ALWAYS = "always"        # 总是清理

cancan_microstack/public/const/operation_consts.py

@@ -0,0 +1,53 @@
+"""
+异步操作相关的常量和枚举定义
+"""
+from enum import StrEnum
+
+
+class OperationType(StrEnum):
+    """操作类型枚举"""
+    START = "start"
+    STOP = "stop"
+    RESTART = "restart"
+    STATUS = "status"
+    LIST = "list"
+    HEALTH = "health"
+    COMPOSE_STATUS = "compose_status"
+
+
+class OperationStatus(StrEnum):
+    """操作状态枚举"""
+    PENDING = "pending"
+    RUNNING = "running"
+    SUCCESS = "success"
+    FAILED = "failed"
+    TIMEOUT = "timeout"
+    CANCELLED = "cancelled"
+
+
+class InitiatedBy(StrEnum):
+    """操作发起者枚举"""
+    OPSBFFSRV = "opsbffsrv"
+    INFRASRV = "infrasrv"
+    CONTROLLERSRV = "controllersrv"
+    SYSTEM = "system"
+    USER = "user"
+    INFRASRV_HEALTH_CHECK = "infrasrv_health_check"
+
+
+class InitiatedFrom(StrEnum):
+    """发起来源枚举"""
+    FRONTEND = "frontend"
+    API = "api"
+    SCHEDULER = "scheduler"
+    WEBHOOK = "webhook"
+    INTERNAL = "internal"
+    HEALTH_CHECK_DOMAIN = "health_check_domain"
+
+
+# 操作超时时间配置（秒）
+OPERATION_TIMEOUTS = {
+    OperationType.START: 120,
+    OperationType.STOP: 60,
+    OperationType.RESTART: 180,
+}

cancan_microstack/public/const/opsbffsrv_error.py

@@ -0,0 +1,92 @@
+"""Opsbffsrv 模块错误码枚举 / Error code enumerations for opsbffsrv."""
+from enum import StrEnum
+
+
+class OpsbffsrvInstanceErrorCode(StrEnum):
+    """实例管理错误码 / Instance management error codes."""
+
+    LIST_HTTP_ERROR = "50001"  # 获取实例列表失败 / Failed to fetch instance list
+    INTERNAL_ERROR = "50000"  # 实例管理内部错误 / Internal instance management error
+    DETAIL_HTTP_ERROR = "50002"  # 获取实例详情失败 / Failed to fetch instance detail
+    STATS_HTTP_ERROR = "50003"  # 获取实例统计信息失败 / Failed to fetch instance statistics
+
+
+class OpsbffsrvServiceLogsErrorCode(StrEnum):
+    """服务日志错误码 / Service logs error codes."""
+
+    INVALID_INPUT = "10001"  # 输入参数无效 / Invalid input parameter
+    INFRA_HTTP_ERROR = "10002"  # 调用 infrasrv HTTP 出错 / HTTP error when calling infrasrv
+    INFRA_RESPONSE_ERROR = "10003"  # infrasrv 返回失败 / infrasrv responded with failure
+    INTERNAL_ERROR = "10004"  # 服务日志内部错误 / Internal service log error
+
+
+class OpsbffsrvServiceConfigErrorCode(StrEnum):
+    """服务配置错误码 / Service configuration error codes."""
+
+    INVALID_INPUT = "20001"  # 输入参数无效 / Invalid input parameter
+    INTERNAL_ERROR = "20002"  # 服务配置内部错误 / Internal service configuration error
+    PUSH_TRIGGER_FAILED = "20003"  # 配置推送触发失败 / Failed to trigger config push
+
+
+class OpsbffsrvDbAdminErrorCode(StrEnum):
+    """数据库管理错误码 / Database administration error codes."""
+
+    SCHEMA_APPLY_FAILED = "30001"  # 模式应用失败 / Schema apply operation failed
+    SCHEMA_DIFF_FAILED = "30002"  # 模式对比失败 / Schema diff operation failed
+    DATABASE_REBUILD_FAILED = "30003"  # 数据库重建失败 / Database rebuild operation failed
+    TABLE_REBUILD_FAILED = "30004"  # 数据表重建失败 / Table rebuild operation failed
+
+
+class OpsbffsrvCaddyRouteErrorCode(StrEnum):
+    """Caddy 路由错误码 / Caddy route management error codes."""
+
+    CREATE_VALIDATION_FAILED = "40001"  # 路由创建参数校验失败 / Route creation validation failed
+    CREATE_SYNC_FAILED = "50001"  # 路由创建同步失败 / Route creation sync failure
+    UPDATE_VALIDATION_FAILED = "40002"  # 路由更新参数校验失败 / Route update validation failed
+    UPDATE_SYNC_FAILED = "50002"  # 路由更新同步失败 / Route update sync failure
+    ROUTE_NOT_FOUND = "40401"  # 路由不存在 / Route not found
+    ROUTE_QUERY_FAILED = "50003"  # 路由查询失败 / Route query failure
+    ROUTE_DELETE_FAILED = "50004"  # 路由删除失败 / Route deletion failure
+    ROUTE_TOGGLE_VALIDATION_FAILED = "40003"  # 路由状态切换参数校验失败 / Route toggle validation failed
+    ROUTE_TOGGLE_FAILED = "50005"  # 路由状态切换失败 / Route toggle failure
+
+
+class OpsbffsrvCaddyStatsErrorCode(StrEnum):
+    """Caddy 统计错误码 / Caddy statistics error codes."""
+
+    REALTIME_GLOBAL_FAILED = "50301"  # 获取实时全局统计失败 / Failed to fetch realtime global stats
+    REALTIME_SERVICE_NOT_FOUND = "40401"  # 服务统计不存在 / Service statistics not found
+    REALTIME_SERVICE_FAILED = "50302"  # 获取实时服务统计失败 / Failed to fetch realtime service stats
+    GLOBAL_TREND_FAILED = "50303"  # 获取全局趋势失败 / Failed to fetch global trend
+    SERVICE_TREND_FAILED = "50304"  # 获取服务趋势失败 / Failed to fetch service trend
+    ROUTE_TREND_FAILED = "50305"  # 获取路由趋势失败 / Failed to fetch route trend
+    TOP_COUNTRY_FAILED = "50306"  # 获取 Top 国家失败 / Failed to fetch top countries
+    TOP_IP_FAILED = "50307"  # 获取 Top IP 失败 / Failed to fetch top IPs
+    CLEANUP_FAILED = "50308"  # 清理统计数据失败 / Failed to cleanup statistics
+
+
+class OpsbffsrvCaddyAccessLogErrorCode(StrEnum):
+    """Caddy 访问日志错误码 / Caddy access log error codes."""
+
+    SEARCH_FAILED = "50401"  # 搜索访问日志失败 / Failed to search access logs
+    SECURITY_EVENT_FAILED = "50402"  # 获取安全事件失败 / Failed to fetch security events
+    GEO_ANALYSIS_FAILED = "50403"  # 分析地理分布失败 / Failed to analyze geographic distribution
+    STATUS_CODE_ANALYSIS_FAILED = "50404"  # 分析状态码分布失败 / Failed to analyze status code distribution
+    SUSPICIOUS_IP_FAILED = "50405"  # 检测可疑 IP 失败 / Failed to detect suspicious IPs
+    ERROR_PATTERN_ANALYSIS_FAILED = "50406"  # 分析错误模式失败 / Failed to analyze error patterns
+    CLEANUP_LOG_FAILED = "50407"  # 清理访问日志失败 / Failed to cleanup access logs
+
+
+class OpsbffsrvAuthErrorCode(StrEnum):
+    """认证错误码 / Authentication error codes."""
+
+    CAPTCHA_INVALID = "60001"      # 验证码错误 / Invalid captcha
+    CREDENTIALS_INVALID = "60002"  # 用户名或密码错误 / Invalid credentials
+    IP_LOCKED = "60003"            # IP 被锁定 / IP locked
+    TEMP_TOKEN_INVALID = "60004"   # 临时 token 无效 / Temp token invalid
+    TOTP_INVALID = "60005"         # TOTP 验证码错误 / Invalid TOTP code
+    TOTP_ALREADY_BOUND = "60006"   # TOTP 已绑定 / TOTP already bound
+    SESSION_INVALID = "60007"      # Session 无效 / Invalid session
+    INTERNAL_ERROR = "60099"       # 认证内部错误 / Authentication internal error
+
+

cancan_microstack/public/const/overrides_consts.py

@@ -0,0 +1,13 @@
+"""Override-related constants.
+
+用于覆盖（override）机制的常量定义。
+Constants for override discovery/configuration.
+"""
+
+# Overrides root environment variable name.
+# overrides 根目录环境变量名。
+OVERRIDE_ENV = "CANCAN_OVERRIDE_ROOT"
+
+# Overrides folder name under workspace.
+# workspace 下 overrides 目录名称。
+OVERRIDE_DIR_NAME = "cancan_overrides"

cancan_microstack/public/const/redis.py

@@ -0,0 +1,17 @@
+from enum import StrEnum
+
+
+class RedisKey(StrEnum):
+    AUTH_ACCESS_KEY = "auth_access_token"
+    AUTH_ACCESS_LOCK_KEY = "access_token_lock"
+    USER_LOGIN_TOKEN_KEY = "user_login_token"
+    USER_ID_TO_LOGIN_TOKEN_KEY = "user_id_to_login_token"
+    USER_SESSION_KEY = "user_session_key"
+
+    SERVICE_REGISTRY_PREFIX = "service_registry:"
+    SERVICE_REGISTRY_INSTANCE = "instance:{service_name}:{instance_id}"
+    SERVICE_REGISTRY_SERVICE_INSTANCES = "instances:{service_name}"
+    SERVICE_REGISTRY_ALL_SERVICES = "all_services"
+    SERVICE_REGISTRY_SERVICE_NAMES = "service_names"
+
+    WORKFLOW_UPDATE_PREFIX = "workflow_update:"

cancan_microstack/public/const/service_consts.py

@@ -0,0 +1,15 @@
+from enum import StrEnum
+
+
+class PushStatus(StrEnum):
+    SUCCESS = "success"
+    FAILED = "failed"
+
+
+class InstanceStatus(StrEnum):
+    """服务实例状态枚举"""
+    STARTING = "starting"
+    RUNNING = "running"
+    STOPPING = "stopping"
+    STOPPED = "stopped"
+    UNHEALTHY = "unhealthy"

cancan_microstack/public/const/workflow_consts.py

@@ -0,0 +1,65 @@
+"""Workflow task constants.
+
+集中声明 Celery 任务名称，避免散落在多个模块中造成字符串不一致。
+Centralizes Celery task identifiers to keep task names consistent across modules.
+"""
+from enum import StrEnum
+
+
+# Immutable workflow node IDs
+# 工作流内置节点 ID（不可变，前端/后端都应视为保留字）
+IMMUTABLE_START_NODE_IDS: frozenset[str] = frozenset({
+    "start",
+    "start_node",
+    "node-start",
+    "node_start",
+})
+
+IMMUTABLE_END_NODE_IDS: frozenset[str] = frozenset({
+    "end",
+    "end_node",
+    "node-end",
+    "node_end",
+})
+
+
+class WorkflowTask(StrEnum):
+    EXECUTE_NODE = "workflows.execute_node"
+    SCAN_SCHEDULED = "workflows.scan_scheduled"
+
+
+class WorkflowStatusEnum(StrEnum):
+    PENDING = "PENDING"
+    RUNNING = "RUNNING"
+    SUCCESS = "SUCCESS"
+    FAILURE = "FAILURE"
+    CANCELLED = "CANCELLED"
+    PAUSED = "PAUSED"
+
+
+class NodeStatusEnum(StrEnum):
+    PENDING = "PENDING"
+    RUNNING = "RUNNING"
+    SUCCESS = "SUCCESS"
+    FAILURE = "FAILURE"
+    SKIPPED = "SKIPPED"
+    SUSPENDED = "SUSPENDED"  # 等待回调
+    RETRYING = "RETRYING"
+    CANCELLED = "CANCELLED"  # 跟随流程取消
+
+
+class TriggerTypeEnum(StrEnum):
+    MANUAL = "MANUAL"
+    SCHEDULE = "SCHEDULE"
+    API = "API"
+
+
+class WorkflowEngineAlertReason(StrEnum):
+    """Workflow engine alert reasons to keep string identifiers consistent."""
+
+    INVALID_RUN_ID = "INVALID_RUN_ID"
+    RUN_NOT_FOUND = "RUN_NOT_FOUND"
+    WORKFLOW_DEFINITION_MISSING = "WORKFLOW_DEFINITION_MISSING"
+    NODE_CONFIG_MISSING = "NODE_CONFIG_MISSING"
+    NODE_EXECUTION_EXCEPTION = "NODE_EXECUTION_EXCEPTION"
+    NODE_TERMINATED_WITHOUT_DOWNSTREAM = "NODE_TERMINATED_WITHOUT_DOWNSTREAM"

cancan_microstack/public/error.py

@@ -0,0 +1,41 @@
+"""Cancan Microstack public exceptions.
+
+为本库代码提供统一异常类型，避免依赖业务仓库的代码。
+Provide shared exceptions for the library without depending on any consumer repo.
+"""
+
+import http
+from typing import Optional
+
+from linglong_web.core.errors import LinglongHTTPException
+
+from cancan_microstack.public.const.error import ErrorCode
+
+
+class HTTPException(LinglongHTTPException):
+    """HTTP 异常 / HTTP exception."""
+
+    def __init__(
+        self,
+        status_code: int = http.HTTPStatus.INTERNAL_SERVER_ERROR.value,
+        error_code: str = ErrorCode.SYSTEM_ERROR,
+        msg: Optional[str] = None,
+        detail: Optional[str] = None,
+    ) -> None:
+        super().__init__(
+            status_code=status_code,
+            error_code=error_code,
+            message=msg,
+            detail=detail,
+        )
+
+
+class ParamError(HTTPException):
+    """参数错误 / Invalid parameter error."""
+
+    def __init__(self, msg: Optional[str] = None, error_code: str = ErrorCode.INVALID_PARAM) -> None:
+        super().__init__(
+            status_code=http.HTTPStatus.BAD_REQUEST.value,
+            error_code=error_code,
+            msg=msg or "Invalid request parameters",
+        )

cancan_microstack/public/logging/initializer.py

@@ -0,0 +1,109 @@
+import logging
+from typing import Optional
+
+from linglong_web import LinglongConfigBase
+from linglong_web import Rmanager
+
+from cancan_microstack.runtime.workspace import ensure_server_log_dir
+from cancan_microstack.public.logging.mq_handler import RabbitMQHandler
+
+# 模块级变量，用于持有处理器实例
+# Module-level variable to hold the handler instance
+_handler: Optional[RabbitMQHandler] = None
+
+
+async def setup_mq_logging(conf: LinglongConfigBase, service_name: str):
+    """
+    初始化并注册 RabbitMQ 日志处理器。
+    此函数会将处理器添加到根日志记录器中，以便捕获所有日志。
+    这是一个异步函数，应在应用资源（如 RabbitMQ 连接）准备就绪后调用。
+
+    Initializes and registers the RabbitMQ log handler.
+    This function adds the handler to the root logger to capture all logs.
+    It is an async function and should be called after application resources
+    (like the RabbitMQ connection) are ready.
+
+    Args:
+        conf: The application's configuration proxy object.
+        service_name: The name of the service, used for routing log messages.
+    """
+    global _handler
+
+    # 确保 server_log_data 目录存在，避免日志写入 venv 目录
+    # Ensure the canonical server_log_data directory exists outside the venv
+    ensure_server_log_dir()
+    # 检查日志管道是否已启用
+    # Check if the log pipeline is enabled in the configuration
+    if not conf.LOG_PIPELINE_ENABLED:
+        logging.info("MQ logging is disabled via LOG_PIPELINE_ENABLED config.")
+        return
+
+    # 确保 RabbitMQ 连接可用
+    # Ensure the RabbitMQ connection is available
+    if not Rmanager.mq_conn or Rmanager.mq_conn.is_closed:
+        logging.error("Cannot setup MQ logging: RabbitMQ connection is not available in Rmanager.")
+        return
+
+    # 检查是否已存在处理器，避免重复添加
+    # Check if a handler is already configured to prevent duplication
+    root_logger = logging.getLogger()
+    if any(isinstance(h, RabbitMQHandler) for h in root_logger.handlers):
+        logging.warning("RabbitMQ log handler already configured.")
+        return
+
+    try:
+        # 从配置中获取 exchange 名称
+        # Get the exchange name from the configuration
+        exchange_name = getattr(conf, "RABBITMQ_LOG_EXCHANGE", None) or conf.LOG_CONFIG.get(
+            'exchange_name',
+            'logs.topic.exchange',
+        )
+        routing_template = getattr(conf, "RABBITMQ_LOG_ROUTING_TEMPLATE", None) or "logs.business.{service}.{level}"
+
+        # 创建处理器实例
+        # Create the handler instance
+        handler = RabbitMQHandler(
+            connection=Rmanager.mq_conn,
+            service_name=service_name,
+            exchange_name=exchange_name,
+            routing_template=routing_template,
+        )
+
+        # 异步初始化在 RabbitMQHandler 的 __init__ 中已经通过 run_coroutine_threadsafe 启动
+        # aio_pika 的 RobustConnection 会自动处理重连，所以我们直接添加处理器即可
+        # Async initialization is already started in RabbitMQHandler's __init__ via run_coroutine_threadsafe.
+        # aio_pika's RobustConnection handles reconnections automatically, so we can add the handler directly.
+        _handler = handler
+        root_logger.addHandler(_handler)
+        logging.info(f"RabbitMQ log handler added for service '{service_name}'. Initialization is in progress.")
+
+    except Exception as e:
+        logging.error(f"Failed to create and add RabbitMQ log handler: {e}", exc_info=True)
+        _handler = None
+
+
+async def shutdown_mq_logging():
+    """
+    异步关闭 RabbitMQ 日志处理器。
+    这会从根日志记录器中移除处理器，并安全地关闭其 RabbitMQ 通道。
+
+    Asynchronously shuts down the RabbitMQ log handler.
+    This removes the handler from the root logger and safely closes its RabbitMQ channel.
+    """
+    global _handler
+    if _handler:
+        root_logger = logging.getLogger()
+        logging.info("Shutting down RabbitMQ log handler.")
+        try:
+            # 首先从 logger 中移除处理器，停止接收新的日志
+            # First, remove the handler from the logger to stop accepting new logs
+            root_logger.removeHandler(_handler)
+
+            # 调用处理器的异步关闭方法
+            # Call the handler's asynchronous close method
+            await _handler.close_async()
+            logging.info("RabbitMQ log handler has been shut down.")
+        except Exception as e:
+            logging.error(f"Error during RabbitMQ log handler shutdown: {e}", exc_info=True)
+        finally:
+            _handler = None