feat: Implement multi-stage Docker build for releases, reusing pre-built artifacts from CI and updating documentation.

.dockerignore

@@ -10,7 +10,9 @@ __pycache__
 .Python
 build/
 develop-eggs/
-dist/
+dist/*
+!dist/docker-input/
+!dist/docker-input/*.tar.gz
 downloads/
 eggs/
 .eggs/

.github/workflows/release-artifacts.yml

@@ -87,6 +87,14 @@ jobs:
             rm -rf "${STAGE}"
           done
 
+      - name: Prepare Docker release inputs
+        run: |
+          set -euo pipefail
+          TAG="${RELEASE_TAG}"
+          mkdir -p dist/docker-input
+          cp "dist/ds2api_${TAG}_linux_amd64.tar.gz" "dist/docker-input/linux_amd64.tar.gz"
+          cp "dist/ds2api_${TAG}_linux_arm64.tar.gz" "dist/docker-input/linux_arm64.tar.gz"
+
       - name: Set up QEMU
         uses: docker/setup-qemu-action@v3
 
@@ -136,6 +144,7 @@ jobs:
         with:
           context: .
           file: ./Dockerfile
+          target: runtime-from-dist
           push: true
           platforms: linux/amd64,linux/arm64
           tags: ${{ steps.meta_release.outputs.tags }}
@@ -148,11 +157,13 @@ jobs:
 
           docker buildx build \
             --platform linux/amd64 \
+            --target runtime-from-dist \
             --output type=docker,dest="dist/ds2api_${TAG}_docker_linux_amd64.tar" \
             .
 
           docker buildx build \
             --platform linux/arm64 \
+            --target runtime-from-dist \
             --output type=docker,dest="dist/ds2api_${TAG}_docker_linux_arm64.tar" \
             .
 

DEPLOY.en.md

@@ -135,11 +135,12 @@ docker-compose up -d --build
 
 ### 2.3 Docker Architecture
 
-The `Dockerfile` uses a three-stage build:
+The `Dockerfile` now provides two image paths:
 
-1. **WebUI build stage**: `node:20` image, runs `npm ci && npm run build`
-2. **Go build stage**: `golang:1.24` image, compiles the binary
-3. **Runtime stage**: `debian:bookworm-slim` minimal image
+1. **Default local/dev path (`runtime-from-source`)**: a three-stage build (WebUI build + Go build + runtime).
+2. **Release path (`runtime-from-dist`)**: CI first creates `dist/ds2api_<tag>_linux_<arch>.tar.gz`, then Docker directly reuses the binary and `static/admin` assets from those release archives, without running `npm build`/`go build` again.
+
+The release path keeps Docker images aligned with release archives and reduces duplicate build work.
 
 Container entry command: `/usr/local/bin/ds2api`, default exposed port: `5001`.
 

DEPLOY.md

@@ -135,11 +135,12 @@ docker-compose up -d --build
 
 ### 2.3 Docker 架构说明
 
-`Dockerfile` 使用三阶段构建：
+`Dockerfile` 提供两条构建路径：
 
-1. **WebUI 构建阶段**：`node:20` 镜像，执行 `npm ci && npm run build`
-2. **Go 构建阶段**：`golang:1.24` 镜像，编译二进制文件
-3. **运行阶段**：`debian:bookworm-slim` 精简镜像
+1. **本地/开发默认路径（`runtime-from-source`）**：三阶段构建（WebUI 构建 + Go 构建 + 运行阶段）。
+2. **Release 路径（`runtime-from-dist`）**：CI 先生成 `dist/ds2api_<tag>_linux_<arch>.tar.gz`，再由 Docker 直接复用该发布包内的二进制和 `static/admin` 产物组装运行镜像，不再重复执行 `npm build`/`go build`。
+
+Release 路径可确保 Docker 镜像与 release 压缩包使用同一套产物，减少重复构建带来的差异。
 
 容器内启动命令：`/usr/local/bin/ds2api`，默认暴露端口 `5001`。
 

Dockerfile

@@ -15,12 +15,37 @@ RUN go mod download
 COPY . .
 RUN CGO_ENABLED=0 GOOS=${TARGETOS} GOARCH=${TARGETARCH} go build -o /out/ds2api ./cmd/ds2api
 
-FROM debian:bookworm-slim
+FROM debian:bookworm-slim AS runtime-base
 WORKDIR /app
 RUN apt-get update && apt-get install -y --no-install-recommends ca-certificates wget && rm -rf /var/lib/apt/lists/*
+
+FROM runtime-base AS runtime-from-source
 COPY --from=go-builder /out/ds2api /usr/local/bin/ds2api
 COPY --from=go-builder /app/sha3_wasm_bg.7b9ca65ddd.wasm /app/sha3_wasm_bg.7b9ca65ddd.wasm
 COPY --from=go-builder /app/config.example.json /app/config.example.json
 COPY --from=webui-builder /app/static/admin /app/static/admin
+
+FROM runtime-base AS runtime-from-dist
+ARG TARGETARCH
+COPY dist/docker-input/linux_amd64.tar.gz /tmp/ds2api_linux_amd64.tar.gz
+COPY dist/docker-input/linux_arm64.tar.gz /tmp/ds2api_linux_arm64.tar.gz
+RUN set -eux; \
+    case "${TARGETARCH}" in \
+      amd64) ARCHIVE="/tmp/ds2api_linux_amd64.tar.gz" ;; \
+      arm64) ARCHIVE="/tmp/ds2api_linux_arm64.tar.gz" ;; \
+      *) echo "unsupported TARGETARCH: ${TARGETARCH}" >&2; exit 1 ;; \
+    esac; \
+    tar -xzf "${ARCHIVE}" -C /tmp; \
+    PKG_DIR="$(find /tmp -maxdepth 1 -type d -name "ds2api_*_linux_${TARGETARCH}" | head -n1)"; \
+    test -n "${PKG_DIR}"; \
+    install -Dm755 "${PKG_DIR}/ds2api" /usr/local/bin/ds2api; \
+    install -Dm644 "${PKG_DIR}/sha3_wasm_bg.7b9ca65ddd.wasm" /app/sha3_wasm_bg.7b9ca65ddd.wasm; \
+    install -Dm644 "${PKG_DIR}/config.example.json" /app/config.example.json; \
+    mkdir -p /app/static; \
+    cp -R "${PKG_DIR}/static/admin" /app/static/admin; \
+    rm -rf /tmp/ds2api_* /tmp/ds2api_linux_amd64.tar.gz /tmp/ds2api_linux_arm64.tar.gz
+
 EXPOSE 5001
 CMD ["/usr/local/bin/ds2api"]
+
+FROM runtime-from-source AS final