1ecefc80af
- 设置 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 - 保持其他环境变量配置不变 - 解决国内代理访问速度或稳定性问题
7.0 KiB
构建与使用
**Referenced Files in This Document** - [build-base-image.sh](file://kami-spider-monorepo/build-base-image.sh) - [Dockerfile.base](file://kami-spider-monorepo/Dockerfile.base) - [README.md](file://kami-spider-monorepo/README.md) - [build-base-image.sh](file://alpine-base/build-base-image.sh) - [Dockerfile.base](file://alpine-base/Dockerfile.base) - [README.md](file://alpine-base/README.md)目录
简介
本文档详细说明如何构建和使用 kami-spider-base 基础 Docker 镜像。该镜像为爬虫应用提供完整的运行时环境，包含 Python 3.13、UV 包管理器、所有项目依赖以及 Playwright 浏览器。通过本指南，开发者可以了解构建脚本的工作原理、配置选项以及如何在实际项目中引用此基础镜像。
Section sources
前置条件与环境准备
在执行构建脚本之前，请确保本地开发环境满足以下条件：
- Docker 引擎：已安装并运行 Docker 服务
- 工作目录：位于
kami-spider-monorepo项目根目录 - 网络连接：能够访问外部包仓库（或配置代理）
- 权限配置：当前用户具有执行脚本和调用 Docker 命令的权限
推荐使用 Linux 或 macOS 系统进行构建。Windows 用户建议使用 WSL2 环境以获得最佳兼容性。
Section sources
构建脚本详解
build-base-image.sh 脚本是构建 kami-spider-base 镜像的核心工具，其执行流程如下：
- 初始化配置：读取环境变量并设置默认值
- 镜像构建：调用
docker build命令，基于Dockerfile.base创建镜像 - 标签处理：为镜像添加版本标签和 latest 标签
- 注册表推送：当指定非本地注册表时，推送镜像到远程仓库
- 结果展示：输出构建完成信息和镜像大小统计
脚本通过 set -e 确保任何步骤失败时立即终止，保证构建过程的可靠性。
flowchart TD
A[开始构建] --> B[读取环境变量]
B --> C[执行Docker构建]
C --> D[生成镜像标签]
D --> E{是否推送?}
E --> |是| F[推送至注册表]
E --> |否| G[跳过推送]
F --> H[显示构建结果]
G --> H
H --> I[结束]
Diagram sources
Section sources
环境变量配置
构建脚本支持以下环境变量来自定义构建行为：
: DOCKER_REGISTRY
- 作用：指定目标镜像注册表地址
- 默认值：
localhost:5000 - 示例：
DOCKER_REGISTRY=git.oceanpay.cc/danial
: VERSION
- 作用：设置镜像版本标签
- 默认值：
latest - 示例：
VERSION=1.2.0
: USE_PROXY
- 作用：启用国内镜像源代理
- 默认值：
0（禁用） - 有效值：
0或1 - 功能：当值为
1时，使用清华源加速 Python 包下载
这些变量采用 ${VARNAME:-default} 语法，允许用户覆盖默认值而不影响全局环境。
Section sources
镜像构建与推送流程
构建命令示例
# 基本构建（使用本地注册表）
./build-base-image.sh
# 使用代理构建
USE_PROXY=1 ./build-base-image.sh
# 推送到私有注册表
DOCKER_REGISTRY=git.oceanpay.cc/danial ./build-base-image.sh
# 指定版本并推送
DOCKER_REGISTRY=git.oceanpay.cc/danial VERSION=1.0.0 ./build-base-image.sh
推送逻辑说明
脚本通过比较 REGISTRY 变量与 localhost:5000 来决定是否执行推送操作：
- 当
REGISTRY为localhost:5000时，仅在本地构建镜像 - 当
REGISTRY为其他值时，自动执行docker tag和docker push操作
此设计避免了向本地测试注册表不必要的推送操作，提高开发效率。
Section sources
基础镜像使用指南
在实际爬虫项目的 Dockerfile 中，可通过以下方式引用 kami-spider-base 镜像：
# 使用基础镜像
FROM git.oceanpay.cc/danial/kami-spider-base:latest
# 复制应用代码
COPY --chown=appuser:appuser . /app/
# 切换到非 root 用户
USER appuser
# 设置工作目录
WORKDIR /app
# 运行应用
CMD ["python", "main.py"]
基础镜像已预装所有依赖，包括：
- Python 3.13 运行时
- UV 包管理器
- Playwright 及其系统依赖
- Chromium 浏览器
- 非 root 用户
appuser
这使得应用 Dockerfile 可以保持极简，专注于业务逻辑。
Section sources
输出信息解析
构建成功后，脚本会输出以下关键信息：
: 构建状态
✅ Combined base image built successfully!：表示镜像构建成功✅ Image pushed to registry successfully!：表示推送成功
: 可用镜像 列出本地生成的镜像标签，通常包含版本标签和 latest 标签。
: 镜像大小
通过 docker images 命令显示镜像大小，格式为表格：
REPOSITORY TAG SIZE
kami-spider-base latest 1.2GB
镜像大小约为 1.2GB，主要由以下部分构成：
- Python 运行时：~100MB
- 系统依赖库：~300MB
- Python 第三方包：~200MB
- Chromium 浏览器：~600MB
Section sources
常见问题排查
问题1：构建失败，提示网络超时
可能原因：无法访问外部包仓库 解决方案：
- 启用代理：
USE_PROXY=1 ./build-base-image.sh - 检查网络连接和防火墙设置
问题2：推送失败，认证错误
可能原因：未登录目标注册表 解决方案：
# 登录私有注册表
docker login git.oceanpay.cc
问题3：权限错误
可能原因：Docker 服务未运行或用户无权限 解决方案：
- 启动 Docker 服务
- 将用户添加到 docker 组：
sudo usermod -aG docker $USER
问题4：磁盘空间不足
可能原因：Chromium 浏览器占用大量空间 解决方案：
- 清理 Docker 缓存：
docker system prune - 确保至少有 2GB 可用磁盘空间
Section sources