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 - 保持其他环境变量配置不变 - 解决国内代理访问速度或稳定性问题
12 KiB
kami-spider-monorepo 模块
**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) - [pyproject.toml](file://kami-spider-monorepo/pyproject.toml) - [uv.lock](file://kami-spider-monorepo/uv.lock) - [README.md](file://kami-spider-monorepo/README.md)目录
简介
kami-spider-monorepo 模块是为Python爬虫平台设计的基础镜像构建系统，旨在提供一个开箱即用、功能完备的开发和运行环境。该模块通过Docker技术封装了Python 3.13运行时、UV包管理器、项目所需的所有Python依赖以及Playwright浏览器自动化框架，为爬虫应用的快速开发和部署提供了坚实的基础。其核心价值在于通过预配置和预安装，显著提升了开发效率和部署一致性，同时通过非root用户运行和确定性依赖管理增强了安全性与可靠性。
项目结构
kami-spider-monorepo 模块的项目结构简洁明了，专注于基础镜像的构建。其核心文件包括用于定义镜像构建流程的 Dockerfile.base、用于自动化构建的 build-base-image.sh 脚本，以及用于管理Python依赖的 pyproject.toml 和 uv.lock 文件。这种结构将构建逻辑、依赖配置和环境定义清晰地分离，便于维护和理解。
graph TD
A[kami-spider-monorepo] --> B[Dockerfile.base]
A --> C[build-base-image.sh]
A --> D[pyproject.toml]
A --> E[uv.lock]
A --> F[README.md]
Diagram sources
Section sources
核心组件
该模块的核心由四个关键文件构成：Dockerfile.base 定义了镜像的构建步骤和最终形态；build-base-image.sh 提供了可执行的构建命令，简化了镜像的创建过程；pyproject.toml 声明了项目所需的所有Python包及其版本范围；uv.lock 则精确锁定了所有依赖包的版本和哈希值，确保了构建的可重复性。这些组件协同工作，共同实现了从源码到可运行镜像的完整构建流程。
Section sources
架构概述
kami-spider-monorepo 模块的架构是一个典型的Docker镜像构建流水线。用户通过执行 build-base-image.sh 脚本来启动构建过程。该脚本会调用Docker命令，并根据环境变量（如 USE_PROXY）来决定是否使用代理。Docker引擎则根据 Dockerfile.base 的指令，从基础的 python:3.13-slim 镜像开始，逐步安装系统依赖、UV包管理器、Python依赖包，并最终完成Playwright浏览器的安装。整个过程确保了最终生成的 kami-spider-base:latest 镜像包含了所有必要的运行时环境。
sequenceDiagram
participant User as 开发者
participant Script as build-base-image.sh
participant Docker as Docker引擎
participant Dockerfile as Dockerfile.base
User->>Script : 执行 ./build-base-image.sh
Script->>Docker : docker build ... --build-arg USE_PROXY=...
Docker->>Dockerfile : 解析构建指令
Dockerfile->>Docker : 安装系统依赖 (apt-get)
Dockerfile->>Docker : 复制并安装 UV 包管理器
Dockerfile->>Docker : 创建非root用户 appuser
Dockerfile->>Docker : 复制 pyproject.toml 和 uv.lock
Dockerfile->>Docker : 使用 uv sync 安装 Python 依赖
Dockerfile->>Docker : 安装 Playwright 系统依赖
Dockerfile->>Docker : 安装 Chromium 浏览器
Docker->>Script : 构建成功，生成镜像
Script->>User : 显示构建完成信息
Diagram sources
详细组件分析
Dockerfile.base 分析
Dockerfile.base 是整个镜像构建的核心蓝图。它从一个轻量级的 python:3.13-slim 基础镜像开始，通过一系列精心设计的指令，构建出一个功能完备的爬虫运行环境。
环境变量配置
文件首先通过 ENV 指令设置了一系列关键的环境变量。PYTHONUNBUFFERED=1 确保Python的输出能够实时打印，便于调试；PYTHONDONTWRITEBYTECODE=1 禁止生成 .pyc 文件，以节省空间；UV_COMPILE_BYTECODE=1 则指示UV在安装包时编译字节码以提升运行时性能。PATH 变量被更新以包含虚拟环境的bin目录，确保命令可以直接执行。PLAYWRIGHT_BROWSERS_PATH 指定了浏览器的安装路径，实现了浏览器的集中管理。
系统依赖安装
RUN apt-get update && apt-get install -y --no-install-recommends 指令用于安装Playwright运行Chromium所必需的系统级库。这些库包括图形界面支持（如 libx11, libatk-bridge2.0-0）、音频支持（libasound2）、打印支持（libcups2t64）和字体支持（fonts-liberation）等。使用 --no-install-recommends 标志可以避免安装不必要的推荐包，从而减小镜像体积。
UV包管理器与非root用户安全配置
镜像通过 COPY --from=ghcr.io/astral-sh/uv:latest /uv /usr/local/bin/uv 这一多阶段构建技巧，从官方镜像中复制了UV包管理器的二进制文件，确保了其来源的可靠性和版本的最新性。随后，Dockerfile创建了一个名为 appuser 的非root用户，并将工作目录 /app 及其子目录的所有权赋予该用户。这遵循了最小权限原则，极大地提升了容器运行时的安全性，即使应用存在漏洞，攻击者也难以获得主机的root权限。
确定性依赖安装与Playwright集成
依赖安装是通过 uv sync 命令完成的。该命令结合 --frozen 参数，会严格依据 uv.lock 文件中的锁定版本进行安装，从而保证了每次构建的依赖环境完全一致，实现了确定性构建。Dockerfile.base 巧妙地在 root 用户和 appuser 用户之间切换：先以 appuser 身份安装Python包，然后切换回 root 安装Playwright的系统依赖，最后再切换到 appuser 来安装Chromium浏览器本身。这种设计确保了所有操作都在正确的权限下执行，避免了权限错误。
flowchart TD
Start([开始构建]) --> BaseImage["FROM python:3.13-slim"]
BaseImage --> SetEnv["设置环境变量"]
SetEnv --> InstallSystem["安装系统依赖 (apt-get)"]
InstallSystem --> InstallUV["安装 UV 包管理器"]
InstallUV --> CreateUser["创建非root用户 appuser"]
CreateUser --> SwitchUser["切换到 appuser 用户"]
SwitchUser --> CopyDeps["复制 pyproject.toml 和 uv.lock"]
CopyDeps --> InstallPython["使用 uv sync 安装 Python 依赖"]
InstallPython --> SwitchRoot["切换回 root 用户"]
SwitchRoot --> InstallPlaywrightDeps["安装 Playwright 系统依赖"]
InstallPlaywrightDeps --> SwitchAppUser["切换到 appuser 用户"]
SwitchAppUser --> InstallBrowser["安装 Chromium 浏览器"]
InstallBrowser --> Finalize["最终化镜像 (权限、清理)"]
Finalize --> End([镜像构建完成])
Diagram sources
Section sources
构建脚本分析
build-base-image.sh 是一个Bash脚本，它封装了复杂的Docker构建命令，为开发者提供了简单易用的接口。脚本通过读取环境变量（如 USE_PROXY, REGISTRY, VERSION）来动态调整构建行为。例如，当 USE_PROXY=1 时，它会将代理设置传递给Docker构建过程，这对于在受限网络环境中构建镜像至关重要。脚本还负责为生成的镜像打上多个标签（包括版本号和 latest），并可选择性地将其推送到指定的镜像仓库。
Section sources
依赖配置分析
pyproject.toml 文件是项目的依赖声明中心，它明确列出了所有必需的Python包，如 fastapi, sqlalchemy, playwright 等。uv.lock 文件则是由UV工具生成的锁定文件，它不仅记录了每个包的确切版本，还包含了其来源、哈希值和所有传递性依赖。这两个文件共同作用，确保了依赖管理的透明性和可重复性。
Section sources
依赖分析
该模块的依赖关系清晰且高效。build-base-image.sh 脚本直接依赖于 Dockerfile.base 来执行构建。Dockerfile.base 则依赖于 pyproject.toml 和 uv.lock 来获取依赖信息，并依赖于 uv 二进制文件来执行安装。uv.lock 文件本身是由 pyproject.toml 中的依赖声明通过 uv 工具生成的。这种依赖链确保了构建过程的每个环节都有明确的输入和输出。
graph LR
A[build-base-image.sh] --> B[Dockerfile.base]
B --> C[pyproject.toml]
B --> D[uv.lock]
B --> E[uv binary]
C --> D
D --> E
Diagram sources
Section sources
性能考虑
该模块在性能方面进行了多项优化。首先，使用 python:3.13-slim 作为基础镜像，从源头上减小了镜像体积。其次，在安装系统依赖时使用 --no-install-recommends 标志，并在安装后立即清理 apt 的缓存（rm -rf /var/lib/apt/lists/*），进一步减少了最终镜像的大小。使用UV包管理器而非pip，可以显著加快依赖安装速度。将浏览器安装在 /app/.browsers 目录下，便于在不同应用间共享，避免了重复下载。
故障排除指南
- 构建失败： 检查
pyproject.toml和uv.lock文件是否同步。如果依赖有更新，请在宿主机上运行uv lock命令重新生成uv.lock文件。 - 网络问题： 在无法访问PyPI的环境中，确保在执行
build-base-image.sh时设置了USE_PROXY=1环境变量。 - 权限错误： 确保
Dockerfile.base中的用户切换逻辑正确。Playwright的浏览器必须由运行应用的同一用户（appuser）来安装。 - 浏览器启动失败： 检查容器内是否缺少必要的系统库。可以参考
Dockerfile.base中的apt-get install命令，确认所有Playwright依赖都已安装。
Section sources
结论
kami-spider-monorepo 模块通过精心设计的Dockerfile和构建脚本，成功地为Python爬虫应用创建了一个强大、安全且高效的开发基础。它通过集成Python 3.13、UV包管理器、清华源代理支持、确定性依赖管理和开箱即用的Playwright浏览器，极大地简化了开发者的环境配置工作。该模块不仅提升了构建效率，还通过非root用户运行和标准化的依赖管理，为应用的稳定性和安全性提供了保障，是构建现代化爬虫应用的理想起点。