danial/docker-registry
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
Files
1ecefc80af4c491ffd6eb5dac4def291b0f97492
docker-registry/.qoder/repowiki/zh/content/kami-gateway 模块/基础镜像构建.md
danial 1ecefc80af chore(docker): 优化 Playwright 浏览器安装和配置 
- 设置 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
- 保持其他环境变量配置不变
- 解决国内代理访问速度或稳定性问题
2025-12-17 15:33:59 +08:00

9.7 KiB
Raw Blame History

基础镜像构建

**Referenced Files in This Document** - [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)

目录

  1. 简介
  2. 项目结构
  3. 核心组件
  4. 架构概述
  5. 详细组件分析
  6. 依赖分析
  7. 性能考虑
  8. 故障排除指南
  9. 结论

简介

本文档详细阐述了 kami-gateway 项目中基础 Docker 镜像的构建机制。该机制通过 Dockerfile.base 和 build-base-image.sh 脚本实现，旨在创建一个安全、高效且适用于中国网络环境的 Go 应用基础镜像。文档将深入解析镜像构建过程中的关键配置，包括中国镜像源设置、时区配置、非 root 用户创建以及 Go 模块代理加速等最佳实践。

项目结构

kami-gateway 目录下的文件组织清晰，专注于基础镜像的构建与管理。主要包含 Docker 配置文件、构建脚本和 Go 模块定义文件。

graph TB
kami-gateway[kami-gateway/]
--> Dockerfile_base[Dockerfile.base]
kami-gateway --> Dockerfile_improved[Dockerfile.improved]
kami-gateway --> build_script[build-base-image.sh]
kami-gateway --> go_mod[go.mod]
kami-gateway --> go_sum[go.sum]
kami-gateway --> README[README.md]

Diagram sources

Section sources

核心组件

kami-gateway 基础镜像构建的核心组件是 Dockerfile.base 和 build-base-image.sh。前者定义了镜像的静态配置和构建步骤，后者则是一个可执行的脚本，用于自动化地调用 Docker 命令来构建、标记和推送镜像。这两个文件共同构成了一个可重复、可靠的镜像构建流程。

Section sources

架构概述

整个基础镜像构建流程遵循了多阶段配置和安全加固的最佳实践。首先，Dockerfile.base 从官方 golang:1.25-alpine 镜像出发，通过一系列 RUN 指令进行环境配置。随后，build-base-image.sh 脚本作为构建的入口，负责执行 docker build 命令，并根据环境变量决定是否将构建好的镜像推送到私有仓库。

graph LR
A[golang:1.25-alpine] --> B[Dockerfile.base]
B --> C[配置环境变量]
C --> D[设置中国镜像源]
D --> E[安装系统工具]
E --> F[创建非root用户]
F --> G[预下载Go依赖]
G --> H[生成基础镜像]
H --> I[build-base-image.sh]
I --> J[执行docker build]
J --> K[生成本地标签]
K --> L{是否推送?}
L --> |是| M[推送至私有仓库]
L --> |否| N[完成]

Diagram sources

详细组件分析

Dockerfile.base 分析

Dockerfile.base 是构建基础镜像的蓝图，其设计体现了安全性和效率的平衡。

环境变量与镜像源配置

该文件通过 ENV 指令设置了关键的环境变量。TZ=Asia/Shanghai 确保了容器内的时间与北京时间一致。GO111MODULE=on 强制启用 Go Modules，保证依赖管理的现代性和一致性。GOPROXY=https://goproxy.cn,direct 将 Go 模块代理设置为中国的镜像服务，极大地加速了 go mod download 命令的执行速度，解决了从国外服务器下载依赖慢的问题。此外，RUN 指令将 Alpine Linux 的软件源替换为阿里云镜像，同样是为了提升 apk 包管理器的下载速度。

安全加固与系统配置

安全是此镜像的核心考量。Dockerfile.base 通过 RUN 指令安装了 tzdata 来支持时区设置，并安装了 ca-certificates 和自定义证书以确保 HTTPS 连接的安全性。最关键的一步是创建了一个非 root 用户 appuser（UID 1001）。通过 addgroup 和 adduser 命令创建用户后，使用 USER appuser 指令将后续所有操作的执行者切换为该普通用户。这遵循了最小权限原则，即使容器被攻破，攻击者也只能获得有限的权限，从而提升了整体安全性。

flowchart TD
Start([开始]) --> SetEnv["设置环境变量\nTZ, GO111MODULE, GOPROXY"]
SetEnv --> ConfigureMirror["配置中国镜像源\n阿里云 Alpine 镜像"]
ConfigureMirror --> InstallTools["安装系统工具\ntzdata, ca-certificates"]
InstallTools --> SetupTimezone["设置时区\nAsia/Shanghai"]
SetupTimezone --> CreateUser["创建非root用户\nappuser (UID 1001)"]
CreateUser --> SwitchUser["切换执行用户\nUSER appuser"]
SwitchUser --> DownloadDeps["预下载Go依赖\ngo mod download"]
DownloadDeps --> Finish([完成])

Diagram sources

Section sources

build-base-image.sh 脚本分析

build-base-image.sh 脚本是构建流程的自动化驱动器，它封装了复杂的 Docker 命令，简化了构建操作。

构建与标记逻辑

脚本首先定义了基础镜像名称、版本号和镜像仓库地址（通过 DOCKER_REGISTRY 环境变量或默认值）。它使用 docker build 命令，通过 --file 参数指定 Dockerfile.base，并使用 --tag 参数同时为镜像打上版本化标签（如 latest 或指定版本）和 latest 标签。这种双标签策略既保证了可追溯性，又提供了最新的稳定版本。

推送与输出逻辑

脚本的核心智能在于条件推送。它通过判断 REGISTRY 变量是否为 localhost:5000 来决定是否执行推送操作。如果指定了私有仓库（如 git.oceanpay.cc/danial），脚本会先使用 docker tag 为本地镜像创建一个包含仓库地址的完整标签，然后调用 docker push 将其推送到远程仓库。构建完成后，脚本会输出成功信息，并使用 docker images 命令结合 grep 过滤，清晰地展示新构建的 kami-gateway-base 镜像的大小，便于开发者评估镜像优化效果。

sequenceDiagram
participant Terminal as "终端"
participant Script as "build-base-image.sh"
participant Docker as "Docker Engine"
Terminal->>Script : 执行 ./build-base-image.sh
Script->>Script : 设置环境变量
Script->>Script : 输出构建信息
Script->>Docker : docker build --file Dockerfile.base ...
Docker-->>Script : 构建成功
Script->>Script : 检查 REGISTRY 是否为 localhost
alt 需要推送
Script->>Docker : docker tag ... git.oceanpay.cc/danial/...
Script->>Docker : docker push git.oceanpay.cc/danial/...
Docker-->>Script : 推送成功
end
Script->>Script : 输出镜像大小信息
Script-->>Terminal : 构建完成

Diagram sources

Section sources

依赖分析

kami-gateway 基础镜像的构建依赖于外部的 Docker 环境和网络服务。其主要依赖关系如下：

graph LR
A[build-base-image.sh] --> B[Docker CLI]
B --> C[Docker Daemon]
C --> D[golang:1.25-alpine]
D --> E[阿里云Alpine镜像]
A --> F[Go Proxy 中国镜像]
F --> G[goproxy.cn]
A --> H[私有镜像仓库]
H --> I[git.oceanpay.cc/danial]

Diagram sources

性能考虑

该构建机制在性能方面进行了精心优化。通过在 Dockerfile.base 中预下载 Go 依赖（go mod download），后续基于此基础镜像构建的应用镜像可以跳过耗时的依赖下载阶段，从而将构建时间从几分钟缩短到十秒左右。使用中国镜像源（阿里云和 goproxy.cn）显著减少了网络延迟，是提升构建速度的关键。多阶段构建和 --no-cache 选项的使用也确保了镜像的精简，减小了最终镜像的体积，有利于快速部署和传输。

故障排除指南

当构建过程出现问题时，可参考以下步骤进行排查：

  1. 网络问题：确认构建环境可以访问阿里云镜像源（mirrors.aliyun.com）和 Go 代理（goproxy.cn）。若网络受限，可尝试更换为其他国内镜像。
  2. 权限问题：检查 build-base-image.sh 脚本是否具有可执行权限（chmod +x build-base-image.sh）。
  3. Docker 服务：确保 Docker 服务正在运行。
  4. 私有仓库认证：如果推送失败，确认已使用 docker login git.oceanpay.cc 登录到私有仓库。
  5. 证书问题：如果出现 HTTPS 证书错误，检查 Dockerfile.base 中的 curl 命令是否能成功下载证书。

Section sources

结论

kami-gateway 的基础镜像构建方案是一个优秀的实践范例。它通过 Dockerfile.base 实现了环境的标准化和安全加固，利用 build-base-image.sh 脚本实现了构建流程的自动化和智能化。该方案不仅解决了中国开发者面临的网络瓶颈问题，还通过非 root 用户运行和预下载依赖等手段，兼顾了安全性与构建效率。这种多阶段、可复用的构建模式，为微服务架构下的持续集成与部署（CI/CD）提供了坚实的基础。