feat: add storage media api

这个提交存在于:
YokiiroBW 2026-07-05 09:14:32 +08:00
父节点 fe2f52fe06
当前提交 7c41348939
共有 6 个文件被更改,包括 366 次插入 和 2 次删除

查看文件

@ -0,0 +1,44 @@
"""Media signing route handlers."""
from __future__ import annotations
from typing import Any
from backend.dto.common import ApiError, ErrorCode
from backend.routes.common import handle_request
from backend.services.media_service import MediaService
from core.identity import RequestContext
from core.security import require_authenticated
def sign_media(
ctx: RequestContext,
query: dict[str, Any],
service: MediaService | None = None,
) -> dict:
media_service = service or MediaService()
def action() -> dict[str, Any]:
require_authenticated(ctx)
uri = str(query.get("uri") or "").strip()
if not uri:
raise ApiError(ErrorCode.VALIDATION_FAILED, "uri is required", {"field": "uri"})
return media_service.sign_media(uri)
return handle_request(ctx, action)
def fetch_media(
ctx: RequestContext,
query: dict[str, Any],
service: MediaService | None = None,
) -> dict:
media_service = service or MediaService()
def action() -> dict[str, Any]:
token = str(query.get("token") or "").strip()
if not token:
raise ApiError(ErrorCode.VALIDATION_FAILED, "token is required", {"field": "token"})
return media_service.fetch_media(token)
return handle_request(ctx, action)

查看文件

@ -0,0 +1,23 @@
"""Storage route handlers."""
from __future__ import annotations
from typing import Any
from backend.routes.common import handle_request
from backend.services.media_service import MediaService
from core.identity import RequestContext
from core.security import require_authenticated
def get_storage_status(
ctx: RequestContext,
service: MediaService | None = None,
) -> dict:
media_service = service or MediaService()
def action() -> dict[str, Any]:
require_authenticated(ctx)
return media_service.storage_status()
return handle_request(ctx, action)

查看文件

@ -0,0 +1,28 @@
"""Storage and media signing service."""
from __future__ import annotations
from typing import Any
from core.config_service import ConfigService
from core.media_proxy import MediaProxy
from core.storage import VfsStorage
class MediaService:
def __init__(
self,
config_service: ConfigService | None = None,
media_proxy: MediaProxy | None = None,
):
self.storage = VfsStorage(config_service)
self.media_proxy = media_proxy or MediaProxy(self.storage)
def storage_status(self) -> dict[str, Any]:
return self.storage.status()
def sign_media(self, uri: str) -> dict[str, Any]:
return self.media_proxy.sign(uri)
def fetch_media(self, token: str) -> dict[str, Any]:
return self.media_proxy.fetch_metadata(token)

查看文件

@ -1 +1,102 @@
"""Signed media URL helpers placeholder."""
"""Signed media URL helpers."""
from __future__ import annotations
import base64
import hashlib
import hmac
import json
import mimetypes
import os
import time
from pathlib import Path
from typing import Any
from backend.dto.common import ApiError, ErrorCode
from core.storage import VfsStorage
DEFAULT_MEDIA_TTL_SECONDS = 300
MEDIA_FETCH_PATH = "/api/v1/plugins/extensions/astrbot_plugin_imagestudio/media/fetch"
class MediaProxy:
def __init__(
self,
storage: VfsStorage | None = None,
*,
signing_secret: str | None = None,
ttl_seconds: int = DEFAULT_MEDIA_TTL_SECONDS,
):
self.storage = storage or VfsStorage()
self.signing_secret = signing_secret or os.environ.get(
"IMAGESTUDIO_MEDIA_SIGNING_SECRET",
"imagestudio-dev-media-signing-secret",
)
self.ttl_seconds = ttl_seconds
def sign(self, uri: str) -> dict[str, Any]:
path = self.storage.ensure_file(uri)
expires_at = int(time.time()) + self.ttl_seconds
payload = {"uri": uri, "expires_at": expires_at}
token = self._encode(payload)
return {
"uri": uri,
"token": token,
"expires_at": expires_at,
"url": f"{MEDIA_FETCH_PATH}?token={token}",
"content_type": _guess_content_type(path),
"size_bytes": path.stat().st_size,
}
def fetch_metadata(self, token: str) -> dict[str, Any]:
payload = self._decode(token)
uri = str(payload.get("uri") or "")
expires_at = int(payload.get("expires_at") or 0)
if int(time.time()) > expires_at:
raise ApiError(ErrorCode.FORBIDDEN, "media token expired", {"expires_at": expires_at})
path = self.storage.ensure_file(uri)
return {
"uri": uri,
"expires_at": expires_at,
"content_type": _guess_content_type(path),
"size_bytes": path.stat().st_size,
}
def _encode(self, payload: dict[str, Any]) -> str:
payload_bytes = json.dumps(payload, separators=(",", ":"), sort_keys=True).encode("utf-8")
payload_part = _b64encode(payload_bytes)
signature = hmac.new(
self.signing_secret.encode("utf-8"),
payload_part.encode("ascii"),
hashlib.sha256,
).digest()
return f"{payload_part}.{_b64encode(signature)}"
def _decode(self, token: str) -> dict[str, Any]:
try:
payload_part, signature_part = token.split(".", 1)
except ValueError as exc:
raise ApiError(ErrorCode.FORBIDDEN, "invalid media token") from exc
expected = hmac.new(
self.signing_secret.encode("utf-8"),
payload_part.encode("ascii"),
hashlib.sha256,
).digest()
actual = _b64decode(signature_part)
if not hmac.compare_digest(expected, actual):
raise ApiError(ErrorCode.FORBIDDEN, "invalid media token signature")
return json.loads(_b64decode(payload_part).decode("utf-8"))
def _guess_content_type(path: Path) -> str:
return mimetypes.guess_type(path.name)[0] or "application/octet-stream"
def _b64encode(value: bytes) -> str:
return base64.urlsafe_b64encode(value).decode("ascii").rstrip("=")
def _b64decode(value: str) -> bytes:
padding = "=" * (-len(value) % 4)
return base64.urlsafe_b64decode(value + padding)

查看文件

@ -1 +1,119 @@
"""VFS storage helpers placeholder."""
"""VFS storage helpers."""
from __future__ import annotations
from dataclasses import dataclass
from pathlib import Path
from typing import Any
from backend.dto.common import ApiError, ErrorCode
from core.config_service import ConfigService, ImageStudioConfig
from database.db_helper import REPO_ROOT
@dataclass(frozen=True)
class VfsEntry:
root: str
uri_prefix: str
exists: bool
writable: bool
bytes: int
def to_dict(self) -> dict[str, Any]:
return {
"root": self.root,
"uri_prefix": self.uri_prefix,
"exists": self.exists,
"writable": self.writable,
"bytes": self.bytes,
}
class VfsStorage:
def __init__(self, config_service: ConfigService | None = None):
self.config_service = config_service or ConfigService()
def status(self) -> dict[str, Any]:
roots = [self._entry(root, path) for root, path in self._root_paths().items()]
return {
"roots": [entry.to_dict() for entry in roots],
"total_bytes": sum(entry.bytes for entry in roots),
}
def resolve_uri(self, uri: str) -> Path:
root, relative = self.split_uri(uri)
root_path = self._root_paths().get(root)
if root_path is None:
raise ApiError(ErrorCode.MEDIA_NOT_FOUND, "unknown storage root", {"uri": uri, "root": root})
resolved_root = _resolve_data_path(root_path).resolve()
resolved_path = (resolved_root / relative).resolve()
if resolved_path != resolved_root and resolved_root not in resolved_path.parents:
raise ApiError(ErrorCode.FORBIDDEN, "storage uri escapes its root", {"uri": uri})
return resolved_path
def ensure_file(self, uri: str) -> Path:
path = self.resolve_uri(uri)
if not path.exists() or not path.is_file():
raise ApiError(ErrorCode.MEDIA_NOT_FOUND, "media file not found", {"uri": uri})
return path
def split_uri(self, uri: str) -> tuple[str, Path]:
if not uri.startswith("storage://"):
raise ApiError(ErrorCode.VALIDATION_FAILED, "uri must use storage://", {"field": "uri"})
rest = uri[len("storage://") :]
if "/" not in rest:
raise ApiError(ErrorCode.VALIDATION_FAILED, "storage uri must include a root and path", {"uri": uri})
root, relative = rest.split("/", 1)
if not root or not relative:
raise ApiError(ErrorCode.VALIDATION_FAILED, "storage uri must include a root and path", {"uri": uri})
relative_path = Path(relative)
if relative_path.is_absolute() or ".." in relative_path.parts:
raise ApiError(ErrorCode.FORBIDDEN, "storage uri contains an unsafe path", {"uri": uri})
return root, relative_path
def _entry(self, root: str, path: str) -> VfsEntry:
resolved = _resolve_data_path(path)
return VfsEntry(
root=root,
uri_prefix=f"storage://{root}/",
exists=resolved.exists(),
writable=_is_writable(resolved),
bytes=_directory_size(resolved),
)
def _root_paths(self) -> dict[str, str]:
config = self.config_service.load()
return _storage_roots(config)
def _storage_roots(config: ImageStudioConfig) -> dict[str, str]:
return {
"images": config.storage.images_path,
"thumbnails": config.storage.thumbnails_path,
"materials": config.storage.materials_path,
"styles": config.storage.styles_path,
"archives": config.storage.archives_path,
"temp": config.storage.temp_path,
}
def _resolve_data_path(path: str) -> Path:
resolved = Path(path)
if not resolved.is_absolute():
resolved = REPO_ROOT / resolved
return resolved
def _directory_size(path: Path) -> int:
if not path.exists():
return 0
total = 0
for child in path.rglob("*"):
if child.is_file():
total += child.stat().st_size
return total
def _is_writable(path: Path) -> bool:
target = path if path.exists() else path.parent
return target.exists() and target.is_dir()

查看文件

@ -13,6 +13,7 @@ from backend.routes.image_routes import (
select_image,
)
from backend.routes.job_routes import cancel_job, get_job, list_jobs, retry_job
from backend.routes.media_routes import fetch_media, sign_media
from backend.routes.node_routes import (
generate_node,
get_node,
@ -34,6 +35,7 @@ from backend.routes.settings_routes import (
get_settings_schema,
validate_settings,
)
from backend.routes.storage_routes import get_storage_status
from backend.routes.ui_routes import get_ui_bootstrap
from backend.routes.workflow_routes import (
archive_workflow,
@ -44,6 +46,7 @@ from backend.routes.workflow_routes import (
)
from backend.services.dashboard_service import DashboardService
from backend.services.image_service import ImageService
from backend.services.media_service import MediaService
from backend.services.profile_service import ProfileService
from backend.services.queue_service import QueueService
from backend.services.settings_service import SettingsService
@ -123,6 +126,7 @@ storage:
audit_service=self.audit_service,
)
self.settings_service = SettingsService(self.config_service)
self.media_service = MediaService(self.config_service)
self.ctx = RequestContext.from_astrbot(
username="admin",
user_id="user_001",
@ -427,6 +431,52 @@ security:
self.assertFalse(response["ok"])
self.assertEqual(response["error_code"], "FORBIDDEN")
def test_storage_status_and_media_signing_do_not_expose_real_paths(self):
response = get_storage_status(self.ctx, self.media_service)
self.assertTrue(response["ok"])
roots = {item["root"]: item for item in response["data"]["roots"]}
self.assertIn("images", roots)
self.assertEqual(roots["images"]["uri_prefix"], "storage://images/")
self.assertGreaterEqual(roots["images"]["bytes"], 5)
self.assertNotIn(str(self.root), str(response["data"]))
signed = sign_media(
self.ctx,
{"uri": "storage://images/sample.bin"},
self.media_service,
)
self.assertTrue(signed["ok"])
self.assertTrue(signed["data"]["url"].startswith("/api/v1/plugins/extensions/"))
self.assertNotIn(str(self.root), str(signed["data"]))
fetched = fetch_media(
RequestContext(),
{"token": signed["data"]["token"]},
self.media_service,
)
self.assertTrue(fetched["ok"])
self.assertEqual(fetched["data"]["uri"], "storage://images/sample.bin")
self.assertEqual(fetched["data"]["size_bytes"], 5)
self.assertNotIn(str(self.root), str(fetched["data"]))
def test_media_signing_rejects_unsafe_or_missing_uri(self):
unsafe = sign_media(
self.ctx,
{"uri": "storage://images/../config.yaml"},
self.media_service,
)
self.assertFalse(unsafe["ok"])
self.assertEqual(unsafe["error_code"], "FORBIDDEN")
missing = sign_media(
self.ctx,
{"uri": "storage://images/missing.png"},
self.media_service,
)
self.assertFalse(missing["ok"])
self.assertEqual(missing["error_code"], "MEDIA_NOT_FOUND")
def test_workflow_node_image_routes_return_wrapped_responses(self):
profile = self.profile_service.create_profile({"name": "Nova"}, self.ctx)