From 582a64ad20bfcc0d2e25d2cedb90fe79df2ba7a8 Mon Sep 17 00:00:00 2001
From: douxu <douxu@clea.com.cn>
Date: Tue, 2 Jun 2026 10:28:31 +0800
Subject: [PATCH] docs: expand eventRT image deploy guide and bump Go to 1.26  
 - add three-stage build table (builder/certs/runtime) to section 3.1   - add
 --build-arg USER_ID option for custom non-root UID   - add method 2: load
 pre-built local image (e.g. eventrt:v1) into Minikube   - add smoke test
 subsection 3.1.1 with size/inspect/run checks   - bump base image from
 golang:1.25-alpine to golang:1.26-alpine   - remove bundled
 config.example.yaml from image (config should be mounted at runtime)

---
 deploy/deploy.md                     | 57 +++++++++++++++++++++++++++-
 deploy/dockerfile/eventrt.Dockerfile | 11 +++---
 2 files changed, 60 insertions(+), 8 deletions(-)

diff --git a/deploy/deploy.md b/deploy/deploy.md
index 936f8f8..ebe44ef 100644
--- a/deploy/deploy.md
+++ b/deploy/deploy.md
@@ -217,14 +217,67 @@ kubectl apply -f deploy/mq/rabbitmq-service.yaml
 
 #### 3.1 构建并推送镜像
 
+镜像采用三阶段构建，最终基于 `scratch`：
+
+| 阶段 | 基础镜像 | 作用 |
+| :--- | :--- | :--- |
+| **builder** | `golang:1.26-alpine` | 编译 Go 二进制（`CGO_ENABLED=0`，`-trimpath -ldflags="-s -w"`） |
+| **certs** | `alpine:3.21` | 提取 CA 证书、时区数据及非 root 用户定义（UID 默认 `1000`） |
+| **runtime** | `scratch` | 仅含可执行文件与运行时依赖，无 shell、无包管理器 |
+
+**方式一：从源码构建并加载**
+
 ```bash
-# 在项目根目录执行
+# 在项目根目录执行（默认运行用户 UID=1000）
 docker build -f deploy/dockerfile/eventrt.Dockerfile -t coslight/eventrt:latest .
 
-# 加载至 Minikube（无需私有仓库时）
+# 自定义运行用户 UID
+docker build -f deploy/dockerfile/eventrt.Dockerfile \
+  --build-arg USER_ID=2000 \
+  -t coslight/eventrt:latest .
+
+# 加载到 Minikube（无需私有仓库）
 minikube image load coslight/eventrt:latest
 ```
 
+**方式二：直接加载已有本地镜像**
+
+Ubuntu 宿主机上已存在构建好的镜像（如 `eventrt:v1`）时，无需重新构建，直接导入 Minikube：
+
+```bash
+# 确认本地镜像存在
+docker images eventrt:v1
+
+# 加载到 Minikube
+minikube image load eventrt:v1
+
+# 验证镜像已进入 Minikube 缓存
+minikube image ls | grep eventrt
+```
+
+> **注意：** `deploy/k8s/eventrt-deployment.yaml` 中的 `image` 字段需与加载的镜像名称一致，并将 `imagePullPolicy` 设为 `Never`，防止 Minikube 尝试从远端拉取。
+
+#### 3.1.1 镜像冒烟测试
+
+```bash
+# 查看镜像大小（scratch 镜像预期 ≤ 25 MB）
+docker images coslight/eventrt:latest
+
+# 检查镜像元信息（确认 User、Cmd、架构）
+docker inspect coslight/eventrt:latest
+
+# 验证二进制可执行（无 config 时程序报错退出属预期行为，说明镜像构建正常）
+docker run --rm coslight/eventrt:latest
+
+# 挂载示例配置做完整启动验证（Ctrl+C 退出）
+docker run --rm \
+  -v "$(pwd)/configs/config.example.yaml:/app/configs/config.yaml" \
+  -p 8081:8081 \
+  coslight/eventrt:latest
+```
+
+> **注意：** `scratch` 镜像不含 shell，无法使用 `docker exec` 进入容器调试；如需排查问题，可临时将最终阶段改为 `alpine` 进行本地调试，确认后再切回 `scratch`。
+
 #### 3.2 创建客户端证书 Secret
 
 在 RabbitMQ TLS 证书生成完成后（见 2.1），进入证书文件所在目录执行：
diff --git a/deploy/dockerfile/eventrt.Dockerfile b/deploy/dockerfile/eventrt.Dockerfile
index d18183e..1e67cb6 100644
--- a/deploy/dockerfile/eventrt.Dockerfile
+++ b/deploy/dockerfile/eventrt.Dockerfile
@@ -1,4 +1,4 @@
-FROM golang:1.25-alpine AS builder
+FROM golang:1.26-alpine AS builder
 RUN apk --no-cache upgrade
 
 WORKDIR /app
@@ -11,8 +11,8 @@ RUN CGO_ENABLED=0 GOOS=linux go build \
     -mod=readonly \
     -o eventrt main.go
 
-# Prepare runtime dependencies in a pinned Alpine stage so they can be
-# copied into scratch without pulling any vulnerable OS packages at run time.
+# prepare runtime dependencies in a pinned alpine stage so they can be
+# copied into scratch without pulling any vulnerable os packages at run time.
 FROM alpine:3.21 AS certs
 ARG USER_ID=1000
 RUN apk --no-cache add ca-certificates tzdata && \
@@ -21,15 +21,14 @@ RUN apk --no-cache add ca-certificates tzdata && \
 FROM scratch
 # CA certificates required for TLS connections (RabbitMQ amqps://)
 COPY --from=certs /etc/ssl/certs/ca-certificates.crt /etc/ssl/certs/
-# Timezone data
+# timezone data
 COPY --from=certs /usr/share/zoneinfo /usr/share/zoneinfo
-# Non-root user/group definitions
+# non-root user/group definitions
 COPY --from=certs /etc/passwd /etc/passwd
 COPY --from=certs /etc/group  /etc/group
 
 WORKDIR /app
 COPY --from=builder /app/eventrt ./eventrt
-COPY configs/config.example.yaml ./configs/config.example.yaml
 
 USER eventrt
 CMD ["/app/eventrt", "-eventRT_config_dir=/app/configs"]