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

7.9 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) - [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-base 基础镜像到实际 API 网关服务镜像的完整构建指南。涵盖如何在应用项目的 Dockerfile 中继承基础镜像，复用预置的 Go 编译环境与依赖缓存以实现极速构建，以及多阶段构建、运行时配置、安全实践等最佳实践。

项目结构

kami-gateway 目录包含构建基础镜像所需的核心文件，包括 Dockerfile、构建脚本和 Go 模块配置。该基础镜像专为 Go 应用设计，预置了编译环境和依赖，旨在加速应用镜像的构建过程。

graph TD
A[kami-gateway/] --> B[Dockerfile.base]
A --> C[build-base-image.sh]
A --> D[go.mod]
A --> E[go.sum]
A --> F[README.md]

图示来源

章节来源

核心组件

kami-gateway 基础镜像的核心组件包括：基于 golang:1.25-alpine 的编译环境、预下载的 Go 依赖包、中国镜像源配置、时区与证书设置，以及非 root 用户运行支持。这些组件共同实现了快速、安全、可复用的构建基础。

章节来源

架构概述

kami-gateway 的镜像构建采用分层架构。基础镜像（kami-gateway-base）封装了通用的 Go 编译环境和依赖。应用镜像则通过 FROM 指令继承此基础镜像，在此基础上编译应用代码并进行运行时配置，最终形成一个轻量、安全的生产级镜像。

graph LR
subgraph "应用镜像构建阶段"
A[应用代码] --> B[Dockerfile.improved]
B --> C[编译二进制]
C --> D[精简运行时镜像]
end
subgraph "基础镜像层"
E[golang:1.25-alpine] --> F[kami-gateway-base]
F --> |继承| B
end
style F fill:#f9f,stroke:#333
style D fill:#bbf,stroke:#333

图示来源

详细组件分析

基础镜像构建分析

Dockerfile.base 定义了 kami-gateway-base 镜像的构建过程。它从官方 Go 镜像开始，优化了国内网络环境下的依赖下载，并预下载了所有 Go 模块，从而在应用构建阶段避免了耗时的 go mod download 步骤。

flowchart TD
Start([开始]) --> SetEnv["设置环境变量<br/>GO111MODULE=on<br/>GOPROXY=https://goproxy.cn"]
SetEnv --> ConfigureAlpine["配置 Alpine 镜像源<br/>使用阿里云镜像"]
ConfigureAlpine --> InstallDeps["安装系统依赖<br/>tzdata, ca-certificates, git"]
InstallDeps --> SetupTimezone["设置时区为 Asia/Shanghai"]
SetupTimezone --> AddCerts["添加自定义证书"]
AddCerts --> CreateUser["创建非 root 用户 appuser"]
CreateUser --> CreateAppDir["创建应用目录 /app"]
CreateAppDir --> SwitchUser["切换到 appuser 用户"]
SwitchUser --> CopyGoFiles["复制 go.mod 和 go.sum"]
CopyGoFiles --> PreDownload["预下载 Go 依赖<br/>go mod download && verify"]
PreDownload --> LabelImage["为镜像添加标签"]
LabelImage --> End([基础镜像构建完成])

图示来源

章节来源

应用镜像构建流程

应用镜像的构建流程分为两个阶段：第一阶段使用 kami-gateway-base 编译二进制文件，第二阶段基于一个极简的运行时镜像（如 distroless）打包，仅包含运行应用所需的文件，从而显著减小最终镜像体积。

sequenceDiagram
participant Dev as 开发者
participant BuildScript as build-base-image.sh
participant Docker as Docker Engine
participant Registry as 镜像仓库
Dev->>BuildScript : 执行 ./build-base-image.sh
BuildScript->>Docker : docker build --file Dockerfile.base ...
Docker->>Docker : 构建 kami-gateway-base 镜像
Docker-->>BuildScript : 构建成功
BuildScript->>BuildScript : 为镜像打标签
alt 指定了镜像仓库
BuildScript->>Docker : docker tag ...
BuildScript->>Docker : docker push ...
Docker-->>Registry : 推送镜像
Registry-->>BuildScript : 推送成功
end
BuildScript->>Dev : 构建完成，镜像可用

图示来源

章节来源

依赖分析

kami-gateway 基础镜像的依赖主要分为两部分：系统依赖和 Go 模块依赖。系统依赖通过 apk add 安装，包括时区数据、证书和 Git。Go 模块依赖则通过 go mod download 预先下载，其具体版本由 go.mod 和 go.sum 文件精确锁定，确保了构建的可重现性。

erDiagram
BASE_IMAGE ||--o{ SYSTEM_DEPS : "包含"
BASE_IMAGE ||--o{ GO_DEPS : "包含"
BASE_IMAGE ||--o{ CONFIG : "包含"
SYSTEM_DEPS {
string package_name PK
string version
string purpose
}
GO_DEPS {
string module_name PK
string version
string checksum
}
CONFIG {
string config_type PK
string value
string description
}
SYSTEM_DEPS }o--|| BASE_IMAGE : "系统依赖"
GO_DEPS }o--|| BASE_IMAGE : "Go依赖"
CONFIG }o--|| BASE_IMAGE : "配置项"

图示来源

章节来源

性能考虑

使用 kami-gateway-base 的主要性能优势在于极速构建。由于基础镜像已预置了 Go 编译环境和所有依赖，应用构建阶段的耗时从数分钟缩短至 10-30 秒。此外，多阶段构建确保了最终镜像的精简，减少了网络传输时间和运行时攻击面。

章节来源

故障排除指南

  • 问题：构建时无法下载 Go 模块
    • 原因：网络问题或 GOPROXY 配置错误。
    • 解决：确认 Dockerfile.base 中的 GOPROXY 设置为 https://goproxy.cn,direct。
  • 问题：镜像推送失败
    • 原因：未登录镜像仓库或 DOCKER_REGISTRY 环境变量设置错误。
    • 解决：执行 docker login git.oceanpay.cc 并检查 build-base-image.sh 脚本中的 REGISTRY 变量。
  • 问题：容器启动失败，权限错误
    • 原因：未正确创建非 root 用户或文件权限问题。
    • 解决：检查 Dockerfile.base 中 addgroup、adduser 和 chown 命令的执行。

章节来源

结论

kami-gateway-base 镜像通过预置环境和依赖，为 Go 应用提供了一个高效、安全的构建基础。通过遵循本文档的指南，开发者可以快速构建出轻量、安全且符合最佳实践的应用镜像，显著提升 CI/CD 流程的效率。