danial/docker-registry
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
Files
1ecefc80af4c491ffd6eb5dac4def291b0f97492
docker-registry/.qoder/repowiki/zh/content/通用构建指南.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

11 KiB
Raw Blame History

通用构建指南

**Referenced Files in This Document ** - [build-base-image.sh](file://alpine-base/build-base-image.sh) - [build-base-image.sh](file://kami-gateway/build-base-image.sh) - [build-base-image.sh](file://kami-spider-monorepo/build-base-image.sh)

目录

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

引言

本文档旨在为 kami 项目中的通用构建流程提供权威指南。通过系统化分析 alpine-base、kami-gateway 和 kami-spider-monorepo 三个模块共用的构建机制，深入解析 build-base-image.sh 脚本的实现逻辑。文档将详细说明环境变量的统一处理方式、Docker 镜像标签的动态生成策略、构建命令的执行流程，并对比各模块构建脚本的异同，提炼出可复用的最佳实践模式，帮助开发者掌握整个项目的构建体系，提升自动化和可维护性。

项目结构

kami 项目的构建体系由三个主要模块构成，每个模块均包含一个独立的 build-base-image.sh 构建脚本。这些脚本遵循相似的设计模式，用于构建各自模块所需的 Docker 基础镜像。项目结构清晰，按功能模块进行隔离，便于独立构建和维护。

graph TB
subgraph "构建模块"
A[alpine-base]
B[kami-gateway]
C[kami-spider-monorepo]
end
A --> |使用| Script[build-base-image.sh]
B --> |使用| Script
C --> |使用| Script
Script --> |执行| Docker[docker build/tag/push]

Diagram sources

Section sources

核心组件

build-base-image.sh 脚本是整个构建体系的核心组件。它是一个 Bash 脚本，为每个模块提供标准化的 Docker 镜像构建、标记和推送流程。该脚本通过环境变量进行配置，实现了高度的灵活性和可复用性。其主要功能包括：解析环境变量、调用 docker build 命令构建镜像、根据配置生成并应用镜像标签、将镜像推送到指定的 Docker 仓库，并在构建完成后输出镜像信息。

Section sources

架构概述

构建系统的架构遵循一个简洁而高效的模式。开发者通过设置环境变量来配置构建过程，然后执行 build-base-image.sh 脚本。脚本首先读取环境变量，然后执行 docker build 命令，利用 Dockerfile.base 文件构建本地镜像。接着，脚本会根据 DOCKER_REGISTRY 的配置，为镜像打上包含仓库地址的标签。如果指定了非本地的仓库，脚本会自动执行 docker push 命令将镜像推送到远程仓库。整个流程通过 set -e 保证了错误的及时中断，确保了构建的可靠性。

sequenceDiagram
participant Developer as 开发者
participant Script as build-base-image.sh
participant Docker as Docker Engine
participant Registry as Docker Registry
Developer->>Script : 设置环境变量并执行脚本
Script->>Script : 读取 DOCKER_REGISTRY, VERSION, USE_PROXY
Script->>Docker : docker build --tag <name> : <version>
Docker-->>Script : 构建成功
alt 非本地仓库
Script->>Script : docker tag 添加仓库前缀
Script->>Registry : docker push 推送镜像
Registry-->>Script : 推送成功
end
Script->>Developer : 输出构建完成信息和镜像大小

Diagram sources

详细组件分析

构建脚本实现逻辑分析

build-base-image.sh 脚本的实现逻辑高度一致，体现了良好的代码复用原则。所有脚本都以 #!/bin/bash 开头，并通过 set -e 确保在任何命令失败时立即退出，防止错误的累积。脚本的核心是 docker build 命令，它使用 --file Dockerfile.base 指定构建文件，并通过 --tag 参数为镜像打上两个标签：一个由 VERSION 环境变量指定的版本号标签，另一个是 latest 标签。

Section sources

环境变量处理

脚本通过 Bash 的参数扩展语法 ${VAR:-default} 来处理环境变量，这使得脚本既灵活又健壮。关键环境变量及其作用如下：

  • DOCKER_REGISTRY: 指定 Docker 镜像仓库的地址。默认值在不同模块中有所不同（alpine-base 和 kami-gateway 默认为 git.oceanpay.cc/danial，kami-spider-monorepo 默认为 localhost:5000）。当该值不为 localhost:5000 时，脚本会执行 docker tag 和 docker push 操作。
  • VERSION: 指定构建的镜像版本号。默认值为 latest。该变量用于生成镜像的版本标签。
  • USE_PROXY: 一个布尔标志（0 或 1），仅在 kami-spider-monorepo 模块中使用。当设置为 1 时，它会作为 --build-arg 传递给 docker build 命令，用于在构建过程中启用中国代理加速，从而加快依赖下载速度。
flowchart TD
Start([开始构建]) --> SetVars["设置环境变量\nDOCKER_REGISTRY, VERSION, USE_PROXY"]
SetVars --> ReadVars["读取变量值\n使用默认值回退"]
ReadVars --> BuildImage["执行 docker build\n生成本地镜像"]
BuildImage --> CheckRegistry{"REGISTRY != localhost:5000?"}
CheckRegistry --> |是| TagImage["执行 docker tag\n添加仓库前缀"]
TagImage --> PushImage["执行 docker push\n推送至远程仓库"]
PushImage --> ShowInfo["显示构建完成信息\n和镜像大小"]
CheckRegistry --> |否| ShowInfo
ShowInfo --> End([构建完成])

Diagram sources

模块间构建脚本对比

通过对三个模块的 build-base-image.sh 脚本进行对比，可以发现它们在核心逻辑上高度一致，但在细节上有所差异，以适应各自模块的需求。

特性 alpine-base kami-gateway kami-spider-monorepo
基础镜像名称 alpine-base kami-gateway-base kami-spider-base
默认 DOCKER_REGISTRY git.oceanpay.cc/danial git.oceanpay.cc/danial localhost:5000
USE_PROXY 支持 否 否 是
构建参数 (build-arg) 无 无 USE_PROXY
用途 提供优化的 Alpine 基础环境 提供 Go 环境和 Alpine 运行时 提供包含 Python 依赖和 Playwright 的综合基础环境

此对比表明，kami-spider-monorepo 模块的构建脚本更为复杂，因为它需要处理网络代理问题，而其他两个模块的脚本则更侧重于基础环境的构建。

Section sources

依赖分析

该构建系统的主要依赖是 Docker 引擎本身。脚本通过调用 docker CLI 命令与 Docker 守护进程进行交互。此外，构建过程依赖于每个模块根目录下的 Dockerfile.base 文件，该文件定义了镜像的具体构建步骤。kami-spider-monorepo 模块还依赖于 pyproject.toml 和 uv.lock 文件来管理其 Python 依赖。

graph LR
Script[build-base-image.sh] --> Docker[docker CLI]
Script --> Dockerfile[Dockerfile.base]
Script --> Env[环境变量]
Dockerfile --> BaseImage[基础操作系统镜像]
Docker --> Registry[Docker Registry]

Diagram sources

性能考虑

构建过程的性能主要受网络带宽和 Docker 构建缓存的影响。USE_PROXY=1 环境变量的引入是针对中国地区网络环境的性能优化，通过代理加速依赖下载，显著缩短了构建时间。此外，Docker 的构建缓存机制可以极大地提升重复构建的效率。只要 Dockerfile 中的指令和上下文没有改变，Docker 就会重用之前的构建层，避免了不必要的重复工作。为了最大化利用缓存，建议在 Dockerfile 中将不常变动的指令（如安装系统包）放在前面，而将经常变动的指令（如复制应用代码）放在后面。

故障排除指南

当构建过程出现问题时，可以采取以下调试技巧：

  1. 检查环境变量：确保 DOCKER_REGISTRY、VERSION 等环境变量已正确设置。
  2. 查看脚本输出：脚本本身提供了详细的日志信息，包括正在执行的步骤和最终的镜像大小，这些信息有助于定位问题。
  3. 手动执行命令：可以复制脚本中的 docker build、docker tag 或 docker push 命令，在终端中手动执行，以获取更详细的错误信息。
  4. 启用详细模式：虽然当前脚本未使用 set -x，但可以在脚本开头添加此命令，以启用 Bash 的调试模式，逐行输出执行的命令，这对于追踪复杂的逻辑分支非常有用。

Section sources

结论

kami 项目的构建体系通过标准化的 build-base-image.sh 脚本，实现了跨模块的构建自动化。该体系设计简洁、逻辑清晰，通过环境变量实现了良好的配置灵活性。USE_PROXY 变量的引入体现了对特定部署环境的考量。通过遵循本文档中总结的最佳实践，如合理利用构建缓存、正确设置环境变量和使用调试技巧，开发者可以高效、可靠地完成镜像构建任务，为项目的持续集成和部署（CI/CD）奠定坚实的基础。