r2_storage_service.py 8.5 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230
  1. import asyncio
  2. import mimetypes
  3. import os
  4. import uuid
  5. from datetime import datetime
  6. from typing import Optional, Tuple, Dict, Any
  7. import boto3
  8. from botocore.config import Config
  9. from botocore.exceptions import ClientError
  10. from fastapi import UploadFile
  11. from app.core.config import settings
  12. from app.core.biz_exception import BizLogicError
  13. from app.core.logger import logger
  14. class R2StorageService:
  15. """
  16. Cloudflare R2 对象存储服务(S3 兼容)
  17. 提供文件上传、公网 URL 拼接、流式下载、预签名临时链接与删除能力。
  18. 针对 FastAPI 异步特性,所有阻塞的 boto3 调用均在异步工作线程中执行。
  19. """
  20. _client = None
  21. @classmethod
  22. def get_client(cls):
  23. """懒加载获取 S3 客户端"""
  24. if cls._client is None:
  25. if not settings.r2_access_key_id or not settings.r2_secret_access_key:
  26. raise BizLogicError("Cloudflare R2 credentials not configured. Please check R2_ACCESS_KEY_ID and R2_SECRET_ACCESS_KEY.")
  27. cls._client = boto3.client(
  28. service_name="s3",
  29. endpoint_url=settings.r2_endpoint_url,
  30. aws_access_key_id=settings.r2_access_key_id,
  31. aws_secret_access_key=settings.r2_secret_access_key,
  32. region_name="auto",
  33. config=Config(
  34. signature_version="s3v4",
  35. retries={"max_attempts": 3, "mode": "standard"},
  36. ),
  37. )
  38. return cls._client
  39. @classmethod
  40. def get_bucket_name(cls, bucket: Optional[str] = None) -> str:
  41. """获取目标 Bucket 名称"""
  42. target = bucket or settings.r2_bucket_name
  43. if not target:
  44. raise BizLogicError("R2 bucket name not specified. Please specify bucket or configure R2_BUCKET_NAME.")
  45. return target.strip()
  46. @classmethod
  47. def get_public_url(cls, key: str, bucket: Optional[str] = None) -> str:
  48. """
  49. 根据配置的公共域名生成下载/浏览 URL。
  50. 若未配置自定义公网域名,则默认生成自身 API 代理访问地址,严格防止泄漏 R2 Endpoint、存储桶名称及 AccessKey 凭证。
  51. """
  52. clean_key = key.lstrip("/")
  53. public_domain = (settings.r2_public_domain or "").strip().rstrip("/")
  54. if public_domain:
  55. return f"{public_domain}/{clean_key}"
  56. # 默认返回自身后端脱敏代理地址,如 https://api.text.skin/api/r2/file?key=...
  57. api_base = (settings.api_base_url or os.getenv("API_BASE_URL", "")).strip().rstrip("/")
  58. if api_base:
  59. return f"{api_base}/api/r2/file?key={clean_key}"
  60. return f"/api/r2/file?key={clean_key}"
  61. @classmethod
  62. def generate_presigned_url(cls, key: str, expires_in: int = 3600, bucket: Optional[str] = None) -> str:
  63. """生成带有效期的 S3 预签名下载 URL"""
  64. b_name = cls.get_bucket_name(bucket)
  65. client = cls.get_client()
  66. try:
  67. return client.generate_presigned_url(
  68. ClientMethod="get_object",
  69. Params={"Bucket": b_name, "Key": key},
  70. ExpiresIn=expires_in,
  71. )
  72. except Exception as e:
  73. logger.error(f"[R2] Failed to generate presigned url for {key}: {e}")
  74. raise BizLogicError(f"Failed to generate presigned download URL: {e}")
  75. @classmethod
  76. def _generate_key(cls, filename: str, prefix: str = "uploads") -> str:
  77. """生成按年月日划分的唯一文件存储 key"""
  78. now = datetime.now()
  79. date_path = now.strftime("%Y/%m/%d")
  80. ext = os.path.splitext(filename)[1].lower()
  81. unique_name = f"{uuid.uuid4().hex[:12]}{ext}"
  82. return f"{prefix.strip('/')}/{date_path}/{unique_name}"
  83. @classmethod
  84. async def upload(
  85. cls,
  86. file: UploadFile,
  87. custom_key: Optional[str] = None,
  88. bucket: Optional[str] = None,
  89. prefix: str = "uploads",
  90. ) -> Dict[str, Any]:
  91. """
  92. 上传 FastAPI UploadFile 到 R2 存储桶
  93. """
  94. content = await file.read()
  95. await file.seek(0)
  96. filename = file.filename or "file.bin"
  97. content_type = file.content_type or mimetypes.guess_type(filename)[0] or "application/octet-stream"
  98. return await cls.upload_bytes(
  99. content=content,
  100. filename=filename,
  101. content_type=content_type,
  102. custom_key=custom_key,
  103. bucket=bucket,
  104. prefix=prefix,
  105. )
  106. # 防刷安全配置:单文件最大 1MB,拒绝超大文件刷爆存储
  107. MAX_FILE_SIZE: int = 1 * 1024 * 1024
  108. # 允许上传的安全扩展名白名单(阻断可执行文件、脚本文件)
  109. ALLOWED_EXTENSIONS = {
  110. ".png", ".jpg", ".jpeg", ".webp", ".gif", ".svg", ".bmp", ".ico",
  111. ".pdf", ".txt", ".csv", ".json", ".zip", ".tar", ".gz"
  112. }
  113. @classmethod
  114. async def upload_bytes(
  115. cls,
  116. content: bytes,
  117. filename: str,
  118. content_type: Optional[str] = None,
  119. custom_key: Optional[str] = None,
  120. bucket: Optional[str] = None,
  121. prefix: str = "uploads",
  122. ) -> Dict[str, Any]:
  123. """
  124. 上传二进制字节数据到 R2(带安全校验:大小拦截、类型拦截)
  125. """
  126. # 1. 拦截超大文件
  127. if len(content) > cls.MAX_FILE_SIZE:
  128. max_mb = cls.MAX_FILE_SIZE // (1024 * 1024)
  129. raise BizLogicError(f"File size exceeds the allowed limit (max {max_mb}MB)")
  130. # 2. 拦截危险文件类型
  131. ext = os.path.splitext(filename)[1].lower()
  132. if ext not in cls.ALLOWED_EXTENSIONS:
  133. raise BizLogicError(f"File extension '{ext}' is not supported. Only safe media and document formats are allowed.")
  134. b_name = cls.get_bucket_name(bucket)
  135. key = custom_key or cls._generate_key(filename, prefix=prefix)
  136. mime = content_type or mimetypes.guess_type(filename)[0] or "application/octet-stream"
  137. client = cls.get_client()
  138. def _do_put():
  139. client.put_object(
  140. Bucket=b_name,
  141. Key=key,
  142. Body=content,
  143. ContentType=mime,
  144. )
  145. try:
  146. await asyncio.to_thread(_do_put)
  147. url = cls.get_public_url(key, bucket=b_name)
  148. logger.info(f"[R2] Upload success: key={key}, bucket={b_name}, size={len(content)} bytes")
  149. return {
  150. "key": key,
  151. "fid": key, # 兼容现有前端对 fid 字段的使用习惯
  152. "url": url,
  153. "filename": filename,
  154. "size": len(content),
  155. "content_type": mime,
  156. }
  157. except ClientError as ce:
  158. logger.error(f"[R2] ClientError during upload: {ce}")
  159. raise BizLogicError(f"R2 upload failed: {ce.response.get('Error', {}).get('Message', str(ce))}")
  160. except Exception as e:
  161. logger.exception(f"[R2] Unexpected upload error: {e}")
  162. raise BizLogicError(f"R2 upload failed with error: {e}")
  163. @classmethod
  164. async def get_file(cls, key: str, bucket: Optional[str] = None) -> Optional[Tuple[bytes, str]]:
  165. """
  166. 获取文件内容及 MIME 类型
  167. """
  168. b_name = cls.get_bucket_name(bucket)
  169. client = cls.get_client()
  170. def _do_get():
  171. try:
  172. resp = client.get_object(Bucket=b_name, Key=key)
  173. content = resp["Body"].read()
  174. content_type = resp.get("ContentType", "application/octet-stream")
  175. return content, content_type
  176. except ClientError as ce:
  177. if ce.response.get("Error", {}).get("Code") in ["NoSuchKey", "404"]:
  178. return None
  179. raise
  180. try:
  181. return await asyncio.to_thread(_do_get)
  182. except Exception as e:
  183. logger.error(f"[R2] Get file error for {key}: {e}")
  184. return None
  185. @classmethod
  186. async def delete_file(cls, key: str, bucket: Optional[str] = None) -> bool:
  187. """
  188. 删除 R2 中的文件对象
  189. """
  190. b_name = cls.get_bucket_name(bucket)
  191. client = cls.get_client()
  192. def _do_delete():
  193. client.delete_object(Bucket=b_name, Key=key)
  194. try:
  195. await asyncio.to_thread(_do_delete)
  196. logger.info(f"[R2] Delete success: key={key}, bucket={b_name}")
  197. return True
  198. except Exception as e:
  199. logger.error(f"[R2] Delete failed for {key}: {e}")
  200. return False