danial/docker-registry
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
Files
1a0a86bfeb8367d69b0c1f4b0525b7167e5f2563
docker-registry/.qoder/repowiki/zh/content/项目概述/kami-gateway 模块/基础镜像构建.md
danial 1a0a86bfeb chore(ci): 注释所有 drone.yml 中的触发分支配置 
- 更改服务器主机地址和端口号
- 注释掉 main、master、develop、production 分支的触发器配置
- 取消自动触发事件的推送限制
- 保持 pipeline 配置完整性但禁用触发条件
- 方便后续手动触发或调整 CI 流程设置

chore(ci): 更新服务器地址和pipeline触发器配置，调整基础镜像代理设置

- 更新spider-base-image和alpine-base-image的服务器地址为38.55.194.49:3422
- 为main、master、develop和production分支的pipeline添加触发器注释，禁用自动执行
- 修改.dron.yml文件，恢复pipeline触发器的配置启用推送事件触发
- 更新kami-gateway和相关模块构建文档，反映最新的服务器地址和CI/CD配置变更
- 注释Dockerfile.base中的GOPROXY环境变量，将中国代理从goproxy.cn替换为goproxy.io
- 移除Alpine Linux阿里云镜像源配置，更新文档中相关代理和构建指引说明
- 增加依赖版本说明，包括新增goquery、stomp、zap等依赖版本精确声明
- 优化故障排查指南，提醒检查新的服务器地址和代理配置影响

chore(ci): 更新Docker注册表地址为新的域名

- 将Spider镜像构建中Docker注册表地址由git.oceanpay.cc改为git.domainpay.top
- 将Gateway镜像构建中Docker注册表地址由git.oceanpay.cc改为git.domainpay.top
- 将Alpine基础镜像构建中Docker注册表地址由git.oceanpay.cc改为git.domainpay.top
- 修改对应的docker login与logout命令以匹配新注册表地址
2025-12-17 15:34:04 +08:00

9.2 KiB
Raw Blame History

基础镜像构建

**本文档引用文件** - [Dockerfile.base](file://kami-gateway/Dockerfile.base) - [build-base-image.sh](file://kami-gateway/build-base-image.sh) - [go.mod](file://kami-gateway/go.mod) - [alpine-base/build-base-image.sh](file://alpine-base/build-base-image.sh) - [alpine-base/README.md](file://alpine-base/README.md) - [kami-gateway/README.md](file://kami-gateway/README.md)

更新摘要

已做更改

  • 更新了 Dockerfile.base 中的 GOPROXY 环境变量配置，从 https://goproxy.cn 变更为 https://goproxy.io 并已被注释
  • 移除了 Alpine Linux 阿里云镜像源的配置
  • 相应更新了文档中所有涉及环境变量和镜像源配置的说明
  • 修正了故障排除指南中的代理配置建议

目录

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

简介

本文档详细说明了 kami-gateway 模块中 Dockerfile.base 的构建逻辑，重点描述如何基于 alpine-base 创建轻量级 Go 1.25 编译环境。文档涵盖了多阶段构建策略、GOPROXY 环境变量配置变更、动态镜像标签生成与私有仓库推送等关键技术点，为开发者提供完整的构建指导和最佳实践。

项目结构

项目结构清晰地组织了不同模块的基础镜像构建文件，包括 alpine-base、kami-gateway 和 kami-spider-monorepo 三个主要目录，每个目录包含相应的构建脚本和配置文件。

graph TD
A[项目根目录] --> B[alpine-base]
A --> C[kami-gateway]
A --> D[kami-spider-monorepo]
B --> B1[Dockerfile.base]
B --> B2[build-base-image.sh]
B --> B3[README.md]
C --> C1[Dockerfile.base]
C --> C2[build-base-image.sh]
C --> C3[go.mod]
C --> C4[go.sum]
C --> C5[README.md]
D --> D1[build-base-image.sh]
D --> D2[pyproject.toml]
D --> D3[uv.lock]
D --> D4[README.md]

文档来源

章节来源

核心组件

kami-gateway 模块的核心组件包括 Dockerfile.base 和 build-base-image.sh 脚本，它们共同实现了轻量级 Go 编译环境的构建和部署。

章节来源

架构概述

kami-gateway 基础镜像采用多阶段构建策略，分离构建依赖与运行时环境，显著减小最终镜像体积。架构设计充分利用了 Alpine Linux 的轻量化特性，并通过预配置优化了中国网络环境下的依赖下载速度。

graph TD
A[基础镜像构建] --> B[Go 1.25 环境]
A --> C[Alpine 运行时]
A --> D[中国镜像源]
A --> E[非 root 用户]
B --> F[Go 模块预下载]
C --> G[轻量级容器]
D --> H[goproxy.io 代理]
E --> I[appuser 用户]
F --> J[快速构建]
G --> K[小体积镜像]
H --> L[加速依赖下载]
I --> M[安全运行]

图表来源

详细组件分析

Dockerfile.base 分析

Dockerfile.base 定义了 kami-gateway 应用的基础镜像，基于 golang:1.25-alpine 构建，包含 Go 1.25 编译环境和 Alpine 运行时。

多阶段构建策略

flowchart TD
Start([开始构建]) --> BaseImage["FROM golang:1.25-alpine"]
BaseImage --> EnvSetup["设置环境变量"]
EnvSetup --> MirrorConfig["配置中国镜像源"]
MirrorConfig --> InstallDeps["安装依赖包"]
InstallDeps --> CertSetup["下载自定义证书"]
CertSetup --> UserSetup["创建非 root 用户"]
UserSetup --> AppDir["创建应用目录"]
AppDir --> SwitchUser["切换到 appuser 用户"]
SwitchUser --> SetWorkDir["设置工作目录 /app"]
SetWorkDir --> CopyGoMod["复制 go.mod 和 go.sum"]
CopyGoMod --> DownloadDeps["预下载 Go 依赖"]
DownloadDeps --> LabelImage["标记镜像信息"]
LabelImage --> End([基础镜像构建完成])

图表来源

章节来源

环境变量配置

Dockerfile.base 中配置了多个关键环境变量，确保构建环境的一致性和可重复性：

环境变量 值 说明
TZ Asia/Shanghai 设置时区为上海
GO111MODULE on 启用 Go 模块
GOPROXY # https://goproxy.io,direct 已注释，原为中国代理
CGO_ENABLED 0 禁用 CGO
GOOS linux 目标操作系统
GOARCH amd64 目标架构

章节来源

build-base-image.sh 脚本分析

build-base-image.sh 脚本实现了基础镜像的自动化构建、标记和推送流程。

动态镜像标签生成

sequenceDiagram
participant 用户 as 用户
participant 脚本 as build-base-image.sh
participant Docker as Docker Engine
用户->>脚本 : 执行脚本
脚本->>脚本 : 读取 DOCKER_REGISTRY 和 VERSION 环境变量
脚本->>脚本 : 设置镜像名称和版本
脚本->>Docker : docker build --tag ...
Docker-->>脚本 : 返回构建结果
脚本->>脚本 : 判断是否需要推送
脚本->>Docker : docker tag ...
脚本->>Docker : docker push ...
Docker-->>脚本 : 返回推送结果
脚本->>用户 : 显示构建完成信息和镜像大小

图表来源

章节来源

构建流程说明

  1. 环境准备：脚本首先设置 set -e 确保任何命令失败时立即退出
  2. 变量配置：定义 BASE_IMAGE_NAME、REGISTRY 和 VERSION 变量
  3. 镜像构建：使用 docker build 命令构建基础镜像
  4. 标签处理：为镜像创建版本标签和 latest 标签
  5. 推送注册表：如果指定了非本地注册表，则推送镜像
  6. 结果展示：显示构建完成信息和镜像大小

章节来源

依赖分析

kami-gateway 基础镜像的依赖关系清晰，通过 go.mod 文件管理所有 Go 依赖包。

erDiagram
DOCKERFILE_BASE {
string FROM
string ENV
string RUN
string COPY
string USER
string WORKDIR
string LABEL
}
GO_MOD {
string module
string go
string toolchain
string require
}
BUILD_SCRIPT {
string BASE_IMAGE_NAME
string REGISTRY
string VERSION
string docker_build
string docker_tag
string docker_push
}
DOCKERFILE_BASE ||--o{ GO_MOD : "复制"
DOCKERFILE_BASE ||--o{ BUILD_SCRIPT : "构建"
BUILD_SCRIPT }|--|| DOCKERFILE_BASE : "使用"

图表来源

章节来源

性能考虑

kami-gateway 基础镜像在性能方面进行了多项优化：

  1. 构建时间优化：通过预下载 Go 依赖包，应用构建时间缩短至 10-30 秒
  2. 镜像体积优化：基于 Alpine Linux，最终镜像体积小
  3. 网络性能优化：使用中国镜像源和 GOPROXY 代理，显著提升依赖下载速度
  4. 缓存利用：基础镜像缓存，避免重复构建

章节来源

故障排除指南

常见问题及解决方案

问题现象 可能原因 解决方案
依赖下载缓慢 未使用中国镜像源 确认 GOPROXY 设置为 https://goproxy.io,direct
构建失败 网络连接问题 检查网络连接，尝试使用代理
镜像推送失败 注册表认证问题 确认 Docker 已登录目标注册表
证书验证失败 自定义证书未正确安装 检查证书下载和更新命令
权限错误 未正确切换用户 确认 USER appuser 命令已执行

章节来源

本地测试流程

  1. 环境准备：确保已安装 Docker 和必要的构建工具
  2. 克隆代码：获取 kami-gateway 仓库代码
  3. 构建镜像：执行 ./build-base-image.sh
  4. 验证镜像：使用 docker images 查看镜像信息
  5. 测试运行：创建测试容器验证基础环境

章节来源

结论

kami-gateway 的 Dockerfile.base 通过多阶段构建策略、中国网络环境优化和安全配置，成功创建了一个轻量级、高性能的 Go 1.25 编译环境。build-base-image.sh 脚本实现了自动化构建和部署，为团队提供了高效的开发体验。该基础镜像设计合理，性能优越，是微服务架构中理想的构建基础。