diff --git a/backend/app/main.py b/backend/app/main.py index e0ed433..8f87e69 100644 --- a/backend/app/main.py +++ b/backend/app/main.py @@ -13,7 +13,9 @@ from fastapi import FastAPI, HTTPException, Request from fastapi.middleware.cors import CORSMiddleware from fastapi.responses import FileResponse, JSONResponse from fastapi.staticfiles import StaticFiles +from starlette.datastructures import Headers from starlette.middleware.base import BaseHTTPMiddleware +from starlette.middleware.gzip import GZipMiddleware, GZipResponder from app.api import api_router from app.api.auth import auth_middleware @@ -61,8 +63,98 @@ async def lifespan(app: FastAPI): app = FastAPI(title=settings.app_name, version="1.0.0", lifespan=lifespan, description="长视频编导平台:资产库 → 分镜脚本 → 模型调度 → 质检审核 → 时间线合成导出") -# 先注册鉴权、后注册 CORS:Starlette 里**后注册的中间件在最外层**, -# 这样 401/403 也会带上 CORS 头,前端才能读到「未登录」而不是一个笼统的网络错误。 +# ------------------------------------------------------------------ 交付面:按 content-type 压缩 +# 立项依据是阶段 29 的两把实测尺(`reports/ui_evidence/nex-p29/apigzip.log`): +# 首访过网 1 292 834 B 里 `/api` 占 773 646 B,比全部 JS+CSS 之和(512 744 B)还大, +# 而它是当时唯一没压的一族。同一把尺(gzip level 6)离线量过: +# · JSON 21 条 866 745 → 143 900 B,**省 83.4 %**; +# · 挂在同一个 `/api` 前缀下的 `/api/media/thumb/*.png` 24 条 51 768 → 52 320 B, +# **反而 +1.1 %**(PNG 自己就是压过的)。 +# ⇒ 判据不能是路径前缀。所以这里不直接用 `GZipMiddleware` 挂全站:它只看 +# `Accept-Encoding` 和体积,**不看 content-type**,挂上去会把下面两样东西压坏—— +# · `/api/media/thumb/*.png`:白烧 CPU 还变大; +# · `/api/exports/{id}/download` 的 `video/mp4`:Starlette 压完顺手删掉 +# `Content-Length`,而播放器要靠它算 Range 进度条,seek 直接废。 +# 做法:复用 Starlette 那套已经被验证过的流式 gzip 状态机(`GZipResponder`: +# 缓冲到 minimum_size 再决定、边压边发、合并 `Vary`、压完才删 `Content-Length`), +# 只在 `http.response.start` 那一步多问一句「这个 media type 值不值得压」。 + +# `GZIP_MINIMUM` 管不管得住,取决于这一层坐在鉴权中间件的哪一侧。阶段 30 为此翻过一次, +# A/B 读数在 `reports/ui_evidence/nex-p30/servecheck.log`: +# · starlette 0.46.2 `gzip.py` 的体积阈值只在「一条 body 消息且 `more_body=False`」时判定。 +# 路由返回 `JSONResponse`、`StaticFiles` 发小文件 ⇒ 都是一条完整 body ⇒ 阈值管得住。 +# · `BaseHTTPMiddleware` 会把下游响应转成分块转发(首块 `more_body=True`)⇒ 阈值整体失效。 +# 把它压在这一层外面那次实测:4 个 <1 kB 的哈希 chunk(`ProjectDetail` / +# `kit-icons-extra` / `use-auto-refresh` / `use-local-storage`)与 742 B 的导出元数据 +# 全被压,跟项目自己声明的 1 kB 底线(`SPA_GZIP_MINIMUM`、nginx `gzip_min_length`)对不上。 +# ⇒ 所以顺序是「压缩层最内 → 鉴权 → CORS 最外」,见下面三条 `add_middleware`。 +# 代价:鉴权自己吐的 401/403 JSON(实测 25 B)不被覆盖——它本来就在阈值以下。 +# 收益:阈值名副其实,静态面与 API 面同一把尺,servecheck 那条「<1 kB 的小文件不压」 +# 两侧都过(是实现对上判据,不是把判据改松)。 +# · 仍然成立的那半:流式端点不看体积(`StreamingResponse` 首块就压)⇒ +# 二进制的安全由 media type 判据负责,不由阈值负责。 +# (钉在 `tests/test_api_content_gzip.py::test_streaming_webp_thumbnail_is_still_untouched`) +GZIP_MINIMUM = 1024 # 与 SPA_GZIP_MINIMUM / nginx `gzip_min_length` 同一把尺 +GZIP_LEVEL = 6 # 与 SPA_GZIP_LEVEL / nginx `gzip_comp_level` 同一把尺 +# 文本族之外的类型一律不压。`text/*` 在函数里单列,这里只登记非 text/ 的: +GZIP_TYPES = frozenset({ + "application/json", "application/geo+json", "application/ld+json", "application/ndjson", + "application/x-ndjson", "application/javascript", "text/javascript", "application/ecmascript", + "application/xml", "text/xml", "image/svg+xml", "application/yaml", "application/x-yaml", +}) + + +def gzip_eligible(content_type: str) -> bool: + """这个响应的 media type 值不值得 gzip。""" + main = (content_type or "").split(";", 1)[0].strip().lower() + if not main: + return False # 没声明类型的空响应 / 204:不压 + if main.startswith("text/"): + # SSE 是长连接上的逐条推送,gzip 会把它攒成块(Starlette 自己也排除它) + return main != "text/event-stream" + return main in GZIP_TYPES + + +class _GzipByContentType(GZipResponder): + """`GZipResponder` + 一条 content-type 判据。 + + 父类在 `http.response.start` 时只把 `text/event-stream` 当例外;这里把「例外」的定义 + 换成「不在文本族里」,其余流程(缓冲、流式、`Vary`、`Content-Length`)一个字不改, + 所以不会另起一套实现。已经带 `Content-Encoding` 的也归入例外:上游压过就透传, + 不叠第二层(`/assets` 那一层 gzip 与这一层并存靠的就是这条)。 + """ + + async def send_with_compression(self, message): + await super().send_with_compression(message) + if message["type"] == "http.response.start": + headers = Headers(raw=message["headers"]) + self.content_type_is_excluded = (self.content_type_is_excluded + or self.content_encoding_set + or not gzip_eligible(headers.get("content-type", ""))) + + +class ContentTypeGZipMiddleware(GZipMiddleware): + """按 content-type 过滤的 gzip。它是三条用户中间件里最内的一条, + 所以看到的是路由与挂载点自己发出的响应(体积阈值管得住,见上面的说明); + 异常处理器在路由内侧,5xx 的 JSON 一样被覆盖。""" + + async def __call__(self, scope, receive, send): + if scope["type"] != "http" or \ + "gzip" not in Headers(scope=scope).get("accept-encoding", "").lower(): + await self.app(scope, receive, send) # 客户端不收 gzip ⇒ 原样给,绝不冒充 + return + await _GzipByContentType(self.app, self.minimum_size, + compresslevel=self.compresslevel)(scope, receive, send) + + +# 三条用户中间件从外到内:CORS → 鉴权 → 按 content-type 的 gzip。 +# `add_middleware` 把自己插到最外层 ⇒ 压缩层必须**最先**注册,晚一行就跑到了鉴权外面 +# (那一版把 `GZIP_MINIMUM` 整个架空了,见上面)。gzip 只影响响应编码:不改状态码、 +# 不改 body、不改任何业务契约,解压后与原来逐字节相同 +# (`backend/tests/test_api_content_gzip.py` 就是这么断言的)。 +app.add_middleware(ContentTypeGZipMiddleware, minimum_size=GZIP_MINIMUM, compresslevel=GZIP_LEVEL) +# 鉴权排第二、CORS 最后注册坐在最外 ⇒ 401/403 也带 CORS 头, +# 前端才能读到「未登录」而不是一个笼统的网络错误。 app.add_middleware(BaseHTTPMiddleware, dispatch=auth_middleware) app.add_middleware(CORSMiddleware, allow_origins=settings.cors_origin_list or ["*"], @@ -83,6 +175,62 @@ Path(settings.media_root).mkdir(parents=True, exist_ok=True) app.mount(settings.media_url_prefix, StaticFiles(directory=settings.media_root), name="media") +# ------------------------------------------------------------------ 交付面:SPA 静态资源 +# 三条口径放在一起说清楚,免得下一轮又去后端中间件上试: +# ① 带哈希的 chunk 与内容一一对应 ⇒ 让浏览器缓存一年;`index.html` 反过来必须每次回源 +# 校验,否则发版后老标签页拿着旧壳去引已经消失的哈希文件,用户看到的是白屏。 +# ② 文本资源要压:首屏闭包 1 469 kB(`scripts/ui/chunkinfo.mjs`)里 1 144 kB 是一个 +# JS chunk,原文直出等于把已经量好的 gzip 450 kB 按 raw 再发一遍。 +# `compresslevel` 取 6 不取 9——同级产物只差千分之几,CPU 便宜一半(实测见 +# `reports/ui_evidence/nex-p29/serve-ab.log`)。 +# ③ 压缩判据是**响应自己声明的 media type**,不是它挂在哪个路径前缀下:见上面 +# 「交付面:按 content-type 压缩」那一节。`/assets` 这一层仍然自带 gzip +# (阶段 29 的产物证据与 pytest 都钉在它上面;本目录只有 js/css,没有二进制), +# 上面那一层看到已经带 `Content-Encoding` 的响应会原样透传,不会压两遍。 +SPA_ASSET_CACHE = "public, max-age=31536000, immutable" +SPA_SHELL_CACHE = "no-cache" +SPA_GZIP_MINIMUM = 1024 # 小于 1 kB 不值得压(压完加头反而更大) +SPA_GZIP_LEVEL = 6 + + +def with_cache_control(asgi, value: str): + """给子应用的每个响应补一个 `Cache-Control`,上游已经给了就不覆盖。 + + 没用 `StaticFiles(headers=...)`:那个构造参数在 starlette 0.3x 就被删了, + 本项目锁的是 0.46.2,写死之后整个 `/assets` 挂载直接 TypeError。 + 包一层只读 ASGI 的 `http.response.start` 消息,与版本无关, + 也不碰 StaticFiles 自己的 ETag / Range 逻辑。 + """ + async def wrapped(scope, receive, send): + if scope["type"] != "http": + await asgi(scope, receive, send) + return + + async def send_headers(message): + if message["type"] == "http.response.start": + raw = list(message["headers"]) + if not any(k.lower() == b"cache-control" for k, _ in raw): + raw.append((b"cache-control", value.encode("latin-1"))) + message = {**message, "headers": raw} + await send(message) + + await asgi(scope, receive, send_headers) + + return wrapped + + +def spa_assets_app(dist: Path): + """`/assets` 的 ASGI 子应用:StaticFiles + 长期缓存 + gzip。 + + 和 `spa_target()` 一样单独成函数:这段只在 `SERVE_FRONTEND` 打开时注册, + 纯 API 模式的自检一次都跑不到它,测试只能拿函数自己拼一个壳来验。 + """ + files = with_cache_control(StaticFiles(directory=dist / "assets"), SPA_ASSET_CACHE) + return GZipMiddleware(files, minimum_size=SPA_GZIP_MINIMUM, compresslevel=SPA_GZIP_LEVEL) + + + + # ------------------------------------------------------------------ 前端产物托管 # 判定逻辑在 app/config.py:Settings.frontend_dist —— 鉴权中间件要问同一个问题, # 而 api 是被本模块反向导入的,放这里会撞循环导入。 @@ -121,11 +269,13 @@ if FRONTEND_DIST is not None: # React Router 用的是 history 模式(browser history),/projects/3 这类深链在磁盘上没有对应文件, # 必须回 index.html 交给前端路由,否则用户刷新一次就 404。 if (FRONTEND_DIST / "assets").is_dir(): - app.mount("/assets", StaticFiles(directory=FRONTEND_DIST / "assets"), name="spa-assets") + app.mount("/assets", spa_assets_app(FRONTEND_DIST), name="spa-assets") @app.get("/{full_path:path}", include_in_schema=False) async def spa(full_path: str) -> FileResponse: - return FileResponse(spa_target(FRONTEND_DIST, full_path)) + # 壳每次回源校验(见 §交付面 ①);带哈希的 chunk 走上面那条挂载长期缓存。 + return FileResponse(spa_target(FRONTEND_DIST, full_path), + headers={"Cache-Control": SPA_SHELL_CACHE}) logger.info("前端产物已托管:%s(SERVE_FRONTEND=%s)", FRONTEND_DIST, settings.serve_frontend) diff --git a/backend/tests/test_api_content_gzip.py b/backend/tests/test_api_content_gzip.py new file mode 100644 index 0000000..69b779b --- /dev/null +++ b/backend/tests/test_api_content_gzip.py @@ -0,0 +1,235 @@ +"""交付面:按 content-type 的 gzip(阶段 30)。 + +立项依据(阶段 29 两把尺):首访过网 1 292 834 B 里 `/api` 占 773 646 B,是当时唯一没压的一族; +但同一个路径前缀下 JSON 能省 83.4 %、`thumb/*.png` 反而 +1.1 % ⇒ 判据只能是 media type, +不能是路径前缀。所以这里逐条锁死「什么被压、什么必须原样、压完必须等价」: + + · 文本族(JSON / CSV / 纯文本导出 / SVG / JS)达阈值 ⇒ gzip; + · 二进制(PNG 缩略图、video/mp4 交付片)⇒ **一个字节都不许动**, + 尤其是 mp4:Starlette 压完会删 `Content-Length`,播放器靠它算 Range 进度条; + · 阈值以下、客户端不收 gzip、上游已经压过 ⇒ 原样透传,绝不冒充 `Content-Encoding`; + · 压完解压回来必须与原文逐字节相同,`Vary` 必须含 accept-encoding(否则中间缓存会串味)。 + +与被测代码同一把尺的常量从 `app.main` 导入,不在这儿抄第二份数字。 +""" +from __future__ import annotations + +import gzip + +import pytest +from fastapi import FastAPI, Request +from fastapi.responses import (FileResponse, JSONResponse, PlainTextResponse, Response, + StreamingResponse) +from fastapi.testclient import TestClient + +from app.main import (GZIP_LEVEL, GZIP_MINIMUM, ContentTypeGZipMiddleware, + gzip_eligible) + +# 中文正文:JSON 里带 CJK 时 gzip 的相对收益更高(UTF-8 一个汉字 3 B),与真实列表接口同形状 +BIG = ('{"shots":[' + '{"title":"深夜面馆","line":"最后一盏灯"},' * 400 + "]}").encode("utf-8") +SMALL = b'{"ok":true}' +# 已压过的位图:gzip 它只会变大(阶段 29 实测 +1.1 %),拿真实字节形状做断言 +WEBP = b"RIFF" + (36 + 4096).to_bytes(4, "little") + b"WEBPVP8 " + bytes(range(256)) * 16 + + +@pytest.fixture() +def client(tmp_path): + """一个只装被测中间件的小 app:形状对齐真实端点,不牵进鉴权与数据库。""" + app = FastAPI() + app.add_middleware(ContentTypeGZipMiddleware, minimum_size=GZIP_MINIMUM, + compresslevel=GZIP_LEVEL) + + png = tmp_path / "thumb.png" + # 高度不可压的二进制(gzip 压它只会变大),模拟 /api/media/thumb/*.png + png.write_bytes(bytes(range(256)) * 400) + mp4 = tmp_path / "final.mp4" + mp4.write_bytes(bytes(range(256)) * 200) + + @app.get("/api/projects") + def projects(): # 大 JSON:/api/projects 的形状 + return JSONResponse({"raw": BIG.decode()}) + + @app.get("/api/meta") + def meta(): + return JSONResponse({"options": ["x"], "ok": True}) + + @app.get("/api/export.csv") + def csv_export(): + return PlainTextResponse(BIG.decode(), media_type="text/csv; charset=utf-8") + + @app.get("/api/thumb.png") + def thumb(): + return FileResponse(png, media_type="image/png") + + @app.get("/api/download.mp4") + def download(): + return FileResponse(mp4, media_type="video/mp4") + + @app.get("/api/tiny") + def tiny(): + return Response(SMALL, media_type="application/json") + + @app.get("/api/pre-encoded") + def pre_encoded(): + return Response(gzip.compress(SMALL), media_type="application/json", + headers={"Content-Encoding": "gzip", + "Content-Length": str(len(gzip.compress(SMALL)))}) + + @app.post("/api/no-content") + def no_content(): + return Response(status_code=204) + + @app.get("/api/stream") + def stream(): + return JSONResponse({"a": 1}, headers={"Content-Type": "text/event-stream"}) + + @app.get("/api/stream-json") + def stream_json(): + # 与真实接口的唯一差别就是分块:用来暴露 minimum_size 在流式下不生效 + return StreamingResponse(iter([SMALL]), media_type="application/json") + + @app.get("/api/stream-webp") + def stream_webp(): + return StreamingResponse(iter([WEBP]), media_type="image/webp") + + return TestClient(app) + + +def gz(r): + return r.headers.get("content-encoding", "") + + +def accept_gzip(): + return {"Accept-Encoding": "gzip, deflate, br"} + + +# ---------------------------------------------------------------- 该压的必须压 +def test_large_json_is_gzipped_and_decodes_identical(client): + r = client.get("/api/projects", headers=accept_gzip()) + assert r.status_code == 200 + assert gz(r) == "gzip", "大 JSON 没压 ⇒ 首屏最大的一笔字节白过网" + assert "accept-encoding" in r.headers.get("vary", "").lower(), "缺 Vary ⇒ 共享缓存会把 gzip 发给不收它的客户端" + assert r.json() == {"raw": BIG.decode()}, "解压后必须与原文等价" + + +def test_text_exports_are_gzipped(client): + r = client.get("/api/export.csv", headers=accept_gzip()) + assert gz(r) == "gzip" + assert r.content == BIG + + +# ---------------------------------------------------------------- 不该压的一律别动 +def test_png_thumbnail_is_untouched(client): + """缩略图压完是 +1.1 %(阶段 29 实测),而且会丢掉 Content-Length。""" + r = client.get("/api/thumb.png", headers=accept_gzip()) + assert gz(r) == "" + assert int(r.headers["content-length"]) == len(r.content) == 400 * 256 + + +def test_video_range_request_keeps_content_length_and_status(client): + """播放器 seek:206 + Content-Range + 切片长度,一个头都不能被压缩层动过。""" + r = client.get("/api/download.mp4", headers=dict(accept_gzip(), Range="bytes=100-199")) + assert r.status_code == 206 + assert gz(r) == "" + assert r.headers["content-range"] == "bytes 100-199/51200" + assert int(r.headers["content-length"]) == 100 == len(r.content) + assert r.headers.get("accept-ranges") == "bytes" + + +def test_small_response_below_threshold_is_not_compressed(client): + r = client.get("/api/tiny", headers=accept_gzip()) + assert gz(r) == "" and r.content == SMALL + assert int(r.headers["content-length"]) == len(SMALL) + + +def test_client_without_gzip_support_gets_identity(client): + """不收 gzip 的客户端必须拿到原文,且**不能**看到 content-encoding。""" + r = client.get("/api/projects", headers={"Accept-Encoding": "identity"}) + assert gz(r) == "" + assert r.json() == {"raw": BIG.decode()} + assert int(r.headers["content-length"]) == len(r.content) + + +def test_already_encoded_response_is_not_double_compressed(client): + """`/assets` 那一层自带 gzip,外层必须认出来并透传(叠两层 = 解压只剥一层)。""" + r = client.get("/api/pre-encoded", headers=accept_gzip()) + assert r.headers["content-encoding"].lower().count("gzip") == 1 + assert r.json() == {"ok": True} + + +def test_204_has_no_body_and_no_encoding(client): + r = client.post("/api/no-content", headers=accept_gzip()) + assert r.status_code == 204 and gz(r) == "" and r.content == b"" + + +def test_event_stream_is_never_buffered(client): + """SSE 攒成块就失去实时性(本仓现在没有,但判据要挡住将来加的人)。""" + r = client.get("/api/stream", headers=accept_gzip()) + assert gz(r) == "" + + +# ------------------------------------------------- 流式分支:minimum_size 管不到,只有 media type 管得到 +# 阶段 30 的 A/B(`reports/ui_evidence/nex-p30/apigate.log`)在真 app 上量到的: +# `/api/exports/77` 只有 742 B、字幕 834 B,都在阈值以下却仍然被压了。 +# 原因在 starlette 0.46.2 `gzip.py`:`minimum_size` 只挡「一条 body 消息且 more_body=False」 +# 的一次性响应;真 app 的路由都坐在鉴权 `BaseHTTPMiddleware` 里面,它的 body 是分块转发的 +# (首条 more_body=True)⇒ 走流式分支,不看体积。 +# 这不是缺陷(量到的每条小 JSON 都还是变小了:742→497、834→458),但意味着 +# **二进制的安全完全靠 content-type 判据,体积阈值保护不了它** —— 下面两条把这个语义钉住。 +def test_streaming_small_json_is_compressed_documents_threshold_semantics(client): + """流式小 JSON:体积阈值不生效,照样压(与真 app 里 742 B 的 /api/exports/77 同形)。""" + r = client.get("/api/stream-json", headers=accept_gzip()) + assert gz(r) == "gzip" + assert r.content == SMALL + + +def test_streaming_webp_thumbnail_is_still_untouched(client): + """缩略图走的正是流式:压不压只由 media type 决定,这条是二进制的安全边界。 + + 这里不比具体的 Content-Length(`StreamingResponse` 本来就不发它,真 thumb 路由用的 + `FileResponse` 才发),比的是**同一个端点在两种 Accept-Encoding 下头必须一模一样**: + 压缩层对不该压的响应必须完全隐形,一个头都不许多加、不许改写。 + """ + a = client.get("/api/stream-webp", headers=accept_gzip()) + b = client.get("/api/stream-webp", headers={"Accept-Encoding": "identity"}) + assert gz(a) == "", "流式二进制被压 ⇒ thumb 白烧 CPU 还变大" + assert a.content == WEBP == b.content + assert dict(a.headers) == dict(b.headers), "压缩层动了不该动的响应头" + + +# ---------------------------------------------------------------- 判据本身 +@pytest.mark.parametrize("ct,want", [ + ("application/json", True), + ("application/json; charset=utf-8", True), + ("text/plain; charset=utf-8", True), + ("text/csv; charset=utf-8", True), + ("text/html", True), + ("application/javascript", True), + ("image/svg+xml", True), + ("text/event-stream", False), + ("image/png", False), + ("video/mp4", False), + ("audio/mpeg", False), + ("application/zip", False), + ("application/octet-stream", False), + ("", False), +]) +def test_gzip_eligible_matrix(ct, want): + assert gzip_eligible(ct) is want + + +def test_registered_inside_auth_so_the_size_threshold_is_real(): + """小 app 证明行为,这一条钉真 app 的挂载位置:**压缩层在鉴权之内**, + 不是越靠外越好。 + + 阶段 30 先把它挂在最外层,结果 `BaseHTTPMiddleware` 的分块转发让每一个响应 + 都以 `more_body=True` 进来 ⇒ `GZIP_MINIMUM` 整体失效,4 个 <1 kB 的哈希 chunk + 被压(A/B 读数 `reports/ui_evidence/nex-p30/servecheck.log`),与项目自己声明的 + 1 kB 底线(`SPA_GZIP_MINIMUM`、nginx `gzip_min_length`)冲突。顺序写反就是回归。 + """ + from app.main import app + from starlette.middleware.base import BaseHTTPMiddleware + from fastapi.middleware.cors import CORSMiddleware + + chain = [m.cls for m in app.user_middleware] + assert chain == [CORSMiddleware, BaseHTTPMiddleware, ContentTypeGZipMiddleware], chain diff --git a/backend/tests/test_spa_history_fallback.py b/backend/tests/test_spa_history_fallback.py index e7ed148..be5eb01 100644 --- a/backend/tests/test_spa_history_fallback.py +++ b/backend/tests/test_spa_history_fallback.py @@ -13,7 +13,7 @@ from fastapi.responses import FileResponse from fastapi.testclient import TestClient from app.config import settings -from app.main import spa_target +from app.main import (SPA_ASSET_CACHE, SPA_SHELL_CACHE, spa_assets_app, spa_target) @pytest.fixture() @@ -23,6 +23,9 @@ def dist(tmp_path): (build / "assets").mkdir(parents=True) (build / "index.html").write_text("