backend: check the image rules without a bucket, and accept a scoped key

A least-privilege key — PutObject / GetObject and no ListBucket — gets a 403
from HeadBucket, and reading that as "the bucket is missing" turned a working
key into a 503. The bucket may well be there and simply not be the key's
business, so a refusal to look at it is no longer a failure; the PUT that
follows is the honest test.

`scripts/check_storage.py` covers what a smoke test cannot, because these are
the rules whose failure is silent: the format read from the magic bytes rather
than the client's word, the key pattern the read route serves and nothing
outside it, a caption that cannot break out of the Markdown it is written into,
what is actually asked of MinIO on a write, and the refusals — unconfigured
storage, a key we never wrote, an object that is gone. boto3's client is a stub,
so it needs no credentials, no bucket and no network.

`frontend/scripts/check-image.mjs` is the third layer: bytes can be stored and
returned perfectly while the `<img>` draws nothing. It builds its own PNG
fixture, drives the page and measures what the browser did — the picture
decoded, the figure is centred on the column, `{width=50%}` is half the column,
the 图注 prints under the picture, an image inside a sentence stays inline, and
「插入图片」 ends with the picture in the paper. Run with `pnpm check:image`; it
needs Playwright, which stays out of the app's dependencies.
This commit is contained in:
2026-09-23 19:24:25 +08:00
parent 0e0fde8f02
commit eb0f12b8cf
5 changed files with 667 additions and 2 deletions
+74
View File
@@ -878,12 +878,15 @@ paper-doc/
│ ├── scripts/smoke_images.py # end-to-end check of upload, serve and refusal
│ ├── scripts/check_citation_styles.py # the formatter, one entry per type
│ │ # (no server, no database)
│ ├── scripts/check_storage.py # the image rules: formats, keys, refusals
│ │ # (no server, no bucket)
│ ├── scripts/mcp_server.py # MCP entry point (stdio / http)
│ ├── scripts/smoke_mcp.py # the same loop, spoken over MCP by a real client
│ ├── alembic.ini
│ ├── requirements.txt
│ └── .env.example
├── frontend/ # Vue 3 SPA
│ ├── scripts/check-image.mjs # the browser check: does a figure draw?
│ ├── src/
│ │ ├── api/ # axios instance and endpoint modules
│ │ ├── components/ # shell, field, template, paper and reference
@@ -951,6 +954,31 @@ cd backend
alembic upgrade head
```
**Object storage**
The images a paper embeds live in MinIO, deployed in the same k3s cluster
(namespace `minio`, manifests in `/opt/kubectl/minio/`): the S3 API on NodePort
`30090`, the console on `30091`. From inside the cluster the Service is
`http://minio.minio.svc.cluster.local:9000`.
```bash
# backend/.env — never committed
MINIO_ENDPOINT=http://192.168.1.88:30090
MINIO_ACCESS_KEY=… # a dedicated key, not the MinIO root account
MINIO_SECRET_KEY=…
MINIO_BUCKET=paper-images # created on the first upload if it is absent
```
The bucket stays **private**. Nothing is made public to display a figure: the
API streams the object out of the bucket on `/api/images/{key}`, which is both
what keeps the paper's addresses portable and what keeps the bucket from being a
second, unauthenticated way into the deployment.
A key scoped to objects alone (`PutObject` / `GetObject`, no `ListBucket`) is
enough, and is the better choice: the upload tolerates the `403` that such a key
gets when it checks whether the bucket exists, rather than mistaking it for a
missing bucket.
**Seed data**
`scripts/seed.py` fills the title library with a standard academic outline (20
@@ -1010,6 +1038,52 @@ cd backend
.venv/bin/python scripts/smoke_papers.py
```
**Checking images**
Three scripts, because the feature has three layers that fail differently.
`scripts/check_storage.py` needs nothing running: it replaces boto3's client
with a stub and checks the rules that decide what may be stored and served at
all — the format sniffed from the magic bytes (and SVG refused), the key pattern
that the read route will serve and nothing outside it, the Markdown a caption
may not break out of, what is asked of MinIO on a write, and that a key which is
not allowed to *look* at the bucket still works.
```bash
cd backend
.venv/bin/python scripts/check_storage.py # no server, no bucket
.venv/bin/python scripts/smoke_images.py # against a running API + MinIO
```
`scripts/smoke_images.py` is the end-to-end one: it uploads each accepted
format, fetches every one back byte for byte, checks the refusals (`415` for
text, an SVG and a mislabelled file, `400` for an empty one, `404` for a key
this application never wrote), proves the same bytes are stored once, and writes
a sentence holding a figure through the paper endpoints to show the Markdown
survives them unchanged. Nothing needs cleaning up afterwards, and that is
itself the property under test — a key is the digest of its picture, so a second
run stores the same objects rather than more copies of them.
The third layer is the page, and it is the one neither of the other two can
reach: bytes can be stored and returned perfectly while the `<img>` shows
nothing. `frontend/scripts/check-image.mjs` therefore measures what the browser
did — that the picture decoded (`naturalWidth`), that a figure took a line of
its own and is centred on the column, that `{width=50%}` came out at exactly
half the column, that the 图注 prints *under* the picture, that an image inside a
sentence stayed in that line, and that the editor's 「插入图片」 button ends with
the picture in the paper after saving. It needs Playwright, which is not a
dependency of the app:
```bash
cd frontend
pnpm add -D playwright && npx playwright install chromium
pnpm check:image
# or point at an install that lives elsewhere
PLAYWRIGHT_MODULE=/path/to/playwright/index.mjs pnpm check:image
```
It creates a throwaway paper for the run and deletes it, so it can be pointed at
a database that holds real work.
**Checking the MCP server**
`scripts/mcp_server.py --check` connects to the database once and prints the