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 - 保持其他环境变量配置不变 - 解决国内代理访问速度或稳定性问题
4.4 KiB
依赖管理
**本文档引用的文件** - [pyproject.toml](file://kami-spider-monorepo/pyproject.toml) - [uv.lock](file://kami-spider-monorepo/uv.lock) - [Dockerfile.base](file://kami-spider-monorepo/Dockerfile.base) - [build-base-image.sh](file://kami-spider-monorepo/build-base-image.sh)目录
依赖管理机制
本项目采用 pyproject.toml 和 uv.lock 文件协同管理 Python 依赖，确保依赖安装的确定性和可重复性。pyproject.toml 定义了项目所需的直接依赖及其版本范围，而 uv.lock 文件则通过锁定所有依赖（包括传递依赖）的确切版本和哈希值，实现了跨环境的完全一致性。
项目选择 uv 作为包管理器替代传统的 pip，主要基于其卓越的性能优势。uv 采用 Rust 编写，通过并行下载和安装、预编译二进制文件（wheels）的优先使用以及高效的解析算法，显著提升了依赖安装速度。在安装如 FastAPI、SQLAlchemy 和 Playwright 等包含大量依赖或大型二进制文件的复杂库时，uv 的安装速度相比 pip 可提升数倍，极大地优化了开发和构建流程。
Section sources
依赖安装流程
在 Docker 构建过程中，uv.lock 文件是确保环境一致性的核心。Dockerfile.base 利用 uv sync 命令，严格依据 uv.lock 文件中锁定的版本进行依赖安装。此过程通过 --frozen 参数确保不会发生任何版本升级，从而保证了无论在何种构建环境中，最终安装的依赖包集合都是完全相同的。
flowchart TD
A[开始] --> B[复制 pyproject.toml 和 uv.lock]
B --> C{USE_PROXY 环境变量}
C --> |是| D[使用清华源镜像]
C --> |否| E[使用默认 PyPI 源]
D --> F[执行 uv sync --frozen]
E --> F
F --> G[安装 Playwright 浏览器]
G --> H[完成]
Diagram sources
Section sources
Docker 构建优化
Dockerfile.base 实现了多项优化策略以提升构建效率和镜像质量。首先，采用了分层缓存策略：将依赖文件的复制与安装作为一个独立的构建阶段，利用 Docker 的层缓存机制。当 pyproject.toml 或 uv.lock 未发生变化时，该阶段可直接使用缓存，避免了重复下载和安装依赖，大幅缩短了后续构建时间。
其次，通过合并安装命令优化了镜像层数。系统依赖（如 Playwright 运行时库）的安装被合并到一个 RUN 指令中，并在命令末尾执行 rm -rf /var/lib/apt/lists/* 清理临时文件，这不仅减少了镜像层数，也减小了最终镜像的体积。此外，构建过程遵循最小权限原则，创建了非 root 用户 appuser 来安装和运行应用，增强了容器的安全性。
Section sources
依赖更新流程
更新 Python 依赖的标准流程如下：首先，修改 pyproject.toml 文件中的依赖项或版本号。然后，在项目根目录下执行 uv update 或 uv sync 命令，该命令会根据新的 pyproject.toml 重新解析依赖关系，并生成更新后的 uv.lock 文件。最后，提交更新后的 pyproject.toml 和 uv.lock 文件。
为验证新镜像的功能完整性，应执行 build-base-image.sh 脚本重新构建基础镜像。构建成功后，可通过运行集成测试或启动应用进行手动验证，确保新版本的依赖未引入任何兼容性问题或功能缺陷。
Section sources