import asyncio import mimetypes import os import uuid from datetime import datetime from typing import Optional, Tuple, Dict, Any import boto3 from botocore.config import Config from botocore.exceptions import ClientError from fastapi import UploadFile from app.core.config import settings from app.core.biz_exception import BizLogicError from app.core.logger import logger class R2StorageService: """ Cloudflare R2 对象存储服务(S3 兼容) 提供文件上传、公网 URL 拼接、流式下载、预签名临时链接与删除能力。 针对 FastAPI 异步特性,所有阻塞的 boto3 调用均在异步工作线程中执行。 """ _client = None @classmethod def get_client(cls): """懒加载获取 S3 客户端""" if cls._client is None: if not settings.r2_access_key_id or not settings.r2_secret_access_key: raise BizLogicError("Cloudflare R2 credentials not configured. Please check R2_ACCESS_KEY_ID and R2_SECRET_ACCESS_KEY.") cls._client = boto3.client( service_name="s3", endpoint_url=settings.r2_endpoint_url, aws_access_key_id=settings.r2_access_key_id, aws_secret_access_key=settings.r2_secret_access_key, region_name="auto", config=Config( signature_version="s3v4", retries={"max_attempts": 3, "mode": "standard"}, ), ) return cls._client @classmethod def get_bucket_name(cls, bucket: Optional[str] = None) -> str: """获取目标 Bucket 名称""" target = bucket or settings.r2_bucket_name if not target: raise BizLogicError("R2 bucket name not specified. Please specify bucket or configure R2_BUCKET_NAME.") return target.strip() @classmethod def get_public_url(cls, key: str, bucket: Optional[str] = None) -> str: """ 根据配置的公共域名生成下载/浏览 URL。 若未配置自定义公网域名,则默认生成自身 API 代理访问地址,严格防止泄漏 R2 Endpoint、存储桶名称及 AccessKey 凭证。 """ clean_key = key.lstrip("/") public_domain = (settings.r2_public_domain or "").strip().rstrip("/") if public_domain: return f"{public_domain}/{clean_key}" # 默认返回自身后端脱敏代理地址,如 https://api.text.skin/api/r2/file?key=... api_base = (settings.api_base_url or os.getenv("API_BASE_URL", "")).strip().rstrip("/") if api_base: return f"{api_base}/api/r2/file?key={clean_key}" return f"/api/r2/file?key={clean_key}" @classmethod def generate_presigned_url(cls, key: str, expires_in: int = 3600, bucket: Optional[str] = None) -> str: """生成带有效期的 S3 预签名下载 URL""" b_name = cls.get_bucket_name(bucket) client = cls.get_client() try: return client.generate_presigned_url( ClientMethod="get_object", Params={"Bucket": b_name, "Key": key}, ExpiresIn=expires_in, ) except Exception as e: logger.error(f"[R2] Failed to generate presigned url for {key}: {e}") raise BizLogicError(f"Failed to generate presigned download URL: {e}") @classmethod def _generate_key(cls, filename: str, prefix: str = "uploads") -> str: """生成按年月日划分的唯一文件存储 key""" now = datetime.now() date_path = now.strftime("%Y/%m/%d") ext = os.path.splitext(filename)[1].lower() unique_name = f"{uuid.uuid4().hex[:12]}{ext}" return f"{prefix.strip('/')}/{date_path}/{unique_name}" @classmethod async def upload( cls, file: UploadFile, custom_key: Optional[str] = None, bucket: Optional[str] = None, prefix: str = "uploads", ) -> Dict[str, Any]: """ 上传 FastAPI UploadFile 到 R2 存储桶 """ content = await file.read() await file.seek(0) filename = file.filename or "file.bin" content_type = file.content_type or mimetypes.guess_type(filename)[0] or "application/octet-stream" return await cls.upload_bytes( content=content, filename=filename, content_type=content_type, custom_key=custom_key, bucket=bucket, prefix=prefix, ) # 防刷安全配置:单文件最大 1MB,拒绝超大文件刷爆存储 MAX_FILE_SIZE: int = 1 * 1024 * 1024 # 允许上传的安全扩展名白名单(阻断可执行文件、脚本文件) ALLOWED_EXTENSIONS = { ".png", ".jpg", ".jpeg", ".webp", ".gif", ".svg", ".bmp", ".ico", ".pdf", ".txt", ".csv", ".json", ".zip", ".tar", ".gz" } @classmethod async def upload_bytes( cls, content: bytes, filename: str, content_type: Optional[str] = None, custom_key: Optional[str] = None, bucket: Optional[str] = None, prefix: str = "uploads", ) -> Dict[str, Any]: """ 上传二进制字节数据到 R2(带安全校验:大小拦截、类型拦截) """ # 1. 拦截超大文件 if len(content) > cls.MAX_FILE_SIZE: max_mb = cls.MAX_FILE_SIZE // (1024 * 1024) raise BizLogicError(f"File size exceeds the allowed limit (max {max_mb}MB)") # 2. 拦截危险文件类型 ext = os.path.splitext(filename)[1].lower() if ext not in cls.ALLOWED_EXTENSIONS: raise BizLogicError(f"File extension '{ext}' is not supported. Only safe media and document formats are allowed.") b_name = cls.get_bucket_name(bucket) key = custom_key or cls._generate_key(filename, prefix=prefix) mime = content_type or mimetypes.guess_type(filename)[0] or "application/octet-stream" client = cls.get_client() def _do_put(): client.put_object( Bucket=b_name, Key=key, Body=content, ContentType=mime, ) try: await asyncio.to_thread(_do_put) url = cls.get_public_url(key, bucket=b_name) logger.info(f"[R2] Upload success: key={key}, bucket={b_name}, size={len(content)} bytes") return { "key": key, "fid": key, # 兼容现有前端对 fid 字段的使用习惯 "url": url, "filename": filename, "size": len(content), "content_type": mime, } except ClientError as ce: logger.error(f"[R2] ClientError during upload: {ce}") raise BizLogicError(f"R2 upload failed: {ce.response.get('Error', {}).get('Message', str(ce))}") except Exception as e: logger.exception(f"[R2] Unexpected upload error: {e}") raise BizLogicError(f"R2 upload failed with error: {e}") @classmethod async def get_file(cls, key: str, bucket: Optional[str] = None) -> Optional[Tuple[bytes, str]]: """ 获取文件内容及 MIME 类型 """ b_name = cls.get_bucket_name(bucket) client = cls.get_client() def _do_get(): try: resp = client.get_object(Bucket=b_name, Key=key) content = resp["Body"].read() content_type = resp.get("ContentType", "application/octet-stream") return content, content_type except ClientError as ce: if ce.response.get("Error", {}).get("Code") in ["NoSuchKey", "404"]: return None raise try: return await asyncio.to_thread(_do_get) except Exception as e: logger.error(f"[R2] Get file error for {key}: {e}") return None @classmethod async def delete_file(cls, key: str, bucket: Optional[str] = None) -> bool: """ 删除 R2 中的文件对象 """ b_name = cls.get_bucket_name(bucket) client = cls.get_client() def _do_delete(): client.delete_object(Bucket=b_name, Key=key) try: await asyncio.to_thread(_do_delete) logger.info(f"[R2] Delete success: key={key}, bucket={b_name}") return True except Exception as e: logger.error(f"[R2] Delete failed for {key}: {e}") return False