feat(storage): add S3 image storage support with file-based config and migration script

.gitignore

@@ -6,4 +6,7 @@ uploads/*
 *.db
 .env
 server.log
-scripts/
+s3_config.json
+scripts/fix_*.py
+scripts/migrate_*.py
+scripts/test_*.py

app/routers/api.py

@@ -13,7 +13,7 @@ from app.models import (
     PERM_POSTCARDS_READ, PERM_POSTCARDS_WRITE,
     PERM_IMAGES_UPLOAD,
 )
-from app.config import UPLOAD_DIR
+# config removed: image storage now via app.storage
 
 router = APIRouter(prefix="/api/v1", tags=["api"])
 
@@ -380,15 +380,16 @@ async def upload_image(
     ak: ApiKey = Depends(require_scopes(PERM_IMAGES_UPLOAD)),
 ):
     pc = _postcard_or_404(ak.user, profile_id, postcard_id, db)
+    from app.storage import get_storage
+    storage = get_storage()
     ext = Path(file.filename).suffix if file.filename else ".jpg"
-    save_name = f"pc_{pc.id}_{side}{ext}"
+    key = f"pc_{pc.id}_{side}{ext}"
-    save_path = UPLOAD_DIR / save_name
     content = await file.read()
-    save_path.write_bytes(content)
+    storage.put(key, content)
     if side == "front":
-        pc.image_front = f"/uploads/{save_name}"
+        pc.image_front = key
     else:
-        pc.image_back = f"/uploads/{save_name}"
+        pc.image_back = key
     db.commit()
     db.refresh(pc)
     return pc

app/routers/web.py

@@ -16,7 +16,7 @@ from app.auth import (
     redirect_if_not_logged_in,
     verify_password,
 )
-from app.config import SECRET_KEY, SESSION_COOKIE_NAME, UPLOAD_DIR
+from app.config import SECRET_KEY, SESSION_COOKIE_NAME
 from app.database import get_db
 from random import choice
 from string import ascii_letters, digits
@@ -86,6 +86,10 @@ def _translate_filter(key: str, lang: str = "zh") -> str:
 
 templates.env.filters["t"] = _translate_filter
 
+# image URL resolver: bare key → full URL (local /uploads/... or S3 public URL)
+from app.storage import resolve_url as _resolve_image_url
+templates.env.filters["image_url"] = lambda v: _resolve_image_url(v) if v else ""
+
 from app.i18n import get_languages as _get_languages
 templates.env.globals["available_languages"] = _get_languages()
 
@@ -188,7 +192,7 @@ def api_public_cards(
         "page": page,
         "has_more": start + limit < total,
         "cards": [{
-            "image_front": c.image_front,
+            "image_front": _resolve_image_url(c.image_front),
             "country_from": c.country_from,
             "country_to": c.country_to,
             "status": c.status,
@@ -230,7 +234,7 @@ def api_public_cards_user(
         "page": page,
         "has_more": start + limit < total,
         "cards": [{
-            "image_front": c.image_front,
+            "image_front": _resolve_image_url(c.image_front),
             "country_from": c.country_from,
             "country_to": c.country_to,
         } for c in batch],
@@ -959,12 +963,13 @@ async def upload_image(
     )
     if not pc:
         return _redirect("/profiles")
+    from app.storage import get_storage
+    storage = get_storage()
     ext = Path(file.filename or "upload.jpg").suffix or ".jpg"
-    filename = f"{uuid4().hex}{ext}"
+    key = f"{uuid4().hex}{ext}"
-    dest = UPLOAD_DIR / filename
     content = await file.read()
-    dest.write_bytes(content)
+    storage.put(key, content)
-    setattr(pc, f"image_{side}", f"/uploads/{filename}")
+    setattr(pc, f"image_{side}", key)
     db.commit()
     return _redirect(f"/postcards/{postcard_id}")
 

app/schemas.py

@@ -1,6 +1,6 @@
 from datetime import datetime
 
-from pydantic import BaseModel
+from pydantic import BaseModel, model_validator
 
 
 # ---------- Profile ----------
@@ -23,6 +23,13 @@ class ProfileOut(BaseModel):
 
     model_config = {"from_attributes": True}
 
+    @model_validator(mode="after")
+    def _resolve_image_urls(self) -> "PostcardOut":
+        from app.storage import resolve_url
+        self.image_front = resolve_url(self.image_front) or None
+        self.image_back = resolve_url(self.image_back) or None
+        return self
+
 
 # ---------- Postcard ----------
 
@@ -68,3 +75,10 @@ class PostcardOut(BaseModel):
     updated_at: datetime
 
     model_config = {"from_attributes": True}
+
+    @model_validator(mode="after")
+    def _resolve_image_urls(self) -> "PostcardOut":
+        from app.storage import resolve_url
+        self.image_front = resolve_url(self.image_front) or None
+        self.image_back = resolve_url(self.image_back) or None
+        return self

app/storage.py

@@ -0,0 +1,180 @@
+"""Image storage abstraction: local filesystem or S3-compatible object storage.
+
+S3 config is read from ``s3_config.json`` in the project root::
+
+    {
+        "enabled": true,
+        "endpoint": "https://s3.amazonaws.com",
+        "bucket": "my-mailova-bucket",
+        "region": "auto",
+        "access_key": "AKIA...",
+        "secret_key": "...",
+        "public_url": "https://cdn.example.com/mailova"
+    }
+
+When the file is missing or ``enabled`` is false, local storage is used.
+
+URL scheme
+~~~~~~~~~~
+Database stores **bare filenames** (``xxx.jpeg``) regardless of backend.
+``resolve_url(key)`` converts a bare key to a full URL:
+  - S3  → ``<public_url>/xxx.jpeg``
+  - local → ``/uploads/xxx.jpeg``
+
+Legacy records that still contain ``/uploads/xxx.jpeg`` are auto-stripped
+by ``resolve_url``.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Protocol
+
+from app.config import UPLOAD_DIR
+
+S3_CONFIG_PATH = Path(__file__).resolve().parent.parent / "s3_config.json"
+
+
+class StorageBackend(Protocol):
+    def put(self, key: str, data: bytes, content_type: str = "image/jpeg") -> str:
+        """Store data and return the bare key."""
+        ...
+
+    def delete(self, key: str) -> None: ...
+
+    def exists(self, key: str) -> bool: ...
+
+    def resolve_url(self, key: str) -> str:
+        """Convert a bare key (or legacy /uploads/xxx path) to a full URL."""
+        ...
+
+
+# ── Local Storage ──────────────────────────────────────────────────
+
+class LocalStorage:
+    def __init__(self) -> None:
+        UPLOAD_DIR.mkdir(parents=True, exist_ok=True)
+
+    def put(self, key: str, data: bytes, content_type: str = "") -> str:
+        (UPLOAD_DIR / key).write_bytes(data)
+        return key
+
+    def delete(self, key: str) -> None:
+        p = UPLOAD_DIR / key
+        if p.exists():
+            p.unlink()
+
+    def exists(self, key: str) -> bool:
+        return (UPLOAD_DIR / key).exists()
+
+    def resolve_url(self, key: str) -> str:
+        return f"/uploads/{_strip_prefix(key)}"
+
+
+# ── S3 Storage ─────────────────────────────────────────────────────
+
+class S3Storage:
+    def __init__(
+        self,
+        endpoint_url: str,
+        bucket: str,
+        access_key: str,
+        secret_key: str,
+        region: str = "auto",
+        public_url: str = "",
+    ) -> None:
+        import boto3
+
+        self.bucket = bucket
+        self.public_url = public_url.rstrip("/")
+        self._client = boto3.client(
+            "s3",
+            endpoint_url=endpoint_url or None,
+            aws_access_key_id=access_key,
+            aws_secret_access_key=secret_key,
+            region_name=region or "auto",
+        )
+
+    def put(self, key: str, data: bytes, content_type: str = "image/jpeg") -> str:
+        self._client.put_object(
+            Bucket=self.bucket, Key=key, Body=data, ContentType=content_type,
+        )
+        return key
+
+    def delete(self, key: str) -> None:
+        self._client.delete_object(Bucket=self.bucket, Key=key)
+
+    def exists(self, key: str) -> bool:
+        try:
+            self._client.head_object(Bucket=self.bucket, Key=key)
+            return True
+        except Exception:
+            return False
+
+    def resolve_url(self, key: str) -> str:
+        k = _strip_prefix(key)
+        if self.public_url:
+            return f"{self.public_url}/{k}"
+        return k
+
+
+# ── Helpers ────────────────────────────────────────────────────────
+
+def _strip_prefix(key: str) -> str:
+    """Strip ``/uploads/`` prefix from legacy DB values."""
+    if key.startswith("/uploads/"):
+        return key[len("/uploads/"):]
+    return key
+
+
+# ── Singleton accessor ─────────────────────────────────────────────
+
+_backend: StorageBackend | None = None
+
+
+def _load_s3_config() -> dict | None:
+    """Read s3_config.json. Returns None if not configured / disabled."""
+    if not S3_CONFIG_PATH.exists():
+        return None
+    try:
+        cfg = json.loads(S3_CONFIG_PATH.read_text(encoding="utf-8"))
+        if not cfg.get("enabled") or not cfg.get("bucket"):
+            return None
+        return cfg
+    except Exception:
+        return None
+
+
+def get_storage() -> StorageBackend:
+    """Get the active storage backend (S3 if configured, otherwise local)."""
+    global _backend
+    if _backend is not None:
+        return _backend
+
+    s3_cfg = _load_s3_config()
+    if s3_cfg:
+        _backend = S3Storage(
+            endpoint_url=s3_cfg.get("endpoint", ""),
+            bucket=s3_cfg["bucket"],
+            access_key=s3_cfg.get("access_key", ""),
+            secret_key=s3_cfg.get("secret_key", ""),
+            region=s3_cfg.get("region", "auto"),
+            public_url=s3_cfg.get("public_url", ""),
+        )
+    else:
+        _backend = LocalStorage()
+    return _backend
+
+
+def resolve_url(key: str | None) -> str:
+    """Convenience: resolve a possibly-None image key to a URL (or empty)."""
+    if not key:
+        return ""
+    return get_storage().resolve_url(key)
+
+
+def reset_storage() -> None:
+    """Force re-detection on next get_storage() call."""
+    global _backend
+    _backend = None

app/templates/dashboard.html

@@ -108,7 +108,7 @@ new Chart(document.getElementById('chart-received'), {
             <a href="/postcards/{{ pc.id }}" class="recent-item">
                 <div class="recent-img">
                     {% if pc.image_front %}
-                    <img src="{{ pc.image_front }}" alt="" loading="lazy">
+                    <img src="{{ pc.image_front|image_url }}" alt="" loading="lazy">
                     {% else %}
                     <span>📷</span>
                     {% endif %}

app/templates/index.html

@@ -33,8 +33,8 @@
 {% if visible|length > 0 or has_more %}
 <div class="showcase-grid" id="showcase-grid">
     {% for pc in visible %}
-    <div class="showcase-card" data-front="{{ pc.image_front }}" onclick="openLightbox(this)">
+    <div class="showcase-card" data-front="{{ pc.image_front|image_url }}" onclick="openLightbox(this)">
-        <img src="{{ pc.image_front }}" alt="" class="showcase-card-img" loading="lazy">
+        <img src="{{ pc.image_front|image_url }}" alt="" class="showcase-card-img" loading="lazy">
         <div class="showcase-card-body">
             <div class="showcase-card-meta">
                 {% if pc.country_from and pc.country_to %}<span>{{ pc.country_from|flag }} {{ pc.country_from }} → {{ pc.country_to|flag }} {{ pc.country_to }}</span>

app/templates/postcard_detail.html

@@ -28,7 +28,7 @@
         <div class="image-block">
             <h3>{{ 'pc_detail.front'|t(user.language) }}</h3>
             {% if postcard.image_front %}
-            <img src="{{ postcard.image_front }}" alt="" class="detail-img">
+            <img src="{{ postcard.image_front|image_url }}" alt="" class="detail-img">
             {% else %}
             <div class="detail-img placeholder">{{ 'pc_detail.no_front'|t(user.language) }}</div>
             {% endif %}
@@ -40,7 +40,7 @@
         <div class="image-block">
             <h3>{{ 'pc_detail.back'|t(user.language) }}</h3>
             {% if postcard.image_back %}
-            <img src="{{ postcard.image_back }}" alt="" class="detail-img">
+            <img src="{{ postcard.image_back|image_url }}" alt="" class="detail-img">
             {% else %}
             <div class="detail-img placeholder">{{ 'pc_detail.no_back'|t(user.language) }}</div>
             {% endif %}

app/templates/postcards.html

@@ -36,7 +36,7 @@
 <a href="/postcards/{{ pc.id }}" class="postcard-row">
     <div class="postcard-row-img">
         {% if pc.image_front %}
-        <img src="{{ pc.image_front }}" alt="" loading="lazy">
+        <img src="{{ pc.image_front|image_url }}" alt="" loading="lazy">
         {% else %}
         <div class="thumb placeholder">📷</div>
         {% endif %}
@@ -78,7 +78,7 @@
 <a href="/postcards/{{ pc.id }}" class="postcard-row">
     <div class="postcard-row-img">
         {% if pc.image_front %}
-        <img src="{{ pc.image_front }}" alt="" loading="lazy">
+        <img src="{{ pc.image_front|image_url }}" alt="" loading="lazy">
         {% else %}
         <div class="thumb placeholder">📷</div>
         {% endif %}

app/templates/showcase.html

@@ -45,8 +45,8 @@
 {% if mode == 'flat' %}
     <div class="showcase-grid" id="grid-sent">
     {% for pc in sent_visible %}
-        <div class="showcase-card" data-front="{{ pc.image_front }}" onclick="openLightbox(this)">
+        <div class="showcase-card" data-front="{{ pc.image_front|image_url }}" onclick="openLightbox(this)">
-            <img src="{{ pc.image_front }}" alt="" class="showcase-card-img" loading="lazy">
+            <img src="{{ pc.image_front|image_url }}" alt="" class="showcase-card-img" loading="lazy">
             <div class="showcase-card-body">
                 <div class="showcase-card-meta">
                     {% if pc.country_from and pc.country_to %}<span>{{ pc.country_from|flag }} {{ pc.country_from }} → {{ pc.country_to|flag }} {{ pc.country_to }}</span>
@@ -70,8 +70,8 @@
     <h3 style="margin:1rem 0 .75rem;font-size:.95rem;color:var(--text-muted)">{{ g.profile.nickname }}</h3>
     <div class="showcase-grid">
         {% for pc in g_sent %}
-        <div class="showcase-card" data-front="{{ pc.image_front }}" onclick="openLightbox(this)">
+        <div class="showcase-card" data-front="{{ pc.image_front|image_url }}" onclick="openLightbox(this)">
-            <img src="{{ pc.image_front }}" alt="" class="showcase-card-img" loading="lazy">
+            <img src="{{ pc.image_front|image_url }}" alt="" class="showcase-card-img" loading="lazy">
             <div class="showcase-card-body">
                 <div class="showcase-card-meta">
                     {% if pc.country_from and pc.country_to %}<span>{{ pc.country_from|flag }} {{ pc.country_from }} → {{ pc.country_to|flag }} {{ pc.country_to }}</span>
@@ -96,8 +96,8 @@
 {% if mode == 'flat' %}
     <div class="showcase-grid" id="grid-received">
     {% for pc in received_visible %}
-        <div class="showcase-card" data-front="{{ pc.image_front }}" onclick="openLightbox(this)">
+        <div class="showcase-card" data-front="{{ pc.image_front|image_url }}" onclick="openLightbox(this)">
-            <img src="{{ pc.image_front }}" alt="" class="showcase-card-img" loading="lazy">
+            <img src="{{ pc.image_front|image_url }}" alt="" class="showcase-card-img" loading="lazy">
             <div class="showcase-card-body">
                 <div class="showcase-card-meta">
                     {% if pc.country_from and pc.country_to %}<span>{{ pc.country_from|flag }} {{ pc.country_from }} → {{ pc.country_to|flag }} {{ pc.country_to }}</span>
@@ -121,8 +121,8 @@
     <h3 style="margin:1rem 0 .75rem;font-size:.95rem;color:var(--text-muted)">{{ g.profile.nickname }}</h3>
     <div class="showcase-grid">
         {% for pc in g_received %}
-        <div class="showcase-card" data-front="{{ pc.image_front }}" onclick="openLightbox(this)">
+        <div class="showcase-card" data-front="{{ pc.image_front|image_url }}" onclick="openLightbox(this)">
-            <img src="{{ pc.image_front }}" alt="" class="showcase-card-img" loading="lazy">
+            <img src="{{ pc.image_front|image_url }}" alt="" class="showcase-card-img" loading="lazy">
             <div class="showcase-card-body">
                 <div class="showcase-card-meta">
                     {% if pc.country_from and pc.country_to %}<span>{{ pc.country_from|flag }} {{ pc.country_from }} → {{ pc.country_to|flag }} {{ pc.country_to }}</span>

s3_config.example.json

@@ -0,0 +1,9 @@
+{
+    "enabled": false,
+    "endpoint": "https://s3.amazonaws.com",
+    "bucket": "my-mailova-bucket",
+    "region": "auto",
+    "access_key": "AKIA...",
+    "secret_key": "...",
+    "public_url": "https://cdn.example.com/mailova"
+}