Split logging: prose event stream vs structured JSONL access stream

Rule: bulk per-request data never lands in the prose log; everything with
analysis value goes to a structured file.

- Event stream (stderr, text): startup summary, warnings, tracebacks --
  what supervisord/journald already captures. Human-readable, low volume.
- Access stream: one JSONL record per request (plus a "startup" meta
  record with the instance config) written to BGFILTER_ACCESS_LOG,
  app-rotated 50MB x 5; falls back to stderr when unset (dev).
  Failed requests carry a truncated `exc` copy so the access file is
  self-contained; the full traceback stays in the event stream, joined
  by request_id.
- BGFILTER_LOG_FORMAT retired: format is now a property of the stream,
  not a global switch.
- uvicorn runs with --no-access-log everywhere (deploy script + unit
  examples): its prose per-request lines duplicated a subset of ours.
- deploy_autodl.sh --log-dir now provisions both files; docs updated
  (EN+ZH: env table, AutoDL section, run/systemd examples).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

DEPLOY_ZH.md

@@ -34,7 +34,7 @@ scripts/deploy_autodl.sh --token <TOKEN>
 | `--open` | — | 显式删除 token、以开放模式运行（无鉴权）。 |
 | `--port <PORT>` | `6006` | 容器内监听端口（对应 AutoDL 的公网映射端口）。 |
 | `--config <cfg>` | `configs/gpu.yaml` | 流水线配置。 |
-| `--log-dir <dir>` | `~/autodl-tmp` | 服务日志 `bgfilter.log` 所在目录。默认落在 AutoDL 持久数据盘 `~/autodl-tmp`（容器重置不丢），而非 `/tmp`。 |
+| `--log-dir <dir>` | `~/autodl-tmp` | 日志目录（默认 AutoDL 持久数据盘——容器重置不丢，`/tmp` 会丢）。含 `bgfilter.log`（散文事件日志）和 `bgfilter-access.jsonl`（结构化每请求日志，应用自轮转）。 |
 
 **前提**：仓库已 checkout（脚本不 `git pull`）、root 用户、torch/CUDA 由 AutoDL 镜像提供、
 python 在 `/root/miniconda3`。
@@ -56,8 +56,9 @@ $S stop bgfilter        # 停服务（supervisord 本身继续跑）
 $S start bgfilter       # 再启动
 $S shutdown             # 全部停掉，包括 supervisord 自己
 
-tail -f ~/autodl-tmp/bgfilter.log   # 服务日志（目录由 --log-dir 决定）
-tail -f ~/supervisord.log           # supervisord 自己的日志（服务起不来时看这个）
+tail -f ~/autodl-tmp/bgfilter.log            # 事件日志:启动/告警/堆栈（散文）
+tail -f ~/autodl-tmp/bgfilter-access.jsonl   # 访问日志:每请求一条 JSON 记录
+tail -f ~/supervisord.log                    # supervisord 自己的日志（服务起不来时看）
 ```
 
 若 supervisord 本身没在跑——容器刚重启还没开过 shell，或报 socket 残留错误——照
@@ -257,8 +258,8 @@ export HF_HUB_DISABLE_XET=1                 # 这些 repo 是 Xet 存储；强
 | `BGFILTER_CONFIG` | `configs/default.yaml` | 管线配置文件 |
 | `BGFILTER_DEVICE` | `cpu` | 同时覆盖 model 和 segmentation 的 device（GPU 用 `cuda`）|
 | `BGFILTER_MAX_IMAGE_PIXELS` | `4194304` | 超过则返回 `413`（约 4 MP）|
-| `BGFILTER_LOG_FORMAT` | `text` | `text`（人读）或 `json`（每行一条结构化对象,便于日志采集）。每请求打一行访问日志,含 `request_id`、参数、分阶段耗时（`t_queue/fetch/decode/process/total_ms`）;该 id 同时以 `X-Request-ID` 响应头返回。 |
-| `BGFILTER_LOG_LEVEL` | `INFO` | 根日志级别。 |
+| `BGFILTER_ACCESS_LOG` | — | **结构化访问日志**的路径（JSONL,每请求一条记录 + 一条 `startup` 元记录;应用自轮转,50 MB × 5）。字段:`request_id`、参数、尺寸、分阶段耗时（`t_queue/fetch/decode/process/total_ms`）、状态码、失败时截断的 `exc`;该 id 同时以 `X-Request-ID` 响应头返回。不设置 = 记录回退到 stderr（开发用）。散文**事件日志**（启动/告警/堆栈）始终走 stderr 由 supervisord/journald 捕获——每请求数据绝不落在散文流里。 |
+| `BGFILTER_LOG_LEVEL` | `INFO` | 根日志级别（事件流）。 |
 | `BGFILTER_FETCH_MAX_BYTES` | `26214400` | `image_url` 模式：下载体上限（约 25 MB）→ `413`。无 SSRF 过滤——务必开鉴权 / 调用方可信。 |
 | `BGFILTER_FETCH_TIMEOUT` | `15` | `image_url` 模式：fetch 读超时（秒；连接超时固定 5 秒）。出站 fetch 并发固定为 `2 × cpu_workers`（硬顶 64）。 |
 | `BGFILTER_PRELOAD` | `1` | 启动时预加载默认模型（首个请求不用冷加载）|
@@ -299,12 +300,15 @@ export HF_HUB_DISABLE_XET=1                 # 这些 repo 是 Xet 存储；强
 ## 7. 运行服务
 
 ```bash
-python -m uvicorn app:app --host 127.0.0.1 --port 18083 --workers 1
+BGFILTER_ACCESS_LOG=logs/bgfilter-access.jsonl \
+python -m uvicorn app:app --host 127.0.0.1 --port 18083 --workers 1 --no-access-log
 ```
 
 - **必须保留 `--workers 1`。** 每个 worker 各加载一整套模型，多 worker 会成倍占内存
   （8 GB 机器会 OOM）。服务已用全局锁串行化推理。
 - `--host 127.0.0.1` 只对本机开放（面向同机调用方）。跨机访问见 §10。
+- `--no-access-log` 关掉 uvicorn 自己的散文版每请求日志——它是应用结构化访问记录
+  （§6 `BGFILTER_ACCESS_LOG`）的子集、纯重复，且每请求数据不该进散文流。
 
 ## 8. 作为 systemd 服务运行
 
@@ -327,9 +331,10 @@ Environment=BGFILTER_CONFIG=configs/default.yaml
 Environment=BGFILTER_DEVICE=cpu
 Environment=BGFILTER_MAX_IMAGE_PIXELS=4194304
 Environment=BGFILTER_PRELOAD=1
+Environment=BGFILTER_ACCESS_LOG=/opt/genarrative-image-host/bgfilter-service/logs/bgfilter-access.jsonl
 Environment=OMP_NUM_THREADS=4
 Environment=MKL_NUM_THREADS=4
-ExecStart=/opt/genarrative-image-host/bgfilter-service/.venv/bin/uvicorn app:app --host 127.0.0.1 --port 18083 --workers 1
+ExecStart=/opt/genarrative-image-host/bgfilter-service/.venv/bin/uvicorn app:app --host 127.0.0.1 --port 18083 --workers 1 --no-access-log
 Restart=on-failure
 RestartSec=5
 MemoryMax=8G