Support verified offline wheels and preserve dependency build cache

.gitignore

@@ -18,3 +18,5 @@ dist/
 
 build-cache/debs/*
 !build-cache/debs/.gitkeep
+build-cache/wheels/*
+!build-cache/wheels/.gitkeep

Dockerfile

@@ -1,10 +1,8 @@
 ARG PYTHON_BASE=python:3.14.5-slim-bookworm@sha256:ec58d916f9e24a6035cab2bdf07f6206c4cc092a16613c60597534711332d9d6
 FROM ${PYTHON_BASE}
-ARG BUILD_COMMIT=development
-ARG BUILD_TIME=unknown
 ARG DEBIAN_MIRROR=deb.debian.org
 ENV PYTHONDONTWRITEBYTECODE=1 PYTHONUNBUFFERED=1 TZ=Asia/Shanghai \
-    DATA_DIR=/data CONFIG_DIR=/config BUILD_COMMIT=$BUILD_COMMIT BUILD_TIME=$BUILD_TIME
+    DATA_DIR=/data CONFIG_DIR=/config
 WORKDIR /app
 # CJK fonts intentionally retained for readable Chinese rendering.
 RUN --mount=type=bind,source=build-cache/debs,target=/build-debs,readonly sed -i "s|http://deb.debian.org|https://${DEBIAN_MIRROR}|g" /etc/apt/sources.list.d/debian.sources \
@@ -22,9 +20,16 @@ RUN --mount=type=bind,source=build-cache/debs,target=/build-debs,readonly sed -i
     && mkdir -p /data/images /data/generated /data/cache /config \
     && chown -R 10333:10333 /data /config
 COPY requirements.lock ./
-RUN pip install --no-cache-dir -r requirements.lock
+RUN --mount=type=bind,source=build-cache/wheels,target=/build-wheels,readonly \
+    if [ -f /build-wheels/SHA256SUMS ]; then \
+      (cd /build-wheels && sha256sum -c SHA256SUMS) \
+      && pip install --no-cache-dir --no-index --find-links=/build-wheels -r requirements.lock; \
+    else pip install --no-cache-dir -r requirements.lock; fi
 COPY pigway_frame_flow ./pigway_frame_flow
 COPY vendor ./vendor
+ARG BUILD_COMMIT=development
+ARG BUILD_TIME=unknown
+ENV BUILD_COMMIT=$BUILD_COMMIT BUILD_TIME=$BUILD_TIME
 USER 10333:10333
 EXPOSE 18787
 HEALTHCHECK --interval=30s --timeout=5s --start-period=20s --retries=3 \

docs/NAS.md

@@ -137,3 +137,8 @@ sudo /usr/local/bin/docker compose build --build-arg DEBIAN_MIRROR=mirrors.aliyu
 Optional `build-cache/debs/fonts-noto-cjk.deb` avoids a slow build-network download.
 Dockerfile verifies it against SHA-256 from the GPG-authenticated APT index before use.
 The cache is not a runtime mount or committed dependency, and empty-cache builds work.
+
+Optional `build-cache/wheels/` can hold all 24 Linux AMD64/Python 3.14 wheels
+and `SHA256SUMS`, verified against official PyPI release metadata. Builds verify
+the manifest and use pip `--no-index`; incomplete caches fail explicitly.
+Build commit/time are set after dependency installation to preserve build cache.