1ecefc80af
- 设置 PLAYWRIGHT_BROWSERS_PATH 环境变量指向 /app/.browsers - 创建 /app/.browsers 目录用于存放浏览器文件 - 分别以 root 用户和 appuser 用户执行 Playwright 依赖和浏览器安装 - 提升 /app/.browsers 目录权限，保证 appuser 访问权限 - 调整安装步骤顺序，优化权限和用户切换流程 docs(kami-gateway): 新增 kami-gateway 模块文档及构建脚本说明 - 添加了 kami-gateway 模块的整体介绍及项目结构概述 - 详细描述了基础镜像构建流程和核心组件（Dockerfile.base 与 build-base-image.sh） - 分析了 Go 依赖管理方式及 Docker 构建优化机制 - 介绍了 CI/CD 集成流程及自动化构建逻辑 - 阐述了性能优化措施，包括中国镜像源配置和极速构建策略 - 提供了常见故障排查指南以提高镜像构建和推送的稳定性 - 补充了安全性设计，如非 root 用户运行和证书管理 chore(docker): 更新 Go 模块代理地址 - 将 GOPROXY 从 https://goproxy.cn 更改为 https://goproxy.io - 保持其他环境变量配置不变 - 解决国内代理访问速度或稳定性问题
6.4 KiB
改进型应用镜像
**本文档引用文件** - [Dockerfile.base](file://kami-gateway/Dockerfile.base) - [build-base-image.sh](file://kami-gateway/build-base-image.sh) - [README.md](file://kami-gateway/README.md)目录
简介
本文档全面介绍 Dockerfile.improved 的设计理念与实现细节，重点阐述其如何基于预构建的 kami-gateway-base 镜像实现极速应用打包。通过复用基础镜像中预下载的 Go 依赖和编译环境，仅需复制应用源码并执行 go build 即可生成二进制文件，将构建时间压缩至 10-30 秒。同时，文档解析多阶段构建策略在减小最终镜像体积方面的优势，以及非 root 用户运行的安全配置机制。
项目结构
项目仓库包含多个子目录，分别对应不同的基础镜像构建方案。其中 kami-gateway 目录为核心分析对象，提供了 Go 应用的基础镜像构建能力。
graph TB
subgraph "基础镜像目录"
A[alpine-base]
B[kami-gateway]
C[kami-spider-monorepo]
end
B --> D[Dockerfile.base]
B --> E[build-base-image.sh]
B --> F[go.mod]
B --> G[go.sum]
Diagram sources
Section sources
核心组件
kami-gateway 的核心组件包括 Dockerfile.base 和 build-base-image.sh 脚本。前者定义了包含 Go 1.25 编译环境和 Alpine 运行时的基础镜像，后者用于自动化构建并推送该镜像至私有注册中心。基础镜像通过预下载所有 Go 模块依赖，显著加速后续应用镜像的构建过程。
Section sources
架构概述
kami-gateway-base 镜像采用分层设计，底层基于 golang:1.25-alpine，逐层叠加中国镜像源、时区配置、证书更新、非 root 用户创建及 Go 依赖预下载。应用镜像通过 FROM kami-gateway-base:latest 继承此环境，实现“仅 COPY 源码 + go build”的极简构建流程。
graph TD
A[golang:1.25-alpine] --> B[配置环境变量]
B --> C[切换至阿里云镜像源]
C --> D[安装系统依赖]
D --> E[更新CA证书]
E --> F[创建非root用户appuser]
F --> G[设置工作目录/app]
G --> H[复制go.mod/go.sum]
H --> I[预下载Go依赖]
I --> J[kami-gateway-base:latest]
J --> K[应用镜像]
K --> L[COPY . .]
L --> M[go build]
M --> N[最终应用镜像]
Diagram sources
详细组件分析
基础镜像设计分析
Dockerfile.base 通过一系列优化步骤构建高效的基础镜像。环境变量配置确保了 Go 模块代理指向国内镜像 goproxy.cn，并禁用 CGO 以生成静态二进制文件。Alpine 镜像源替换为阿里云镜像，极大提升包管理效率。
环境与依赖配置流程
flowchart TD
Start([开始]) --> SetEnv["设置环境变量<br/>GO111MODULE=on<br/>GOPROXY=https://goproxy.cn"]
SetEnv --> Mirror["配置Alpine镜像源<br/>mirrors.aliyun.com"]
Mirror --> Install["安装系统依赖<br/>tzdata, ca-certificates, git"]
Install --> Cert["下载并安装自定义CA证书"]
Cert --> User["创建非root用户appuser"]
User --> Workdir["设置工作目录 /app"]
Workdir --> CopyMod["复制go.mod和go.sum"]
CopyMod --> Download["执行go mod download"]
Download --> Verify["执行go mod verify"]
Verify --> Label["添加镜像标签"]
Label --> End([基础镜像构建完成])
Diagram sources
Section sources
构建脚本分析
build-base-image.sh 是一个 Bash 脚本，用于自动化构建和推送 kami-gateway-base 镜像。它支持通过环境变量自定义镜像名称、版本和目标注册中心，实现灵活的 CI/CD 集成。
Section sources
依赖分析
kami-gateway-base 镜像的依赖分为两层：Docker 层依赖和 Go 模块层依赖。Docker 层依赖通过 apk add 安装必要的运行时工具，Go 模块层依赖通过 go mod download 在构建阶段预先拉取，避免每次应用构建时重复下载。
graph LR
A[kami-gateway-base] --> B[Alpine v3.22]
A --> C[Go 1.25]
A --> D[CA证书]
A --> E[Git]
A --> F[Go模块依赖]
F --> G[第三方库]
F --> H[项目私有模块]
Diagram sources
性能考量
通过预构建 kami-gateway-base 镜像，将耗时的依赖下载和环境配置过程前置，使得应用镜像的构建时间从分钟级缩短至 10-30 秒。多阶段构建进一步优化最终镜像体积，仅包含运行时必要的二进制文件和配置，提升部署效率和安全性。
故障排除指南
当基础镜像构建失败时，应首先检查网络连接，特别是对 goproxy.cn 和 mirrors.aliyun.com 的访问。若 go mod download 失败，可尝试清除 Go 模块缓存后重试。镜像推送失败通常与 Docker 注册中心认证或网络策略有关。
Section sources
结论
kami-gateway-base 镜像通过精心设计的分层结构和预构建策略，为 Go 应用提供了极速、安全、一致的构建基础。结合多阶段构建和非 root 用户运行，该方案在提升开发效率的同时，保障了生产环境的安全性与稳定性，是现代化容器化部署的理想选择。