build: make Go image build resilient to registry mirror failures

backend/Dockerfile

@@ -1,8 +1,20 @@
 # syntax=docker/dockerfile:1
 # Build context: the repository backend/ directory.
 #   docker build -f backend/Dockerfile -t REGISTRY/PROJECT/zhinian-go-api:TAG backend/
+#
+# GOLANG_IMAGE and RUNTIME_IMAGE are overridable for build environments whose
+# registry mirror cannot serve the default docker.io images:
+#   docker build -f backend/Dockerfile \
+#     --build-arg GOLANG_IMAGE=<working-mirror>/golang:1.21-alpine \
+#     --build-arg RUNTIME_IMAGE=<working-mirror>/alpine:3.20 \
+#     -t REGISTRY/PROJECT/zhinian-go-api:TAG backend/
+#
+# If no mirror can serve the golang image at all, use backend/Dockerfile.runtime
+# with a prebuilt static binary instead (see backend/README.md).
+ARG GOLANG_IMAGE=golang:1.21-alpine
+ARG RUNTIME_IMAGE=alpine:3.20
 
-FROM golang:1.21-alpine AS build
+FROM ${GOLANG_IMAGE} AS build
 WORKDIR /src
 ENV CGO_ENABLED=0 GOOS=linux
 COPY go.mod go.sum ./
@@ -10,7 +22,7 @@ RUN go mod download
 COPY . .
 RUN go build -trimpath -ldflags="-s -w" -o /out/zhinian-api ./cmd/zhinian-api
 
-FROM alpine:3.20
+FROM ${RUNTIME_IMAGE}
 RUN apk add --no-cache ca-certificates tzdata \
     && addgroup -S -g 10001 zhinian \
     && adduser -S -D -H -u 10001 -G zhinian zhinian \

backend/Dockerfile.runtime

@@ -0,0 +1,24 @@
+# syntax=docker/dockerfile:1
+# Runtime-only image for build environments whose registry mirror cannot serve
+# the golang builder image. Build the static binary first (any machine with
+# Go 1.21, no Docker required), then assemble this image from alpine only:
+#
+#   cd backend
+#   CGO_ENABLED=0 GOOS=linux GOARCH=amd64 \
+#     go build -trimpath -ldflags="-s -w" -o zhinian-api.linux ./cmd/zhinian-api
+#   docker build -f backend/Dockerfile.runtime \
+#     -t REGISTRY/PROJECT/zhinian-go-api:TAG backend/
+#
+# RUNTIME_IMAGE is overridable the same way as in Dockerfile.
+ARG RUNTIME_IMAGE=alpine:3.20
+
+FROM ${RUNTIME_IMAGE}
+RUN apk add --no-cache ca-certificates tzdata \
+    && addgroup -S -g 10001 zhinian \
+    && adduser -S -D -H -u 10001 -G zhinian zhinian \
+    && mkdir -p /var/lib/zhinian \
+    && chown -R zhinian:zhinian /var/lib/zhinian
+COPY zhinian-api.linux /usr/local/bin/zhinian-api
+USER 10001:10001
+EXPOSE 8080
+ENTRYPOINT ["zhinian-api"]

backend/README.md

@@ -37,6 +37,35 @@ npm run go:vet
 npm run go:build
 ```
 
+## Container images
+
+Standard multi-stage build (needs the `golang` builder image):
+
+```bash
+docker build -f backend/Dockerfile -t REGISTRY/PROJECT/zhinian-go-api:TAG backend/
+```
+
+Mirror-friendly build (override the base images when the registry accelerator
+cannot serve docker.io images):
+
+```bash
+docker build -f backend/Dockerfile \
+  --build-arg GOLANG_IMAGE=<mirror>/golang:1.21-alpine \
+  --build-arg RUNTIME_IMAGE=<mirror>/alpine:3.20 \
+  -t REGISTRY/PROJECT/zhinian-go-api:TAG backend/
+```
+
+Prebuilt-binary build (no `golang` image at all; compile the static binary on
+any Go 1.21 machine, then assemble from `alpine` only):
+
+```bash
+cd backend
+CGO_ENABLED=0 GOOS=linux GOARCH=amd64 \
+  go build -trimpath -ldflags="-s -w" -o zhinian-api.linux ./cmd/zhinian-api
+docker build -f backend/Dockerfile.runtime \
+  -t REGISTRY/PROJECT/zhinian-go-api:TAG backend/
+```
+
 The runner defaults to `CGO_ENABLED=0` for reproducible cross-platform builds.
 To exercise the local foundation manually without changing the existing Next
 server, use a different port: