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

项目概述

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

目录

  1. 项目简介
  2. 项目结构
  3. 核心模块分析
  4. 架构设计
  5. 构建流程与使用方法
  6. 安全与优化实践
  7. CI/CD集成
  8. 总结

项目简介

docker-registry 项目是一个为不同技术栈提供优化基础镜像的容器化构建系统。该项目通过三个核心模块——alpine-base、kami-gateway 和 kami-spider-monorepo，为 Alpine、Go 和 Python 技术栈提供高度优化的 Docker 基础镜像。其核心设计理念是通过分层继承、构建脚本复用和非 root 安全运行机制，实现快速、安全、一致的容器化部署。

该项目的主要功能包括：

  • 加速镜像构建：通过预下载依赖和缓存基础层，显著缩短构建时间
  • 统一开发环境：为团队提供一致的运行时环境，避免“在我机器上能运行”的问题
  • 中国镜像源优化：配置阿里云等国内镜像源，大幅提升依赖下载速度
  • 自定义证书集成：预装 Comodo AAA 证书，解决特定环境下的 SSL/TLS 信任问题
  • 轻量化设计：基于 Alpine Linux 和 slim 镜像，保持最小化体积

在微服务架构中，这些基础镜像作为所有服务的共同起点，确保了技术栈的一致性、安全性和部署效率。

项目结构

项目采用模块化设计，每个技术栈拥有独立的目录，包含其特定的构建文件和配置。

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

Diagram sources

Section sources

核心模块分析

alpine-base 模块

alpine-base 模块是整个项目的基础，为所有其他镜像提供一个优化的 Alpine Linux 运行时环境。

核心特性：

  • 基础镜像：基于 alpine:latest，保证了最小化体积（约 50MB）
  • 中国镜像源：配置阿里云镜像源，加速 apk 包管理器的下载速度
  • 时区配置：默认设置为 Asia/Shanghai
  • 预装工具：包含 curl、wget、git、bash 等常用工具
  • 安全机制：创建非 root 用户 appuser (UID: 1001)，强制应用以最小权限运行
  • 证书管理：预装 CA 证书和 Comodo AAA 自定义证书

该模块生成的镜像标记为 alpine-base:latest，可作为其他自定义镜像的基础。

Section sources

kami-gateway 模块

kami-gateway 模块专为 Go 语言应用设计，构建了一个包含 Go 1.25 编译环境和 Alpine 运行时的完整基础镜像。

核心特性：

  • Go 编译环境：基于 golang:1.25-alpine，提供完整的 Go 开发工具链
  • 依赖预下载：在构建过程中执行 go mod download，缓存所有依赖，使后续应用构建时间缩短至 10-30 秒
  • 中国镜像源：配置 GOPROXY=https://goproxy.cn,direct，加速 Go 模块下载
  • 安全运行：同样使用非 root 用户 appuser 运行应用
  • 多阶段构建：虽然未在基础镜像中体现，但其设计支持通过 Dockerfile.improved 实现多阶段构建以优化最终镜像

该模块生成的镜像标记为 kami-gateway-base:latest。

Section sources

kami-spider-monorepo 模块

kami-spider-monorepo 模块为 Python 应用，特别是网络爬虫类应用，提供了一个功能完备的基础镜像。

核心特性：

  • Python 运行时：基于 python:3.13-slim，平衡了功能和体积
  • UV 包管理器：使用现代的 uv 工具替代 pip，显著提升依赖安装速度
  • Playwright 支持：预装 Playwright 运行时库和 Chromium 浏览器，开箱即用
  • 系统依赖：安装了 Playwright 所需的所有系统级库（如 libnss3、libatk-bridge2.0-0 等）
  • 代理支持：通过 USE_PROXY 构建参数，支持使用清华源等国内镜像加速 PyPI 包下载
  • 安全配置：创建非 root 用户 appuser，并正确设置文件权限

该模块生成的镜像标记为 kami-spider-base:latest。

Section sources

架构设计

该项目的架构设计体现了清晰的分层和继承思想。

graph TD
subgraph "基础层"
A[alpine:latest] --> B[alpine-base:latest]
end
subgraph "技术栈层"
B --> C[golang:1.25-alpine]
C --> D[kami-gateway-base:latest]
B --> E[python:3.13-slim]
E --> F[kami-spider-base:latest]
end
subgraph "应用层"
D --> G[具体 Go 应用镜像]
F --> H[具体 Python 应用镜像]
end

Diagram sources

Section sources

设计要点：

  1. 分层继承：alpine-base 作为最底层的通用优化镜像，被 kami-gateway 和 kami-spider-monorepo 继承，避免了重复配置。
  2. 构建脚本复用：所有模块的 build-base-image.sh 脚本结构高度一致，实现了构建逻辑的标准化。
  3. 环境变量控制：通过 DOCKER_REGISTRY、VERSION、USE_PROXY 等环境变量，灵活控制构建行为。
  4. 非 root 安全机制：所有镜像都创建了 appuser 用户，强制应用以非特权用户身份运行，提升了容器安全性。

构建流程与使用方法

构建流程

所有模块的构建流程都通过 build-base-image.sh 脚本自动化完成。

flowchart TD
Start([开始构建]) --> SetEnv["设置环境变量\n(DOCKER_REGISTRY, VERSION)"]
SetEnv --> Build["执行 docker build"]
Build --> Tag["打标签\n(local 和 registry)"]
Tag --> Push{"是否推送至远程仓库?"}
Push --> |是| PushToRegistry["执行 docker push"]
Push --> |否| SkipPush["跳过推送"]
PushToRegistry --> Complete["构建完成"]
SkipPush --> Complete
Complete --> ShowSize["显示镜像大小"]
ShowSize --> End([结束])

Diagram sources

Section sources

使用方法

构建基础镜像

# 构建 alpine-base 镜像
cd alpine-base && ./build-base-image.sh

# 构建并推送到指定镜像仓库
DOCKER_REGISTRY=git.oceanpay.cc/danial ./build-base-image.sh

在应用中使用

# 使用 alpine-base 作为基础
FROM git.oceanpay.cc/danial/alpine-base:latest
COPY --chown=appuser:appuser . /app/
USER appuser
CMD ["./your-app"]

# 使用 kami-gateway-base 作为基础
FROM git.oceanpay.cc/danial/kami-gateway-base:latest
# 复制源码并构建
COPY --chown=appuser:appuser . .
RUN go build -o main .
CMD ["./main"]

安全与优化实践

安全实践

  • 非 root 用户：所有镜像都创建了 UID 为 1001 的 appuser，并通过 USER 指令切换，遵循最小权限原则。
  • 文件权限：应用目录 /app 及其内容的所有权被正确设置为 appuser。
  • 镜像来源：基础镜像均来自官方仓库（alpine, golang, python），保证了来源可信。

优化实践

  • 中国镜像源：Alpine、Go 和 Python 的依赖下载均配置了国内镜像源，解决了网络延迟问题。
  • 依赖预下载：Go 模块和 Python 依赖在构建基础镜像时就已下载，避免了每次构建应用时的重复下载。
  • 轻量化：使用 --no-cache 和 rm -rf 清理构建缓存，保持镜像体积最小化。
  • 环境变量：通过 CGO_ENABLED=0 等 Go 环境变量，构建静态链接的二进制文件，减少对系统库的依赖。

CI/CD集成

kami-gateway 模块明确提到了使用 Drone CI 进行自动化构建。其 CI/CD 流程如下：

  1. 触发条件：检测到 kami-gateway/ 目录下的代码变更。
  2. 自动构建：CI 系统自动执行 build-base-image.sh 脚本。
  3. 条件推送：根据配置，将新构建的 kami-gateway-base:latest 镜像推送到远程镜像仓库。
  4. 资源优化：采用条件构建策略，避免不必要的资源消耗。

这种自动化流程确保了基础镜像的及时更新和一致性，是 DevOps 实践的重要组成部分。

Section sources

总结

docker-registry 项目通过精心设计的模块化架构，为不同技术栈提供了高效、安全、一致的基础镜像解决方案。其核心价值在于：

  • 提升效率：通过预构建和缓存，将应用构建时间从分钟级缩短到秒级。
  • 保障安全：强制非 root 用户运行，降低了安全风险。
  • 统一环境：消除了开发、测试、生产环境之间的差异。
  • 优化网络：针对中国网络环境进行了专门优化。

该项目是现代微服务架构中不可或缺的基础设施，为团队的快速迭代和稳定部署提供了坚实的基础。