docs(runbook): test qBittorrent override example for SIM-1

Co-Authored-By: Claude Opus 5.5 <[email protected]>

docs/runbook/deploy.md

@@ -234,3 +234,41 @@ services:
 ```
 
 防火墙只放行 docker 网段:`ufw allow from 172.16.0.0/12 to 172.17.0.1 port 7891 proto tcp`。compose 默认网络已固定在 `UMT_SUBNET`(缺省 172.30.0.0/24,与本机其他网络冲突时在 `.env.deploy` 改成 172.16.0.0/12 内的空闲网段,如 172.16.80.0/24),否则 compose 自动分配的 192.168.x 网段不在放行范围内。Deno 的 fetch 会读 `HTTP(S)_PROXY`/`NO_PROXY`;TMDB、境外 Pi 上游、camofox 访问境外站都经此代理,站内(postgres/camofox)不走代理。
+
+## 测试用 qB(override 示例)
+
+只用于本地模拟"下载完成 → 自动整理"(SIM-1):qB 与 app 共用 compose 网络,app 经 `http://qbittorrent:8080` 访问;不映射公网端口,本机调试只绑 `127.0.0.1:8081`。写在本机 `docker-compose.override.yml`(不进 git):
+
+```yaml
+services:
+  app:
+    environment:
+      # 配了 HTTP(S)_PROXY 时必须把 qbittorrent 加进 NO_PROXY:Deno 按主机名匹配,不会因解析到内网 IP 而直连
+      NO_PROXY: localhost,127.0.0.1,postgres,camofox,proxy-relay,qbittorrent,10.0.0.0/8,172.16.0.0/12,192.168.0.0/16
+  qbittorrent:
+    image: lscr.io/linuxserver/qbittorrent:5.1.2   # 5.2.x 登录返回 204 + QBT_SID_<port> cookie,当前适配器不兼容
+    restart: unless-stopped
+    environment: { PUID: "10001", PGID: "10001", TZ: Asia/Shanghai, WEBUI_PORT: "8080" }
+    volumes:
+      - /opt/umt-demo/downloads:/downloads          # 与 app 挂同一路径,路径映射 /downloads ↔ /downloads
+      - umt-qb-config:/config
+    ports:
+      - "127.0.0.1:8081:8080"
+volumes:
+  umt-qb-config:
+```
+
+```sh
+docker compose --env-file .env.deploy --profile tls up -d --no-deps qbittorrent      # 只起 qB
+docker compose --env-file .env.deploy --profile tls logs qbittorrent | grep 'temporary password'   # 首次启动的临时密码
+# 改 NO_PROXY 后只重建 app 容器、不重建镜像(APP_VERSION 与当前运行镜像一致):
+APP_VERSION=<当前版本> docker compose --env-file .env.deploy --profile tls up -d --no-deps --no-build app
+```
+
+- 本机经 8081 访问时 qB 的 Host 头校验要求端口与 `WEBUI_PORT` 一致:curl 加 `-H 'Host: localhost:8080'`,否则 401。
+- 用临时密码登录后 `POST /api/v2/app/setPreferences`:`web_ui_password`(随机强密码,存本机凭据文件)、`save_path=/downloads`、
+  `dht/pex/lsd/upnp=false`、`up_limit`/`dl_limit` 限速、`auto_tmm_enabled=false`、`torrent_content_layout=Original`。
+- 控制台登记:下载器实例 `http://qbittorrent:8080`、管理标签 `umt`、`settings.savePath=/downloads`;路径映射 downloader `/downloads` ↔ `/downloads`;
+  自动整理要求库根为 `managed`(`register_only` 时 `no_library_root`)。
+- 模拟完成:按发布名把样片放进下载目录,用真实 piece 哈希做种子(testkit `makeTorrent` 的 pieces 是伪值,qB 校验不到 100%),
+  带标签 `umt` 加入 qB,校验后即 100% 做种,`downloads.sync` 接管。