cancan-microstack 0.0.1__py3-none-any.whl

cancan_microstack/services/opsbffsrv/domain/service_registry/service_registry.py

@@ -0,0 +1,292 @@
+"""
+服务注册查询领域层
+负责为ops前端提供服务实例的查询功能
+不包含服务注册/注销/心跳等写操作（由infrasrv负责）
+说明：本服务直接从数据库读取由 infrasrv 维护的服务状态，不执行任何独立的健康检查或陈旧实例过滤。
+"""
+from typing import (
+    List,
+    Dict,
+)
+from datetime import (
+    datetime,
+    timezone,
+)
+
+from cancan_microstack.public.const.health_consts import (
+    HealthOverallStatus,
+    InstanceHealthStatus,
+    ServiceExpectedStatusAlias,
+    ServiceRuntimeStatus,
+)
+from cancan_microstack.public.schemas.infra.enums import ServiceType
+from cancan_microstack.public.schemas.infra.overview import ServiceOverview
+from cancan_microstack.public.schemas.infra.service_registry import ServiceInstance
+from cancan_microstack.services.opsbffsrv.infrastructure.db.operate.service_info_op import get_all_service_info
+from cancan_microstack.services.opsbffsrv.infrastructure.db.operate.service_registry import (
+    get_all_service_names,
+    get_all_services,
+    get_service_by_instance,
+    get_service_instances as db_get_service_instances,
+)
+from linglong_web import LinglongConfig
+from linglong_web.utils import logger
+
+
+class ServiceRegistryDomain:
+    """
+    服务注册查询域
+    Service Registry Query Domain
+
+    职责：直接查询并返回由 infrasrv 清理和维护的服务注册数据。
+    Responsibility: Directly query and return service registry data maintained and cleaned by infrasrv.
+    """
+
+    @staticmethod
+    def _normalize_service_name(service_name: str) -> str:
+        """规范化服务名（兼容 .service 后缀）
+        Normalize service name (compatible with .service suffix)
+        """
+        value = (service_name or "").strip()
+        if value.endswith(".service"):
+            return value[:-len(".service")]
+        return value
+
+    @staticmethod
+    def _normalize_expected_status(expected_status: str) -> ServiceRuntimeStatus:
+        """规范化期望状态
+        Normalize expected status string
+        """
+        value = (expected_status or ServiceRuntimeStatus.RUNNING.value).strip().lower()
+        if value in {
+            ServiceExpectedStatusAlias.STOP.value,
+            ServiceExpectedStatusAlias.STOPPED.value,
+            ServiceExpectedStatusAlias.DOWN.value,
+        }:
+            return ServiceRuntimeStatus.STOPPED
+        return ServiceRuntimeStatus.RUNNING
+
+    @staticmethod
+    def _extract_instance_timestamp(instance: ServiceInstance) -> datetime | None:
+        """提取实例最近活动时间
+        Extract last seen timestamp for an instance
+        """
+        for field_name in ("last_heartbeat", "update_time", "created_time"):
+            timestamp = getattr(instance, field_name, None)
+            if timestamp is not None:
+                if timestamp.tzinfo is None:
+                    return timestamp.replace(tzinfo=timezone.utc)
+                return timestamp
+        return None
+
+    def _is_stale_instance(self, instance: ServiceInstance, now: datetime) -> bool:
+        """判断实例是否超时陈旧
+        Determine whether an instance is stale by heartbeat/update timestamp
+        """
+        stale_seconds = int(getattr(LinglongConfig, "SERVICE_INSTANCE_STALE_SECONDS", 180) or 180)
+        if stale_seconds <= 0:
+            return False
+
+        last_seen = self._extract_instance_timestamp(instance)
+        if last_seen is None:
+            return False
+
+        return (now - last_seen).total_seconds() > stale_seconds
+
+    def _build_instance_dedupe_key(self, instance: ServiceInstance) -> str:
+        """构建实例去重键
+        Build dedupe key for instance consolidation
+        """
+        normalized_service_name = self._normalize_service_name(instance.service_name)
+
+        if instance.container_name:
+            return f"{normalized_service_name}|container:{instance.container_name}"
+
+        return (
+            f"{normalized_service_name}|endpoint:{instance.host}:{instance.port}:{instance.internal_port}"
+        )
+
+    async def _load_expected_status_map(self) -> Dict[str, ServiceRuntimeStatus]:
+        """加载服务期望状态映射
+        Load expected status map from service info table
+        """
+        service_info_list = await get_all_service_info()
+        status_map: Dict[str, ServiceRuntimeStatus] = {}
+        for service_info in service_info_list:
+            normalized_service_name = self._normalize_service_name(service_info.service_name)
+            status_map[normalized_service_name] = self._normalize_expected_status(service_info.expected_status)
+        return status_map
+
+    def _filter_and_dedupe_instances(
+            self,
+            instances: List[ServiceInstance],
+            expected_status_map: Dict[str, ServiceRuntimeStatus],
+    ) -> List[ServiceInstance]:
+        """过滤陈旧实例并做同容器去重
+        Filter stale instances and dedupe duplicated container rows
+        """
+        now = datetime.now(timezone.utc)
+        deduped_instances: Dict[str, ServiceInstance] = {}
+
+        for instance in instances:
+            normalized_service_name = self._normalize_service_name(instance.service_name)
+            expected_status = expected_status_map.get(normalized_service_name)
+            if expected_status == ServiceRuntimeStatus.STOPPED:
+                continue
+
+            if self._is_stale_instance(instance, now):
+                continue
+
+            dedupe_key = self._build_instance_dedupe_key(instance)
+            existing = deduped_instances.get(dedupe_key)
+            if existing is None:
+                deduped_instances[dedupe_key] = instance
+                continue
+
+            existing_ts = self._extract_instance_timestamp(existing)
+            current_ts = self._extract_instance_timestamp(instance)
+            if existing_ts is None and current_ts is not None:
+                deduped_instances[dedupe_key] = instance
+            elif existing_ts is not None and current_ts is not None and current_ts >= existing_ts:
+                deduped_instances[dedupe_key] = instance
+
+        return list(deduped_instances.values())
+
+    @staticmethod
+    def _derive_actual_status(total_instances: int, healthy_instances: int) -> ServiceRuntimeStatus:
+        """根据实例统计推导实际状态
+        Derive actual status from instance counters
+        """
+        if total_instances <= 0:
+            return ServiceRuntimeStatus.STOPPED
+        if healthy_instances > 0:
+            return ServiceRuntimeStatus.RUNNING
+        return ServiceRuntimeStatus.DEGRADED
+
+    def _to_models(self, instances: List[ServiceInstance]) -> List[ServiceInstance]:
+        """将数据库模型转换为 Pydantic 模型 / Convert DB models to Pydantic models."""
+        return [ServiceInstance.model_validate(inst, from_attributes=True) for inst in instances]
+
+    async def get_service_instances(self, service_name: str | None = None, only_healthy: bool = True) -> List[ServiceInstance]:
+        """
+        获取服务实例列表
+        Get the list of instances for a service.
+
+        Args:
+            service_name: 服务名称 / Service name
+            only_healthy: 是否只返回健康实例 / Whether to return only healthy instances
+        """
+        logger.debug(f"Querying instances for service: {service_name}, only_healthy: {only_healthy}")
+
+        normalized_service_name = self._normalize_service_name(service_name or "")
+        health_status_filter = InstanceHealthStatus.HEALTHY if only_healthy else None
+
+        if normalized_service_name:
+            instances = await db_get_service_instances(
+                normalized_service_name,
+                health_status=health_status_filter,
+            )
+        else:
+            instances = await get_all_services()
+            if health_status_filter:
+                instances = [instance for instance in instances if instance.health_status == health_status_filter]
+
+        expected_status_map = await self._load_expected_status_map()
+        cleaned_instances = self._filter_and_dedupe_instances(instances, expected_status_map)
+        logger.info(
+            "Found %s cleaned instances for service=%s (only_healthy=%s)",
+            len(cleaned_instances),
+            normalized_service_name or "ALL",
+            only_healthy,
+        )
+        return self._to_models(cleaned_instances)
+
+    async def get_all_instances(self) -> List[ServiceInstance]:
+        """
+        获取所有服务实例
+        Get all service instances.
+        """
+        logger.debug("Querying all service instances.")
+        instances = await get_all_services()
+        expected_status_map = await self._load_expected_status_map()
+        cleaned_instances = self._filter_and_dedupe_instances(instances, expected_status_map)
+        return self._to_models(cleaned_instances)
+
+    async def get_instance(self, service_name: str, instance_id: str) -> ServiceInstance | None:
+        """
+        获取指定服务实例
+        Get a specific service instance.
+        """
+        instance = await get_service_by_instance(service_name, instance_id)
+        return ServiceInstance.model_validate(instance, from_attributes=True) if instance else None
+
+    async def get_all_service_names(self) -> List[str]:
+        """
+        获取所有服务名称
+        Get all service names.
+        """
+        return await get_all_service_names()
+
+    async def get_services_overview(self) -> List[ServiceOverview]:
+        """
+        获取所有服务的概览信息（服务名、状态统计）
+        基于 service_info_tbl 的元数据配合实例信息完成统计
+        包含没有实例运行的服务
+        Get an overview of all services (name, status statistics).
+        This is based on metadata from service_info_tbl combined with instance information.
+        Includes services that have no running instances.
+        """
+        all_service_info = await get_all_service_info()
+        all_instances = await get_all_services()
+        service_map: Dict[str, ServiceOverview] = {}
+        expected_status_map = await self._load_expected_status_map()
+        cleaned_instances = self._filter_and_dedupe_instances(all_instances, expected_status_map)
+
+        for service_info in all_service_info:
+            service_name = service_info.service_name
+            expected_status = self._normalize_expected_status(service_info.expected_status)
+            service_map[service_name] = ServiceOverview(
+                service_name=service_name,
+                description=service_info.description or "",
+                service_type=service_info.service_type or ServiceType.BUSINESS,
+                expected_status=expected_status,
+                desired_replicas=int(service_info.desired_replicas or 1),
+                actual_replicas=int(service_info.actual_replicas or 0),
+            )
+
+        for instance in cleaned_instances:
+            service_name = self._normalize_service_name(instance.service_name)
+            if service_name not in service_map:
+                service_map[service_name] = ServiceOverview(
+                    service_name=service_name,
+                    service_type=ServiceType.BUSINESS,
+                    expected_status=ServiceRuntimeStatus.RUNNING,
+                )
+
+            service_map[service_name].total_instances += 1
+            if instance.status == HealthOverallStatus.UP or instance.status == InstanceHealthStatus.HEALTHY:
+                service_map[service_name].healthy_instances += 1
+            else:
+                service_map[service_name].unhealthy_instances += 1
+
+        for info in service_map.values():
+            info.actual_replicas = info.total_instances
+            info.actual_status = self._derive_actual_status(info.total_instances, info.healthy_instances)
+            info.status_matches_expected = info.expected_status == info.actual_status
+
+            if info.expected_status == ServiceRuntimeStatus.STOPPED:
+                if info.actual_status == ServiceRuntimeStatus.STOPPED:
+                    info.overall_status = HealthOverallStatus.UP
+                else:
+                    info.overall_status = HealthOverallStatus.PARTIAL
+            elif info.total_instances == 0:
+                info.overall_status = HealthOverallStatus.DOWN
+            elif info.healthy_instances == 0:
+                info.overall_status = HealthOverallStatus.DOWN
+            elif info.unhealthy_instances > 0:
+                info.overall_status = HealthOverallStatus.PARTIAL
+            else:
+                info.overall_status = HealthOverallStatus.UP
+
+        logger.info(f"Retrieved overview for {len(service_map)} services")
+        return list(service_map.values())

cancan_microstack/services/opsbffsrv/infrastructure/api/infrasrv_api.py

@@ -0,0 +1,242 @@
+"""
+InfraSrv API 客户端 / InfraSrv API Client
+
+用于调用 infrasrv 的内部接口和服务管理接口 / For calling infrasrv internal and service management interfaces
+"""
+from typing import (
+    Optional,
+)
+import os
+import http
+
+from linglong_web.utils import logger
+from linglong_web import LinglongConfig
+from linglong_web import (
+    HTTPClientConfig,
+    http_client,
+)
+from cancan_microstack.public.api.infrasrv_client import InfraSrvApiClient
+from cancan_microstack.public.error import HTTPException
+from cancan_microstack.public.const.error import ErrorCode
+from cancan_microstack.public.schemas.infra.service_management import (
+    ServiceManagementRequest,
+    ServiceManagementAPIResponse,
+)
+from cancan_microstack.public.schemas.infra.operation import (
+    OperationCreateRequest,
+    OperationUpdateRequest,
+)
+
+
+class InfraSrvApi(InfraSrvApiClient):
+    """
+    用于与 InfraSrv 通信的 API 客户端 / API client for communicating with InfraSrv
+    继承自 InfraSrvApiClient，提供配置注入 / Inherits from InfraSrvApiClient with configuration injection
+    
+    继承的方法 / Inherited methods:
+    - create_operation(request: OperationCreateRequest) -> Dict[str, Any]
+    - update_operation(request: OperationUpdateRequest) -> Dict[str, Any]
+    - get_operation(operation_id: str) -> Dict[str, Any]
+    - list_operations(service_name, status, limit, offset) -> Dict[str, Any]
+    
+    新增方法（服务管理）/ New methods (service management):
+    - start_service(request: ServiceManagementRequest) -> Dict[str, Any]
+    - stop_service(request: ServiceManagementRequest) -> Dict[str, Any]
+    - restart_service(request: ServiceManagementRequest) -> Dict[str, Any]
+    """
+
+    def __init__(self):
+        # 注意：该类可能会在 LinglongConfig 初始化前被 import。
+        # Note: This class may be imported before LinglongConfig is initialized.
+        config_host = getattr(LinglongConfig, "INFRASRV_HOST", None)
+        infrasrv_host = os.getenv(
+            "INFRASRV_HOST",
+            config_host or "http://infrasrv.service:8080",
+        )
+
+        base_url = f"{infrasrv_host}"
+        super().__init__(base_url)
+        self._internal_base_url = f"{infrasrv_host}/v1/infrasrv/internal"
+        self.service_mgmt_base_url = f"{infrasrv_host}/v1/infrasrv/service"
+        logger.info(f"InfraSrvApi initialized (opsbffsrv) with base_url: {base_url}")
+        logger.info(f"Service management base URL: {self.service_mgmt_base_url}")
+        logger.info(f"Internal base URL: {self._internal_base_url}")
+
+    async def create_operation(self, request: OperationCreateRequest):
+        """创建操作记录（内部接口）/ Create operation via internal API."""
+        json_data = request.model_dump(mode="json")
+        return await self._make_request(
+            http.HTTPMethod.POST,
+            "/v1/infrasrv/internal/operation/create",
+            json_data=json_data,
+            response_models=self.OPERATION_RESPONSE_MODELS,
+        )
+
+    async def update_operation(self, request: OperationUpdateRequest):
+        """更新操作记录（内部接口）/ Update operation via internal API."""
+        json_data = request.model_dump(mode="json", exclude_none=True)
+        if request.started_at:
+            json_data["started_at"] = request.started_at.isoformat()
+        if request.completed_at:
+            json_data["completed_at"] = request.completed_at.isoformat()
+        return await self._make_request(
+            http.HTTPMethod.POST,
+            "/v1/infrasrv/internal/operation/update",
+            json_data=json_data,
+            response_models=self.OPERATION_RESPONSE_MODELS,
+        )
+
+    async def get_operation(self, operation_id: str):
+        """获取操作记录（内部接口）/ Get operation via internal API."""
+        return await self._make_request(
+            http.HTTPMethod.GET,
+            "/v1/infrasrv/internal/operation/get",
+            params={"operation_id": operation_id},
+            response_models=self.OPERATION_RESPONSE_MODELS,
+        )
+
+    async def list_operations(
+            self,
+            service_name: Optional[str] = None,
+            status: Optional[str] = None,
+            limit: int = 50,
+            offset: int = 0,
+    ):
+        """列出操作记录（内部接口）/ List operations via internal API."""
+        params: dict[str, object] = {"limit": limit, "offset": offset}
+        if service_name:
+            params["service_name"] = service_name
+        if status:
+            params["status"] = status
+        return await self._make_request(
+            http.HTTPMethod.GET,
+            "/v1/infrasrv/internal/operation/list",
+            params=params,
+            response_models=self.OPERATION_LIST_MODELS,
+        )
+
+    async def _make_service_management_request(
+            self,
+            endpoint: str,
+            request: ServiceManagementRequest
+    ) -> ServiceManagementAPIResponse:
+        """
+        调用 infrasrv 服务管理接口的通用方法 / Generic method for calling infrasrv service management interfaces
+        
+        Args:
+            endpoint: API 端点（如 /start, /stop）/ API endpoint (e.g., /start, /stop)
+            request: 服务管理请求 / Service management request
+        
+        Returns:
+            ServiceManagementAPIResponse
+        
+        Raises:
+            HTTPException: 调用失败时抛出异常 / Raise exception on call failure
+        """
+        url = f"{self.service_mgmt_base_url}{endpoint}"
+        json_data = request.model_dump(mode='json')
+
+        try:
+            resp = await http_client.post(
+                url=url,
+                json=json_data,
+                timeout=HTTPClientConfig.INTERNAL_SERVICE_TIMEOUT
+            )
+
+            if resp and resp.status == 200:
+                response_json = await resp.json()
+                logger.debug(f"Successfully called infrasrv service management API [{endpoint}]")
+
+                # 处理 infrasrv 的标准响应格式 / Handle infrasrv's standard response format
+                if isinstance(response_json, dict) and "success" in response_json:
+                    if response_json.get("success"):
+                        data = response_json.get("data", {})
+                        # 将 dict 转换为 model / Convert dict to model
+                        try:
+                            return ServiceManagementAPIResponse(**data)
+                        except Exception as e:
+                            logger.error(f"Failed to parse response as ServiceManagementAPIResponse: {e}")
+                            raise HTTPException(
+                                status_code=http.HTTPStatus.INTERNAL_SERVER_ERROR.value,
+                                error_code=ErrorCode.SYSTEM_ERROR,
+                                msg=f"Failed to parse response from infrasrv: {str(e)}"
+                            )
+                    else:
+                        error_info = response_json.get("error", {})
+                        error_msg = error_info.get("msg", "Unknown error") if isinstance(error_info, dict) else str(
+                            error_info)
+                        error_code = error_info.get("code", ErrorCode.SYSTEM_ERROR) if isinstance(error_info,
+                                                                                                  dict) else ErrorCode.SYSTEM_ERROR
+                        logger.error(f"infrasrv returned error: {error_msg}")
+                        raise HTTPException(
+                            status_code=http.HTTPStatus.INTERNAL_SERVER_ERROR.value,
+                            error_code=error_code,
+                            msg=f"Infrasrv error: {error_msg}"
+                        )
+                else:
+                    logger.error(f"Unexpected response format from infrasrv: {response_json}")
+                    raise HTTPException(
+                        status_code=http.HTTPStatus.INTERNAL_SERVER_ERROR.value,
+                        error_code=ErrorCode.SYSTEM_ERROR,
+                        msg=f"Unexpected response format from infrasrv"
+                    )
+            else:
+                status_code = resp.status if resp else 500
+                error_msg = f"HTTP error: {status_code}"
+                logger.error(f"Failed to call infrasrv service management API [{endpoint}]: {error_msg}")
+                raise HTTPException(
+                    status_code=status_code,
+                    error_code=ErrorCode.NETWORK_ERROR,
+                    msg=f"Failed to call infrasrv: {error_msg}"
+                )
+        except HTTPException:
+            raise
+        except Exception as e:
+            logger.error(f"Error calling infrasrv service management API [{endpoint}]: {e}", exc_info=True)
+            raise HTTPException(
+                status_code=http.HTTPStatus.INTERNAL_SERVER_ERROR.value,
+                error_code=ErrorCode.SYSTEM_ERROR,
+                msg=f"Error calling infrasrv: {str(e)}"
+            )
+
+    async def start_service(self, request: ServiceManagementRequest) -> ServiceManagementAPIResponse:
+        """
+        调用 infrasrv 启动服务 / Call infrasrv to start service
+        
+        Args:
+            request: 服务管理请求 / Service management request
+        
+        Returns:
+            ServiceManagementAPIResponse 或 None / ServiceManagementAPIResponse or None
+        """
+        logger.info(
+            f"[opsbffsrv → infrasrv] Starting service: {request.service_name}, operation_id: {request.operation_id}")
+        return await self._make_service_management_request("/start", request)
+
+    async def stop_service(self, request: ServiceManagementRequest) -> ServiceManagementAPIResponse:
+        """
+        调用 infrasrv 停止服务 / Call infrasrv to stop service
+        
+        Args:
+            request: 服务管理请求 / Service management request
+        
+        Returns:
+            操作结果 / Operation result
+        """
+        logger.info(
+            f"[opsbffsrv → infrasrv] Stopping service: {request.service_name}, operation_id: {request.operation_id}")
+        return await self._make_service_management_request("/stop", request)
+
+    async def restart_service(self, request: ServiceManagementRequest) -> ServiceManagementAPIResponse:
+        """
+        调用 infrasrv 重启服务 / Call infrasrv to restart service
+        
+        Args:
+            request: 服务管理请求 / Service management request
+        
+        Returns:
+            ServiceManagementAPIResponse 或 None / ServiceManagementAPIResponse or None
+        """
+        logger.info(
+            f"[opsbffsrv → infrasrv] Restarting service: {request.service_name}, operation_id: {request.operation_id}")
+        return await self._make_service_management_request("/restart", request)

cancan_microstack/services/opsbffsrv/infrastructure/auth/captcha_service.py

@@ -0,0 +1,67 @@
+"""图形验证码生成 / Captcha image generation using Pillow."""
+import base64
+import io
+import random
+import secrets
+import string
+
+from nanoid import generate as nanoid_generate
+from PIL import Image, ImageDraw, ImageFont
+
+# 排除易混淆字符 0/O/I/1
+_CHARS = "".join(c for c in string.ascii_uppercase + string.digits if c not in "OI01")
+_CAPTCHA_LENGTH = 6
+_IMG_WIDTH = 200
+_IMG_HEIGHT = 60
+
+
+def generate_captcha() -> tuple[str, str, str]:
+    """生成图形验证码 / Generate a captcha: (captcha_id, answer, image_base64).
+
+    Returns:
+        captcha_id: 唯一标识符
+        answer: 验证码答案（大写）
+        image_base64: data URI 格式的 PNG 图片
+    """
+    captcha_id = nanoid_generate(size=16)
+    # 验证码答案必须用 CSPRNG（不可预测），避免被预测/暴力绕过。
+    # Captcha answer must use a CSPRNG so it cannot be predicted.
+    # (The visual noise/jitter below stays on `random` — not security-relevant.)
+    answer = "".join(secrets.choice(_CHARS) for _ in range(_CAPTCHA_LENGTH))
+
+    image = Image.new("RGB", (_IMG_WIDTH, _IMG_HEIGHT), color=(255, 255, 255))
+    draw = ImageDraw.Draw(image)
+
+    # 尝试使用系统字体，不可用时使用默认字体
+    try:
+        font = ImageFont.truetype("Arial", 32)
+    except (OSError, IOError):
+        font = ImageFont.load_default()
+
+    # 绘制字符（带随机偏移和颜色）
+    x_offset = 15
+    for ch in answer:
+        color = (random.randint(0, 150), random.randint(0, 150), random.randint(0, 150))
+        y_offset = random.randint(5, 15)
+        draw.text((x_offset, y_offset), ch, fill=color, font=font)
+        x_offset += 28
+
+    # 绘制干扰线
+    for _ in range(5):
+        x1, y1 = random.randint(0, _IMG_WIDTH), random.randint(0, _IMG_HEIGHT)
+        x2, y2 = random.randint(0, _IMG_WIDTH), random.randint(0, _IMG_HEIGHT)
+        color = (random.randint(100, 200), random.randint(100, 200), random.randint(100, 200))
+        draw.line([(x1, y1), (x2, y2)], fill=color, width=1)
+
+    # 绘制噪点
+    for _ in range(100):
+        x, y = random.randint(0, _IMG_WIDTH - 1), random.randint(0, _IMG_HEIGHT - 1)
+        color = (random.randint(100, 200), random.randint(100, 200), random.randint(100, 200))
+        draw.point((x, y), fill=color)
+
+    buf = io.BytesIO()
+    image.save(buf, format="PNG")
+    b64 = base64.b64encode(buf.getvalue()).decode("utf-8")
+    image_base64 = f"data:image/png;base64,{b64}"
+
+    return captcha_id, answer, image_base64

cancan_microstack/services/opsbffsrv/infrastructure/auth/password_service.py

@@ -0,0 +1,12 @@
+"""bcrypt 密码哈希与验证 / Password hashing and verification with bcrypt."""
+import bcrypt
+
+
+def hash_password(plain: str) -> str:
+    """生成 bcrypt 密码哈希 / Generate bcrypt hash for a plaintext password."""
+    return bcrypt.hashpw(plain.encode("utf-8"), bcrypt.gensalt()).decode("utf-8")
+
+
+def verify_password(plain: str, hashed: str) -> bool:
+    """校验明文密码与 bcrypt 哈希 / Verify plaintext password against bcrypt hash."""
+    return bcrypt.checkpw(plain.encode("utf-8"), hashed.encode("utf-8"))