danial/docker-registry
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
Files
1ecefc80af4c491ffd6eb5dac4def291b0f97492
docker-registry/.qoder/repowiki/zh/content/kami-spider-monorepo 模块/配置选项.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

5.9 KiB
Raw Blame History

配置选项

**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)

目录

  1. 引言
  2. 核心环境变量
  3. Dockerfile静态配置
  4. 配置最佳实践

引言

本文档深入解析kami-spider-monorepo模块的构建配置体系，重点阐述环境变量与Dockerfile中的关键配置项。通过分析build-base-image.sh构建脚本和Dockerfile.base基础镜像文件，揭示系统如何通过环境变量控制代理、版本和镜像仓库等核心行为，以及Dockerfile中关于系统依赖和运行环境的静态配置。

核心环境变量

本节分析控制构建流程的核心环境变量，包括USE_PROXY、VERSION和DOCKER_REGISTRY。

USE_PROXY：代理加速控制

USE_PROXY环境变量用于控制在安装Python依赖时是否启用国内镜像加速。该变量在build-base-image.sh脚本中被读取，并作为构建参数传递给Docker。

当USE_PROXY设置为1时，构建过程将使用清华大学的PyPI镜像源（https://pypi.tuna.tsinghua.edu.cn/simple/）来安装依赖，显著提升在特定网络环境下的下载速度。若该变量未设置或为其他值，则使用默认的官方PyPI源。

此机制通过在Dockerfile.base中使用条件判断实现，直接影响uv sync命令的--index-url参数，从而改变uv包管理器的行为。pip等其他兼容工具在该镜像环境中也会继承相同的网络策略。

Section sources

VERSION：镜像版本管理

VERSION环境变量用于指定Docker镜像的标签（tag）。在build-base-image.sh脚本中，该变量具有默认值latest，允许用户在构建时灵活指定语义化版本号（如1.0.0、v2.1.3等）。

该变量的值被用于docker build命令的--tag参数，为生成的镜像打上版本标签。同时，脚本也会创建一个latest标签的镜像，便于在开发和测试环境中快速引用最新版本。

这种设计支持语义化版本管理，使得镜像的发布、回滚和依赖追踪成为可能。

Section sources

DOCKER_REGISTRY：镜像仓库配置

DOCKER_REGISTRY环境变量决定了Docker镜像的推送目标地址。该变量在build-base-image.sh中被读取，其默认值为localhost:5000，指向本地的Docker Registry。

当DOCKER_REGISTRY被设置为非默认值时（例如公司的私有Registry地址），构建脚本会执行以下操作：

  1. 标记镜像：使用docker tag命令为本地镜像添加包含Registry地址的完整标签。
  2. 推送镜像：使用docker push命令将标记好的镜像推送到指定的远程Registry。

此机制实现了镜像分发的灵活性，允许在不同环境（开发、测试、生产）中将镜像推送到不同的目标仓库。

Section sources

Dockerfile静态配置

本节分析Dockerfile.base文件中定义的静态配置项，这些配置在构建时即被固化到镜像中。

时区与语言环境

Dockerfile.base文件通过ENV指令设置了多个环境变量，但并未直接配置Asia/Shanghai时区或zh_CN.UTF-8语言环境。这表明时区和语言环境的配置可能由基础镜像python:3.13-slim继承，或在更高层的应用镜像中进行设置。

文件中定义的PYTHONUNBUFFERED和PYTHONDONTWRITEBYTECODE等环境变量，主要用于优化Python应用的运行时行为，确保日志实时输出和避免生成.pyc文件。

Section sources

系统依赖

Dockerfile.base通过apt-get命令安装了运行Playwright浏览器所必需的系统级依赖库。这些依赖包括：

  • 核心工具：ca-certificates, curl
  • 图形与多媒体：fonts-liberation, libnss3, libasound2, libcups2t64
  • 显示与输入：libatk-bridge2.0-0, libxkbcommon0, libxcomposite1, libxrandr2

此外，文件还通过playwright install-deps chromium命令安装了Chromium浏览器的特定系统依赖。这些静态配置确保了Playwright在无头模式下能够稳定运行。

Section sources

配置最佳实践

在CI/CD流水线中安全传递Registry地址

为了在CI/CD流水线中安全地传递DOCKER_REGISTRY地址，最佳实践是使用CI/CD平台的**秘密（Secrets）**功能。具体步骤如下：

  1. 在CI/CD平台（如GitHub Actions, GitLab CI）的项目设置中，将Registry地址和认证凭据（如用户名、密码或Token）配置为加密的秘密变量。
  2. 在流水线配置文件（如.github/workflows/build.yml）中，引用这些秘密变量作为环境变量。
  3. 在调用build-base-image.sh脚本时，将这些环境变量传递给脚本。

例如，在GitHub Actions中：

env:
  DOCKER_REGISTRY: ${{ secrets.DOCKER_REGISTRY }}
  DOCKER_USERNAME: ${{ secrets.DOCKER_USERNAME }}
  DOCKER_PASSWORD: ${{ secrets.DOCKER_PASSWORD }}

这种方式避免了将敏感信息硬编码在代码或配置文件中，保障了安全性。

Section sources