Merge pull request #19 from 2686521696/main

线上事故三修：Neon 初始化堵死 / 推演阻塞事件循环 / 缩略图 PNG→WebP

Author: xiaojilele-glitch

.env.example

@@ -138,6 +138,22 @@ SESSION_SECRET=replace_with_a_64_char_random_hex_secret
 # ⚠️ 从第 3 级开始数据与远端分叉：远端恢复后本地这段时间的记录不会自动回流，
 # 需要人工导出/合并。降级时日志会打印"现在写在哪"。
 #
+# 直接走 Neon SQL over HTTP，跳过 TCP（默认关，2026-08-02 事故后加）。
+#
+# 什么时候需要它：TCP **能连上、但是慢**的环境。上面那套降级只在 TCP
+# 抛异常时才轮到 HTTP，而"慢"不抛异常，于是永远走不到——线上就是这么被堵死的。
+#
+# 两条通道实测（同一个库同一份数据）：
+#   TCP   Neon pooler 解析出 6 个地址（3 IPv4 + 3 IPv6），psycopg 逐个试、
+#         每个 connect_timeout=4s，最坏单次连接 24s。
+#   HTTP  共享 httpx 连接（keep-alive）、每次查询 15s 硬超时，不会卡住不返回。
+#         实测 p50 77ms（= 网络往返）、并发 8 吞吐 31 条/s；11 个存储接口方法
+#         全部自实现，与 SQLAlchemy 后端功能逐项对齐（含版本链/继承/删除）。
+#
+# 只对 *.neon.tech 生效；自建 PG/RDS 没有这个端点，设了会被忽略。
+# 它自己连不上时照旧继续往下降级（SQLite → JSON）。
+# APP_STORE_NEON_HTTP=false
+
 # 本地 SQLite 档的路径（默认如下）。置空则跳过这一级、直接用 JSON——
 # 只读文件系统或不想在磁盘上留库文件时用得上：
 # APP_STORE_LOCAL_SQLITE=sqlite:///data/sliderule-apps.db

client/src/lib/thumb-capture.ts

@@ -99,8 +99,30 @@ function cropToAspect(
   return out;
 }
 
+/**
+ * WebP 编码质量。与服务端 thumb_image.WEBP_QUALITY 保持一致（0~1 vs 0~100）。
+ *
+ * 参照：Next.js Image 默认 75、thumbor 默认 80、imgproxy 默认 80。取 0.82 是
+ * 因为这些是**界面截图**——大片纯色加细字，比照片更吃量化噪声，稍高一档更稳。
+ */
+const WEBP_QUALITY = 0.82;
+
+/**
+ * 采出来的画面编码成 blob。
+ *
+ * **直接出 WebP，不出 PNG**（2026-08-02）。实测同样分辨率下 805KB PNG →
+ * 43KB WebP，小 19 倍，而分辨率一个像素不减。这条省的是两段流量：回传时的
+ * 上行，以及之后每个访客看这张卡的下行（后者才是大头——应用中心一次首屏
+ * 23 张卡，10.7MB → 约 0.9MB）。
+ *
+ * 服务端也会再压一次（thumb_image.to_webp），那是给参照板那一路和历史存量用的；
+ * 已经是 WebP 的它会原样放行，不会重复编码掉画质。
+ *
+ * canvas.toBlob 对不认识的 type 会**静默回落成 PNG**（规范如此），所以这里
+ * 显式检查一次实际拿到的类型——回落了就如实按 PNG 走，不假装省了带宽。
+ */
 function canvasToBlob(canvas: HTMLCanvasElement): Promise<Blob | null> {
-  return new Promise(resolve => canvas.toBlob(resolve, "image/png"));
+  return new Promise(resolve => canvas.toBlob(resolve, "image/webp", WEBP_QUALITY));
 }
 
 /** 浏览器空闲时再动手——采集是给缩略图用的，永远排在用户交互后面。 */
@@ -164,7 +186,8 @@ export function captureAndUpload(req: CaptureRequest): Promise<boolean> {
 
       const res = await fetch(`/api/sliderule/apps/${encodeURIComponent(appId)}/preview`, {
         method: "POST",
-        headers: { "Content-Type": "image/png" },
+        // 按 blob 实际类型报，不写死——toBlob 不认 webp 时会静默回落成 PNG。
+        headers: { "Content-Type": blob.type || "image/webp" },
         body: blob,
       });
       if (!res.ok) return false;

slide-rule-python/Dockerfile

@@ -36,4 +36,10 @@ EXPOSE 9700
 # IPv4 连接 → 健康检查超时。这类平台把 UVICORN_HOST 设成 0.0.0.0 即可。
 # 端口听平台注入的 $PORT，没有回落 9700（compose 设了 PORT=9700）。
 # sh -c + exec 保证 uvicorn 是 PID 1、正常收 SIGTERM 优雅退出。
-CMD ["sh", "-c", "exec python -m uvicorn app:app --host ${UVICORN_HOST:-::} --port ${PORT:-9700}"]
+#
+# --timeout-graceful-shutdown：收到 SIGTERM 后最多等在途请求这么久，然后强退
+# （2026-08-02 事故后加）。默认是**无限等**——而一趟推演要 6~20 分钟，于是
+# 容器停不下来：实测本地 dev:stop 停不掉、端口一直被占，只能手动 kill 端口
+# 占用进程。部署时这表现为滚动更新卡住。30s 够让正常请求收尾，又不会被一趟
+# 长推演拖住。
+CMD ["sh", "-c", "exec python -m uvicorn app:app --host ${UVICORN_HOST:-::} --port ${PORT:-9700} --timeout-graceful-shutdown ${UVICORN_GRACEFUL_TIMEOUT:-30}"]

slide-rule-python/requirements.txt

@@ -34,3 +34,8 @@ psycopg[binary]>=3.2
 
 # P2b execution tools: code.run runs ONLY inside E2B sandbox (fail-closed without key)
 e2b-code-interpreter>=2.8.0
+
+# 缩略图编码（2026-08-02）：卡片缩略图从 PNG 换 WebP，实测 805KB → 43KB
+# （分辨率不减）。见 services/thumb_image.py。
+# 惰性导入 + fail-open：装不上时整条压缩链路静默失效、原样存 PNG，不影响功能。
+pillow>=10.4

slide-rule-python/routes/sliderule_full.py

@@ -585,7 +585,9 @@ async def exec_cap(payload: Dict[str, Any], x_internal_key: Optional[str] = Head
     return result
 
 @router.post("/drive-turn")
-async def drive(payload: Dict[str, Any], x_internal_key: Optional[str] = Header(None)):
+# `def` 而不是 `async def`——理由与 /drive-full 那条完全相同（见下面那段长注释）：
+# drive_reasoning_turn 是同步的重活，写在 async 里会占住事件循环。
+def drive(payload: Dict[str, Any], x_internal_key: Optional[str] = Header(None)):
     """Single turn drive (drive_reasoning_turn). Full multi-loop driver authority exposed via /drive-full."""
     _auth(x_internal_key)
     state = V5SessionState(**payload["state"])
@@ -594,7 +596,29 @@ async def drive(payload: Dict[str, Any], x_internal_key: Optional[str] = Header(
     return {"state": new_state.model_dump(), "stateAuthority": STATE_AUTHORITY_PYTHON, "provenance": PROVENANCE_PYTHON_RAG, "backend": PYTHON_BACKEND}
 
 @router.post("/drive-full")
-async def drive_full(payload: Dict[str, Any], x_internal_key: Optional[str] = Header(None)):
+# ⚠️ 这条路由是 `def` 而不是 `async def`——**故意的，别改回去**（2026-08-02）。
+#
+# 事故形状：只要有人在推演，整个服务就不响应，连 /api/health 都超时。原因是
+# drive_full_v5_session 是**同步**函数（v5_full_driver.py），一趟推演 6~20 分钟
+# （实测本次 5 个话题 374~1190s），此前它被直接写在 `async def` 里，于是整段
+# 跑在事件循环那条线程上——单 worker 下，事件循环被占住 = 全站失联。
+#
+# 修法用的是 FastAPI 官方口径，不是自己发明的：
+#   "When you declare a path operation function with normal `def` instead of
+#    `async def`, it is run in an external threadpool that is then awaited,
+#    instead of being called directly (as it would block the server)."
+#   —— fastapi.tiangolo.com/async/
+# 底层是 Starlette 的 run_in_threadpool → anyio.to_thread.run_sync。
+#
+# 为什么不用 asyncio.to_thread 手动包一层：能达到同样效果，但要在每个调用点
+# 各写一遍、且容易漏（本文件里 LLM/RAG 那几条就是这么写的，而这两条当初正是
+# 漏掉的）。函数签名去掉 async 是**声明式**的，漏不掉。
+#
+# 代价（记下来，别踩）：线程池默认只有 40 个槽（anyio 的
+# current_default_thread_limiter），而每趟推演会占住一个槽十几分钟。同时在跑的
+# 推演超过 40 个就会开始排队——真到那一天，正确的解法是把推演挪进任务队列，
+# 而不是把这个数字调大。
+def drive_full(payload: Dict[str, Any], x_internal_key: Optional[str] = Header(None)):
     """Python driver authority for multiple capability loops until stop condition (coverage/empty picks/max_loops).
     Wires drive_full_v5_session as the visible full-path multi-loop API (PYTHON_AUTHORITY).
     Real userText (user instruction) is forwarded so it drives pick/orchestrate/execute/artifacts/GCOV/phase.
@@ -1432,20 +1456,34 @@ async def list_generated_apps(
     offset: int = 0,
     x_internal_key: Optional[str] = Header(None),
 ):
-    """应用画廊列表——默认每个应用只出最新版，摘要不含大模型载荷。"""
+    """应用画廊列表——默认每个应用只出最新版，摘要不含大模型载荷。
+
+    **同步的库调用必须 to_thread**（2026-08-02 线上事故修复）。这几条路由是
+    `async def`，而 uvicorn 只跑一个 worker、一个事件循环；直接在协程里调同步
+    的 SQLAlchemy，一次慢查询就把整个事件循环冻住——`/api/health` 与
+    `/api/agent-loop/health` 跟着一起超时，"存储层拖垮主链路"的承诺当场作废。
+    这正是切回 Neon 后线上观察到的形状。
+
+    本文件里 LLM/RAG/附件解析那几条早就是这么写的（见 asyncio.to_thread 的
+    其它调用点），app store 这几条是漏网的。
+    """
     _auth(x_internal_key)
     from services import app_store
 
-    return {"apps": app_store.list_apps(limit=limit, offset=offset)}
+    apps = await asyncio.to_thread(app_store.list_apps, limit=limit, offset=offset)
+    return {"apps": apps}
 
 
 @router.get("/apps/{app_id}")
 async def get_generated_app(app_id: str, x_internal_key: Optional[str] = Header(None)):
-    """取一个生成应用的完整记录（含 model_json，可直接重开渲染）。"""
+    """取一个生成应用的完整记录（含 model_json，可直接重开渲染）。
+
+    同步库调用走 to_thread，理由见 list_generated_apps。
+    """
     _auth(x_internal_key)
     from services import app_store
 
-    record = app_store.get_app(app_id)
+    record = await asyncio.to_thread(app_store.get_app, app_id)
     if record is None:
         raise HTTPException(404, "app not found")
     return record
@@ -1454,6 +1492,7 @@ async def get_generated_app(app_id: str, x_internal_key: Optional[str] = Header(
 @router.get("/apps/{app_id}/preview")
 async def get_generated_app_preview(
     app_id: str,
+    request: Request,
     source: Optional[str] = None,
     x_internal_key: Optional[str] = Header(None),
 ):
@@ -1480,14 +1519,30 @@ async def get_generated_app_preview(
     _auth(x_internal_key)
     from services import app_store
 
-    png = app_store.get_app_preview_png(
-        app_id, source=app_store.normalize_preview_source(source) if source else None
+    # 同步库调用走 to_thread，理由见 list_generated_apps。
+    data = await asyncio.to_thread(
+        app_store.get_app_preview_png,
+        app_id,
+        source=app_store.normalize_preview_source(source) if source else None,
     )
-    if not png:
+    if not data:
         raise HTTPException(404, "preview not found")
+
+    from services.thumb_image import client_accepts_webp, sniff_media_type, to_png
+
+    # 按内容报 Content-Type，不写死 image/png：库里存量是 PNG、新写入是 WebP，
+    # 报错类型浏览器可能拒绝渲染，CDN 也会缓存错。
+    media = sniff_media_type(data)
+    # Accept 头协商（thumbor / imgproxy / Next.js Image 同款做法）：不认 WebP 的
+    # 客户端现场转回 PNG。WebP 覆盖率 97%+，这条是给极老客户端和抓取工具留的，
+    # 不是主路径。转不动就原样给——宁可让客户端拿到一张它可能不认的图，
+    # 也不要 500。
+    if media == "image/webp" and not client_accepts_webp(request.headers.get("accept")):
+        data = await asyncio.to_thread(to_png, data)
+        media = sniff_media_type(data)
     return Response(
-        content=png,
-        media_type="image/png",
+        content=data,
+        media_type=media,
         headers={"Cache-Control": "public, max-age=31536000, immutable"},
     )
 
@@ -1497,9 +1552,22 @@ async def get_generated_app_preview(
 #: 这是一张缩略图，几 MB 的东西进来只会把列表接口和 Neon 拖慢。
 _MAX_SHOT_BYTES = 3 * 1024 * 1024
 
-#: PNG 的魔数。只认 PNG：取图路由是按 image/png 回的，别的格式进来会让
-#: 浏览器拿到一个声称是 PNG 的 JPEG。
-_PNG_MAGIC = b"\x89PNG\r\n\x1a\n"
+#: 允许回传的图片格式。采集端出的是 WebP（见 client/src/lib/thumb-capture.ts），
+#: 但 canvas.toBlob 对不认识的 type 会静默回落成 PNG，所以两种都得收。
+#: 仍然只收这两种：取图路由按内容嗅探报 Content-Type，收进来一个声称是图片的
+#: 任意字节流只会让浏览器拿到一张渲染不出来的东西。
+_ALLOWED_SHOT_MAGIC = ("image/png", "image/webp")
+
+
+def _looks_like_image(data: bytes) -> bool:
+    """真的按魔数验一遍。
+
+    sniff_media_type 认不出时会**兜底返回 image/png**（为了让历史存量能正常
+    显示），所以它不能单独用来做入口校验——不然任意字节流都会被判成 PNG 放进来。
+    """
+    return data.startswith(b"\x89PNG\r\n\x1a\n") or (
+        data[:4] == b"RIFF" and data[8:12] == b"WEBP"
+    )
 
 
 @router.post("/apps/{app_id}/preview")
@@ -1533,20 +1601,23 @@ async def upload_generated_app_shot(
     _auth(x_internal_key)
     from services import app_store
 
-    if app_store.get_app(app_id) is None:
+    # 同步库调用走 to_thread，理由见 list_generated_apps。
+    if await asyncio.to_thread(app_store.get_app, app_id) is None:
         raise HTTPException(404, "app not found")
-    if app_store.app_has_shot(app_id):
+    if await asyncio.to_thread(app_store.app_has_shot, app_id):
         return {"stored": False, "reason": "already_has_shot"}
 
     body = await request.body()
     if not body:
         raise HTTPException(400, "empty body")
     if len(body) > _MAX_SHOT_BYTES:
         raise HTTPException(413, "screenshot too large")
-    if not body.startswith(_PNG_MAGIC):
-        raise HTTPException(415, "expected a PNG")
+    from services.thumb_image import sniff_media_type
+
+    if sniff_media_type(body) not in _ALLOWED_SHOT_MAGIC or not _looks_like_image(body):
+        raise HTTPException(415, "expected a PNG or WebP image")
 
-    stored = app_store.save_app_shot(app_id, body)
+    stored = await asyncio.to_thread(app_store.save_app_shot, app_id, body)
     return {"stored": stored, "bytes": len(body)}
 
 
@@ -1556,7 +1627,8 @@ async def list_generated_app_versions(root_id: str, x_internal_key: Optional[str
     _auth(x_internal_key)
     from services import app_store
 
-    return {"versions": app_store.list_versions(root_id)}
+    versions = await asyncio.to_thread(app_store.list_versions, root_id)
+    return {"versions": versions}
 
 
 @router.post("/apps/{app_id}/fork")

slide-rule-python/scripts/thumb_recompress.py

@@ -0,0 +1,109 @@
+"""把库里存量的 PNG 缩略图重新编码成 WebP（2026-08-02）。
+
+新写入的缩略图已经是 WebP（services/thumb_image），但改动之前落的那些还是 PNG，
+每张 805~857KB。这个脚本把它们就地换掉——**分辨率不动，只换编码**。
+
+    cd slide-rule-python
+    .venv/bin/python scripts/thumb_recompress.py --dry-run   # 只看能省多少
+    .venv/bin/python scripts/thumb_recompress.py             # 真写
+
+--dry-run 是默认关的反面：默认**只看不写**，要加 --apply 才真改。缩略图是线上
+数据，误跑一次没有回头路（原始 PNG 不会另存一份）。
+
+顺带：这个脚本的输出就是压缩比的实测依据。单测里**不**断言压缩比——合成夹具
+造不出真实缩略图那种体积，在它上面断言比例是自欺欺人（见 tests/test_thumb_image
+里那段说明）。
+"""
+
+from __future__ import annotations
+
+import argparse
+import base64
+import sys
+from pathlib import Path
+
+_PY_DIR = Path(__file__).resolve().parent.parent
+sys.path.insert(0, str(_PY_DIR))
+
+
+def _load_env() -> None:
+    """按 .env 配好存储后端——脚本跟服务读同一份配置。"""
+    import os
+
+    for path in (_PY_DIR.parent / ".env", _PY_DIR / ".env"):
+        try:
+            text = path.read_text(encoding="utf-8")
+        except OSError:
+            continue
+        for line in text.splitlines():
+            line = line.strip()
+            if not line or line.startswith("#") or "=" not in line:
+                continue
+            k, _, v = line.partition("=")
+            os.environ.setdefault(k.strip(), v.strip())
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--apply", action="store_true", help="真的写回去（默认只看不写）")
+    ap.add_argument("--limit", type=int, default=0, help="只处理前 N 条（调试用）")
+    args = ap.parse_args()
+
+    _load_env()
+    from services import app_store as store
+    from services.thumb_image import sniff_media_type, to_webp
+
+    backend = store.get_backend()
+    tags = backend.preview_sources()
+    ids = sorted(tags)
+    if args.limit:
+        ids = ids[: args.limit]
+    if not ids:
+        print("库里没有缩略图，无事可做")
+        return 0
+
+    print(f"{'app_id':<10}{'来源':<7}{'原始':>10}{'WebP':>10}{'倍数':>7}")
+    total_before = total_after = 0
+    changed = 0
+    for app_id in ids:
+        for src in store.PREVIEW_SOURCE_PRIORITY:
+            b64 = backend.get_preview(app_id, source=src)
+            if not b64:
+                continue
+            raw = base64.b64decode(b64)
+            if sniff_media_type(raw) == "image/webp":
+                continue  # 已经换过了
+            out = to_webp(raw)
+            total_before += len(raw)
+            total_after += len(out)
+            ratio = len(raw) / max(1, len(out))
+            print(
+                f"{app_id[:8]:<10}{src:<7}{len(raw)//1024:>8}KB{len(out)//1024:>8}KB"
+                f"{ratio:>6.1f}x"
+            )
+            if args.apply and len(out) < len(raw):
+                backend.save_preview(
+                    app_id, base64.b64encode(out).decode("ascii"), source=src
+                )
+                changed += 1
+
+    if total_before == 0:
+        print("\n所有缩略图都已经是 WebP，无事可做")
+        return 0
+    mb = lambda n: n / 1024 / 1024  # noqa: E731
+    print(
+        f"\n合计 {mb(total_before):.1f}MB → {mb(total_after):.1f}MB"
+        f"（小 {total_before / max(1, total_after):.1f} 倍）"
+    )
+    # 5Mbps = 640KB/s，应用中心首屏要把所有卡的图都拉一遍
+    for label, n in (("改前", total_before), ("改后", total_after)):
+        print(f"  {label}：5Mbps 出口上冷启动一次 ≈ {n / 1024 / 640:.1f}s")
+    if args.apply:
+        print(f"\n已写回 {changed} 张")
+    else:
+        print("\n（--dry-run 模式，什么都没写。要真改加 --apply）")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())