Document AutoDL deploy path; harden its token/log handling

Add a section 0 to DEPLOY.md/DEPLOY_ZH.md covering the AutoDL one-click path (supervisord, not systemd), which was previously only self-documented in scripts/deploy_autodl.sh. deploy_autodl.sh: - --log-dir (default ~/autodl-tmp, the persistent data disk) so the service log no longer lands in /tmp, which AutoDL wipes on container reset. - Re-running without --token now REUSES an existing token instead of deleting it, so tweaking an unrelated knob can't silently disable auth; add --open to explicitly run without auth. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-07-17 04:19:10 +00:00
parent dc4badd0e0
commit 755e5fda44
3 changed files with 139 additions and 12 deletions
@@ -9,6 +9,63 @@ deployment (the default); GPU notes are called out where relevant.
 The service entry point is `app.py` (`uvicorn app:app`). See [README.md](README.md)
 for the API contract and algorithm details.

+Sections 1–12 below are the **manual CPU deploy** (systemd + nginx, the default).
+If you are deploying to an **AutoDL GPU box**, the one-click script in section 0 is
+faster; the two are independent deployment paths.
+
+---
+
+## 0. Fast path: AutoDL one-click deploy (GPU)
+
+On an AutoDL GPU instance, use the repo's bundled one-click script instead of the
+manual dependency install / systemd setup:
+
+```bash
+# Assumes the repo is already checked out on the instance (the script does NOT
+# git pull); use the server-edition branch.
+cd /root/BGfilter-server            # your actual path
+scripts/deploy_autodl.sh --token <TOKEN>
+```
+
+The script **idempotently** installs deps + fetches model weights + installs the
+CuPy wheel matching the CUDA version (GPU foreground compositing) + starts a
+**supervisord** instance (crash auto-restart) + adds an interactive-login
+autostart to `~/.bashrc`, then launches the service and verifies `/healthz`.
+
+Arguments:
+
+| Argument | Default | Meaning |
+| --- | --- | --- |
+| `--token <TOKEN>` | none | Auth token; sets/updates the `X-Genarrative-Image-Token` requirement. **Omitting it reuses an existing token** (re-running to tweak another knob won't drop auth); only a first run with no token starts OPEN. |
+| `--open` | — | Explicitly remove the token and run OPEN (no auth). |
+| `--port <PORT>` | `6006` | In-container listen port (matches the AutoDL public port mapping). |
+| `--config <cfg>` | `configs/gpu.yaml` | Pipeline config. |
+| `--log-dir <dir>` | `~/autodl-tmp` | Directory for the service log `bgfilter.log`. Defaults to the AutoDL persistent data disk `~/autodl-tmp` (survives container resets, unlike `/tmp`). |
+
+**Assumes**: repo already checked out (no `git pull`), root user, torch/CUDA
+provided by the AutoDL image, python at `/root/miniconda3`.
+
+**Two AutoDL-inherent gotchas** (the script can't fix these):
+
+- The **public URL mapping** (e.g. `6006 → https://...:8443`) is set in the
+  **AutoDL web console**, not by this script.
+- **After a container restart** the service does not come back on its own — AutoDL
+  has no systemd / boot hook, so the autostart lives in `~/.bashrc` and only fires
+  when you open an **interactive shell (SSH / JupyterLab terminal)**.
+
+Talking to supervisord (socket at `~/bgfilter-supervisor.sock`, config at
+`~/supervisord.conf`):
+
+```bash
+/root/miniconda3/bin/supervisorctl -c ~/supervisord.conf status bgfilter   # status
+/root/miniconda3/bin/supervisorctl -c ~/supervisord.conf restart bgfilter  # restart
+tail -f ~/autodl-tmp/bgfilter.log                                           # logs (default ~/autodl-tmp)
+```
+
+> After editing `configs/*.yaml` (e.g. enabling `cross_check.reuse_as_seg`), run
+> the `restart bgfilter` above so the service reloads config — config is read only
+> at startup; there is no per-request switch for it.
+
 ---

 ## 1. Prerequisites
@@ -7,6 +7,55 @@

 服务入口是 `app.py`（`uvicorn app:app`）。API 契约和算法细节见 [README.md](README.md)。

+下面第 1–12 节是**手动 CPU 部署**（systemd + nginx，推荐默认）。如果你部署在
+**AutoDL GPU 盒子**上，走第 0 节的一键脚本更快；两者是各自独立的部署路线。
+
+---
+
+## 0. 快速路径：AutoDL 一键部署（GPU）
+
+在 AutoDL GPU 实例上，用仓库自带的一键脚本部署，无需手动装依赖 / 配 systemd：
+
+```bash
+# 假设仓库已 checkout 到实例（脚本不会 git pull），使用 server-edition 分支
+cd /root/BGfilter-server            # 你的实际路径
+scripts/deploy_autodl.sh --token <TOKEN>
+```
+
+脚本**幂等**地完成：装依赖 + 拉模型权重 + 按 CUDA 版本装对应 CuPy（GPU 前景合成）
+ 起一个 **supervisord** 实例（崩溃自动重启）+ 往 `~/.bashrc` 写交互登录自启，
+最后启动服务并校验 `/healthz`。
+
+参数：
+
+| 参数 | 默认 | 说明 |
+| --- | --- | --- |
+| `--token <TOKEN>` | 无 | 鉴权 token，设置/更新后 `/remove-background` 要求 header `X-Genarrative-Image-Token`。**省略则沿用已有 token**（重跑改别的参数不会误关鉴权）；只有首次无 token 才开放。 |
+| `--open` | — | 显式删除 token、以开放模式运行（无鉴权）。 |
+| `--port <PORT>` | `6006` | 容器内监听端口（对应 AutoDL 的公网映射端口）。 |
+| `--config <cfg>` | `configs/gpu.yaml` | 流水线配置。 |
+| `--log-dir <dir>` | `~/autodl-tmp` | 服务日志 `bgfilter.log` 所在目录。默认落在 AutoDL 持久数据盘 `~/autodl-tmp`（容器重置不丢），而非 `/tmp`。 |
+
+**前提**：仓库已 checkout（脚本不 `git pull`）、root 用户、torch/CUDA 由 AutoDL 镜像提供、
+python 在 `/root/miniconda3`。
+
+**两个 AutoDL 固有的坑**（脚本管不了）：
+
+- **公网 URL 映射**（如 `6006 → https://...:8443`）要在 **AutoDL 网页控制台**里设，脚本不负责。
+- **容器重启后**服务不会自动起来——AutoDL 没有 systemd / 开机钩子，自启写在 `~/.bashrc` 里，
+  需要**开一个交互式 shell（SSH / JupyterLab 终端）** 才会触发拉起。
+
+与 supervisord 打交道（socket 在 `~/bgfilter-supervisor.sock`，配置在 `~/supervisord.conf`）：
+
+```bash
+/root/miniconda3/bin/supervisorctl -c ~/supervisord.conf status bgfilter   # 状态
+/root/miniconda3/bin/supervisorctl -c ~/supervisord.conf restart bgfilter  # 重启
+tail -f ~/autodl-tmp/bgfilter.log                                           # 日志（默认 ~/autodl-tmp）
+```
+
+> 改了 `configs/*.yaml`（比如开 `cross_check.reuse_as_seg`）后，用上面的 `restart bgfilter`
+> 让服务重新加载配置——配置只在启动时读入，没有请求级开关。
+
 ---

 ## 1. 前置条件
@@ -6,11 +6,18 @@
 # then starts the service and verifies /healthz.
 #
 # Usage:
-#   scripts/deploy_autodl.sh [--token <TOKEN>] [--port <PORT>] [--config <cfg>]
-#     --token   auth token; sets the X-Genarrative-Image-Token requirement.
-#               Omit to run OPEN (no auth) -- a warning is printed.
-#     --port    public-mapped container port (default 6006).
-#     --config  pipeline config (default configs/gpu.yaml).
+#   scripts/deploy_autodl.sh [--token <TOKEN>] [--open] [--port <PORT>]
+#                            [--config <cfg>] [--log-dir <dir>]
+#     --token    auth token; sets/updates the X-Genarrative-Image-Token
+#                requirement. Omitting it REUSES an existing token (a re-run to
+#                tweak another knob won't drop auth); only a first run with no
+#                token starts OPEN.
+#     --open     explicitly remove the token and run OPEN (no auth).
+#     --port     public-mapped container port (default 6006).
+#     --config   pipeline config (default configs/gpu.yaml).
+#     --log-dir  directory for bgfilter.log (default ~/autodl-tmp, the AutoDL
+#                persistent data disk; unlike /tmp it survives container resets).
+#                File is <dir>/bgfilter.log.
 #
 # Assumes: the repo is already checked out (this script does NOT git pull), root
 # user, torch/CUDA provided by the AutoDL image, python at /root/miniconda3.
@@ -25,13 +32,17 @@ set -euo pipefail

 # ---- args ----
 TOKEN=""
+OPEN=0
 PORT=6006
 CONFIG="configs/gpu.yaml"
+LOG_DIR="$HOME/autodl-tmp"
 while [ $# -gt 0 ]; do
  case "$1" in
-    --token)  TOKEN="${2:-}"; shift 2;;
-    --port)   PORT="${2:-}"; shift 2;;
-    --config) CONFIG="${2:-}"; shift 2;;
+    --token)   TOKEN="${2:-}"; shift 2;;
+    --open)    OPEN=1; shift;;
+    --port)    PORT="${2:-}"; shift 2;;
+    --config)  CONFIG="${2:-}"; shift 2;;
+    --log-dir) LOG_DIR="${2:-}"; shift 2;;
    -h|--help) sed -n '2,30p' "$0" | sed 's/^# \?//'; exit 0;;
    *) echo "unknown arg: $1" >&2; exit 1;;
  esac
@@ -48,9 +59,12 @@ TOKEN_FILE="$HOME/.bgfilter_token"
 RUN_WRAPPER="$HOME/bgfilter_run.sh"
 SUP_CONF="$HOME/supervisord.conf"
 SUP_SOCK="$HOME/bgfilter-supervisor.sock"
-LOG=/tmp/bgfilter.log
+# Service log: persistent by default ($HOME survives, /tmp does not on AutoDL).
+# Override the directory with --log-dir; the file is always <dir>/bgfilter.log.
+mkdir -p "$LOG_DIR"
+LOG="$LOG_DIR/bgfilter.log"

-echo "[deploy] app_dir=$APP_DIR python=$PY port=$PORT config=$CONFIG"
+echo "[deploy] app_dir=$APP_DIR python=$PY port=$PORT config=$CONFIG log=$LOG"

 # ---- 1. detect CUDA -> pick the matching cupy wheel (GPU foreground) ----
 CUDA_VER="$("$PY" -c 'import torch;print(torch.version.cuda or "")' 2>/dev/null || echo "")"
@@ -78,12 +92,19 @@ echo "[deploy] fetching weights..."
 ( cd "$APP_DIR" && "$PY" scripts/fetch_weights.py )

 # ---- 4. auth token ----
+# --token sets/updates the token; --open explicitly removes it (service OPEN).
+# With neither, an existing token is REUSED (so re-running to tweak an unrelated
+# knob never silently drops auth); only a first run with no token starts OPEN.
 if [ -n "$TOKEN" ]; then
  printf '%s' "$TOKEN" > "$TOKEN_FILE"; chmod 600 "$TOKEN_FILE"
  echo "[deploy] auth ENABLED (token -> $TOKEN_FILE, chmod 600)"
-else
+elif [ "$OPEN" = 1 ]; then
  rm -f "$TOKEN_FILE"
-  echo "[deploy] WARN: no --token -> service is OPEN (no auth)"
+  echo "[deploy] auth DISABLED via --open (service is OPEN, no auth)"
+elif [ -f "$TOKEN_FILE" ]; then
+  echo "[deploy] reusing existing token ($TOKEN_FILE); pass --open to disable auth"
+else
+  echo "[deploy] WARN: no token -> service is OPEN (no auth); pass --token to enable"
 fi

 # ---- 5. launch wrapper (exec so supervisord tracks the uvicorn PID) ----