Configure mainland build mirrors and persist BuildKit apt and pip caches

README.md

@@ -237,3 +237,50 @@ Gallery supports read-only NAS folders and HTTPS WebDAV sources, random photo
 preview, and device-bound scheduled random photos. Source definitions are persisted
 in SQLite. See [setup and limits](docs/PHOTO_SOURCES.md).
 NAS 本地目录需要显式只读挂载；网盘先支持通用 WebDAV，也可使用同步到 NAS 的目录。
+
+### Build networking and cache
+
+The Dockerfile retains the pinned Python base, locked Python dependencies,
+`fonts-noto-cjk`, Debian repository signature checks, and offline artifact
+SHA256 verification. Both production and CI use `scripts/build-verify.sh`,
+which enables BuildKit and retains `docker compose build --pull`.
+
+APT mirror hosts are configurable through `DEBIAN_MIRROR` and
+`DEBIAN_SECURITY_MIRROR` (hosts only, without scheme or path). Defaults are
+`deb.debian.org`; HTTPS is used for both Debian and security repositories.
+For mainland-China NAS builds, use the shared profile:
+
+```sh
+. ./deploy/build-cn.env
+./scripts/build-verify.sh
+```
+
+CI loads this same profile, using Tsinghua TUNA for both repositories unless
+Gitea repository variables `DEBIAN_MIRROR` / `DEBIAN_SECURITY_MIRROR` override
+it. Production may also set the two hosts directly in `.env` when calling the
+build script without the profile. An alternate mainland mirror is
+`mirrors.ustc.edu.cn`; availability and throughput depend on the Runner network.
+No fallback disables signature verification or removes packages.
+
+Layer order stays: pinned base → APT/font dependencies → `requirements.lock`
+→ pip dependencies → application/vendor source → build metadata.
+A source-only change therefore reuses the APT and pip layers, provided the
+same builder, base digest, mirror arguments, and optional offline artifacts
+are used. Changing the lockfile rebuilds pip and later layers, not APT.
+Changing the mirror or APT instructions rebuilds APT and later layers.
+
+Previously an APT layer miss redownloaded indexes/packages, and pip used
+`--no-cache-dir`. Now locked BuildKit mounts retain APT indexes, downloaded
+`.deb` files, and pip downloads/wheels outside the final image. Debian's
+`docker-clean` hook is disabled so it cannot discard cached packages.
+Re-executed APT steps still run `apt-get update` and validate repository
+signatures; cached packages and pip artifacts can avoid repeat large downloads.
+The initial build after this Dockerfile change will miss dependency layers;
+subsequent builds benefit. No measured speedup is claimed before CI completes.
+
+Caches belong to the Docker builder, not the ephemeral CI workspace. Keep the
+NAS Runner's builder storage across jobs; removing the builder, pruning caches,
+or using a fresh Docker daemon loses the benefit. Cache mounts are disposable:
+an empty cache still builds correctly. `--pull` remains enabled; a pinned base
+digest check alone does not invalidate dependency layers. To deliberately
+refresh installed APT versions, use `docker compose build --pull --no-cache`.