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

6.4 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) - [README.md](file://alpine-base/README.md) - [README.md](file://kami-gateway/README.md) - [README.md](file://kami-spider-monorepo/README.md)

目录

  1. 简介
  2. 构建基础镜像
  3. 环境变量配置
  4. 实际应用示例
  5. 常见问题与解决方案
  6. 最佳实践

简介

本指南旨在帮助新手开发者在5分钟内完成基础镜像的本地构建。项目提供了三个模块（alpine-base、kami-gateway、kami-spider-monorepo）的预构建基础镜像，每个模块都包含一个 build-base-image.sh 构建脚本，用于创建优化的Docker基础镜像。这些镜像预装了常用工具、配置了中国镜像源、设置了正确的时区，并遵循安全最佳实践。

Section sources

构建基础镜像

基本构建步骤

要构建基础镜像，请按照以下步骤操作：

  1. 打开终端并导航到目标模块目录
  2. 运行构建脚本
# 进入 alpine-base 模块
cd alpine-base
# 执行构建
./build-base-image.sh

# 进入 kami-gateway 模块
cd kami-gateway
# 执行构建
./build-base-image.sh

# 进入 kami-spider-monorepo 模块
cd kami-spider-monorepo
# 执行构建
./build-base-image.sh

构建成功后，您将看到类似以下的输出：

🎉 Build completed successfully!
Available images:
  - alpine-base:latest
  - alpine-base:${VERSION}

Section sources

环境变量配置

构建脚本支持以下关键环境变量，您可以在运行脚本前设置它们：

DOCKER_REGISTRY

指定镜像推送的目标仓库地址。如果未设置，将使用默认值。

  • alpine-base 和 kami-gateway: 默认为 git.oceanpay.cc/danial
  • kami-spider-monorepo: 默认为 localhost:5000
# 推送到私有镜像仓库
DOCKER_REGISTRY=your-registry.com ./build-base-image.sh

VERSION

指定镜像的版本标签。默认值为 latest。

# 构建指定版本的镜像
VERSION=1.0.0 ./build-base-image.sh

USE_PROXY

仅适用于 kami-spider-monorepo 模块，用于在构建时启用代理下载。

# 使用代理构建
USE_PROXY=1 ./build-base-image.sh

Section sources

实际应用示例

构建场景示例

不带参数构建

# 在 alpine-base 目录下执行
./build-base-image.sh
# 结果: 创建 alpine-base:latest 镜像

使用代理构建

# 在 kami-spider-monorepo 目录下执行
USE_PROXY=1 ./build-base-image.sh
# 结果: 启用代理下载依赖并创建 kami-spider-base:latest 镜像

推送到私有镜像仓库

# 在 kami-gateway 目录下执行
DOCKER_REGISTRY=my-registry.com/company ./build-base-image.sh
# 结果: 构建并推送 kami-gateway-base:latest 到指定仓库

构建成功后的镜像标签

  • alpine-base: alpine-base:latest, alpine-base:${VERSION}
  • kami-gateway: kami-gateway-base:latest, kami-gateway-base:${VERSION}
  • kami-spider-monorepo: kami-spider-base:latest, kami-spider-base:${VERSION}

在应用Dockerfile中使用基础镜像

# 使用基础镜像
FROM alpine-base:latest

# 复制应用代码并设置正确的所有者
COPY --chown=appuser:appuser . /app/

# 切换到非root用户运行
USER appuser

# 运行应用
CMD ["./your-app"]

Section sources

常见问题与解决方案

网络超时

问题: 构建过程中出现网络下载超时错误。

解决方案:

  1. 对于 kami-spider-monorepo 模块，使用代理构建： 
    USE_PROXY=1 ./build-base-image.sh
  2. 检查网络连接，确保可以访问所需的包管理器源。

权限错误

问题: 运行构建脚本时出现权限不足错误。

解决方案:

  1. 确保构建脚本具有可执行权限： 
    chmod +x build-base-image.sh
  2. 确保Docker服务正在运行且当前用户有权限访问Docker守护进程。

镜像推送失败

问题: 当设置 DOCKER_REGISTRY 时，镜像推送失败。

解决方案:

  1. 确认已登录到目标镜像仓库： 
    docker login your-registry.com
  2. 检查仓库地址和权限是否正确。

Section sources

最佳实践

非root用户运行

所有基础镜像都配置了非root用户 appuser (UID: 1001)，这是重要的安全最佳实践。在您的应用Dockerfile中，应始终使用 USER 指令切换到非root用户：

# 在复制应用代码后切换用户
COPY --chown=appuser:appuser . /app/
USER appuser

镜像优化

  • 轻量化: 基于Alpine Linux，镜像体积小（约50MB）
  • 快速构建: 预装常用工具和配置，避免重复下载
  • 网络优化: 配置中国镜像源，加速依赖下载
  • 证书支持: 预装CA证书和自定义证书

CI/CD集成

kami-gateway 模块已配置Drone CI，能够自动检测目录变更并构建推送基础镜像，实现条件构建以节省资源。

Section sources