danial/docker-registry
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
Files
1ecefc80af4c491ffd6eb5dac4def291b0f97492
docker-registry/.qoder/repowiki/zh/content/项目概述/kami-gateway 模块/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.6 KiB
Raw Blame History

kami-gateway 模块

**本文档引用文件** - [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) - [go.sum](file://kami-gateway/go.sum) - [README.md](file://kami-gateway/README.md)

目录

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

简介

kami-gateway 模块提供了一个专为 Go 语言网关服务设计的基础 Docker 镜像，旨在优化构建效率、提升安全性并简化部署流程。该模块通过预配置的编译环境和依赖缓存机制，显著缩短了应用构建时间（10-30秒），适用于 API 网关类微服务的快速迭代与发布。

项目结构

kami-gateway 模块包含构建基础镜像所需的核心文件，组织清晰，职责明确：

kami-gateway/
├── README.md           # 模块说明文档
├── build-base-image.sh # 基础镜像构建脚本
├── go.mod              # Go 依赖管理文件
├── go.sum              # 依赖校验文件
├── Dockerfile.base     # 基础镜像定义
└── Dockerfile.improved # 改进版应用镜像定义（引用）

Section sources

核心组件

本模块的核心在于 Dockerfile.base 和 build-base-image.sh 脚本的协同工作，前者定义了包含 Go 1.25 编译环境和 Alpine 运行时的基础镜像，后者则封装了镜像构建、标记与推送的完整流程。

Section sources

架构概述

kami-gateway 的架构围绕“基础镜像预构建 + 应用镜像快速构建”的理念展开。基础镜像预先集成了 Go 编译环境、中国镜像源、时区、证书及依赖包，使得后续的应用镜像构建只需专注于业务代码编译，从而实现极速构建。

graph TB
subgraph "基础镜像构建"
A[Dockerfile.base] --> B[Go 1.25 Alpine]
B --> C[配置环境变量]
C --> D[安装系统依赖]
D --> E[下载自定义证书]
E --> F[创建非root用户]
F --> G[预下载Go依赖]
G --> H[kami-gateway-base:latest]
end
subgraph "应用镜像构建"
I[Dockerfile.improved] --> J[多阶段构建]
J --> K[使用kami-gateway-base作为基础]
K --> L[编译Go应用]
L --> M[生成轻量运行镜像]
end
H --> K

Diagram sources

详细组件分析

Dockerfile.base 实现细节

Dockerfile.base 是构建 kami-gateway 基础镜像的核心。它从 golang:1.25-alpine 镜像开始，通过一系列优化步骤构建出一个高效、安全的编译环境。

环境与依赖配置

该文件设置了关键的 Go 环境变量，包括 GO111MODULE=on 启用模块化管理，GOPROXY=https://goproxy.cn,direct 配置国内代理以加速依赖下载，以及 CGO_ENABLED=0 确保生成静态链接的二进制文件。

系统优化

使用阿里云的 Alpine 镜像源替换默认源，显著提升 apk 包管理器的下载速度。同时，预装了 tzdata 并设置时区为 Asia/Shanghai，避免了应用运行时的时区问题。

安全与证书

创建了 UID 为 1001 的非 root 用户 appuser，并在后续步骤中切换至此用户，遵循最小权限原则。此外，通过 curl 下载并安装了 Comodo AAA 证书，解决了某些网络环境下可能出现的证书信任问题。

依赖预下载

通过 COPY go.mod go.sum* ./ 和 RUN go mod download && go mod verify 命令，将依赖下载和验证步骤前置到基础镜像中。这使得所有基于此镜像构建的应用都能跳过耗时的依赖拉取过程，直接进入代码编译阶段。

flowchart TD
Start([开始构建]) --> BaseImage["FROM golang:1.25-alpine"]
BaseImage --> Env["设置环境变量<br/>GOPROXY, CGO_ENABLED等"]
Env --> Repos["配置Alpine镜像源<br/>阿里云"]
Repos --> Install["安装系统依赖<br/>tzdata, curl, git"]
Install --> Cert["下载并安装<br/>Comodo AAA证书"]
Cert --> User["创建非root用户<br/>appuser"]
User --> Workdir["创建工作目录<br/>/app"]
Workdir --> SwitchUser["切换到appuser"]
SwitchUser --> CopyMod["复制go.mod/go.sum"]
CopyMod --> Download["预下载Go依赖<br/>go mod download"]
Download --> Label["添加镜像标签"]
Label --> End([基础镜像构建完成])

Diagram sources

Section sources

build-base-image.sh 脚本分析

该脚本自动化了基础镜像的构建、标记和推送流程，是实现 CI/CD 集成的关键。

环境变量控制

脚本通过 REGISTRY="${DOCKER_REGISTRY:-git.oceanpay.cc/danial}" 和 VERSION="${VERSION:-latest}" 读取环境变量，允许用户在调用时动态指定镜像仓库地址和版本标签。若未指定，则使用默认值。

构建与标记

使用 docker build 命令，基于 Dockerfile.base 构建镜像，并同时打上 $VERSION 和 latest 两个标签。如果指定了非本地仓库（REGISTRY 不为 localhost:5000），则会使用 docker tag 命令为镜像添加仓库前缀。

推送逻辑

脚本包含条件推送逻辑：只有当 REGISTRY 不是 localhost:5000 时，才会执行 docker push 将镜像推送到远程仓库。这避免了在本地开发测试时不必要的网络操作。

flowchart LR
A[开始] --> B{读取环境变量<br/>DOCKER_REGISTRY, VERSION}
B --> C[构建基础镜像<br/>docker build]
C --> D{REGISTRY != localhost:5000?}
D --> |是| E[标记镜像<br/>docker tag]
D --> |否| F[跳过标记]
E --> G[推送镜像<br/>docker push]
F --> H[完成]
G --> H
H --> I[显示镜像大小]

Diagram sources

Section sources

依赖管理分析

go.mod 文件定义了 kami-gateway 基础镜像所预下载的所有 Go 依赖。这些依赖涵盖了 Web 框架（beego）、JSON 处理（sonic）、数据库驱动（mysql）、Redis 客户端（go-redis）、OpenTelemetry 监控、日志（zap）等网关服务常用组件。

最佳实践

  • 明确指定 Go 版本：go 1.24.0 和 toolchain go1.24.6 确保了构建环境的一致性。
  • 区分直接与间接依赖：require 块清晰地分开了项目直接依赖和间接依赖，便于维护。
  • 使用国内代理：GOPROXY=https://goproxy.cn,direct 的配置在 Dockerfile.base 中生效，极大提升了依赖下载速度。

Section sources

Dockerfile.improved 多阶段构建

虽然 Dockerfile.improved 未在当前上下文中提供完整内容，但根据 README.md 的描述，它采用了多阶段构建策略。

优化原理

第一阶段使用 kami-gateway-base:latest 作为基础镜像进行代码编译，利用其预下载的依赖和完整的 Go 环境。第二阶段则使用一个极小的运行时镜像（如 alpine 或 scratch），仅将第一阶段编译出的二进制文件复制进去。这种方式将最终镜像体积降至最低，同时保证了构建速度。

Section sources

依赖分析

kami-gateway 模块的依赖关系清晰，主要依赖于 Go 官方镜像和 Alpine Linux 发行版。其内部组件通过 Dockerfile.base 和 build-base-image.sh 协同工作，形成一个自包含的构建单元。

graph TD
A[kami-gateway] --> B[golang:1.25-alpine]
A --> C[Alpine Linux]
A --> D[阿里云镜像源]
A --> E[Comodo AAA证书]
B --> F[Go 1.25工具链]
C --> G[轻量级Linux内核]
D --> H[加速apk包下载]
E --> I[解决证书信任]

Diagram sources

Section sources

性能考量

kami-gateway 模块在性能方面进行了多项优化：

  • 构建速度：通过预下载 Go 依赖，将应用构建时间从分钟级缩短至 10-30 秒。
  • 镜像体积：基于 Alpine Linux 和多阶段构建，确保最终运行镜像尽可能小。
  • 网络效率：使用国内镜像源和代理，减少网络延迟。

故障排除指南

  • 构建失败：检查 go.mod 文件是否正确，确保所有依赖均可通过 goproxy.cn 下载。
  • 推送失败：确认 DOCKER_REGISTRY 环境变量设置正确，并且已登录到目标镜像仓库。
  • 证书错误：若遇到 HTTPS 证书问题，可检查 Dockerfile.base 中的证书下载 URL 是否有效。

Section sources

结论

kami-gateway 模块通过精心设计的 Dockerfile.base 和 build-base-image.sh 脚本，成功构建了一个高效、安全、易用的 Go 语言网关服务基础镜像。其预下载依赖、国内镜像源、非 root 用户运行等特性，不仅显著提升了构建效率，也增强了应用的安全性。结合 Drone CI 的自动化构建流程，该模块为 API 网关微服务的持续集成与交付提供了坚实的基础。