danial/docker-registry
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

chore(docker): 优化 Playwright 浏览器安装和配置

Browse Source 
- 设置 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
- 保持其他环境变量配置不变
- 解决国内代理访问速度或稳定性问题
This commit is contained in:
danial
2025-11-09 23:02:43 +08:00
parent f521333a4e
commit 1ecefc80af
25 changed files with 3824 additions and 5 deletions
Download Patch File Download Diff File Expand all files Collapse all files

186
.qoder/repowiki/zh/content/alpine-base 模块.md Normal file
View File

@@ -0,0 +1,186 @@
# alpine-base 模块
<cite>
**Referenced Files in This Document**
- [README.md](file://alpine-base/README.md)
- [build-base-image.sh](file://alpine-base/build-base-image.sh)
- [Dockerfile.base](file://alpine-base/Dockerfile.base)
</cite>
## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构概述](#架构概述)
5. [详细组件分析](#详细组件分析)
6. [依赖分析](#依赖分析)
7. [性能考虑](#性能考虑)
8. [故障排除指南](#故障排除指南)
9. [结论](#结论)
## 简介
`alpine-base` 模块是一个优化的 Alpine Linux 基础镜像，专为各种容器化应用设计。该镜像基于 `alpine:latest`，配置了中国镜像源以加速包下载，设置了 `Asia/Shanghai` 时区，并预装了常用的网络和系统工具。此外，镜像还包含了 CA 证书和自定义证书，确保了安全性和兼容性。通过创建非 root 用户 `appuser`（UID: 1001），提高了安全性。镜像大小约为 50MB，适合轻量级应用。
## 项目结构
`alpine-base` 模块包含以下文件：
- `README.md`：项目说明文档
- `build-base-image.sh`：基础镜像构建脚本
- `Dockerfile.base`：基础镜像定义文件
```mermaid
graph TD
A[alpine-base] --> B[README.md]
A --> C[build-base-image.sh]
A --> D[Dockerfile.base]
```
**Diagram sources**
- [README.md](file://alpine-base/README.md#L1-L70)
- [build-base-image.sh](file://alpine-base/build-base-image.sh#L1-L51)
- [Dockerfile.base](file://alpine-base/Dockerfile.base#L1-L58)
**Section sources**
- [README.md](file://alpine-base/README.md#L1-L70)
- [build-base-image.sh](file://alpine-base/build-base-image.sh#L1-L51)
- [Dockerfile.base](file://alpine-base/Dockerfile.base#L1-L58)
## 核心组件
`alpine-base` 模块的核心组件包括 `Dockerfile.base` 和 `build-base-image.sh`。`Dockerfile.base` 定义了基础镜像的构建过程，而 `build-base-image.sh` 脚本则负责执行构建、打标和推送操作。
**Section sources**
- [Dockerfile.base](file://alpine-base/Dockerfile.base#L1-L58)
- [build-base-image.sh](file://alpine-base/build-base-image.sh#L1-L51)
## 架构概述
`alpine-base` 模块的架构主要包括以下几个部分：
1. **基础镜像**：基于 `alpine:latest`。
2. **镜像源配置**：使用阿里云镜像源加速包下载。
3. **时区设置**：设置为 `Asia/Shanghai`。
4. **预装工具**：包括 `curl`、`wget`、`git`、`bash`、`tar`、`gzip` 等。
5. **证书管理**：包含 CA 证书和自定义证书。
6. **用户配置**：创建非 root 用户 `appuser`（UID: 1001）。
7. **应用目录**：创建 `/app` 目录并设置权限。
```mermaid
graph TD
A[alpine:latest] --> B[配置阿里云镜像源]
B --> C[设置时区为Asia/Shanghai]
C --> D[安装预装工具]
D --> E[下载并更新证书]
E --> F[创建非root用户appuser]
F --> G[创建应用目录/app]
G --> H[切换到appuser用户]
H --> I[设置工作目录为/app]
I --> J[标记镜像]
```
**Diagram sources**
- [Dockerfile.base](file://alpine-base/Dockerfile.base#L1-L58)
## 详细组件分析
### Dockerfile.base 分析
`Dockerfile.base` 文件定义了基础镜像的构建过程。以下是其主要步骤：
1. **基础镜像**：从 `alpine:latest` 开始。
2. **环境变量**：设置 `TZ` 为 `Asia/Shanghai`。
3. **镜像源配置**：将阿里云镜像源写入 `/etc/apk/repositories`。
4. **安装包**：更新包列表，升级现有包，并安装一系列常用工具和证书。
5. **时区设置**：复制 `Asia/Shanghai` 时区信息到 `/etc/localtime`，并写入 `/etc/timezone`。
6. **清理缓存**：删除 `/var/cache/apk/*` 以减少镜像大小。
7. **下载自定义证书**：从指定 URL 下载自定义证书并更新 CA 证书。
8. **创建非 root 用户**：创建 `appuser` 用户和组，UID 为 1001。
9. **创建应用目录**：创建 `/app` 目录并设置所有者为 `appuser`。
10. **切换用户**：切换到 `appuser` 用户。
11. **设置工作目录**：设置工作目录为 `/app`。
12. **标记镜像**：添加维护者、版本和描述标签。
```mermaid
flowchart TD
Start([开始]) --> BaseImage["FROM alpine:latest"]
BaseImage --> SetEnv["ENV TZ=Asia/Shanghai"]
SetEnv --> ConfigureRepo["配置阿里云镜像源"]
ConfigureRepo --> InstallPackages["安装包"]
InstallPackages --> SetupTimezone["设置时区"]
SetupTimezone --> Cleanup["清理缓存"]
Cleanup --> DownloadCerts["下载自定义证书"]
DownloadCerts --> CreateUser["创建非root用户appuser"]
CreateUser --> CreateAppDir["创建应用目录/app"]
CreateAppDir --> SwitchUser["切换到appuser用户"]
SwitchUser --> SetWorkDir["设置工作目录为/app"]
SetWorkDir --> LabelImage["标记镜像"]
LabelImage --> End([结束])
```
**Diagram sources**
- [Dockerfile.base](file://alpine-base/Dockerfile.base#L1-L58)
**Section sources**
- [Dockerfile.base](file://alpine-base/Dockerfile.base#L1-L58)
### build-base-image.sh 分析
`build-base-image.sh` 脚本负责构建、打标和推送基础镜像。以下是其主要步骤：
1. **配置**：设置基础镜像名称、注册表和版本。
2. **构建镜像**：使用 `docker build` 命令构建镜像，并打上版本和 latest 标签。
3. **标记注册表**：如果指定了注册表，则为镜像打上注册表标签。
4. **推送镜像**：如果指定了注册表，则将镜像推送到注册表。
5. **显示镜像大小**：显示构建完成后的镜像大小。
```mermaid
flowchart TD
Start([开始]) --> Config["配置变量"]
Config --> BuildImage["构建基础镜像"]
BuildImage --> TagRegistry["标记注册表"]
TagRegistry --> PushImage["推送镜像"]
PushImage --> ShowSize["显示镜像大小"]
ShowSize --> End([结束])
```
**Diagram sources**
- [build-base-image.sh](file://alpine-base/build-base-image.sh#L1-L51)
**Section sources**
- [build-base-image.sh](file://alpine-base/build-base-image.sh#L1-L51)
## 依赖分析
`alpine-base` 模块依赖于 `alpine:latest` 镜像，并通过 `apk` 包管理器安装了一系列工具和证书。这些依赖项确保了镜像的功能性和安全性。
```mermaid
graph TD
A[alpine:latest] --> B[apk-tools]
B --> C[curl]
B --> D[wget]
B --> E[git]
B --> F[bash]
B --> G[tar]
B --> H[gzip]
B --> I[ca-certificates]
I --> J[自定义证书]
```
**Diagram sources**
- [Dockerfile.base](file://alpine-base/Dockerfile.base#L1-L58)
**Section sources**
- [Dockerfile.base](file://alpine-base/Dockerfile.base#L1-L58)
## 性能考虑
`alpine-base` 模块通过以下方式优化性能：
- **轻量化**：基于 Alpine Linux，镜像大小约为 50MB。
- **快速构建**：预装常用工具和配置，减少构建时间。
- **网络优化**：使用阿里云镜像源加速包下载。
- **安全**：创建非 root 用户 `appuser`，提高安全性。
## 故障排除指南
如果在构建或使用 `alpine-base` 镜像时遇到问题，可以参考以下建议：
- **构建失败**：检查 `Dockerfile.base` 中的命令是否正确，确保网络连接正常。
- **推送失败**：确认 `DOCKER_REGISTRY` 环境变量是否正确设置，检查 Docker 登录状态。
- **权限问题**：确保 `appuser` 用户和 `/app` 目录的权限设置正确。
**Section sources**
- [Dockerfile.base](file://alpine-base/Dockerfile.base#L1-L58)
- [build-base-image.sh](file://alpine-base/build-base-image.sh#L1-L51)
## 结论
`alpine-base` 模块提供了一个优化的 Alpine Linux 基础镜像，适用于各种容器化应用。通过预装常用工具、配置中国镜像源、设置时区和创建非 root 用户，该镜像在功能性和安全性方面表现出色。镜像大小约为 50MB，适合轻量级应用。通过 `build-base-image.sh` 脚本，可以轻松构建、打标和推送镜像，确保了开发和部署的高效性。

164
.qoder/repowiki/zh/content/kami-gateway 模块/CI_CD集成.md Normal file
View File

@@ -0,0 +1,164 @@
# CI/CD集成
<cite>
**Referenced Files in This Document**
- [README.md](file://kami-gateway/README.md)
- [build-base-image.sh](file://kami-gateway/build-base-image.sh)
</cite>
## 目录
1. [引言](#引言)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构概述](#架构概述)
5. [详细组件分析](#详细组件分析)
6. [依赖分析](#依赖分析)
7. [性能考量](#性能考量)
8. [故障排除指南](#故障排除指南)
9. [结论](#结论)
## 引言
本文档系统性地描述了kami-gateway模块在Drone CI环境下的自动化构建与发布流程。重点说明CI配置如何监听kami-gateway目录变更，触发build-base-image.sh脚本执行，以及环境变量在CI流水线中的作用机制。通过分析自动化流程，展示其在提升构建效率和保障环境一致性方面的优势。
## 项目结构
kami-gateway模块包含构建基础Docker镜像所需的核心文件。项目结构设计清晰，将构建脚本、配置文件和源代码组织在独立目录中，便于CI/CD系统识别和处理变更。
```mermaid
graph TD
A[kami-gateway/] --> B[README.md]
A --> C[build-base-image.sh]
A --> D[go.mod]
A --> E[go.sum]
```
**Diagram sources**
- [README.md](file://kami-gateway/README.md)
- [build-base-image.sh](file://kami-gateway/build-base-image.sh)
**Section sources**
- [README.md](file://kami-gateway/README.md)
- [build-base-image.sh](file://kami-gateway/build-base-image.sh)
## 核心组件
kami-gateway的CI/CD流程围绕两个核心组件构建：`build-base-image.sh`构建脚本和`README.md`中的CI/CD说明文档。构建脚本负责执行具体的镜像构建、标记和推送操作，而文档则定义了CI系统的触发条件和工作流程。
**Section sources**
- [README.md](file://kami-gateway/README.md#L53-L60)
- [build-base-image.sh](file://kami-gateway/build-base-image.sh#L1-L51)
## 架构概述
kami-gateway的CI/CD架构采用事件驱动模式，当kami-gateway目录发生变更时，Drone CI系统被触发，执行预定义的构建流水线。该流水线调用构建脚本，完成从代码到容器镜像的转换，并根据配置决定是否将镜像推送到远程仓库。
```mermaid
graph LR
A[代码仓库变更] --> B{Drone CI触发}
B --> C[执行build-base-image.sh]
C --> D[构建本地镜像]
D --> E{REGISTRY != localhost:5000?}
E --> |是| F[标记并推送镜像]
E --> |否| G[仅本地构建]
F --> H[通知完成]
G --> H
```
**Diagram sources**
- [README.md](file://kami-gateway/README.md#L53-L58)
- [build-base-image.sh](file://kami-gateway/build-base-image.sh#L26-L40)
## 详细组件分析
### 构建脚本分析
`build-base-image.sh`脚本是自动化流程的核心执行单元，负责处理镜像的构建、标记和推送逻辑。
#### 环境变量注入与处理
```mermaid
flowchart TD
Start([开始]) --> Config["配置环境变量"]
Config --> REGISTRY["REGISTRY = ${DOCKER_REGISTRY:-git.oceanpay.cc/danial}"]
Config --> VERSION["VERSION = ${VERSION:-latest}"]
REGISTRY --> Display["显示Registry: $REGISTRY"]
VERSION --> Display
Display --> Build["构建本地镜像"]
```
**Diagram sources**
- [build-base-image.sh](file://kami-gateway/build-base-image.sh#L9-L15)
#### 条件推送逻辑
```mermaid
flowchart TD
Check["检查REGISTRY值"]
Check --> Condition{"REGISTRY != localhost:5000?"}
Condition --> |真| Tag["标记远程镜像"]
Condition --> |假| SkipTag["跳过标记"]
Tag --> Push["推送镜像到仓库"]
SkipTag --> Complete["构建完成"]
Push --> Complete
```
**Diagram sources**
- [build-base-image.sh](file://kami-gateway/build-base-image.sh#L27-L30)
- [build-base-image.sh](file://kami-gateway/build-base-image.sh#L35-L39)
**Section sources**
- [build-base-image.sh](file://kami-gateway/build-base-image.sh#L1-L51)
### CI/CD流程说明
#### 流水线触发机制
```mermaid
sequenceDiagram
participant Repo as 代码仓库
participant Drone as Drone CI
participant Script as build-base-image.sh
Repo->>Drone : kami-gateway/目录变更
Drone->>Drone : 检测到变更
Drone->>Script : 执行构建脚本
Script->>Script : 设置环境变量
Script->>Script : 构建本地镜像
Script->>Script : 条件性推送
Script-->>Drone : 返回状态
Drone-->>Repo : 更新构建状态
```
**Diagram sources**
- [README.md](file://kami-gateway/README.md#L56)
## 依赖分析
kami-gateway的CI/CD流程依赖于外部系统和环境配置，包括Drone CI平台、Docker运行时环境和镜像仓库服务。这些依赖关系确保了构建流程的完整性和可靠性。
```mermaid
graph TD
A[Drone CI] --> B[kami-gateway模块]
C[Docker Engine] --> B
D[镜像仓库] --> B
B --> E[应用部署]
```
**Diagram sources**
- [README.md](file://kami-gateway/README.md#L53)
- [build-base-image.sh](file://kami-gateway/build-base-image.sh#L35-L39)
**Section sources**
- [README.md](file://kami-gateway/README.md#L53-L60)
## 性能考量
kami-gateway的CI/CD流程设计注重效率和资源优化。通过条件构建机制，避免了不必要的镜像推送操作，特别是在本地测试环境中。基础镜像缓存和预下载依赖包的设计，显著缩短了构建时间，实现了10-30秒内的快速构建。
## 故障排除指南
当CI/CD流程出现问题时，应首先检查环境变量是否正确注入，特别是`DOCKER_REGISTRY`和`VERSION`。确认Drone CI是否正确检测到kami-gateway目录的变更，并验证构建脚本的执行权限。对于推送失败的情况，需检查网络连接和镜像仓库的访问凭证。
**Section sources**
- [build-base-image.sh](file://kami-gateway/build-base-image.sh#L26-L40)
## 结论
kami-gateway模块的CI/CD集成通过自动化构建与发布流程，实现了高效的开发运维实践。Drone CI系统能够准确监听目录变更并触发构建，环境变量的灵活注入机制支持多环境部署，而条件推送逻辑则有效避免了本地测试时的无效操作。这一自动化流程不仅提升了构建效率，还保障了不同环境间的一致性，为持续交付提供了可靠的基础。

85
.qoder/repowiki/zh/content/kami-gateway 模块/Go依赖管理.md Normal file
View File

@@ -0,0 +1,85 @@
# Go依赖管理
<cite>
**本文档引用文件**
- [go.mod](file://kami-gateway/go.mod)
- [go.sum](file://kami-gateway/go.sum)
- [Dockerfile.base](file://kami-gateway/Dockerfile.base)
</cite>
## 目录
1. [项目依赖声明](#项目依赖声明)
2. [间接依赖管理](#间接依赖管理)
3. [Docker构建优化机制](#docker构建优化机制)
4. [Go工具链版本一致性](#go工具链版本一致性)
5. [依赖更新与安全审计建议](#依赖更新与安全审计建议)
## 项目依赖声明
kami-gateway模块通过`go.mod`文件明确声明了核心依赖，确保项目构建的可重复性和稳定性。主要依赖包括：
- **Web框架**: `github.com/beego/beego/v2 v2.3.8`，提供MVC架构支持
- **高性能JSON解析**: `github.com/bytedance/sonic v1.14.2`，显著提升序列化性能
- **OpenTelemetry监控**: 包含`go.opentelemetry.io/otel`系列包，实现分布式追踪、指标和日志采集
- **数据库驱动**: `github.com/go-sql-driver/mysql` 和 `github.com/redis/go-redis/v9`
- **HTTP客户端**: `github.com/go-resty/resty/v2`，简化外部服务调用
这些依赖通过`require`指令直接声明，版本号精确到补丁级别，确保开发、测试和生产环境的一致性。
**Section sources**
- [go.mod](file://kami-gateway/go.mod#L7-L39)
## 间接依赖管理
`go.mod`文件中通过`require`块标记为`// indirect`的依赖项是间接依赖。这些依赖并非由项目直接导入，而是作为直接依赖的依赖被引入。例如：
- `golang.org/x/crypto` 和 `golang.org/x/net`：被OpenTelemetry等库依赖
- `github.com/cespare/xxhash/v2`：被`sonic`等高性能库使用
- `google.golang.org/grpc`：被OTLP（OpenTelemetry Protocol）导出器依赖
Go模块系统自动解析并锁定这些间接依赖的版本，记录在`go.sum`文件中。`go.sum`不仅包含依赖模块的版本哈希，还包含其所有依赖的哈希，形成一个完整的依赖图校验链，有效防止依赖被篡改。
**Section sources**
- [go.mod](file://kami-gateway/go.mod#L41-L81)
- [go.sum](file://kami-gateway/go.sum#L1-L165)
## Docker构建优化机制
`Dockerfile.base`中的指令是提升CI/CD效率的关键：
```dockerfile
COPY --chown=appuser:appuser go.mod go.sum ./
RUN go mod download && go mod verify
```
这两条指令的作用如下：
1. **提前复制模块文件**: 在构建早期阶段就将`go.mod`和`go.sum`复制到镜像中。这利用了Docker的层缓存机制。
2. **预下载并验证依赖**: `go mod download`会根据`go.mod`和`go.sum`下载所有声明的模块到`$GOPATH/pkg/mod`。`go mod verify`会校验下载的模块是否与`go.sum`中的哈希匹配，确保完整性。
3. **缓存优势**: 只要`go.mod`或`go.sum`文件内容不变，Docker就会复用`go mod download`这一层的缓存。后续构建时，无需重新下载可能多达数百个的Go模块，从而将应用构建时间从几分钟缩短到十几秒。
4. **CI/CD价值**: 在持续集成环境中，代码变更远比依赖变更频繁。此策略避免了每次构建都重复拉取网络依赖，极大地提升了构建速度，降低了对网络的依赖和失败风险。
**Section sources**
- [Dockerfile.base](file://kami-gateway/Dockerfile.base#L50-L54)
## Go工具链版本一致性
`go.mod`文件中的`toolchain go1.24.6`指令是Go 1.24引入的重要特性，用于保障构建环境的一致性。
- **作用**: 该指令明确指定项目应使用Go 1.24.6版本的工具链进行构建。当开发者或CI系统使用`go build`命令时，如果本地Go版本不是1.24.6，Go命令行工具会自动下载并使用指定版本的工具链，而不是使用本地安装的版本。
- **优势**: 彻底解决了“在我机器上能运行”的问题。无论开发者的本地环境如何，都能确保使用完全相同的编译器、链接器等工具进行构建，保证了二进制输出的可重现性，对于生产环境的稳定性至关重要。
**Section sources**
- [go.mod](file://kami-gateway/go.mod#L5)
## 依赖更新与安全审计建议
为维护项目健康，建议遵循以下实践：
1. **定期更新**: 使用`go get -u ./...`或`go get -u=patch ./...`定期更新依赖。更新后，`go.mod`和`go.sum`会自动更新。
2. **安全审计**: 使用`govulncheck`工具（Go安全扫描工具）扫描项目，识别已知的漏洞。例如：`govulncheck ./...`。
3. **审查变更**: 在更新依赖（尤其是主版本号变更）后，务必进行充分的测试，因为新版本可能包含破坏性变更。
4. **最小化依赖**: 定期审查`go.mod`，移除不再使用的依赖，以减小攻击面和构建复杂性。
5. **锁定版本**: 在生产项目中，始终使用精确的版本号，避免使用`latest`等不稳定的版本标识。
通过结合`go.mod`的精确版本控制、`toolchain`指令的构建一致性保障以及Docker的缓存优化，kami-gateway项目建立了一个高效、可靠且安全的依赖管理体系。

215
.qoder/repowiki/zh/content/kami-gateway 模块/kami-gateway 模块.md Normal file
View File

@@ -0,0 +1,215 @@
# kami-gateway 模块
<cite>
**本文档引用文件**
- [Dockerfile.base](file://kami-gateway/Dockerfile.base)
- [build-base-image.sh](file://kami-gateway/build-base-image.sh)
- [go.mod](file://kami-gateway/go.mod)
- [README.md](file://kami-gateway/README.md)
</cite>
## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构概述](#架构概述)
5. [详细组件分析](#详细组件分析)
6. [依赖分析](#依赖分析)
7. [性能考量](#性能考量)
8. [故障排除指南](#故障排除指南)
9. [结论](#结论)
## 简介
kami-gateway 模块是一个为 Go 语言网关服务设计的基础镜像构建系统，旨在通过优化的 Docker 构建流程提升微服务架构下的开发与部署效率。该模块通过 `Dockerfile.base` 和 `build-base-image.sh` 脚本实现了一个高度可复用、安全且高效的构建环境。其核心设计理念是将 Go 编译环境、依赖预下载、中国镜像加速、非 root 用户安全运行等关键要素集成到一个基础镜像中，从而为上层应用提供极速构建能力。通过多阶段构建和 CI/CD 集成，该模块显著缩短了应用镜像的构建时间至 10-30 秒，是现代云原生微服务架构中的关键基础设施。
## 项目结构
kami-gateway 模块的项目结构简洁明了，专注于基础镜像的构建与管理。其核心文件包括定义构建环境的 Dockerfile、自动化构建脚本、Go 依赖配置文件和说明文档。
```mermaid
graph TB
subgraph "kami-gateway/"
DockerfileBase[Dockerfile.base<br>基础镜像定义]
BuildScript[build-base-image.sh<br>构建脚本]
GoMod[go.mod<br>依赖管理]
Readme[README.md<br>使用说明]
end
DockerfileBase --> BuildScript : "被调用"
BuildScript --> GoMod : "读取依赖"
Readme --> DockerfileBase : "文档说明"
Readme --> BuildScript : "文档说明"
```
**Diagram sources**
- [Dockerfile.base](file://kami-gateway/Dockerfile.base#L1-L59)
- [build-base-image.sh](file://kami-gateway/build-base-image.sh#L1-L51)
- [go.mod](file://kami-gateway/go.mod#L1-L82)
- [README.md](file://kami-gateway/README.md#L1-L60)
**Section sources**
- [Dockerfile.base](file://kami-gateway/Dockerfile.base#L1-L59)
- [build-base-image.sh](file://kami-gateway/build-base-image.sh#L1-L51)
- [go.mod](file://kami-gateway/go.mod#L1-L82)
- [README.md](file://kami-gateway/README.md#L1-L60)
## 核心组件
kami-gateway 模块的核心组件由三个关键文件构成：`Dockerfile.base` 定义了基础镜像的完整构建过程，`build-base-image.sh` 提供了自动化构建与推送的脚本逻辑，`go.mod` 则精确管理了所有 Go 语言依赖。这些组件协同工作，实现了从环境配置到镜像发布的完整流水线。`Dockerfile.base` 通过多阶段配置，确保了构建环境的纯净与最终镜像的轻量化；`build-base-image.sh` 利用环境变量实现了灵活的构建参数控制，支持自定义镜像仓库和版本；`go.mod` 文件中声明的依赖，如 beego、sonic 和 opentelemetry，为网关服务提供了高性能的 Web 框架、JSON 处理和可观测性支持。
**Section sources**
- [Dockerfile.base](file://kami-gateway/Dockerfile.base#L1-L59)
- [build-base-image.sh](file://kami-gateway/build-base-image.sh#L1-L51)
- [go.mod](file://kami-gateway/go.mod#L1-L82)
## 架构概述
kami-gateway 模块采用分层架构设计，将构建过程解耦为基础镜像构建和应用镜像构建两个独立阶段。基础镜像构建阶段是整个系统的核心，它一次性完成所有耗时操作，包括 Go 环境配置、系统依赖安装、时区与证书设置以及最关键的 Go 模块预下载。应用镜像构建阶段则基于此预构建的基础镜像，直接进行应用代码的编译和打包，从而实现了极速构建。
```mermaid
graph TD
subgraph "基础镜像构建阶段"
A[Dockerfile.base] --> B[使用 golang:1.25-alpine]
B --> C[配置环境变量<br>GO111MODULE=on<br>GOPROXY=https://goproxy.cn,direct]
C --> D[设置中国镜像源<br>Alpine & CA证书]
D --> E[创建非root用户 appuser]
E --> F[复制 go.mod/go.sum]
F --> G[执行 go mod download]
G --> H[生成 kami-gateway-base:latest]
end
subgraph "应用镜像构建阶段"
I[Dockerfile.improved] --> J[FROM kami-gateway-base:latest]
J --> K[复制源代码]
K --> L[执行 go build]
L --> M[生成最终应用镜像]
end
H --> J : "作为基础"
```
**Diagram sources**
- [Dockerfile.base](file://kami-gateway/Dockerfile.base#L4-L59)
- [README.md](file://kami-gateway/README.md#L8-L9)
## 详细组件分析
### Dockerfile.base 分析
`Dockerfile.base` 是 kami-gateway 基础镜像的蓝图，其设计体现了高度的优化和安全性。
#### 构建流程与安全配置
```mermaid
flowchart TD
Start([开始]) --> BaseImage["FROM golang:1.25-alpine"]
BaseImage --> EnvConfig["配置环境变量<br>TZ, GO111MODULE, GOPROXY"]
EnvConfig --> MirrorConfig["配置中国镜像源<br>Alpine repositories"]
MirrorConfig --> InstallDeps["安装系统依赖<br>tzdata, curl, ca-certificates"]
InstallDeps --> Timezone["设置时区为 Asia/Shanghai"]
Timezone --> Certs["下载并安装自定义CA证书"]
Certs --> CreateUser["创建非root用户 appuser"]
CreateUser --> CreateAppDir["创建 /app 目录并授权"]
CreateUser --> SwitchUser["切换到 USER appuser"]
SwitchUser --> SetWorkdir["设置 WORKDIR /app"]
SetWorkdir --> CopyGoMod["复制 go.mod 和 go.sum"]
CopyGoMod --> PreDownload["RUN go mod download && go mod verify"]
PreDownload --> LabelImage["为镜像添加 LABEL 信息"]
LabelImage --> End([基础镜像构建完成])
```
**Diagram sources**
- [Dockerfile.base](file://kami-gateway/Dockerfile.base#L4-L59)
**Section sources**
- [Dockerfile.base](file://kami-gateway/Dockerfile.base#L1-L59)
### build-base-image.sh 脚本分析
`build-base-image.sh` 是一个 Bash 脚本，用于自动化执行基础镜像的构建、标记和推送流程。
#### 脚本执行流程
```mermaid
sequenceDiagram
participant Terminal as "终端"
participant Script as "build-base-image.sh"
participant Docker as "Docker Engine"
Terminal->>Script : 执行 ./build-base-image.sh
Script->>Script : 设置环境变量<br>BASE_IMAGE_NAME, REGISTRY, VERSION
Script->>Script : 打印构建信息
Script->>Docker : docker build --file Dockerfile.base<br>--tag kami-gateway-base : $VERSION<br>--tag kami-gateway-base : latest .
Docker-->>Script : 返回构建成功
Script->>Script : 检查 REGISTRY 是否为 localhost
alt REGISTRY 不是 localhost
Script->>Docker : docker tag 本地镜像为远程仓库镜像
Script->>Docker : docker push 推送镜像到远程仓库
Docker-->>Script : 返回推送成功
end
Script->>Script : 打印构建完成信息和镜像大小
Script-->>Terminal : 脚本执行结束
```
**Diagram sources**
- [build-base-image.sh](file://kami-gateway/build-base-image.sh#L1-L51)
**Section sources**
- [build-base-image.sh](file://kami-gateway/build-base-image.sh#L1-L51)
### go.mod 依赖管理分析
`go.mod` 文件是 Go 项目依赖管理的核心，kami-gateway 模块在此文件中声明了构建网关服务所需的所有依赖。
#### 关键依赖及其作用
| 依赖模块 | 版本 | 主要用途 |
| :--- | :--- | :--- |
| github.com/beego/beego/v2 | v2.3.8 | 高性能 Web 框架，用于构建 RESTful API |
| github.com/bytedance/sonic | v1.14.2 | 字节跳动开源的超快 JSON 序列化库 |
| go.opentelemetry.io/otel | v1.38.0 | OpenTelemetry SDK，提供分布式追踪和指标 |
| github.com/go-resty/resty/v2 | v2.16.5 | 简单易用的 HTTP 客户端 |
| github.com/redis/go-redis/v9 | v9.14.0 | Redis 客户端，用于缓存和会话管理 |
| go.uber.org/zap | v1.27.0 | 高性能日志库 |
**Section sources**
- [go.mod](file://kami-gateway/go.mod#L1-L82)
## 依赖分析
kami-gateway 模块的依赖关系清晰，主要分为直接依赖和间接依赖。直接依赖在 `go.mod` 文件的 `require` 块中明确列出，是网关服务功能实现的基石。间接依赖（indirect）是这些直接依赖所依赖的库，由 Go 模块系统自动解析和管理。通过在 `Dockerfile.base` 中执行 `go mod download`，所有这些依赖（包括间接依赖）都会被预先下载到镜像的模块缓存中。这种预下载机制是实现极速构建的关键，它消除了每次构建应用时重复下载网络依赖的耗时过程。基础镜像与 `go.mod` 文件的版本绑定，确保了构建环境的一致性和可重现性。
```mermaid
erDiagram
DIRECT_DEPENDENCY ||--o{ INDIRECT_DEPENDENCY : "requires"
DIRECT_DEPENDENCY {
string module_name PK
string version
string purpose
}
INDIRECT_DEPENDENCY {
string module_name PK
string version
}
DIRECT_DEPENDENCY }|--|| BASE_IMAGE : "pre-downloaded in"
BASE_IMAGE {
string image_name PK
string tag
datetime build_time
}
```
**Diagram sources**
- [go.mod](file://kami-gateway/go.mod#L7-L82)
- [Dockerfile.base](file://kami-gateway/Dockerfile.base#L54)
**Section sources**
- [go.mod](file://kami-gateway/go.mod#L1-L82)
- [Dockerfile.base](file://kami-gateway/Dockerfile.base#L54)
## 性能考量
kami-gateway 模块的设计在性能方面表现出色，主要体现在以下几个方面：
- **极速构建**：通过将耗时的依赖下载过程前置到基础镜像中，应用镜像的构建时间被压缩到 10-30 秒，极大地提升了开发迭代和 CI/CD 流水线的效率。
- **镜像体积优化**：采用 Alpine Linux 作为基础操作系统，并结合多阶段构建（虽然在 `Dockerfile.base` 中未直接体现，但其为应用的多阶段构建提供了基础），最终生成的运行时镜像非常轻量，减少了存储和网络传输开销。
- **网络效率**：通过配置 `GOPROXY=https://goproxy.cn,direct` 和使用阿里云的 Alpine 镜像源，显著加速了在中国大陆地区的依赖下载速度，避免了因网络问题导致的构建失败或延迟。
- **资源复用**：基础镜像可以被多个基于 Go 的微服务共享，避免了为每个服务重复构建相同的环境，节省了计算资源和时间。
## 故障排除指南
当使用 kami-gateway 模块时，可能会遇到以下常见问题及解决方案：
- **构建失败，提示无法访问 goproxy.cn**：检查构建环境的网络连接，确保可以访问 `https://goproxy.cn`。如果处于严格的企业防火墙后，可能需要联系网络管理员或临时调整 `GOPROXY` 环境变量。
- **推送镜像到私有仓库失败**：确保已通过 `docker login` 命令登录到目标镜像仓库（由 `DOCKER_REGISTRY` 环境变量指定）。检查仓库地址和凭据是否正确。
- **应用构建时出现依赖版本冲突**：确保应用的 `go.mod` 文件与基础镜像构建时使用的 `go.mod` 文件兼容。如果应用引入了新版本的依赖，可能需要重新构建基础镜像。
- **容器运行时权限错误**：由于镜像以非 root 用户 `appuser` 运行，确保应用代码和数据目录的权限设置正确，避免尝试写入 `/` 等受保护的目录。
**Section sources**
- [Dockerfile.base](file://kami-gateway/Dockerfile.base#L37-L38)
- [build-base-image.sh](file://kami-gateway/build-base-image.sh#L10-L11)
## 结论
kami-gateway 模块通过精心设计的 `Dockerfile.base` 和 `build-base-image.sh` 脚本，成功构建了一个高效、安全、可复用的 Go 语言网关服务基础镜像。该模块通过预下载依赖、配置中国镜像源、创建非 root 用户等最佳实践，解决了传统 Go 应用 Docker 构建中的痛点，实现了 10-30 秒的极速构建。结合 `go.mod` 的精确依赖管理和 Drone CI 的自动化流程，kami-gateway 为微服务架构提供了一个稳定可靠的基础设施。开发者可以基于此基础镜像快速构建和部署应用，将精力集中在业务逻辑开发上，而非繁琐的环境配置，从而显著提升了开发效率和系统稳定性。

177
.qoder/repowiki/zh/content/kami-gateway 模块/基础镜像构建.md Normal file
View File

@@ -0,0 +1,177 @@
# 基础镜像构建
<cite>
**Referenced Files in This Document**
- [Dockerfile.base](file://kami-gateway/Dockerfile.base)
- [build-base-image.sh](file://kami-gateway/build-base-image.sh)
- [README.md](file://kami-gateway/README.md)
</cite>
## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构概述](#架构概述)
5. [详细组件分析](#详细组件分析)
6. [依赖分析](#依赖分析)
7. [性能考虑](#性能考虑)
8. [故障排除指南](#故障排除指南)
9. [结论](#结论)
## 简介
本文档详细阐述了 `kami-gateway` 项目中基础 Docker 镜像的构建机制。该机制通过 `Dockerfile.base` 和 `build-base-image.sh` 脚本实现，旨在创建一个安全、高效且适用于中国网络环境的 Go 应用基础镜像。文档将深入解析镜像构建过程中的关键配置，包括中国镜像源设置、时区配置、非 root 用户创建以及 Go 模块代理加速等最佳实践。
## 项目结构
`kami-gateway` 目录下的文件组织清晰，专注于基础镜像的构建与管理。主要包含 Docker 配置文件、构建脚本和 Go 模块定义文件。
```mermaid
graph TB
kami-gateway[kami-gateway/]
--> Dockerfile_base[Dockerfile.base]
kami-gateway --> Dockerfile_improved[Dockerfile.improved]
kami-gateway --> build_script[build-base-image.sh]
kami-gateway --> go_mod[go.mod]
kami-gateway --> go_sum[go.sum]
kami-gateway --> README[README.md]
```
**Diagram sources**
- [Dockerfile.base](file://kami-gateway/Dockerfile.base)
- [build-base-image.sh](file://kami-gateway/build-base-image.sh)
- [README.md](file://kami-gateway/README.md)
**Section sources**
- [Dockerfile.base](file://kami-gateway/Dockerfile.base)
- [build-base-image.sh](file://kami-gateway/build-base-image.sh)
## 核心组件
`kami-gateway` 基础镜像构建的核心组件是 `Dockerfile.base` 和 `build-base-image.sh`。前者定义了镜像的静态配置和构建步骤，后者则是一个可执行的脚本，用于自动化地调用 Docker 命令来构建、标记和推送镜像。这两个文件共同构成了一个可重复、可靠的镜像构建流程。
**Section sources**
- [Dockerfile.base](file://kami-gateway/Dockerfile.base#L1-L59)
- [build-base-image.sh](file://kami-gateway/build-base-image.sh#L1-L51)
## 架构概述
整个基础镜像构建流程遵循了多阶段配置和安全加固的最佳实践。首先，`Dockerfile.base` 从官方 `golang:1.25-alpine` 镜像出发，通过一系列 `RUN` 指令进行环境配置。随后，`build-base-image.sh` 脚本作为构建的入口，负责执行 `docker build` 命令，并根据环境变量决定是否将构建好的镜像推送到私有仓库。
```mermaid
graph LR
A[golang:1.25-alpine] --> B[Dockerfile.base]
B --> C[配置环境变量]
C --> D[设置中国镜像源]
D --> E[安装系统工具]
E --> F[创建非root用户]
F --> G[预下载Go依赖]
G --> H[生成基础镜像]
H --> I[build-base-image.sh]
I --> J[执行docker build]
J --> K[生成本地标签]
K --> L{是否推送?}
L --> |是| M[推送至私有仓库]
L --> |否| N[完成]
```
**Diagram sources**
- [Dockerfile.base](file://kami-gateway/Dockerfile.base#L4-L59)
- [build-base-image.sh](file://kami-gateway/build-base-image.sh#L20-L40)
## 详细组件分析
### Dockerfile.base 分析
`Dockerfile.base` 是构建基础镜像的蓝图，其设计体现了安全性和效率的平衡。
#### 环境变量与镜像源配置
该文件通过 `ENV` 指令设置了关键的环境变量。`TZ=Asia/Shanghai` 确保了容器内的时间与北京时间一致。`GO111MODULE=on` 强制启用 Go Modules，保证依赖管理的现代性和一致性。`GOPROXY=https://goproxy.cn,direct` 将 Go 模块代理设置为中国的镜像服务，极大地加速了 `go mod download` 命令的执行速度，解决了从国外服务器下载依赖慢的问题。此外，`RUN` 指令将 Alpine Linux 的软件源替换为阿里云镜像，同样是为了提升 `apk` 包管理器的下载速度。
#### 安全加固与系统配置
安全是此镜像的核心考量。`Dockerfile.base` 通过 `RUN` 指令安装了 `tzdata` 来支持时区设置，并安装了 `ca-certificates` 和自定义证书以确保 HTTPS 连接的安全性。最关键的一步是创建了一个非 root 用户 `appuser`（UID 1001）。通过 `addgroup` 和 `adduser` 命令创建用户后，使用 `USER appuser` 指令将后续所有操作的执行者切换为该普通用户。这遵循了最小权限原则，即使容器被攻破，攻击者也只能获得有限的权限，从而提升了整体安全性。
```mermaid
flowchart TD
Start([开始]) --> SetEnv["设置环境变量\nTZ, GO111MODULE, GOPROXY"]
SetEnv --> ConfigureMirror["配置中国镜像源\n阿里云 Alpine 镜像"]
ConfigureMirror --> InstallTools["安装系统工具\ntzdata, ca-certificates"]
InstallTools --> SetupTimezone["设置时区\nAsia/Shanghai"]
SetupTimezone --> CreateUser["创建非root用户\nappuser (UID 1001)"]
CreateUser --> SwitchUser["切换执行用户\nUSER appuser"]
SwitchUser --> DownloadDeps["预下载Go依赖\ngo mod download"]
DownloadDeps --> Finish([完成])
```
**Diagram sources**
- [Dockerfile.base](file://kami-gateway/Dockerfile.base#L7-L54)
**Section sources**
- [Dockerfile.base](file://kami-gateway/Dockerfile.base#L1-L59)
### build-base-image.sh 脚本分析
`build-base-image.sh` 脚本是构建流程的自动化驱动器，它封装了复杂的 Docker 命令，简化了构建操作。
#### 构建与标记逻辑
脚本首先定义了基础镜像名称、版本号和镜像仓库地址（通过 `DOCKER_REGISTRY` 环境变量或默认值）。它使用 `docker build` 命令，通过 `--file` 参数指定 `Dockerfile.base`，并使用 `--tag` 参数同时为镜像打上版本化标签（如 `latest` 或指定版本）和 `latest` 标签。这种双标签策略既保证了可追溯性，又提供了最新的稳定版本。
#### 推送与输出逻辑
脚本的核心智能在于条件推送。它通过判断 `REGISTRY` 变量是否为 `localhost:5000` 来决定是否执行推送操作。如果指定了私有仓库（如 `git.oceanpay.cc/danial`），脚本会先使用 `docker tag` 为本地镜像创建一个包含仓库地址的完整标签，然后调用 `docker push` 将其推送到远程仓库。构建完成后，脚本会输出成功信息，并使用 `docker images` 命令结合 `grep` 过滤，清晰地展示新构建的 `kami-gateway-base` 镜像的大小，便于开发者评估镜像优化效果。
```mermaid
sequenceDiagram
participant Terminal as "终端"
participant Script as "build-base-image.sh"
participant Docker as "Docker Engine"
Terminal->>Script : 执行 ./build-base-image.sh
Script->>Script : 设置环境变量
Script->>Script : 输出构建信息
Script->>Docker : docker build --file Dockerfile.base ...
Docker-->>Script : 构建成功
Script->>Script : 检查 REGISTRY 是否为 localhost
alt 需要推送
Script->>Docker : docker tag ... git.oceanpay.cc/danial/...
Script->>Docker : docker push git.oceanpay.cc/danial/...
Docker-->>Script : 推送成功
end
Script->>Script : 输出镜像大小信息
Script-->>Terminal : 构建完成
```
**Diagram sources**
- [build-base-image.sh](file://kami-gateway/build-base-image.sh#L18-L51)
**Section sources**
- [build-base-image.sh](file://kami-gateway/build-base-image.sh#L1-L51)
## 依赖分析
`kami-gateway` 基础镜像的构建依赖于外部的 Docker 环境和网络服务。其主要依赖关系如下：
```mermaid
graph LR
A[build-base-image.sh] --> B[Docker CLI]
B --> C[Docker Daemon]
C --> D[golang:1.25-alpine]
D --> E[阿里云Alpine镜像]
A --> F[Go Proxy 中国镜像]
F --> G[goproxy.cn]
A --> H[私有镜像仓库]
H --> I[git.oceanpay.cc/danial]
```
**Diagram sources**
- [Dockerfile.base](file://kami-gateway/Dockerfile.base#L4-L16)
- [build-base-image.sh](file://kami-gateway/build-base-image.sh#L10-L30)
## 性能考虑
该构建机制在性能方面进行了精心优化。通过在 `Dockerfile.base` 中预下载 Go 依赖（`go mod download`），后续基于此基础镜像构建的应用镜像可以跳过耗时的依赖下载阶段，从而将构建时间从几分钟缩短到十秒左右。使用中国镜像源（阿里云和 goproxy.cn）显著减少了网络延迟，是提升构建速度的关键。多阶段构建和 `--no-cache` 选项的使用也确保了镜像的精简，减小了最终镜像的体积，有利于快速部署和传输。
## 故障排除指南
当构建过程出现问题时，可参考以下步骤进行排查：
1. **网络问题**：确认构建环境可以访问阿里云镜像源（`mirrors.aliyun.com`）和 Go 代理（`goproxy.cn`）。若网络受限，可尝试更换为其他国内镜像。
2. **权限问题**：检查 `build-base-image.sh` 脚本是否具有可执行权限（`chmod +x build-base-image.sh`）。
3. **Docker 服务**：确保 Docker 服务正在运行。
4. **私有仓库认证**：如果推送失败，确认已使用 `docker login git.oceanpay.cc` 登录到私有仓库。
5. **证书问题**：如果出现 HTTPS 证书错误，检查 `Dockerfile.base` 中的 `curl` 命令是否能成功下载证书。
**Section sources**
- [Dockerfile.base](file://kami-gateway/Dockerfile.base#L33-L34)
- [build-base-image.sh](file://kami-gateway/build-base-image.sh#L35-L39)
## 结论
`kami-gateway` 的基础镜像构建方案是一个优秀的实践范例。它通过 `Dockerfile.base` 实现了环境的标准化和安全加固，利用 `build-base-image.sh` 脚本实现了构建流程的自动化和智能化。该方案不仅解决了中国开发者面临的网络瓶颈问题，还通过非 root 用户运行和预下载依赖等手段，兼顾了安全性与构建效率。这种多阶段、可复用的构建模式，为微服务架构下的持续集成与部署（CI/CD）提供了坚实的基础。

140
.qoder/repowiki/zh/content/kami-gateway 模块/改进型应用镜像.md Normal file
View File

@@ -0,0 +1,140 @@
# 改进型应用镜像
<cite>
**本文档引用文件**
- [Dockerfile.base](file://kami-gateway/Dockerfile.base)
- [build-base-image.sh](file://kami-gateway/build-base-image.sh)
- [README.md](file://kami-gateway/README.md)
</cite>
## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构概述](#架构概述)
5. [详细组件分析](#详细组件分析)
6. [依赖分析](#依赖分析)
7. [性能考量](#性能考量)
8. [故障排除指南](#故障排除指南)
9. [结论](#结论)
## 简介
本文档全面介绍 `Dockerfile.improved` 的设计理念与实现细节，重点阐述其如何基于预构建的 `kami-gateway-base` 镜像实现极速应用打包。通过复用基础镜像中预下载的 Go 依赖和编译环境，仅需复制应用源码并执行 `go build` 即可生成二进制文件，将构建时间压缩至 10-30 秒。同时，文档解析多阶段构建策略在减小最终镜像体积方面的优势，以及非 root 用户运行的安全配置机制。
## 项目结构
项目仓库包含多个子目录，分别对应不同的基础镜像构建方案。其中 `kami-gateway` 目录为核心分析对象，提供了 Go 应用的基础镜像构建能力。
```mermaid
graph TB
subgraph "基础镜像目录"
A[alpine-base]
B[kami-gateway]
C[kami-spider-monorepo]
end
B --> D[Dockerfile.base]
B --> E[build-base-image.sh]
B --> F[go.mod]
B --> G[go.sum]
```
**Diagram sources**
- [kami-gateway/Dockerfile.base](file://kami-gateway/Dockerfile.base#L1-L59)
- [kami-gateway/build-base-image.sh](file://kami-gateway/build-base-image.sh#L1-L51)
**Section sources**
- [kami-gateway/Dockerfile.base](file://kami-gateway/Dockerfile.base#L1-L59)
- [kami-gateway/build-base-image.sh](file://kami-gateway/build-base-image.sh#L1-L51)
## 核心组件
`kami-gateway` 的核心组件包括 `Dockerfile.base` 和 `build-base-image.sh` 脚本。前者定义了包含 Go 1.25 编译环境和 Alpine 运行时的基础镜像，后者用于自动化构建并推送该镜像至私有注册中心。基础镜像通过预下载所有 Go 模块依赖，显著加速后续应用镜像的构建过程。
**Section sources**
- [kami-gateway/Dockerfile.base](file://kami-gateway/Dockerfile.base#L50-L55)
- [kami-gateway/build-base-image.sh](file://kami-gateway/build-base-image.sh#L1-L10)
## 架构概述
`kami-gateway-base` 镜像采用分层设计，底层基于 `golang:1.25-alpine`，逐层叠加中国镜像源、时区配置、证书更新、非 root 用户创建及 Go 依赖预下载。应用镜像通过 `FROM kami-gateway-base:latest` 继承此环境，实现“仅 COPY 源码 + go build”的极简构建流程。
```mermaid
graph TD
A[golang:1.25-alpine] --> B[配置环境变量]
B --> C[切换至阿里云镜像源]
C --> D[安装系统依赖]
D --> E[更新CA证书]
E --> F[创建非root用户appuser]
F --> G[设置工作目录/app]
G --> H[复制go.mod/go.sum]
H --> I[预下载Go依赖]
I --> J[kami-gateway-base:latest]
J --> K[应用镜像]
K --> L[COPY . .]
L --> M[go build]
M --> N[最终应用镜像]
```
**Diagram sources**
- [kami-gateway/Dockerfile.base](file://kami-gateway/Dockerfile.base#L4-L55)
## 详细组件分析
### 基础镜像设计分析
`Dockerfile.base` 通过一系列优化步骤构建高效的基础镜像。环境变量配置确保了 Go 模块代理指向国内镜像 `goproxy.cn`，并禁用 CGO 以生成静态二进制文件。Alpine 镜像源替换为阿里云镜像，极大提升包管理效率。
#### 环境与依赖配置流程
```mermaid
flowchart TD
Start([开始]) --> SetEnv["设置环境变量<br/>GO111MODULE=on<br/>GOPROXY=https://goproxy.cn"]
SetEnv --> Mirror["配置Alpine镜像源<br/>mirrors.aliyun.com"]
Mirror --> Install["安装系统依赖<br/>tzdata, ca-certificates, git"]
Install --> Cert["下载并安装自定义CA证书"]
Cert --> User["创建非root用户appuser"]
User --> Workdir["设置工作目录 /app"]
Workdir --> CopyMod["复制go.mod和go.sum"]
CopyMod --> Download["执行go mod download"]
Download --> Verify["执行go mod verify"]
Verify --> Label["添加镜像标签"]
Label --> End([基础镜像构建完成])
```
**Diagram sources**
- [kami-gateway/Dockerfile.base](file://kami-gateway/Dockerfile.base#L6-L59)
**Section sources**
- [kami-gateway/Dockerfile.base](file://kami-gateway/Dockerfile.base#L6-L59)
### 构建脚本分析
`build-base-image.sh` 是一个 Bash 脚本，用于自动化构建和推送 `kami-gateway-base` 镜像。它支持通过环境变量自定义镜像名称、版本和目标注册中心，实现灵活的 CI/CD 集成。
**Section sources**
- [kami-gateway/build-base-image.sh](file://kami-gateway/build-base-image.sh#L1-L51)
## 依赖分析
`kami-gateway-base` 镜像的依赖分为两层：Docker 层依赖和 Go 模块层依赖。Docker 层依赖通过 `apk add` 安装必要的运行时工具，Go 模块层依赖通过 `go mod download` 在构建阶段预先拉取，避免每次应用构建时重复下载。
```mermaid
graph LR
A[kami-gateway-base] --> B[Alpine v3.22]
A --> C[Go 1.25]
A --> D[CA证书]
A --> E[Git]
A --> F[Go模块依赖]
F --> G[第三方库]
F --> H[项目私有模块]
```
**Diagram sources**
- [kami-gateway/Dockerfile.base](file://kami-gateway/Dockerfile.base#L19-L25)
- [kami-gateway/Dockerfile.base](file://kami-gateway/Dockerfile.base#L54)
## 性能考量
通过预构建 `kami-gateway-base` 镜像，将耗时的依赖下载和环境配置过程前置，使得应用镜像的构建时间从分钟级缩短至 10-30 秒。多阶段构建进一步优化最终镜像体积，仅包含运行时必要的二进制文件和配置，提升部署效率和安全性。
## 故障排除指南
当基础镜像构建失败时，应首先检查网络连接，特别是对 `goproxy.cn` 和 `mirrors.aliyun.com` 的访问。若 `go mod download` 失败，可尝试清除 Go 模块缓存后重试。镜像推送失败通常与 Docker 注册中心认证或网络策略有关。
**Section sources**
- [kami-gateway/README.md](file://kami-gateway/README.md#L53-L60)
- [kami-gateway/build-base-image.sh](file://kami-gateway/build-base-image.sh#L35-L45)
## 结论
`kami-gateway-base` 镜像通过精心设计的分层结构和预构建策略，为 Go 应用提供了极速、安全、一致的构建基础。结合多阶段构建和非 root 用户运行，该方案在提升开发效率的同时，保障了生产环境的安全性与稳定性，是现代化容器化部署的理想选择。

224
.qoder/repowiki/zh/content/kami-spider-monorepo 模块/Playwright集成.md Normal file
View File

@@ -0,0 +1,224 @@
# Playwright集成
<cite>
**本文档中引用的文件**
- [Dockerfile.base](file://kami-spider-monorepo/Dockerfile.base)
- [pyproject.toml](file://kami-spider-monorepo/pyproject.toml)
- [uv.lock](file://kami-spider-monorepo/uv.lock)
- [build-base-image.sh](file://kami-spider-monorepo/build-base-image.sh)
- [README.md](file://kami-spider-monorepo/README.md)
</cite>
## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [系统级依赖详解](#系统级依赖详解)
4. [Chromium浏览器预下载机制](#chromium浏览器预下载机制)
5. [Playwright Python API使用示例](#playwright-python-api使用示例)
6. [环境变量控制安装行为](#环境变量控制安装行为)
7. [常见问题与解决方案](#常见问题与解决方案)
8. [构建与使用说明](#构建与使用说明)
## 简介
本文档详细说明了如何在Docker镜像中集成Playwright，实现开箱即用的浏览器自动化能力。重点涵盖系统依赖安装、Chromium浏览器预加载、Playwright API使用方法、环境变量控制以及常见问题处理。
## 项目结构
`kami-spider-monorepo`目录包含构建Playwright集成Docker镜像所需的核心文件。该结构旨在提供一个完整、可复用的基础镜像，适用于需要浏览器自动化的爬虫服务。
```mermaid
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]
```
**图示来源**
- [Dockerfile.base](file://kami-spider-monorepo/Dockerfile.base#L1-L87)
- [pyproject.toml](file://kami-spider-monorepo/pyproject.toml#L1-L144)
**本节来源**
- [README.md](file://kami-spider-monorepo/README.md#L1-L34)
## 系统级依赖详解
`Dockerfile.base`中通过`apt-get`安装了一系列系统级依赖库，这些库对于Chromium在无头Linux容器中稳定运行至关重要。
| 依赖包 | 用途说明 |
|--------|----------|
| `libnss3` | 网络安全服务库，支持HTTPS/TLS加密通信 |
| `libasound2` | ALSA音频支持库，防止因缺少音频设备导致的崩溃 |
| `libx11-6` | X11客户端库，提供基础的图形界面通信能力 |
| `libatk-bridge2.0-0` | 辅助技术工具包桥接，支持无障碍功能 |
| `libdrm2` | 直接渲染管理器库，支持GPU加速渲染 |
| `libxkbcommon0` | 键盘处理公共库，处理键盘布局和输入 |
| `libxcomposite1` | X复合扩展库，支持窗口合成 |
| `libxdamage1` | X损伤扩展库，用于检测屏幕变化 |
| `libxrandr2` | X随机访问内存库，管理显示分辨率 |
| `libgbm1` | 通用缓冲区管理库，支持GPU内存管理 |
| `libcups2t64` | 通用Unix打印系统库，防止打印相关错误 |
| `libxfixes3` | X修复扩展库，修复图形渲染问题 |
| `libcairo2` | 2D图形绘制库，支持矢量图形渲染 |
| `libpango-1.0-0` | 文本布局与渲染库，支持复杂文本显示 |
这些依赖通过`playwright install-deps chromium`命令进一步验证和补充，确保Chromium所有运行时需求都被满足。
**本节来源**
- [Dockerfile.base](file://kami-spider-monorepo/Dockerfile.base#L17-L36)
- [Dockerfile.base](file://kami-spider-monorepo/Dockerfile.base#L69)
## Chromium浏览器预下载机制
为实现“开箱即用”的体验，Docker镜像在构建阶段即预下载并安装Chromium浏览器。
- **存储路径**：`/app/.browsers`
- **环境变量**：`PLAYWRIGHT_BROWSERS_PATH=/app/.browsers`
- **安装命令**：`/app/.venv/bin/playwright install chromium`
- **用户权限**：由非root用户`appuser`执行安装，确保运行时权限一致
- **权限设置**：安装完成后，root用户将浏览器目录权限设为`755`，保证`appuser`可读写
此机制确保容器启动时无需额外下载浏览器，显著提升启动速度和稳定性。
```mermaid
sequenceDiagram
participant DockerBuild as Docker构建
participant RootUser as Root用户
participant AppUser as appuser用户
participant Playwright as Playwright CLI
DockerBuild->>RootUser : 开始构建
RootUser->>AppUser : 切换至appuser
AppUser->>Playwright : playwright install chromium
Playwright->>AppUser : 下载并安装Chromium到/app/.browsers
AppUser->>RootUser : 切换回root
RootUser->>RootUser : chmod -R 755 /app/.browsers
RootUser->>DockerBuild : 构建完成
```
**图示来源**
- [Dockerfile.base](file://kami-spider-monorepo/Dockerfile.base#L10)
- [Dockerfile.base](file://kami-spider-monorepo/Dockerfile.base#L75-L82)
**本节来源**
- [Dockerfile.base](file://kami-spider-monorepo/Dockerfile.base#L70-L76)
## Playwright Python API使用示例
以下代码展示了如何在容器内使用Playwright Python API进行浏览器自动化。
```python
from playwright.sync_api import sync_playwright
import os
def main():
with sync_playwright() as p:
# 启动Chromium浏览器
browser = p.chromium.launch(
headless=True,
args=[
'--no-sandbox',
'--disable-setuid-sandbox',
'--disable-dev-shm-usage',
'--disable-gpu'
]
)
page = browser.new_page()
# 拦截请求示例
def intercept_request(route, request):
if request.resource_type in ["image", "stylesheet", "font"]:
route.abort()
else:
route.continue_()
page.route("**/*", intercept_request)
# 处理反爬检测
page.add_init_script("""
Object.defineProperty(navigator, 'webdriver', {
get: () => false,
});
""")
page.goto("https://example.com")
print(page.title())
browser.close()
if __name__ == "__main__":
main()
```
**本节来源**
- [pyproject.toml](file://kami-spider-monorepo/pyproject.toml#L45)
- [uv.lock](file://kami-spider-monorepo/uv.lock#L1440-L1457)
## 环境变量控制安装行为
通过环境变量可灵活控制Docker镜像的构建和运行行为。
| 环境变量 | 作用 | 默认值 | 使用场景 |
|---------|------|--------|---------|
| `USE_PROXY` | 是否使用PyPI镜像代理 | 0 | 在网络受限环境中设为1 |
| `PLAYWRIGHT_BROWSERS_PATH` | 浏览器安装路径 | `/app/.browsers` | 自定义浏览器存储位置 |
| `UV_LINK_MODE` | UV包管理器链接模式 | copy | 控制依赖安装方式 |
| `PYDEVD_DISABLE` | 禁用PyDev调试器 | 1 | 生产环境禁用调试 |
例如，使用代理构建镜像：
```bash
USE_PROXY=1 ./build-base-image.sh
```
**本节来源**
- [Dockerfile.base](file://kami-spider-monorepo/Dockerfile.base#L4-L14)
- [build-base-image.sh](file://kami-spider-monorepo/build-base-image.sh#L12)
## 常见问题与解决方案
### 问题：Browser closed unexpectedly
**原因**：
- 缺少系统依赖库
- 权限问题
- 内存不足
- 未正确设置`--no-sandbox`等启动参数
**解决方案**：
1. 确保`Dockerfile.base`中所有系统依赖已安装
2. 检查`/app/.browsers`目录权限为`755`
3. 增加容器内存限制
4. 启动浏览器时添加必要参数：
```python
args=[
'--no-sandbox',
'--disable-setuid-sandbox',
'--disable-dev-shm-usage',
'--disable-gpu'
]
```
### 问题：无法加载页面或超时
**解决方案**：
- 检查网络连接
- 增加超时时间
- 使用`wait_for_load_state("networkidle")`
- 启用请求拦截减少资源加载
**本节来源**
- [Dockerfile.base](file://kami-spider-monorepo/Dockerfile.base#L17-L36)
- [Dockerfile.base](file://kami-spider-monorepo/Dockerfile.base#L81-L82)
## 构建与使用说明
使用提供的脚本可一键构建基础镜像：
```bash
# 构建基础镜像
./build-base-image.sh
# 使用代理构建
USE_PROXY=1 ./build-base-image.sh
# 推送到私有镜像仓库
DOCKER_REGISTRY=your-registry.com ./build-base-image.sh
```
构建完成后，镜像标记为`kami-spider-base:latest`，可直接用于部署需要Playwright的爬虫服务。
**本节来源**
- [build-base-image.sh](file://kami-spider-monorepo/build-base-image.sh#L1-L54)
- [README.md](file://kami-spider-monorepo/README.md#L12-L23)

177
.qoder/repowiki/zh/content/kami-spider-monorepo 模块/kami-spider-monorepo 模块.md Normal file
View File

@@ -0,0 +1,177 @@
# kami-spider-monorepo 模块
<cite>
**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)
</cite>
## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构概述](#架构概述)
5. [详细组件分析](#详细组件分析)
6. [依赖分析](#依赖分析)
7. [性能考虑](#性能考虑)
8. [故障排除指南](#故障排除指南)
9. [结论](#结论)
## 简介
`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` 文件。这种结构将构建逻辑、依赖配置和环境定义清晰地分离，便于维护和理解。
```mermaid
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**
- [Dockerfile.base](file://kami-spider-monorepo/Dockerfile.base)
- [build-base-image.sh](file://kami-spider-monorepo/build-base-image.sh)
- [pyproject.toml](file://kami-spider-monorepo/pyproject.toml)
- [uv.lock](file://kami-spider-monorepo/uv.lock)
- [README.md](file://kami-spider-monorepo/README.md)
**Section sources**
- [README.md](file://kami-spider-monorepo/README.md)
## 核心组件
该模块的核心由四个关键文件构成：`Dockerfile.base` 定义了镜像的构建步骤和最终形态；`build-base-image.sh` 提供了可执行的构建命令，简化了镜像的创建过程；`pyproject.toml` 声明了项目所需的所有Python包及其版本范围；`uv.lock` 则精确锁定了所有依赖包的版本和哈希值，确保了构建的可重复性。这些组件协同工作，共同实现了从源码到可运行镜像的完整构建流程。
**Section sources**
- [Dockerfile.base](file://kami-spider-monorepo/Dockerfile.base)
- [build-base-image.sh](file://kami-spider-monorepo/build-base-image.sh)
- [pyproject.toml](file://kami-spider-monorepo/pyproject.toml)
- [uv.lock](file://kami-spider-monorepo/uv.lock)
## 架构概述
`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` 镜像包含了所有必要的运行时环境。
```mermaid
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**
- [build-base-image.sh](file://kami-spider-monorepo/build-base-image.sh)
- [Dockerfile.base](file://kami-spider-monorepo/Dockerfile.base)
## 详细组件分析
### 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浏览器本身。这种设计确保了所有操作都在正确的权限下执行，避免了权限错误。
```mermaid
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**
- [Dockerfile.base](file://kami-spider-monorepo/Dockerfile.base)
**Section sources**
- [Dockerfile.base](file://kami-spider-monorepo/Dockerfile.base)
### 构建脚本分析
`build-base-image.sh` 是一个Bash脚本，它封装了复杂的Docker构建命令，为开发者提供了简单易用的接口。脚本通过读取环境变量（如 `USE_PROXY`, `REGISTRY`, `VERSION`）来动态调整构建行为。例如，当 `USE_PROXY=1` 时，它会将代理设置传递给Docker构建过程，这对于在受限网络环境中构建镜像至关重要。脚本还负责为生成的镜像打上多个标签（包括版本号和 `latest`），并可选择性地将其推送到指定的镜像仓库。
**Section sources**
- [build-base-image.sh](file://kami-spider-monorepo/build-base-image.sh)
### 依赖配置分析
`pyproject.toml` 文件是项目的依赖声明中心，它明确列出了所有必需的Python包，如 `fastapi`, `sqlalchemy`, `playwright` 等。`uv.lock` 文件则是由UV工具生成的锁定文件，它不仅记录了每个包的确切版本，还包含了其来源、哈希值和所有传递性依赖。这两个文件共同作用，确保了依赖管理的透明性和可重复性。
**Section sources**
- [pyproject.toml](file://kami-spider-monorepo/pyproject.toml)
- [uv.lock](file://kami-spider-monorepo/uv.lock)
## 依赖分析
该模块的依赖关系清晰且高效。`build-base-image.sh` 脚本直接依赖于 `Dockerfile.base` 来执行构建。`Dockerfile.base` 则依赖于 `pyproject.toml` 和 `uv.lock` 来获取依赖信息，并依赖于 `uv` 二进制文件来执行安装。`uv.lock` 文件本身是由 `pyproject.toml` 中的依赖声明通过 `uv` 工具生成的。这种依赖链确保了构建过程的每个环节都有明确的输入和输出。
```mermaid
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**
- [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)
**Section sources**
- [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)
## 性能考虑
该模块在性能方面进行了多项优化。首先，使用 `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**
- [Dockerfile.base](file://kami-spider-monorepo/Dockerfile.base)
- [build-base-image.sh](file://kami-spider-monorepo/build-base-image.sh)
## 结论
`kami-spider-monorepo` 模块通过精心设计的Dockerfile和构建脚本，成功地为Python爬虫应用创建了一个强大、安全且高效的开发基础。它通过集成Python 3.13、UV包管理器、清华源代理支持、确定性依赖管理和开箱即用的Playwright浏览器，极大地简化了开发者的环境配置工作。该模块不仅提升了构建效率，还通过非root用户运行和标准化的依赖管理，为应用的稳定性和安全性提供了保障，是构建现代化爬虫应用的理想起点。

71
.qoder/repowiki/zh/content/kami-spider-monorepo 模块/依赖管理.md Normal file
View File

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

81
.qoder/repowiki/zh/content/kami-spider-monorepo 模块/功能特性.md Normal file
View File

@@ -0,0 +1,81 @@
# 功能特性
<cite>
**本文档引用的文件**
- [README.md](file://kami-spider-monorepo/README.md)
- [Dockerfile.base](file://kami-spider-monorepo/Dockerfile.base)
- [build-base-image.sh](file://kami-spider-monorepo/build-base-image.sh)
- [pyproject.toml](file://kami-spider-monorepo/pyproject.toml)
- [uv.lock](file://kami-spider-monorepo/uv.lock)
</cite>
## 目录
1. [引言](#引言)
2. [核心功能组件](#核心功能组件)
3. [Python 3.13与UV包管理器集成](#python-313与uv包管理器集成)
4. [Playwright自动化框架与Chromium浏览器](#playwright自动化框架与chromium浏览器)
5. [国内网络环境优化机制](#国内网络环境优化机制)
6. [安全运行策略](#安全运行策略)
7. [实际应用场景优势](#实际应用场景优势)
8. [与通用Python镜像对比分析](#与通用python镜像对比分析)
9. [构建与使用方法](#构建与使用方法)
## 引言
kami-spider-monorepo模块提供了一个专为Python爬虫应用优化的基础Docker镜像，旨在解决复杂网页抓取、反爬虫绕过和高并发请求等挑战。该镜像集成了最新的Python 3.13运行时、高效的UV包管理器以及完整的Playwright自动化框架，特别针对中国网络环境进行了优化，包括配置了清华源加速机制和自定义证书支持。通过预装Chromium浏览器和非root用户安全策略，该镜像不仅提升了依赖安装效率和运行安全性，还为处理JavaScript渲染页面和动态内容抓取提供了强大支持。
## 核心功能组件
kami-spider基础镜像通过精心设计的组件集成，为爬虫应用提供了完整的运行环境。镜像基于`python:3.13-slim`构建，确保了Python 3.13的最新特性和性能优化。UV包管理器被集成用于快速、确定性的依赖安装，显著缩短了构建时间。Playwright框架及其运行时库被完整安装，支持对复杂动态页面的自动化操作。所有项目所需的Python依赖包都已预先安装，包括用于网络请求的`httpx`、`curl-cffi`，用于数据解析的`beautifulsoup4`、`lxml`，以及用于验证码识别的`ddddocr`等。此外，镜像还配置了非root用户`appuser`，增强了生产环境下的安全性。
**本文档引用的文件**
- [README.md](file://kami-spider-monorepo/README.md)
- [Dockerfile.base](file://kami-spider-monorepo/Dockerfile.base)
- [pyproject.toml](file://kami-spider-monorepo/pyproject.toml)
## Python 3.13与UV包管理器集成
该镜像的核心是Python 3.13运行时环境，它为爬虫应用提供了最新的语言特性和性能改进。为了优化依赖管理，镜像集成了UV包管理器，这是一个用Rust编写的超高速Python包安装工具。UV通过`COPY --from=ghcr.io/astral-sh/uv:latest /uv /usr/local/bin/uv`指令被安装到镜像中，确保了其可用性。在构建过程中，UV利用`uv sync`命令根据`uv.lock`文件精确安装所有依赖，保证了环境的一致性和可重复性。与传统的`pip`相比，UV的安装速度显著提升，特别是在处理大量依赖时，这极大地缩短了Docker镜像的构建时间。
**本文档引用的文件**
- [Dockerfile.base](file://kami-spider-monorepo/Dockerfile.base)
- [pyproject.toml](file://kami-spider-monorepo/pyproject.toml)
- [uv.lock](file://kami-spider-monorepo/uv.lock)
## Playwright自动化框架与Chromium浏览器
为了应对现代网站广泛使用的JavaScript动态渲染，该镜像深度集成了Playwright自动化框架。在Dockerfile中，通过`RUN /app/.venv/bin/playwright install-deps chromium`和`RUN /app/.venv/bin/playwright install chromium`指令，系统级依赖和Chromium浏览器本身被安装到镜像中。这使得爬虫能够模拟真实用户行为，如页面导航、表单填写、点击操作和等待动态内容加载，从而有效抓取由JavaScript生成的内容。Playwright的API提供了对浏览器上下文、页面和元素的精细控制，是绕过复杂反爬虫机制的关键工具。
**本文档引用的文件**
- [Dockerfile.base](file://kami-spider-monorepo/Dockerfile.base)
- [pyproject.toml](file://kami-spider-monorepo/pyproject.toml)
## 国内网络环境优化机制
考虑到国内开发者面临的网络挑战，该镜像内置了针对中国网络环境的优化机制。通过在构建脚本中设置`USE_PROXY`环境变量，镜像构建过程可以智能地选择是否使用代理。当`USE_PROXY=1`时，`uv sync`命令会使用`--index-url https://pypi.tuna.tsinghua.edu.cn/simple/`参数，将包索引源切换到清华大学的镜像站。这一机制显著加速了依赖包的下载速度，解决了从官方PyPI源下载缓慢或不稳定的问题。此外，镜像还预装了必要的系统证书，确保了与国内HTTPS服务的安全通信。
**本文档引用的文件**
- [Dockerfile.base](file://kami-spider-monorepo/Dockerfile.base)
- [build-base-image.sh](file://kami-spider-monorepo/build-base-image.sh)
## 安全运行策略
安全性是生产环境部署的关键考量。该镜像遵循最小权限原则，创建了一个名为`appuser`的非root用户。在Dockerfile中，通过`RUN groupadd -r appuser && useradd -r -g appuser -d /home/appuser -m appuser`指令创建该用户，并通过`USER appuser`指令在后续步骤中以该用户身份运行。这种策略有效降低了因应用漏洞导致的系统级安全风险。即使爬虫应用被攻破，攻击者也只能在`appuser`的权限范围内活动，无法对宿主系统造成严重破坏，从而提升了整体部署的安全性。
**本文档引用的文件**
- [Dockerfile.base](file://kami-spider-monorepo/Dockerfile.base)
## 实际应用场景优势
该镜像在处理复杂爬虫任务时展现出显著优势。对于需要JavaScript渲染的单页应用（SPA），Playwright可以完美模拟浏览器行为，获取动态加载的数据。在反爬虫绕过方面，结合`fake-useragent`生成随机User-Agent、`curl-cffi`模拟真实浏览器指纹以及Playwright的自动化操作，可以有效应对基于行为分析的反爬机制。在高并发请求场景下，`aiofiles`和`aiomysql`等异步库与`gunicorn`和`uvicorn`的结合，确保了应用的高吞吐量和低延迟。此外，`apscheduler`提供了强大的定时任务调度能力，适用于周期性数据抓取任务。
**本文档引用的文件**
- [pyproject.toml](file://kami-spider-monorepo/pyproject.toml)
- [uv.lock](file://kami-spider-monorepo/uv.lock)
## 与通用Python镜像对比分析
相较于标准的`python:3.13-slim`等通用镜像，kami-spider基础镜像体现了专为爬虫优化的设计理念。通用镜像仅提供Python运行时，开发者需要自行安装所有依赖和工具，过程繁琐且易出错。而kami-spider镜像开箱即用，预装了爬虫所需的所有核心组件，极大地简化了开发和部署流程。在性能上，UV包管理器比`pip`快数倍；在功能性上，集成的Playwright和Chromium省去了复杂的环境配置；在安全性上，非root用户策略是通用镜像通常不具备的。这种一体化的设计，使得kami-spider镜像成为构建高效、稳定爬虫应用的理想选择。
**本文档引用的文件**
- [Dockerfile.base](file://kami-spider-monorepo/Dockerfile.base)
- [pyproject.toml](file://kami-spider-monorepo/pyproject.toml)
## 构建与使用方法
构建该基础镜像非常简单，只需在`kami-spider-monorepo`目录下运行`./build-base-image.sh`脚本。如果需要使用代理加速国内网络，可以执行`USE_PROXY=1 ./build-base-image.sh`。构建完成后，镜像将被标记为`kami-spider-base:latest`。用户可以在自己的Dockerfile中通过`FROM kami-spider-base:latest`来继承此基础镜像，从而快速启动爬虫应用的开发。整个构建过程自动化，确保了环境的一致性和可重复性。
**本文档引用的文件**
- [build-base-image.sh](file://kami-spider-monorepo/build-base-image.sh)
- [README.md](file://kami-spider-monorepo/README.md)

210
.qoder/repowiki/zh/content/kami-spider-monorepo 模块/构建与使用.md Normal file
View File

@@ -0,0 +1,210 @@
# 构建与使用
<cite>
**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)
</cite>
## 目录
1. [简介](#简介)
2. [前置条件与环境准备](#前置条件与环境准备)
3. [构建脚本详解](#构建脚本详解)
4. [环境变量配置](#环境变量配置)
5. [镜像构建与推送流程](#镜像构建与推送流程)
6. [基础镜像使用指南](#基础镜像使用指南)
7. [输出信息解析](#输出信息解析)
8. [常见问题排查](#常见问题排查)
## 简介
本文档详细说明如何构建和使用 `kami-spider-base` 基础 Docker 镜像。该镜像为爬虫应用提供完整的运行时环境，包含 Python 3.13、UV 包管理器、所有项目依赖以及 Playwright 浏览器。通过本指南，开发者可以了解构建脚本的工作原理、配置选项以及如何在实际项目中引用此基础镜像。
**Section sources**
- [README.md](file://kami-spider-monorepo/README.md#L1-L34)
## 前置条件与环境准备
在执行构建脚本之前，请确保本地开发环境满足以下条件：
- **Docker 引擎**：已安装并运行 Docker 服务
- **工作目录**：位于 `kami-spider-monorepo` 项目根目录
- **网络连接**：能够访问外部包仓库（或配置代理）
- **权限配置**：当前用户具有执行脚本和调用 Docker 命令的权限
推荐使用 Linux 或 macOS 系统进行构建。Windows 用户建议使用 WSL2 环境以获得最佳兼容性。
**Section sources**
- [build-base-image.sh](file://kami-spider-monorepo/build-base-image.sh#L1-L54)
## 构建脚本详解
`build-base-image.sh` 脚本是构建 `kami-spider-base` 镜像的核心工具，其执行流程如下：
1. **初始化配置**：读取环境变量并设置默认值
2. **镜像构建**：调用 `docker build` 命令，基于 `Dockerfile.base` 创建镜像
3. **标签处理**：为镜像添加版本标签和 latest 标签
4. **注册表推送**：当指定非本地注册表时，推送镜像到远程仓库
5. **结果展示**：输出构建完成信息和镜像大小统计
脚本通过 `set -e` 确保任何步骤失败时立即终止，保证构建过程的可靠性。
```mermaid
flowchart TD
A[开始构建] --> B[读取环境变量]
B --> C[执行Docker构建]
C --> D[生成镜像标签]
D --> E{是否推送?}
E --> |是| F[推送至注册表]
E --> |否| G[跳过推送]
F --> H[显示构建结果]
G --> H
H --> I[结束]
```
**Diagram sources**
- [build-base-image.sh](file://kami-spider-monorepo/build-base-image.sh#L1-L54)
**Section sources**
- [build-base-image.sh](file://kami-spider-monorepo/build-base-image.sh#L1-L54)
## 环境变量配置
构建脚本支持以下环境变量来自定义构建行为：
**: 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](file://kami-spider-monorepo/build-base-image.sh#L8-L12)
## 镜像构建与推送流程
### 构建命令示例
```bash
# 基本构建（使用本地注册表）
./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**
- [build-base-image.sh](file://kami-spider-monorepo/build-base-image.sh#L26-L43)
## 基础镜像使用指南
在实际爬虫项目的 `Dockerfile` 中，可通过以下方式引用 `kami-spider-base` 镜像：
```dockerfile
# 使用基础镜像
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**
- [Dockerfile.base](file://kami-spider-monorepo/Dockerfile.base#L1-L87)
- [README.md](file://kami-spider-monorepo/README.md#L25-L32)
## 输出信息解析
构建成功后，脚本会输出以下关键信息：
**: 构建状态**
- `✅ 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**
- [build-base-image.sh](file://kami-spider-monorepo/build-base-image.sh#L45-L54)
## 常见问题排查
### 问题1：构建失败，提示网络超时
**可能原因**：无法访问外部包仓库
**解决方案**：
- 启用代理：`USE_PROXY=1 ./build-base-image.sh`
- 检查网络连接和防火墙设置
### 问题2：推送失败，认证错误
**可能原因**：未登录目标注册表
**解决方案**：
```bash
# 登录私有注册表
docker login git.oceanpay.cc
```
### 问题3：权限错误
**可能原因**：Docker 服务未运行或用户无权限
**解决方案**：
- 启动 Docker 服务
- 将用户添加到 docker 组：`sudo usermod -aG docker $USER`
### 问题4：磁盘空间不足
**可能原因**：Chromium 浏览器占用大量空间
**解决方案**：
- 清理 Docker 缓存：`docker system prune`
- 确保至少有 2GB 可用磁盘空间
**Section sources**
- [build-base-image.sh](file://kami-spider-monorepo/build-base-image.sh#L6-L54)
- [Dockerfile.base](file://kami-spider-monorepo/Dockerfile.base#L1-L87)

101
.qoder/repowiki/zh/content/kami-spider-monorepo 模块/配置选项.md Normal file
View File

@@ -0,0 +1,101 @@
# 配置选项
<cite>
**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)
</cite>
## 目录
1. [引言](#引言)
2. [核心环境变量](#核心环境变量)
3. [Dockerfile静态配置](#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**
- [build-base-image.sh](file://kami-spider-monorepo/build-base-image.sh#L12)
- [Dockerfile.base](file://kami-spider-monorepo/Dockerfile.base#L59-L62)
### VERSION：镜像版本管理
`VERSION`环境变量用于指定Docker镜像的标签（tag）。在`build-base-image.sh`脚本中，该变量具有默认值`latest`，允许用户在构建时灵活指定语义化版本号（如`1.0.0`、`v2.1.3`等）。
该变量的值被用于`docker build`命令的`--tag`参数，为生成的镜像打上版本标签。同时，脚本也会创建一个`latest`标签的镜像，便于在开发和测试环境中快速引用最新版本。
这种设计支持语义化版本管理，使得镜像的发布、回滚和依赖追踪成为可能。
**Section sources**
- [build-base-image.sh](file://kami-spider-monorepo/build-base-image.sh#L11)
- [build-base-image.sh](file://kami-spider-monorepo/build-base-image.sh#L24-L25)
### 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**
- [build-base-image.sh](file://kami-spider-monorepo/build-base-image.sh#L10)
- [build-base-image.sh](file://kami-spider-monorepo/build-base-image.sh#L30-L32)
- [build-base-image.sh](file://kami-spider-monorepo/build-base-image.sh#L38-L41)
## Dockerfile静态配置
本节分析`Dockerfile.base`文件中定义的静态配置项，这些配置在构建时即被固化到镜像中。
### 时区与语言环境
`Dockerfile.base`文件通过`ENV`指令设置了多个环境变量，但并未直接配置`Asia/Shanghai`时区或`zh_CN.UTF-8`语言环境。这表明时区和语言环境的配置可能由基础镜像`python:3.13-slim`继承，或在更高层的应用镜像中进行设置。
文件中定义的`PYTHONUNBUFFERED`和`PYTHONDONTWRITEBYTECODE`等环境变量，主要用于优化Python应用的运行时行为，确保日志实时输出和避免生成`.pyc`文件。
**Section sources**
- [Dockerfile.base](file://kami-spider-monorepo/Dockerfile.base#L4-L14)
### 系统依赖
`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**
- [Dockerfile.base](file://kami-spider-monorepo/Dockerfile.base#L17-L36)
- [Dockerfile.base](file://kami-spider-monorepo/Dockerfile.base#L70)
## 配置最佳实践
### 在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中：
```yaml
env:
DOCKER_REGISTRY: ${{ secrets.DOCKER_REGISTRY }}
DOCKER_USERNAME: ${{ secrets.DOCKER_USERNAME }}
DOCKER_PASSWORD: ${{ secrets.DOCKER_PASSWORD }}
```
这种方式避免了将敏感信息硬编码在代码或配置文件中，保障了安全性。
**Section sources**
- [build-base-image.sh](file://kami-spider-monorepo/build-base-image.sh#L10)

217
.qoder/repowiki/zh/content/快速开始.md Normal file
View File

@@ -0,0 +1,217 @@
# 快速开始
<cite>
**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)
</cite>
## 目录
1. [简介](#简介)
2. [构建基础镜像](#构建基础镜像)
3. [环境变量配置](#环境变量配置)
4. [实际应用示例](#实际应用示例)
5. [常见问题与解决方案](#常见问题与解决方案)
6. [最佳实践](#最佳实践)
## 简介
本指南旨在帮助新手开发者在5分钟内完成基础镜像的本地构建。项目提供了三个模块（alpine-base、kami-gateway、kami-spider-monorepo）的预构建基础镜像，每个模块都包含一个 `build-base-image.sh` 构建脚本，用于创建优化的Docker基础镜像。这些镜像预装了常用工具、配置了中国镜像源、设置了正确的时区，并遵循安全最佳实践。
**Section sources**
- [README.md](file://alpine-base/README.md#L1-L70)
- [README.md](file://kami-gateway/README.md#L1-L60)
- [README.md](file://kami-spider-monorepo/README.md#L1-L34)
## 构建基础镜像
### 基本构建步骤
要构建基础镜像，请按照以下步骤操作：
1. 打开终端并导航到目标模块目录
2. 运行构建脚本
```bash
# 进入 alpine-base 模块
cd alpine-base
# 执行构建
./build-base-image.sh
```
```bash
# 进入 kami-gateway 模块
cd kami-gateway
# 执行构建
./build-base-image.sh
```
```bash
# 进入 kami-spider-monorepo 模块
cd kami-spider-monorepo
# 执行构建
./build-base-image.sh
```
构建成功后，您将看到类似以下的输出：
```
🎉 Build completed successfully!
Available images:
- alpine-base:latest
- alpine-base:${VERSION}
```
**Section sources**
- [build-base-image.sh](file://alpine-base/build-base-image.sh#L1-L51)
- [build-base-image.sh](file://kami-gateway/build-base-image.sh#L1-L51)
- [build-base-image.sh](file://kami-spider-monorepo/build-base-image.sh#L1-L54)
## 环境变量配置
构建脚本支持以下关键环境变量，您可以在运行脚本前设置它们：
### DOCKER_REGISTRY
指定镜像推送的目标仓库地址。如果未设置，将使用默认值。
- **alpine-base 和 kami-gateway**: 默认为 `git.oceanpay.cc/danial`
- **kami-spider-monorepo**: 默认为 `localhost:5000`
```bash
# 推送到私有镜像仓库
DOCKER_REGISTRY=your-registry.com ./build-base-image.sh
```
### VERSION
指定镜像的版本标签。默认值为 `latest`。
```bash
# 构建指定版本的镜像
VERSION=1.0.0 ./build-base-image.sh
```
### USE_PROXY
仅适用于 `kami-spider-monorepo` 模块，用于在构建时启用代理下载。
```bash
# 使用代理构建
USE_PROXY=1 ./build-base-image.sh
```
**Section sources**
- [build-base-image.sh](file://alpine-base/build-base-image.sh#L9-L11)
- [build-base-image.sh](file://kami-gateway/build-base-image.sh#L9-L11)
- [build-base-image.sh](file://kami-spider-monorepo/build-base-image.sh#L9-L13)
## 实际应用示例
### 构建场景示例
#### 不带参数构建
```bash
# 在 alpine-base 目录下执行
./build-base-image.sh
# 结果: 创建 alpine-base:latest 镜像
```
#### 使用代理构建
```bash
# 在 kami-spider-monorepo 目录下执行
USE_PROXY=1 ./build-base-image.sh
# 结果: 启用代理下载依赖并创建 kami-spider-base:latest 镜像
```
#### 推送到私有镜像仓库
```bash
# 在 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中使用基础镜像
```dockerfile
# 使用基础镜像
FROM alpine-base:latest
# 复制应用代码并设置正确的所有者
COPY --chown=appuser:appuser . /app/
# 切换到非root用户运行
USER appuser
# 运行应用
CMD ["./your-app"]
```
**Section sources**
- [README.md](file://alpine-base/README.md#L39-L52)
- [README.md](file://kami-gateway/README.md#L23-L30)
- [README.md](file://kami-spider-monorepo/README.md#L14-L23)
## 常见问题与解决方案
### 网络超时
**问题**: 构建过程中出现网络下载超时错误。
**解决方案**:
1. 对于 `kami-spider-monorepo` 模块，使用代理构建：
```bash
USE_PROXY=1 ./build-base-image.sh
```
2. 检查网络连接，确保可以访问所需的包管理器源。
### 权限错误
**问题**: 运行构建脚本时出现权限不足错误。
**解决方案**:
1. 确保构建脚本具有可执行权限：
```bash
chmod +x build-base-image.sh
```
2. 确保Docker服务正在运行且当前用户有权限访问Docker守护进程。
### 镜像推送失败
**问题**: 当设置 `DOCKER_REGISTRY` 时，镜像推送失败。
**解决方案**:
1. 确认已登录到目标镜像仓库：
```bash
docker login your-registry.com
```
2. 检查仓库地址和权限是否正确。
**Section sources**
- [build-base-image.sh](file://alpine-base/build-base-image.sh#L35-L39)
- [build-base-image.sh](file://kami-gateway/build-base-image.sh#L35-L39)
- [build-base-image.sh](file://kami-spider-monorepo/build-base-image.sh#L38-L42)
## 最佳实践
### 非root用户运行
所有基础镜像都配置了非root用户 `appuser` (UID: 1001)，这是重要的安全最佳实践。在您的应用Dockerfile中，应始终使用 `USER` 指令切换到非root用户：
```dockerfile
# 在复制应用代码后切换用户
COPY --chown=appuser:appuser . /app/
USER appuser
```
### 镜像优化
- **轻量化**: 基于Alpine Linux，镜像体积小（约50MB）
- **快速构建**: 预装常用工具和配置，避免重复下载
- **网络优化**: 配置中国镜像源，加速依赖下载
- **证书支持**: 预装CA证书和自定义证书
### CI/CD集成
`kami-gateway` 模块已配置Drone CI，能够自动检测目录变更并构建推送基础镜像，实现条件构建以节省资源。
**Section sources**
- [README.md](file://alpine-base/README.md#L62-L70)
- [README.md](file://kami-gateway/README.md#L53-L60)
- [README.md](file://kami-spider-monorepo/README.md#L25-L34)

170
.qoder/repowiki/zh/content/通用构建指南.md Normal file
View File

@@ -0,0 +1,170 @@
# 通用构建指南
<cite>
**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)
</cite>
## 目录
1. [引言](#引言)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构概述](#架构概述)
5. [详细组件分析](#详细组件分析)
6. [依赖分析](#依赖分析)
7. [性能考虑](#性能考虑)
8. [故障排除指南](#故障排除指南)
9. [结论](#结论)
## 引言
本文档旨在为 `kami` 项目中的通用构建流程提供权威指南。通过系统化分析 `alpine-base`、`kami-gateway` 和 `kami-spider-monorepo` 三个模块共用的构建机制，深入解析 `build-base-image.sh` 脚本的实现逻辑。文档将详细说明环境变量的统一处理方式、Docker 镜像标签的动态生成策略、构建命令的执行流程，并对比各模块构建脚本的异同，提炼出可复用的最佳实践模式，帮助开发者掌握整个项目的构建体系，提升自动化和可维护性。
## 项目结构
`kami` 项目的构建体系由三个主要模块构成，每个模块均包含一个独立的 `build-base-image.sh` 构建脚本。这些脚本遵循相似的设计模式，用于构建各自模块所需的 Docker 基础镜像。项目结构清晰，按功能模块进行隔离，便于独立构建和维护。
```mermaid
graph TB
subgraph "构建模块"
A[alpine-base]
B[kami-gateway]
C[kami-spider-monorepo]
end
A --> |使用| Script[build-base-image.sh]
B --> |使用| Script
C --> |使用| Script
Script --> |执行| Docker[docker build/tag/push]
```
**Diagram sources**
- [alpine-base/build-base-image.sh](file://alpine-base/build-base-image.sh)
- [kami-gateway/build-base-image.sh](file://kami-gateway/build-base-image.sh)
- [kami-spider-monorepo/build-base-image.sh](file://kami-spider-monorepo/build-base-image.sh)
**Section sources**
- [alpine-base/build-base-image.sh](file://alpine-base/build-base-image.sh)
- [kami-gateway/build-base-image.sh](file://kami-gateway/build-base-image.sh)
- [kami-spider-monorepo/build-base-image.sh](file://kami-spider-monorepo/build-base-image.sh)
## 核心组件
`build-base-image.sh` 脚本是整个构建体系的核心组件。它是一个 Bash 脚本，为每个模块提供标准化的 Docker 镜像构建、标记和推送流程。该脚本通过环境变量进行配置，实现了高度的灵活性和可复用性。其主要功能包括：解析环境变量、调用 `docker build` 命令构建镜像、根据配置生成并应用镜像标签、将镜像推送到指定的 Docker 仓库，并在构建完成后输出镜像信息。
**Section sources**
- [alpine-base/build-base-image.sh](file://alpine-base/build-base-image.sh)
- [kami-gateway/build-base-image.sh](file://kami-gateway/build-base-image.sh)
- [kami-spider-monorepo/build-base-image.sh](file://kami-spider-monorepo/build-base-image.sh)
## 架构概述
构建系统的架构遵循一个简洁而高效的模式。开发者通过设置环境变量来配置构建过程，然后执行 `build-base-image.sh` 脚本。脚本首先读取环境变量，然后执行 `docker build` 命令，利用 `Dockerfile.base` 文件构建本地镜像。接着，脚本会根据 `DOCKER_REGISTRY` 的配置，为镜像打上包含仓库地址的标签。如果指定了非本地的仓库，脚本会自动执行 `docker push` 命令将镜像推送到远程仓库。整个流程通过 `set -e` 保证了错误的及时中断，确保了构建的可靠性。
```mermaid
sequenceDiagram
participant Developer as 开发者
participant Script as build-base-image.sh
participant Docker as Docker Engine
participant Registry as Docker Registry
Developer->>Script : 设置环境变量并执行脚本
Script->>Script : 读取 DOCKER_REGISTRY, VERSION, USE_PROXY
Script->>Docker : docker build --tag <name> : <version>
Docker-->>Script : 构建成功
alt 非本地仓库
Script->>Script : docker tag 添加仓库前缀
Script->>Registry : docker push 推送镜像
Registry-->>Script : 推送成功
end
Script->>Developer : 输出构建完成信息和镜像大小
```
**Diagram sources**
- [alpine-base/build-base-image.sh](file://alpine-base/build-base-image.sh)
- [kami-gateway/build-base-image.sh](file://kami-gateway/build-base-image.sh)
- [kami-spider-monorepo/build-base-image.sh](file://kami-spider-monorepo/build-base-image.sh)
## 详细组件分析
### 构建脚本实现逻辑分析
`build-base-image.sh` 脚本的实现逻辑高度一致，体现了良好的代码复用原则。所有脚本都以 `#!/bin/bash` 开头，并通过 `set -e` 确保在任何命令失败时立即退出，防止错误的累积。脚本的核心是 `docker build` 命令，它使用 `--file Dockerfile.base` 指定构建文件，并通过 `--tag` 参数为镜像打上两个标签：一个由 `VERSION` 环境变量指定的版本号标签，另一个是 `latest` 标签。
**Section sources**
- [alpine-base/build-base-image.sh](file://alpine-base/build-base-image.sh#L1-L51)
- [kami-gateway/build-base-image.sh](file://kami-gateway/build-base-image.sh#L1-L51)
- [kami-spider-monorepo/build-base-image.sh](file://kami-spider-monorepo/build-base-image.sh#L1-L54)
#### 环境变量处理
脚本通过 Bash 的参数扩展语法 `${VAR:-default}` 来处理环境变量，这使得脚本既灵活又健壮。关键环境变量及其作用如下：
- **`DOCKER_REGISTRY`**: 指定 Docker 镜像仓库的地址。默认值在不同模块中有所不同（`alpine-base` 和 `kami-gateway` 默认为 `git.oceanpay.cc/danial`，`kami-spider-monorepo` 默认为 `localhost:5000`）。当该值不为 `localhost:5000` 时，脚本会执行 `docker tag` 和 `docker push` 操作。
- **`VERSION`**: 指定构建的镜像版本号。默认值为 `latest`。该变量用于生成镜像的版本标签。
- **`USE_PROXY`**: 一个布尔标志（0 或 1），仅在 `kami-spider-monorepo` 模块中使用。当设置为 `1` 时，它会作为 `--build-arg` 传递给 `docker build` 命令，用于在构建过程中启用中国代理加速，从而加快依赖下载速度。
```mermaid
flowchart TD
Start([开始构建]) --> SetVars["设置环境变量\nDOCKER_REGISTRY, VERSION, USE_PROXY"]
SetVars --> ReadVars["读取变量值\n使用默认值回退"]
ReadVars --> BuildImage["执行 docker build\n生成本地镜像"]
BuildImage --> CheckRegistry{"REGISTRY != localhost:5000?"}
CheckRegistry --> |是| TagImage["执行 docker tag\n添加仓库前缀"]
TagImage --> PushImage["执行 docker push\n推送至远程仓库"]
PushImage --> ShowInfo["显示构建完成信息\n和镜像大小"]
CheckRegistry --> |否| ShowInfo
ShowInfo --> End([构建完成])
```
**Diagram sources**
- [alpine-base/build-base-image.sh](file://alpine-base/build-base-image.sh#L10-L11)
- [kami-gateway/build-base-image.sh](file://kami-gateway/build-base-image.sh#L10-L11)
- [kami-spider-monorepo/build-base-image.sh](file://kami-spider-monorepo/build-base-image.sh#L10-L12)
#### 模块间构建脚本对比
通过对三个模块的 `build-base-image.sh` 脚本进行对比，可以发现它们在核心逻辑上高度一致，但在细节上有所差异，以适应各自模块的需求。
| 特性 | alpine-base | kami-gateway | kami-spider-monorepo |
| :--- | :--- | :--- | :--- |
| **基础镜像名称** | `alpine-base` | `kami-gateway-base` | `kami-spider-base` |
| **默认 DOCKER_REGISTRY** | `git.oceanpay.cc/danial` | `git.oceanpay.cc/danial` | `localhost:5000` |
| **USE_PROXY 支持** | 否 | 否 | 是 |
| **构建参数 (build-arg)** | 无 | 无 | `USE_PROXY` |
| **用途** | 提供优化的 Alpine 基础环境 | 提供 Go 环境和 Alpine 运行时 | 提供包含 Python 依赖和 Playwright 的综合基础环境 |
此对比表明，`kami-spider-monorepo` 模块的构建脚本更为复杂，因为它需要处理网络代理问题，而其他两个模块的脚本则更侧重于基础环境的构建。
**Section sources**
- [alpine-base/build-base-image.sh](file://alpine-base/build-base-image.sh)
- [kami-gateway/build-base-image.sh](file://kami-gateway/build-base-image.sh)
- [kami-spider-monorepo/build-base-image.sh](file://kami-spider-monorepo/build-base-image.sh)
## 依赖分析
该构建系统的主要依赖是 Docker 引擎本身。脚本通过调用 `docker` CLI 命令与 Docker 守护进程进行交互。此外，构建过程依赖于每个模块根目录下的 `Dockerfile.base` 文件，该文件定义了镜像的具体构建步骤。`kami-spider-monorepo` 模块还依赖于 `pyproject.toml` 和 `uv.lock` 文件来管理其 Python 依赖。
```mermaid
graph LR
Script[build-base-image.sh] --> Docker[docker CLI]
Script --> Dockerfile[Dockerfile.base]
Script --> Env[环境变量]
Dockerfile --> BaseImage[基础操作系统镜像]
Docker --> Registry[Docker Registry]
```
**Diagram sources**
- [alpine-base/build-base-image.sh](file://alpine-base/build-base-image.sh)
- [kami-gateway/build-base-image.sh](file://kami-gateway/build-base-image.sh)
- [kami-spider-monorepo/build-base-image.sh](file://kami-spider-monorepo/build-base-image.sh)
## 性能考虑
构建过程的性能主要受网络带宽和 Docker 构建缓存的影响。`USE_PROXY=1` 环境变量的引入是针对中国地区网络环境的性能优化，通过代理加速依赖下载，显著缩短了构建时间。此外，Docker 的构建缓存机制可以极大地提升重复构建的效率。只要 `Dockerfile` 中的指令和上下文没有改变，Docker 就会重用之前的构建层，避免了不必要的重复工作。为了最大化利用缓存，建议在 `Dockerfile` 中将不常变动的指令（如安装系统包）放在前面，而将经常变动的指令（如复制应用代码）放在后面。
## 故障排除指南
当构建过程出现问题时，可以采取以下调试技巧：
1. **检查环境变量**：确保 `DOCKER_REGISTRY`、`VERSION` 等环境变量已正确设置。
2. **查看脚本输出**：脚本本身提供了详细的日志信息，包括正在执行的步骤和最终的镜像大小，这些信息有助于定位问题。
3. **手动执行命令**：可以复制脚本中的 `docker build`、`docker tag` 或 `docker push` 命令，在终端中手动执行，以获取更详细的错误信息。
4. **启用详细模式**：虽然当前脚本未使用 `set -x`，但可以在脚本开头添加此命令，以启用 Bash 的调试模式，逐行输出执行的命令，这对于追踪复杂的逻辑分支非常有用。
**Section sources**
- [alpine-base/build-base-image.sh](file://alpine-base/build-base-image.sh)
- [kami-gateway/build-base-image.sh](file://kami-gateway/build-base-image.sh)
- [kami-spider-monorepo/build-base-image.sh](file://kami-spider-monorepo/build-base-image.sh)
## 结论
`kami` 项目的构建体系通过标准化的 `build-base-image.sh` 脚本，实现了跨模块的构建自动化。该体系设计简洁、逻辑清晰，通过环境变量实现了良好的配置灵活性。`USE_PROXY` 变量的引入体现了对特定部署环境的考量。通过遵循本文档中总结的最佳实践，如合理利用构建缓存、正确设置环境变量和使用调试技巧，开发者可以高效、可靠地完成镜像构建任务，为项目的持续集成和部署（CI/CD）奠定坚实的基础。

206
.qoder/repowiki/zh/content/项目概述/alpine-base 模块.md Normal file
View File

@@ -0,0 +1,206 @@
# alpine-base 模块
<cite>
**Referenced Files in This Document**
- [README.md](file://alpine-base/README.md)
- [build-base-image.sh](file://alpine-base/build-base-image.sh)
- [Dockerfile.base](file://alpine-base/Dockerfile.base)
</cite>
## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心特性](#核心特性)
4. [架构设计](#架构设计)
5. [构建流程](#构建流程)
6. [使用方法](#使用方法)
7. [性能与安全](#性能与安全)
8. [结论](#结论)
## 简介
`alpine-base` 模块是一个优化的 Alpine Linux 基础镜像，专为各种容器化应用设计。该镜像基于 `alpine:latest`，通过配置中国镜像源、设置时区、创建非 root 用户和集成自定义证书等优化措施，提供了一个轻量、安全、网络优化的 Linux 运行时环境。预装的常用工具集（如 curl、wget、git、bash 等）显著提升了开发效率。该模块在微服务架构中扮演着基础支撑角色，为上层镜像提供一致且可靠的运行环境。
**Section sources**
- [README.md](file://alpine-base/README.md#L1-L70)
## 项目结构
`alpine-base` 模块包含以下核心文件：
- `Dockerfile.base`：定义基础镜像的 Dockerfile
- `build-base-image.sh`：用于构建和推送镜像的脚本
- `README.md`：模块的说明文档
这些文件共同构成了一个完整的镜像构建和管理解决方案，确保了镜像的一致性和可重复性。
```mermaid
graph TD
A[Dockerfile.base] --> B[基础镜像定义]
C[build-base-image.sh] --> D[构建与推送]
E[README.md] --> F[使用说明]
B --> G[alpine-base:latest]
D --> G
F --> G
```
**Diagram sources**
- [Dockerfile.base](file://alpine-base/Dockerfile.base#L1-L58)
- [build-base-image.sh](file://alpine-base/build-base-image.sh#L1-L51)
- [README.md](file://alpine-base/README.md#L1-L70)
**Section sources**
- [README.md](file://alpine-base/README.md#L5-L8)
## 核心特性
`alpine-base` 镜像具备以下核心特性：
### 基础环境
- **基础镜像**：基于最新的 `alpine:latest`，确保系统安全性和稳定性
- **镜像源**：配置阿里云中国镜像源，显著加速软件包下载速度
- **时区**：设置为 `Asia/Shanghai`，符合中国用户的时区需求
### 预装工具
- **网络工具**：预装 `curl`、`wget`、`git`，方便网络操作和代码管理
- **系统工具**：包含 `bash`、`tar`、`gzip`，提供基本的系统操作能力
- **证书管理**：集成 `ca-certificates` 和自定义证书，确保安全通信
- **包管理**：预装 `apk-tools`，便于后续软件包管理
### 用户配置
- **非 root 用户**：创建 `appuser` 用户（UID 1001），以非 root 权限运行应用，提升安全性
- **应用目录**：创建 `/app` 目录并设置正确的文件权限
- **安全权限**：所有文件和目录均设置为安全的权限配置
**Section sources**
- [README.md](file://alpine-base/README.md#L12-L27)
## 架构设计
`alpine-base` 的架构设计体现了分层继承和优化配置的理念。
### 分层继承机制
镜像基于 `alpine:latest` 进行构建，通过 Docker 的分层机制，每一层都添加特定的配置和工具。这种设计使得镜像构建过程清晰且可维护。
### 中国镜像源配置
通过修改 `/etc/apk/repositories` 文件，将 Alpine 的软件源替换为阿里云镜像源。这不仅加快了软件包的下载速度，还提高了构建的稳定性。
### 时区设置
通过设置 `TZ` 环境变量和复制时区文件，将系统时区设置为 `Asia/Shanghai`。这确保了容器内的时间与本地时间一致。
### 非 root 用户创建
使用 `addgroup` 和 `adduser` 命令创建 `appuser` 用户，并将其主目录设置为 `/app`。通过 `USER` 指令切换到该用户，确保应用以非 root 权限运行。
### 自定义证书集成
通过 `curl` 下载自定义证书并使用 `update-ca-certificates` 命令更新证书库，确保容器能够信任特定的证书颁发机构。
```mermaid
classDiagram
class AlpineBase {
+string base_image : alpine : latest
+string timezone : Asia/Shanghai
+string registry : git.oceanpay.cc/danial
+string user : appuser (UID : 1001)
+string workdir : /app
+list tools : [curl, wget, git, bash, ...]
+list certificates : [ca-certificates, custom.crt]
+build() : void
+push() : void
}
AlpineBase : --|> alpine : latest : inherits
AlpineBase : uses "阿里云镜像源" : configures
AlpineBase : creates "appuser" : user management
AlpineBase : installs "预装工具" : package management
AlpineBase : integrates "自定义证书" : security
```
**Diagram sources**
- [Dockerfile.base](file://alpine-base/Dockerfile.base#L4-L58)
**Section sources**
- [Dockerfile.base](file://alpine-base/Dockerfile.base#L4-L58)
- [README.md](file://alpine-base/README.md#L13-L15)
## 构建流程
`alpine-base` 的构建流程由 `build-base-image.sh` 脚本自动化完成。
### 构建脚本逻辑
1. **配置参数**：设置镜像名称、注册表和版本号
2. **构建镜像**：使用 `docker build` 命令基于 `Dockerfile.base` 构建镜像
3. **标记镜像**：为本地和远程注册表创建相应的标签
4. **推送镜像**：如果指定了远程注册表，则推送镜像
5. **显示信息**：输出构建完成的信息和镜像大小
### 环境变量
- `DOCKER_REGISTRY`：指定镜像推送的目标注册表，默认为 `git.oceanpay.cc/danial`
- `VERSION`：指定镜像版本，默认为 `latest`
```mermaid
flowchart TD
A[开始构建] --> B[读取环境变量]
B --> C{是否指定注册表?}
C --> |是| D[设置REGISTRY]
C --> |否| E[使用默认值]
D --> F[构建镜像]
E --> F
F --> G[标记本地镜像]
G --> H{是否远程注册表?}
H --> |是| I[标记远程镜像]
H --> |否| J[跳过]
I --> K[推送镜像]
J --> L[完成]
K --> L
L --> M[显示镜像信息]
```
**Diagram sources**
- [build-base-image.sh](file://alpine-base/build-base-image.sh#L1-L51)
**Section sources**
- [build-base-image.sh](file://alpine-base/build-base-image.sh#L1-L51)
- [README.md](file://alpine-base/README.md#L30-L37)
## 使用方法
### 本地构建与推送
```bash
# 构建基础镜像
./build-base-image.sh
# 推送到镜像仓库
DOCKER_REGISTRY=git.oceanpay.cc/danial ./build-base-image.sh
```
### 在应用 Dockerfile 中使用
```dockerfile
# 使用基础镜像
FROM git.oceanpay.cc/danial/alpine-base:latest
# 复制应用代码
COPY --chown=appuser:appuser . /app/
# 切换到非 root 用户
USER appuser
# 运行应用
CMD ["./your-app"]
```
**Section sources**
- [README.md](file://alpine-base/README.md#L39-L52)
## 性能与安全
### 性能优化
- **镜像缓存**：利用 Docker 的层缓存机制，避免重复下载和安装
- **精简安装**：使用 `--no-cache` 选项，减少镜像体积
- **并行构建**：在 CI/CD 中并行构建多个镜像
### 安全加固
- **非 root 运行**：应用以 `appuser` 用户身份运行，降低安全风险
- **最小权限**：只安装必要的工具和包
- **定期更新**：定期更新基础镜像和软件包
### CI/CD 集成
- **自动化构建**：在 CI/CD 流水线中自动构建和推送镜像
- **版本管理**：使用语义化版本号管理镜像版本
- **镜像扫描**：集成安全扫描工具，检测漏洞
**Section sources**
- [README.md](file://alpine-base/README.md#L62-L69)
## 结论
`alpine-base` 模块通过精心设计的架构和优化配置，为上层镜像提供了一个轻量、安全、高效的 Linux 运行时环境。其预装的工具集和中国镜像源配置显著提升了开发效率和构建速度。通过非 root 用户运行和自定义证书集成，确保了应用的安全性。该模块在微服务架构中扮演着基础支撑角色，为构建稳定可靠的容器化应用提供了坚实的基础。

150
.qoder/repowiki/zh/content/项目概述/kami-gateway 模块/CI_CD集成与自动化.md Normal file
View File

@@ -0,0 +1,150 @@
# CI/CD集成与自动化
<cite>
**Referenced Files in This Document**
- [build-base-image.sh](file://kami-gateway/build-base-image.sh)
- [README.md](file://kami-gateway/README.md)
- [build-base-image.sh](file://kami-spider-monorepo/build-base-image.sh)
- [build-base-image.sh](file://alpine-base/build-base-image.sh)
</cite>
## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构概述](#架构概述)
5. [详细组件分析](#详细组件分析)
6. [依赖分析](#依赖分析)
7. [性能考虑](#性能考虑)
8. [故障排除指南](#故障排除指南)
9. [结论](#结论)
## 简介
本文档全面介绍kami-gateway模块与Drone CI等持续集成系统的集成方案。文档解析了构建脚本中的环境变量控制逻辑，说明了如何实现条件化构建与镜像推送，阐述了变更检测机制如何避免不必要的镜像重建，展示了在CI流水线中如何安全地注入凭证并执行构建任务，并讨论了镜像标签策略的最佳实践。
## 项目结构
项目包含多个模块的构建脚本，每个模块都有独立的构建配置。kami-gateway模块作为重点分析对象，其构建流程代表了整个项目的CI/CD实践标准。
**Section sources**
- [build-base-image.sh](file://kami-gateway/build-base-image.sh#L1-L51)
- [README.md](file://kami-gateway/README.md#L1-L60)
## 核心组件
kami-gateway模块的核心构建组件是`build-base-image.sh`脚本，该脚本负责创建包含Go环境和Alpine运行时的基础Docker镜像。脚本实现了环境变量控制、条件构建、镜像标记和推送等关键功能。
**Section sources**
- [build-base-image.sh](file://kami-gateway/build-base-image.sh#L1-L51)
## 架构概述
kami-gateway的CI/CD架构基于Drone CI系统，通过变更检测机制触发条件化构建流程。构建脚本与CI系统协同工作，实现了高效的镜像构建和推送流程。
```mermaid
graph TB
subgraph "CI/CD Pipeline"
Trigger["变更检测\n(Drone CI)"] --> Condition["条件判断\n(目录变更)"]
Condition --> Build["执行构建\n(build-base-image.sh)"]
Build --> Push["镜像推送\n(Registry)"]
end
subgraph "构建脚本"
Env["环境变量控制\n(VERSION, DOCKER_REGISTRY)"] --> Build
Proxy["代理配置\n(USE_PROXY)"] --> Build
Tagging["镜像标记策略\n(latest, version)"] --> Build
end
Trigger --> Build
Build --> Push
```
**Diagram sources **
- [build-base-image.sh](file://kami-gateway/build-base-image.sh#L1-L51)
- [README.md](file://kami-gateway/README.md#L53-L60)
## 详细组件分析
### 构建脚本分析
kami-gateway的构建脚本实现了完整的CI/CD流程，包括环境变量配置、镜像构建、标记和推送等步骤。
#### 环境变量控制逻辑
```mermaid
flowchart TD
Start([开始]) --> Registry["REGISTRY=\n${DOCKER_REGISTRY:-git.oceanpay.cc/danial}"]
Registry --> Version["VERSION=\n${VERSION:-latest}"]
Version --> UseProxy["USE_PROXY=\n${USE_PROXY:-0}"]
UseProxy --> Build["执行docker build"]
Build --> ConditionalTag["条件标记\n(REGISTRY != localhost:5000)"]
ConditionalTag --> Push["条件推送\n(REGISTRY != localhost:5000)"]
Push --> End([完成])
```
**Diagram sources **
- [build-base-image.sh](file://kami-gateway/build-base-image.sh#L9-L11)
- [build-base-image.sh](file://kami-spider-monorepo/build-base-image.sh#L9-L12)
**Section sources**
- [build-base-image.sh](file://kami-gateway/build-base-image.sh#L1-L51)
#### CI/CD工作流程
```mermaid
sequenceDiagram
participant Drone as "Drone CI"
participant Script as "build-base-image.sh"
participant Docker as "Docker Engine"
participant Registry as "镜像仓库"
Drone->>Script : 检测到kami-gateway/目录变更
Script->>Script : 初始化环境变量
Script->>Docker : 执行docker build
Docker-->>Script : 返回构建结果
Script->>Script : 检查REGISTRY配置
alt 非本地仓库
Script->>Docker : 执行docker tag
Script->>Registry : 执行docker push
Registry-->>Script : 返回推送结果
end
Script->>Drone : 返回构建状态
```
**Diagram sources **
- [README.md](file://kami-gateway/README.md#L53-L60)
- [build-base-image.sh](file://kami-gateway/build-base-image.sh#L27-L39)
### 镜像标签策略
kami-gateway采用多标签策略，为每个构建版本创建两个标签：版本号标签和latest标签，确保既有版本追溯性又有最新版本可用性。
**Section sources**
- [build-base-image.sh](file://kami-gateway/build-base-image.sh#L21-L23)
## 依赖分析
各模块的构建脚本具有相似的结构和逻辑，表明项目采用了统一的构建标准。kami-gateway模块作为Go应用的代表，其构建流程为其他模块提供了参考模式。
```mermaid
graph TB
alpine-base --> kami-gateway
kami-gateway --> kami-spider-monorepo
common["通用构建模式"] --> alpine-base
common --> kami-gateway
common --> kami-spider-monorepo
```
**Diagram sources **
- [build-base-image.sh](file://alpine-base/build-base-image.sh#L1-L51)
- [build-base-image.sh](file://kami-gateway/build-base-image.sh#L1-L51)
- [build-base-image.sh](file://kami-spider-monorepo/build-base-image.sh#L1-L54)
**Section sources**
- [build-base-image.sh](file://alpine-base/build-base-image.sh#L1-L51)
- [build-base-image.sh](file://kami-gateway/build-base-image.sh#L1-L51)
- [build-base-image.sh](file://kami-spider-monorepo/build-base-image.sh#L1-L54)
## 性能考虑
通过条件化构建和变更检测机制，系统避免了不必要的镜像重建，显著提升了资源利用率。基础镜像缓存机制将应用构建时间缩短至10-30秒，Go模块预下载避免了重复下载，多阶段构建优化了最终镜像体积。
**Section sources**
- [README.md](file://kami-gateway/README.md#L47-L52)
## 故障排除指南
当CI/CD流程出现问题时，应首先检查环境变量配置是否正确，特别是DOCKER_REGISTRY和VERSION变量。确认变更检测机制是否正常工作，检查构建脚本的条件判断逻辑是否按预期执行。
**Section sources**
- [build-base-image.sh](file://kami-gateway/build-base-image.sh#L27-L39)
## 结论
kami-gateway模块的CI/CD集成方案展示了高效的自动化构建实践。通过环境变量控制、条件化构建、变更检测和多标签策略，系统实现了资源高效利用和版本可追溯性的平衡。该方案可作为其他模块的参考模板，并可根据需要扩展支持多平台构建和自动化安全扫描等高级功能。

169
.qoder/repowiki/zh/content/项目概述/kami-gateway 模块/Go依赖管理.md Normal file
View File

@@ -0,0 +1,169 @@
# Go依赖管理
<cite>
**Referenced Files in This Document**
- [go.mod](file://kami-gateway/go.mod)
- [go.sum](file://kami-gateway/go.sum)
- [Dockerfile.base](file://kami-gateway/Dockerfile.base)
- [build-base-image.sh](file://kami-gateway/build-base-image.sh)
- [README.md](file://kami-gateway/README.md)
</cite>
## 目录
1. [引言](#引言)
2. [项目结构](#项目结构)
3. [核心依赖分析](#核心依赖分析)
4. [依赖版本锁定机制](#依赖版本锁定机制)
5. [Docker构建优化策略](#docker构建优化策略)
6. [预下载依赖的优势](#预下载依赖的优势)
7. [常见问题解决方案](#常见问题解决方案)
8. [依赖升级与兼容性验证](#依赖升级与兼容性验证)
9. [结论](#结论)
## 引言
本文档深入解析kami-gateway模块的Go依赖管理体系，重点阐述基于go.mod和go.sum文件的依赖版本锁定机制与可重现构建的重要性。通过分析Docker构建过程中预下载依赖（go mod download）的实践，说明其如何消除构建时的网络不确定性并大幅提升CI/CD效率。同时对比直接在运行时下载依赖的模式，分析预下载方案在稳定性、安全性和性能方面的优势，并提供常见问题的解决方案。
## 项目结构
kami-gateway模块采用标准的Go项目结构，包含go.mod和go.sum文件用于依赖管理，以及Docker相关文件用于容器化构建。项目通过Docker多阶段构建实现高效的CI/CD流程。
```mermaid
graph TD
A[项目根目录] --> B[go.mod]
A --> C[go.sum]
A --> D[Dockerfile.base]
A --> E[build-base-image.sh]
A --> F[README.md]
```
**Diagram sources**
- [go.mod](file://kami-gateway/go.mod)
- [go.sum](file://kami-gateway/go.sum)
- [Dockerfile.base](file://kami-gateway/Dockerfile.base)
**Section sources**
- [README.md](file://kami-gateway/README.md)
## 核心依赖分析
kami-gateway模块依赖多个关键的第三方库，这些库在API网关场景下发挥着重要作用：
- **beego/beego/v2**: Web框架，提供路由、MVC架构等基础功能
- **bytedance/sonic**: 高性能JSON序列化库，提升API数据处理效率
- **go.opentelemetry.io/otel**: 分布式追踪和监控框架，实现服务可观测性
- **redis/go-redis/v9**: Redis客户端，用于缓存和会话管理
- **go-resty/resty/v2**: HTTP客户端，简化外部API调用
这些依赖通过go.mod文件明确声明，确保了依赖关系的清晰和可管理性。
**Section sources**
- [go.mod](file://kami-gateway/go.mod#L7-L39)
## 依赖版本锁定机制
Go模块系统通过go.mod和go.sum文件实现依赖版本的精确锁定和完整性验证。
go.mod文件定义了项目直接依赖的模块及其版本，例如：
- github.com/beego/beego/v2 v2.3.8
- github.com/bytedance/sonic v1.14.2
- go.opentelemetry.io/otel v1.38.0
go.sum文件则记录了每个依赖模块的校验和，确保下载的依赖包未被篡改。这种双重锁定机制保证了构建的可重现性，无论在何种环境下构建，都能获得完全相同的依赖版本和内容。
可重现构建对于生产环境至关重要，它消除了"在我机器上能运行"的问题，确保开发、测试和生产环境的一致性。
**Section sources**
- [go.mod](file://kami-gateway/go.mod)
- [go.sum](file://kami-gateway/go.sum)
## Docker构建优化策略
kami-gateway采用创新的Docker构建策略，通过预下载依赖大幅提升构建效率。
在Dockerfile.base中，关键步骤包括：
1. 复制go.mod和go.sum文件
2. 执行`go mod download`预下载所有依赖
3. 构建应用时直接使用已缓存的依赖
这种策略将依赖下载与应用构建分离，实现了构建缓存的最大化利用。当应用代码变更时，Docker只需重新构建应用层，而无需重新下载可能耗时的依赖包。
```mermaid
sequenceDiagram
participant Dev as 开发者
participant Docker as Docker构建
participant Proxy as GOPROXY
Dev->>Docker : 提交代码变更
Docker->>Docker : 检查Dockerfile变更
alt 依赖未变更
Docker->>Docker : 使用缓存的依赖层
Docker->>Docker : 快速构建应用
Docker-->>Dev : 10-30秒完成构建
else 依赖变更
Docker->>Proxy : 下载新依赖
Proxy-->>Docker : 返回依赖包
Docker->>Docker : 构建新依赖层
Docker->>Docker : 构建应用
Docker-->>Dev : 完成构建
end
```
**Diagram sources**
- [Dockerfile.base](file://kami-gateway/Dockerfile.base#L50-L55)
- [build-base-image.sh](file://kami-gateway/build-base-image.sh)
## 预下载依赖的优势
预下载依赖方案相比直接在运行时下载依赖具有显著优势：
### 稳定性优势
- 消除网络波动对构建过程的影响
- 避免因依赖仓库临时不可用导致的构建失败
- 通过go mod verify确保依赖完整性
### 安全性优势
- 所有依赖经过预先验证和审核
- 减少构建时对外部网络的依赖，降低攻击面
- 可以在隔离环境中完成依赖下载和验证
### 性能优势
- 应用构建时间从分钟级缩短至10-30秒
- CI/CD流水线执行效率大幅提升
- 资源利用率更高，减少构建节点的负载
这种优化使得开发者能够更快地获得反馈，加速迭代周期。
**Section sources**
- [Dockerfile.base](file://kami-gateway/Dockerfile.base#L54)
- [README.md](file://kami-gateway/README.md#L49-L51)
## 常见问题解决方案
### 依赖冲突处理
当出现依赖版本冲突时，可以使用go mod tidy命令自动解决，或手动在go.mod中使用replace指令指定特定版本。
### 私有模块拉取配置
通过设置GOPRIVATE环境变量，可以配置哪些模块为私有模块，避免通过公共代理下载：
```bash
ENV GOPRIVATE=git.oceanpay.cc/*
```
### 校验和不匹配错误
当go.sum中记录的校验和与实际下载的包不匹配时，可能是依赖包被篡改或缓存损坏。解决方案包括：
1. 执行`go clean -modcache`清除模块缓存
2. 重新执行`go mod download`
3. 检查网络代理是否返回了正确的包
**Section sources**
- [Dockerfile.base](file://kami-gateway/Dockerfile.base#L9)
- [go.sum](file://kami-gateway/go.sum)
## 依赖升级与兼容性验证
安全地升级依赖版本需要遵循以下步骤：
1. 使用`go get -u`命令升级特定依赖
2. 运行`go mod tidy`清理未使用的依赖
3. 执行完整的测试套件验证功能兼容性
4. 检查性能基准是否有显著变化
5. 在预发布环境进行充分验证
对于关键依赖如OpenTelemetry、beego等，建议密切关注其发布说明，了解可能的破坏性变更。
**Section sources**
- [go.mod](file://kami-gateway/go.mod)
## 结论
kami-gateway模块通过科学的Go依赖管理实践，实现了高效、稳定和安全的构建流程。基于go.mod和go.sum的版本锁定机制确保了可重现构建，而Docker预下载依赖策略则大幅提升了CI/CD效率。这种架构设计不仅优化了开发体验，也为生产环境的稳定性提供了坚实保障。建议持续遵循最佳实践，定期审查和更新依赖，保持系统的安全性和性能。

203
.qoder/repowiki/zh/content/项目概述/kami-gateway 模块/kami-gateway 模块.md Normal file
View File

@@ -0,0 +1,203 @@
# kami-gateway 模块
<cite>
**本文档引用文件**
- [Dockerfile.base](file://kami-gateway/Dockerfile.base)
- [build-base-image.sh](file://kami-gateway/build-base-image.sh)
- [go.mod](file://kami-gateway/go.mod)
- [go.sum](file://kami-gateway/go.sum)
- [README.md](file://kami-gateway/README.md)
</cite>
## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构概述](#架构概述)
5. [详细组件分析](#详细组件分析)
6. [依赖分析](#依赖分析)
7. [性能考量](#性能考量)
8. [故障排除指南](#故障排除指南)
9. [结论](#结论)
## 简介
kami-gateway 模块提供了一个专为 Go 语言网关服务设计的基础 Docker 镜像，旨在优化构建效率、提升安全性并简化部署流程。该模块通过预配置的编译环境和依赖缓存机制，显著缩短了应用构建时间（10-30秒），适用于 API 网关类微服务的快速迭代与发布。
## 项目结构
kami-gateway 模块包含构建基础镜像所需的核心文件，组织清晰，职责明确：
```
kami-gateway/
├── README.md # 模块说明文档
├── build-base-image.sh # 基础镜像构建脚本
├── go.mod # Go 依赖管理文件
├── go.sum # 依赖校验文件
├── Dockerfile.base # 基础镜像定义
└── Dockerfile.improved # 改进版应用镜像定义（引用）
```
**Section sources**
- [README.md](file://kami-gateway/README.md#L1-L60)
## 核心组件
本模块的核心在于 `Dockerfile.base` 和 `build-base-image.sh` 脚本的协同工作，前者定义了包含 Go 1.25 编译环境和 Alpine 运行时的基础镜像，后者则封装了镜像构建、标记与推送的完整流程。
**Section sources**
- [Dockerfile.base](file://kami-gateway/Dockerfile.base#L1-L59)
- [build-base-image.sh](file://kami-gateway/build-base-image.sh#L1-L51)
## 架构概述
kami-gateway 的架构围绕“基础镜像预构建 + 应用镜像快速构建”的理念展开。基础镜像预先集成了 Go 编译环境、中国镜像源、时区、证书及依赖包，使得后续的应用镜像构建只需专注于业务代码编译，从而实现极速构建。
```mermaid
graph TB
subgraph "基础镜像构建"
A[Dockerfile.base] --> B[Go 1.25 Alpine]
B --> C[配置环境变量]
C --> D[安装系统依赖]
D --> E[下载自定义证书]
E --> F[创建非root用户]
F --> G[预下载Go依赖]
G --> H[kami-gateway-base:latest]
end
subgraph "应用镜像构建"
I[Dockerfile.improved] --> J[多阶段构建]
J --> K[使用kami-gateway-base作为基础]
K --> L[编译Go应用]
L --> M[生成轻量运行镜像]
end
H --> K
```
**Diagram sources**
- [Dockerfile.base](file://kami-gateway/Dockerfile.base#L1-L59)
- [README.md](file://kami-gateway/README.md#L7-L8)
## 详细组件分析
### Dockerfile.base 实现细节
`Dockerfile.base` 是构建 kami-gateway 基础镜像的核心。它从 `golang:1.25-alpine` 镜像开始，通过一系列优化步骤构建出一个高效、安全的编译环境。
#### 环境与依赖配置
该文件设置了关键的 Go 环境变量，包括 `GO111MODULE=on` 启用模块化管理，`GOPROXY=https://goproxy.cn,direct` 配置国内代理以加速依赖下载，以及 `CGO_ENABLED=0` 确保生成静态链接的二进制文件。
#### 系统优化
使用阿里云的 Alpine 镜像源替换默认源，显著提升 `apk` 包管理器的下载速度。同时，预装了 `tzdata` 并设置时区为 `Asia/Shanghai`，避免了应用运行时的时区问题。
#### 安全与证书
创建了 UID 为 1001 的非 root 用户 `appuser`，并在后续步骤中切换至此用户，遵循最小权限原则。此外，通过 `curl` 下载并安装了 Comodo AAA 证书，解决了某些网络环境下可能出现的证书信任问题。
#### 依赖预下载
通过 `COPY go.mod go.sum* ./` 和 `RUN go mod download && go mod verify` 命令，将依赖下载和验证步骤前置到基础镜像中。这使得所有基于此镜像构建的应用都能跳过耗时的依赖拉取过程，直接进入代码编译阶段。
```mermaid
flowchart TD
Start([开始构建]) --> BaseImage["FROM golang:1.25-alpine"]
BaseImage --> Env["设置环境变量<br/>GOPROXY, CGO_ENABLED等"]
Env --> Repos["配置Alpine镜像源<br/>阿里云"]
Repos --> Install["安装系统依赖<br/>tzdata, curl, git"]
Install --> Cert["下载并安装<br/>Comodo AAA证书"]
Cert --> User["创建非root用户<br/>appuser"]
User --> Workdir["创建工作目录<br/>/app"]
Workdir --> SwitchUser["切换到appuser"]
SwitchUser --> CopyMod["复制go.mod/go.sum"]
CopyMod --> Download["预下载Go依赖<br/>go mod download"]
Download --> Label["添加镜像标签"]
Label --> End([基础镜像构建完成])
```
**Diagram sources**
- [Dockerfile.base](file://kami-gateway/Dockerfile.base#L1-L59)
**Section sources**
- [Dockerfile.base](file://kami-gateway/Dockerfile.base#L1-L59)
### build-base-image.sh 脚本分析
该脚本自动化了基础镜像的构建、标记和推送流程，是实现 CI/CD 集成的关键。
#### 环境变量控制
脚本通过 `REGISTRY="${DOCKER_REGISTRY:-git.oceanpay.cc/danial}"` 和 `VERSION="${VERSION:-latest}"` 读取环境变量，允许用户在调用时动态指定镜像仓库地址和版本标签。若未指定，则使用默认值。
#### 构建与标记
使用 `docker build` 命令，基于 `Dockerfile.base` 构建镜像，并同时打上 `$VERSION` 和 `latest` 两个标签。如果指定了非本地仓库（`REGISTRY` 不为 `localhost:5000`），则会使用 `docker tag` 命令为镜像添加仓库前缀。
#### 推送逻辑
脚本包含条件推送逻辑：只有当 `REGISTRY` 不是 `localhost:5000` 时，才会执行 `docker push` 将镜像推送到远程仓库。这避免了在本地开发测试时不必要的网络操作。
```mermaid
flowchart LR
A[开始] --> B{读取环境变量<br/>DOCKER_REGISTRY, VERSION}
B --> C[构建基础镜像<br/>docker build]
C --> D{REGISTRY != localhost:5000?}
D --> |是| E[标记镜像<br/>docker tag]
D --> |否| F[跳过标记]
E --> G[推送镜像<br/>docker push]
F --> H[完成]
G --> H
H --> I[显示镜像大小]
```
**Diagram sources**
- [build-base-image.sh](file://kami-gateway/build-base-image.sh#L1-L51)
**Section sources**
- [build-base-image.sh](file://kami-gateway/build-base-image.sh#L1-L51)
### 依赖管理分析
`go.mod` 文件定义了 kami-gateway 基础镜像所预下载的所有 Go 依赖。这些依赖涵盖了 Web 框架（beego）、JSON 处理（sonic）、数据库驱动（mysql）、Redis 客户端（go-redis）、OpenTelemetry 监控、日志（zap）等网关服务常用组件。
#### 最佳实践
- **明确指定 Go 版本**：`go 1.24.0` 和 `toolchain go1.24.6` 确保了构建环境的一致性。
- **区分直接与间接依赖**：`require` 块清晰地分开了项目直接依赖和间接依赖，便于维护。
- **使用国内代理**：`GOPROXY=https://goproxy.cn,direct` 的配置在 `Dockerfile.base` 中生效，极大提升了依赖下载速度。
**Section sources**
- [go.mod](file://kami-gateway/go.mod#L1-L82)
### Dockerfile.improved 多阶段构建
虽然 `Dockerfile.improved` 未在当前上下文中提供完整内容，但根据 `README.md` 的描述，它采用了多阶段构建策略。
#### 优化原理
第一阶段使用 `kami-gateway-base:latest` 作为基础镜像进行代码编译，利用其预下载的依赖和完整的 Go 环境。第二阶段则使用一个极小的运行时镜像（如 `alpine` 或 `scratch`），仅将第一阶段编译出的二进制文件复制进去。这种方式将最终镜像体积降至最低，同时保证了构建速度。
**Section sources**
- [README.md](file://kami-gateway/README.md#L8-L9)
## 依赖分析
kami-gateway 模块的依赖关系清晰，主要依赖于 Go 官方镜像和 Alpine Linux 发行版。其内部组件通过 `Dockerfile.base` 和 `build-base-image.sh` 协同工作，形成一个自包含的构建单元。
```mermaid
graph TD
A[kami-gateway] --> B[golang:1.25-alpine]
A --> C[Alpine Linux]
A --> D[阿里云镜像源]
A --> E[Comodo AAA证书]
B --> F[Go 1.25工具链]
C --> G[轻量级Linux内核]
D --> H[加速apk包下载]
E --> I[解决证书信任]
```
**Diagram sources**
- [Dockerfile.base](file://kami-gateway/Dockerfile.base#L4-L34)
**Section sources**
- [Dockerfile.base](file://kami-gateway/Dockerfile.base#L1-L59)
## 性能考量
kami-gateway 模块在性能方面进行了多项优化：
- **构建速度**：通过预下载 Go 依赖，将应用构建时间从分钟级缩短至 10-30 秒。
- **镜像体积**：基于 Alpine Linux 和多阶段构建，确保最终运行镜像尽可能小。
- **网络效率**：使用国内镜像源和代理，减少网络延迟。
## 故障排除指南
- **构建失败**：检查 `go.mod` 文件是否正确，确保所有依赖均可通过 `goproxy.cn` 下载。
- **推送失败**：确认 `DOCKER_REGISTRY` 环境变量设置正确，并且已登录到目标镜像仓库。
- **证书错误**：若遇到 HTTPS 证书问题，可检查 `Dockerfile.base` 中的证书下载 URL 是否有效。
**Section sources**
- [build-base-image.sh](file://kami-gateway/build-base-image.sh#L35-L39)
- [Dockerfile.base](file://kami-gateway/Dockerfile.base#L33-L34)
## 结论
kami-gateway 模块通过精心设计的 `Dockerfile.base` 和 `build-base-image.sh` 脚本，成功构建了一个高效、安全、易用的 Go 语言网关服务基础镜像。其预下载依赖、国内镜像源、非 root 用户运行等特性，不仅显著提升了构建效率，也增强了应用的安全性。结合 Drone CI 的自动化构建流程，该模块为 API 网关微服务的持续集成与交付提供了坚实的基础。

247
.qoder/repowiki/zh/content/项目概述/kami-gateway 模块/基础镜像构建.md Normal file
View File

@@ -0,0 +1,247 @@
# 基础镜像构建
<cite>
**Referenced Files in This Document**
- [Dockerfile.base](file://kami-gateway/Dockerfile.base)
- [build-base-image.sh](file://kami-gateway/build-base-image.sh)
- [go.mod](file://kami-gateway/go.mod)
- [alpine-base/build-base-image.sh](file://alpine-base/build-base-image.sh)
- [alpine-base/README.md](file://alpine-base/README.md)
- [kami-gateway/README.md](file://kami-gateway/README.md)
</cite>
## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构概述](#架构概述)
5. [详细组件分析](#详细组件分析)
6. [依赖分析](#依赖分析)
7. [性能考虑](#性能考虑)
8. [故障排除指南](#故障排除指南)
9. [结论](#结论)
## 简介
本文档详细说明了 `kami-gateway` 模块中 `Dockerfile.base` 的构建逻辑，重点描述如何基于 `alpine-base` 创建轻量级 Go 1.25 编译环境。文档涵盖了多阶段构建策略、goproxy.cn 代理配置机制、动态镜像标签生成与私有仓库推送等关键技术点，为开发者提供完整的构建指导和最佳实践。
## 项目结构
项目结构清晰地组织了不同模块的基础镜像构建文件，包括 `alpine-base`、`kami-gateway` 和 `kami-spider-monorepo` 三个主要目录，每个目录包含相应的构建脚本和配置文件。
```mermaid
graph TD
A[项目根目录] --> B[alpine-base]
A --> C[kami-gateway]
A --> D[kami-spider-monorepo]
B --> B1[Dockerfile.base]
B --> B2[build-base-image.sh]
B --> B3[README.md]
C --> C1[Dockerfile.base]
C --> C2[build-base-image.sh]
C --> C3[go.mod]
C --> C4[go.sum]
C --> C5[README.md]
D --> D1[build-base-image.sh]
D --> D2[pyproject.toml]
D --> D3[uv.lock]
D --> D4[README.md]
```
**Diagram sources**
- [alpine-base/README.md](file://alpine-base/README.md)
- [kami-gateway/README.md](file://kami-gateway/README.md)
**Section sources**
- [alpine-base/README.md](file://alpine-base/README.md#L1-L70)
- [kami-gateway/README.md](file://kami-gateway/README.md#L1-L60)
## 核心组件
`kami-gateway` 模块的核心组件包括 `Dockerfile.base` 和 `build-base-image.sh` 脚本，它们共同实现了轻量级 Go 编译环境的构建和部署。
**Section sources**
- [Dockerfile.base](file://kami-gateway/Dockerfile.base#L1-L59)
- [build-base-image.sh](file://kami-gateway/build-base-image.sh#L1-L51)
## 架构概述
`kami-gateway` 基础镜像采用多阶段构建策略，分离构建依赖与运行时环境，显著减小最终镜像体积。架构设计充分利用了 Alpine Linux 的轻量化特性，并通过预配置优化了中国网络环境下的依赖下载速度。
```mermaid
graph TD
A[基础镜像构建] --> B[Go 1.25 环境]
A --> C[Alpine 运行时]
A --> D[中国镜像源]
A --> E[非 root 用户]
B --> F[Go 模块预下载]
C --> G[轻量级容器]
D --> H[goproxy.cn 代理]
E --> I[appuser 用户]
F --> J[快速构建]
G --> K[小体积镜像]
H --> L[加速依赖下载]
I --> M[安全运行]
```
**Diagram sources**
- [Dockerfile.base](file://kami-gateway/Dockerfile.base#L4-L59)
- [build-base-image.sh](file://kami-gateway/build-base-image.sh#L1-L51)
## 详细组件分析
### Dockerfile.base 分析
`Dockerfile.base` 定义了 `kami-gateway` 应用的基础镜像，基于 `golang:1.25-alpine` 构建，包含 Go 1.25 编译环境和 Alpine 运行时。
#### 多阶段构建策略
```mermaid
flowchart TD
Start([开始构建]) --> BaseImage["FROM golang:1.25-alpine"]
BaseImage --> EnvSetup["设置环境变量"]
EnvSetup --> MirrorConfig["配置中国镜像源"]
MirrorConfig --> InstallDeps["安装依赖包"]
InstallDeps --> CertSetup["下载自定义证书"]
CertSetup --> UserSetup["创建非 root 用户"]
UserSetup --> AppDir["创建应用目录"]
AppDir --> SwitchUser["切换到 appuser 用户"]
SwitchUser --> SetWorkDir["设置工作目录 /app"]
SetWorkDir --> CopyGoMod["复制 go.mod 和 go.sum"]
CopyGoMod --> DownloadDeps["预下载 Go 依赖"]
DownloadDeps --> LabelImage["标记镜像信息"]
LabelImage --> End([基础镜像构建完成])
```
**Diagram sources**
- [Dockerfile.base](file://kami-gateway/Dockerfile.base#L4-L59)
**Section sources**
- [Dockerfile.base](file://kami-gateway/Dockerfile.base#L1-L59)
#### 环境变量配置
`Dockerfile.base` 中配置了多个关键环境变量，确保构建环境的一致性和可重复性：
| 环境变量 | 值 | 说明 |
|---------|-----|------|
| TZ | Asia/Shanghai | 设置时区为上海 |
| GO111MODULE | on | 启用 Go 模块 |
| GOPROXY | https://goproxy.cn,direct | 配置中国代理 |
| CGO_ENABLED | 0 | 禁用 CGO |
| GOOS | linux | 目标操作系统 |
| GOARCH | amd64 | 目标架构 |
**Section sources**
- [Dockerfile.base](file://kami-gateway/Dockerfile.base#L7-L12)
### build-base-image.sh 脚本分析
`build-base-image.sh` 脚本实现了基础镜像的自动化构建、标记和推送流程。
#### 动态镜像标签生成
```mermaid
sequenceDiagram
participant User as 用户
participant Script as build-base-image.sh
participant Docker as Docker Engine
User->>Script : 执行脚本
Script->>Script : 读取 DOCKER_REGISTRY 和 VERSION 环境变量
Script->>Script : 设置镜像名称和版本
Script->>Docker : docker build --tag ...
Docker-->>Script : 返回构建结果
Script->>Script : 判断是否需要推送
Script->>Docker : docker tag ...
Script->>Docker : docker push ...
Docker-->>Script : 返回推送结果
Script->>User : 显示构建完成信息和镜像大小
```
**Diagram sources**
- [build-base-image.sh](file://kami-gateway/build-base-image.sh#L1-L51)
**Section sources**
- [build-base-image.sh](file://kami-gateway/build-base-image.sh#L1-L51)
#### 构建流程说明
1. **环境准备**：脚本首先设置 `set -e` 确保任何命令失败时立即退出
2. **变量配置**：定义 `BASE_IMAGE_NAME`、`REGISTRY` 和 `VERSION` 变量
3. **镜像构建**：使用 `docker build` 命令构建基础镜像
4. **标签处理**：为镜像创建版本标签和 latest 标签
5. **推送注册表**：如果指定了非本地注册表，则推送镜像
6. **结果展示**：显示构建完成信息和镜像大小
**Section sources**
- [build-base-image.sh](file://kami-gateway/build-base-image.sh#L1-L51)
## 依赖分析
`kami-gateway` 基础镜像的依赖关系清晰，通过 `go.mod` 文件管理所有 Go 依赖包。
```mermaid
erDiagram
DOCKERFILE_BASE {
string FROM
string ENV
string RUN
string COPY
string USER
string WORKDIR
string LABEL
}
GO_MOD {
string module
string go
string toolchain
string require
}
BUILD_SCRIPT {
string BASE_IMAGE_NAME
string REGISTRY
string VERSION
string docker_build
string docker_tag
string docker_push
}
DOCKERFILE_BASE ||--o{ GO_MOD : "复制"
DOCKERFILE_BASE ||--o{ BUILD_SCRIPT : "构建"
BUILD_SCRIPT }|--|| DOCKERFILE_BASE : "使用"
```
**Diagram sources**
- [Dockerfile.base](file://kami-gateway/Dockerfile.base#L1-L59)
- [go.mod](file://kami-gateway/go.mod#L1-L82)
- [build-base-image.sh](file://kami-gateway/build-base-image.sh#L1-L51)
**Section sources**
- [go.mod](file://kami-gateway/go.mod#L1-L82)
## 性能考虑
`kami-gateway` 基础镜像在性能方面进行了多项优化：
1. **构建时间优化**：通过预下载 Go 依赖包，应用构建时间缩短至 10-30 秒
2. **镜像体积优化**：基于 Alpine Linux，最终镜像体积小
3. **网络性能优化**：使用中国镜像源和 goproxy.cn 代理，显著提升依赖下载速度
4. **缓存利用**：基础镜像缓存，避免重复构建
**Section sources**
- [kami-gateway/README.md](file://kami-gateway/README.md#L47-L52)
## 故障排除指南
### 常见问题及解决方案
| 问题现象 | 可能原因 | 解决方案 |
|--------|--------|--------|
| 依赖下载缓慢 | 未使用中国镜像源 | 确认 `GOPROXY` 设置为 `https://goproxy.cn,direct` |
| 构建失败 | 网络连接问题 | 检查网络连接，尝试使用代理 |
| 镜像推送失败 | 注册表认证问题 | 确认 Docker 已登录目标注册表 |
| 证书验证失败 | 自定义证书未正确安装 | 检查证书下载和更新命令 |
| 权限错误 | 未正确切换用户 | 确认 `USER appuser` 命令已执行 |
**Section sources**
- [Dockerfile.base](file://kami-gateway/Dockerfile.base#L33-L34)
- [build-base-image.sh](file://kami-gateway/build-base-image.sh#L35-L39)
### 本地测试流程
1. **环境准备**：确保已安装 Docker 和必要的构建工具
2. **克隆代码**：获取 `kami-gateway` 仓库代码
3. **构建镜像**：执行 `./build-base-image.sh`
4. **验证镜像**：使用 `docker images` 查看镜像信息
5. **测试运行**：创建测试容器验证基础环境
**Section sources**
- [build-base-image.sh](file://kami-gateway/build-base-image.sh#L1-L51)
## 结论
`kami-gateway` 的 `Dockerfile.base` 通过多阶段构建策略、中国网络环境优化和安全配置，成功创建了一个轻量级、高性能的 Go 1.25 编译环境。`build-base-image.sh` 脚本实现了自动化构建和部署，为团队提供了高效的开发体验。该基础镜像设计合理，性能优越，是微服务架构中理想的构建基础。

194
.qoder/repowiki/zh/content/项目概述/kami-gateway 模块/应用镜像构建指南.md Normal file
View File

@@ -0,0 +1,194 @@
# 应用镜像构建指南
<cite>
**本文档中引用的文件**
- [Dockerfile.base](file://kami-gateway/Dockerfile.base)
- [build-base-image.sh](file://kami-gateway/build-base-image.sh)
- [go.mod](file://kami-gateway/go.mod)
- [go.sum](file://kami-gateway/go.sum)
- [README.md](file://kami-gateway/README.md)
</cite>
## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构概述](#架构概述)
5. [详细组件分析](#详细组件分析)
6. [依赖分析](#依赖分析)
7. [性能考虑](#性能考虑)
8. [故障排除指南](#故障排除指南)
9. [结论](#结论)
## 简介
本文档提供从 `kami-gateway-base` 基础镜像到实际 API 网关服务镜像的完整构建指南。涵盖如何在应用项目的 Dockerfile 中继承基础镜像，复用预置的 Go 编译环境与依赖缓存以实现极速构建，以及多阶段构建、运行时配置、安全实践等最佳实践。
## 项目结构
`kami-gateway` 目录包含构建基础镜像所需的核心文件，包括 Dockerfile、构建脚本和 Go 模块配置。该基础镜像专为 Go 应用设计，预置了编译环境和依赖，旨在加速应用镜像的构建过程。
```mermaid
graph TD
A[kami-gateway/] --> B[Dockerfile.base]
A --> C[build-base-image.sh]
A --> D[go.mod]
A --> E[go.sum]
A --> F[README.md]
```
**图示来源**
- [Dockerfile.base](file://kami-gateway/Dockerfile.base)
- [build-base-image.sh](file://kami-gateway/build-base-image.sh)
- [README.md](file://kami-gateway/README.md)
**章节来源**
- [README.md](file://kami-gateway/README.md)
## 核心组件
`kami-gateway` 基础镜像的核心组件包括：基于 `golang:1.25-alpine` 的编译环境、预下载的 Go 依赖包、中国镜像源配置、时区与证书设置，以及非 root 用户运行支持。这些组件共同实现了快速、安全、可复用的构建基础。
**章节来源**
- [Dockerfile.base](file://kami-gateway/Dockerfile.base#L1-L59)
- [go.mod](file://kami-gateway/go.mod#L1-L82)
- [README.md](file://kami-gateway/README.md#L34-L40)
## 架构概述
`kami-gateway` 的镜像构建采用分层架构。基础镜像（`kami-gateway-base`）封装了通用的 Go 编译环境和依赖。应用镜像则通过 `FROM` 指令继承此基础镜像，在此基础上编译应用代码并进行运行时配置，最终形成一个轻量、安全的生产级镜像。
```mermaid
graph LR
subgraph "应用镜像构建阶段"
A[应用代码] --> B[Dockerfile.improved]
B --> C[编译二进制]
C --> D[精简运行时镜像]
end
subgraph "基础镜像层"
E[golang:1.25-alpine] --> F[kami-gateway-base]
F --> |继承| B
end
style F fill:#f9f,stroke:#333
style D fill:#bbf,stroke:#333
```
**图示来源**
- [Dockerfile.base](file://kami-gateway/Dockerfile.base#L4-L59)
- [README.md](file://kami-gateway/README.md#L7-L8)
## 详细组件分析
### 基础镜像构建分析
`Dockerfile.base` 定义了 `kami-gateway-base` 镜像的构建过程。它从官方 Go 镜像开始，优化了国内网络环境下的依赖下载，并预下载了所有 Go 模块，从而在应用构建阶段避免了耗时的 `go mod download` 步骤。
```mermaid
flowchart TD
Start([开始]) --> SetEnv["设置环境变量<br/>GO111MODULE=on<br/>GOPROXY=https://goproxy.cn"]
SetEnv --> ConfigureAlpine["配置 Alpine 镜像源<br/>使用阿里云镜像"]
ConfigureAlpine --> InstallDeps["安装系统依赖<br/>tzdata, ca-certificates, git"]
InstallDeps --> SetupTimezone["设置时区为 Asia/Shanghai"]
SetupTimezone --> AddCerts["添加自定义证书"]
AddCerts --> CreateUser["创建非 root 用户 appuser"]
CreateUser --> CreateAppDir["创建应用目录 /app"]
CreateAppDir --> SwitchUser["切换到 appuser 用户"]
SwitchUser --> CopyGoFiles["复制 go.mod 和 go.sum"]
CopyGoFiles --> PreDownload["预下载 Go 依赖<br/>go mod download && verify"]
PreDownload --> LabelImage["为镜像添加标签"]
LabelImage --> End([基础镜像构建完成])
```
**图示来源**
- [Dockerfile.base](file://kami-gateway/Dockerfile.base#L1-L59)
**章节来源**
- [Dockerfile.base](file://kami-gateway/Dockerfile.base#L1-L59)
- [README.md](file://kami-gateway/README.md#L34-L39)
### 应用镜像构建流程
应用镜像的构建流程分为两个阶段：第一阶段使用 `kami-gateway-base` 编译二进制文件，第二阶段基于一个极简的运行时镜像（如 `distroless`）打包，仅包含运行应用所需的文件，从而显著减小最终镜像体积。
```mermaid
sequenceDiagram
participant Dev as 开发者
participant BuildScript as build-base-image.sh
participant Docker as Docker Engine
participant Registry as 镜像仓库
Dev->>BuildScript : 执行 ./build-base-image.sh
BuildScript->>Docker : docker build --file Dockerfile.base ...
Docker->>Docker : 构建 kami-gateway-base 镜像
Docker-->>BuildScript : 构建成功
BuildScript->>BuildScript : 为镜像打标签
alt 指定了镜像仓库
BuildScript->>Docker : docker tag ...
BuildScript->>Docker : docker push ...
Docker-->>Registry : 推送镜像
Registry-->>BuildScript : 推送成功
end
BuildScript->>Dev : 构建完成，镜像可用
```
**图示来源**
- [build-base-image.sh](file://kami-gateway/build-base-image.sh#L1-L51)
- [Dockerfile.base](file://kami-gateway/Dockerfile.base#L20-L24)
**章节来源**
- [build-base-image.sh](file://kami-gateway/build-base-image.sh#L1-L51)
- [README.md](file://kami-gateway/README.md#L14-L21)
## 依赖分析
`kami-gateway` 基础镜像的依赖主要分为两部分：系统依赖和 Go 模块依赖。系统依赖通过 `apk add` 安装，包括时区数据、证书和 Git。Go 模块依赖则通过 `go mod download` 预先下载，其具体版本由 `go.mod` 和 `go.sum` 文件精确锁定，确保了构建的可重现性。
```mermaid
erDiagram
BASE_IMAGE ||--o{ SYSTEM_DEPS : "包含"
BASE_IMAGE ||--o{ GO_DEPS : "包含"
BASE_IMAGE ||--o{ CONFIG : "包含"
SYSTEM_DEPS {
string package_name PK
string version
string purpose
}
GO_DEPS {
string module_name PK
string version
string checksum
}
CONFIG {
string config_type PK
string value
string description
}
SYSTEM_DEPS }o--|| BASE_IMAGE : "系统依赖"
GO_DEPS }o--|| BASE_IMAGE : "Go依赖"
CONFIG }o--|| BASE_IMAGE : "配置项"
```
**图示来源**
- [Dockerfile.base](file://kami-gateway/Dockerfile.base#L19-L30)
- [go.mod](file://kami-gateway/go.mod#L1-L82)
- [Dockerfile.base](file://kami-gateway/Dockerfile.base#L7-L12)
**章节来源**
- [go.mod](file://kami-gateway/go.mod#L1-L82)
- [Dockerfile.base](file://kami-gateway/Dockerfile.base#L19-L34)
## 性能考虑
使用 `kami-gateway-base` 的主要性能优势在于**极速构建**。由于基础镜像已预置了 Go 编译环境和所有依赖，应用构建阶段的耗时从数分钟缩短至 10-30 秒。此外，多阶段构建确保了最终镜像的精简，减少了网络传输时间和运行时攻击面。
**章节来源**
- [README.md](file://kami-gateway/README.md#L48-L52)
## 故障排除指南
- **问题：构建时无法下载 Go 模块**
- **原因**：网络问题或 GOPROXY 配置错误。
- **解决**：确认 `Dockerfile.base` 中的 `GOPROXY` 设置为 `https://goproxy.cn,direct`。
- **问题：镜像推送失败**
- **原因**：未登录镜像仓库或 `DOCKER_REGISTRY` 环境变量设置错误。
- **解决**：执行 `docker login git.oceanpay.cc` 并检查 `build-base-image.sh` 脚本中的 `REGISTRY` 变量。
- **问题：容器启动失败，权限错误**
- **原因**：未正确创建非 root 用户或文件权限问题。
- **解决**：检查 `Dockerfile.base` 中 `addgroup`、`adduser` 和 `chown` 命令的执行。
**章节来源**
- [build-base-image.sh](file://kami-gateway/build-base-image.sh#L27-L30)
- [Dockerfile.base](file://kami-gateway/Dockerfile.base#L37-L42)
## 结论
`kami-gateway-base` 镜像通过预置环境和依赖，为 Go 应用提供了一个高效、安全的构建基础。通过遵循本文档的指南，开发者可以快速构建出轻量、安全且符合最佳实践的应用镜像，显著提升 CI/CD 流程的效率。

160
.qoder/repowiki/zh/content/项目概述/kami-spider-monorepo 模块.md Normal file
View File

@@ -0,0 +1,160 @@
# kami-spider-monorepo 模块
<cite>
**本文档引用文件**
- [README.md](file://kami-spider-monorepo/README.md)
- [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)
</cite>
## 目录
1. [简介](#简介)
2. [镜像内容与技术架构](#镜像内容与技术架构)
3. [Dockerfile.base 技术实现](#dockerfilebase-技术实现)
4. [依赖管理与可重现构建](#依赖管理与可重现构建)
5. [构建脚本与代理支持](#构建脚本与代理支持)
6. [构建命令与工作流程](#构建命令与工作流程)
7. [安全实践与性能优化](#安全实践与性能优化)
8. [高级部署与最佳实践](#高级部署与最佳实践)
## 简介
kami-spider-monorepo 模块是 kami-spider 爬虫平台的核心基础镜像构建系统。该模块通过 Docker 容器化技术，为 Python 爬虫应用提供一个预配置、高性能、安全的运行环境。其核心目标是简化爬虫应用的构建流程，通过预集成 Python 3.13 运行时、UV 包管理器、Playwright 浏览器自动化框架以及所有项目依赖，实现“开箱即用”的开发体验。该基础镜像以 `kami-spider-base:latest` 为标签，是自动化数据采集场景中不可或缺的基础设施。
## 镜像内容与技术架构
kami-spider 基础镜像是一个功能完备的 Python 爬虫运行时环境，集成了开发和生产所需的所有关键组件。其技术架构设计旨在提供一个稳定、高效且安全的平台。
### 核心组件
- **Python 3.13 运行时环境**：提供最新的 Python 语言特性和性能优化，确保爬虫应用能够利用现代 Python 的所有优势。
- **UV 包管理器**：作为现代、快速的 Python 包管理工具，UV 显著加速了依赖安装过程，是实现快速构建的关键。
- **Playwright 浏览器自动化框架**：预安装了 Chromium 浏览器，支持无头（headless）模式下的网页渲染、交互和数据抓取，能够处理复杂的动态网页内容。
- **预装 Python 依赖包**：包含了项目所需的所有第三方库，如 FastAPI（Web 框架）、SQLAlchemy（数据库 ORM）、Redis（缓存）、Pandas（数据处理）等，极大减少了应用镜像的构建时间和复杂性。
- **系统级运行时库**：安装了 Playwright 运行所需的系统依赖，如字体库、图形库（libnss3, libatk-bridge2.0-0 等），确保浏览器在容器内稳定运行。
- **非 root 用户配置**：遵循最小权限原则，应用在非 root 用户（`appuser`）下运行，显著提升了容器的安全性。
**Section sources**
- [README.md](file://kami-spider-monorepo/README.md#L25-L34)
## Dockerfile.base 技术实现
`Dockerfile.base` 是构建 kami-spider 基础镜像的蓝图，其设计体现了高效、安全和可维护性的最佳实践。
### 多阶段用户切换
Dockerfile 通过精心设计的用户切换流程来平衡权限和安全性：
1. **初始配置**：基于 `python:3.13-slim` 基础镜像，设置了一系列环境变量，如 `PYTHONUNBUFFERED`（确保日志实时输出）、`PYTHONDONTWRITEBYTECODE`（避免生成 `__pycache__` 目录）和 `UV_CACHE_DIR`（指定 UV 缓存目录）。
2. **系统依赖安装**：以 root 用户身份运行，使用 `apt-get` 安装 Playwright 所需的系统级库（如 `libnss3`, `libasound2`, `libcups2t64` 等），并清理包管理器缓存以减小镜像体积。
3. **非 root 用户创建**：创建名为 `appuser` 的非 root 用户和组，并设置其主目录。同时创建应用目录 `/app` 和浏览器缓存目录 `/app/.browsers`，并正确设置所有权。
4. **依赖安装**：切换到 `appuser` 用户，复制 `pyproject.toml` 和 `uv.lock` 文件，并使用 `uv sync` 命令安装 Python 依赖。此步骤在非特权用户下执行，降低了依赖安装过程中的安全风险。
5. **Playwright 配置**：先切换回 root 用户安装 Playwright 的系统依赖（`playwright install-deps chromium`），然后再次切换到 `appuser` 用户来安装 Chromium 浏览器本身（`playwright install chromium`）。这确保了浏览器文件由运行时用户拥有，避免了权限问题。
6. **最终清理**：最后切换回 root 用户，确保浏览器目录的权限正确，并添加镜像元数据标签。
### 关键环境变量
- `PLAYWRIGHT_BROWSERS_PATH=/app/.browsers`：将浏览器安装到一个持久化且用户可访问的路径，便于管理和缓存。
- `UV_LINK_MODE=copy`：配置 UV 使用复制模式而非硬链接，提高在某些文件系统上的兼容性。
**Section sources**
- [Dockerfile.base](file://kami-spider-monorepo/Dockerfile.base#L1-L87)
## 依赖管理与可重现构建
kami-spider 基础镜像通过 `pyproject.toml` 和 `uv.lock` 文件实现了严格的依赖锁定和可重现构建。
### pyproject.toml
该文件定义了项目的基本信息和依赖项。它声明了项目名称 `kami_spider`、Python 版本要求（`>=3.13`）以及所有直接依赖的包及其版本范围。例如，它指定了 `fastapi>=0.120.0` 和 `playwright>=1.55.0`。这为依赖管理提供了声明式的起点。
### uv.lock
这是实现可重现构建的核心。`uv.lock` 文件由 `uv` 工具生成，它记录了所有依赖（包括传递依赖）的精确版本号、哈希值和下载源。这意味着无论在何时何地构建镜像，只要使用相同的 `uv.lock` 文件，安装的依赖包版本将完全一致，彻底消除了“在我机器上能运行”的问题。
```mermaid
flowchart TD
A["pyproject.toml\n(声明依赖范围)"] --> B["uv sync\n(解析依赖)"]
B --> C["uv.lock\n(锁定精确版本)"]
C --> D["安装依赖\n(可重现构建)"]
```
**Diagram sources**
- [pyproject.toml](file://kami-spider-monorepo/pyproject.toml#L1-L49)
- [uv.lock](file://kami-spider-monorepo/uv.lock#L1-L647)
**Section sources**
- [pyproject.toml](file://kami-spider-monorepo/pyproject.toml#L1-L49)
- [uv.lock](file://kami-spider-monorepo/uv.lock#L1-L647)
## 构建脚本与代理支持
`build-base-image.sh` 脚本自动化了基础镜像的构建、标记和推送流程，并通过 `USE_PROXY` 环境变量实现了灵活的网络配置。
### 脚本功能
该脚本接受三个环境变量作为配置：
- `BASE_IMAGE_NAME`：镜像名称，默认为 `kami-spider-base`。
- `REGISTRY`：目标镜像仓库地址，默认为 `localhost:5000`。
- `USE_PROXY`：代理开关，`1` 表示启用，`0` 表示禁用，默认为 `0`。
- `VERSION`：镜像版本标签，默认为 `latest`。
脚本首先输出配置信息，然后调用 `docker build` 命令，并通过 `--build-arg USE_PROXY` 将代理开关传递给 Dockerfile。构建成功后，如果指定了非本地仓库，脚本会自动为镜像打上仓库前缀的标签并推送至远程仓库。
### 代理切换机制
在 `Dockerfile.base` 中，`RUN` 指令通过 `if` 语句检查 `USE_PROXY` 变量的值。如果为 `1`，则 `uv sync` 命令会使用 `-i` 参数指定国内镜像源（如清华源 `https://pypi.tuna.tsinghua.edu.cn/simple/`）；否则，使用默认的 PyPI 源。这种设计使得镜像构建能够适应不同的网络环境，极大地提高了在受限网络下的构建成功率。
**Section sources**
- [build-base-image.sh](file://kami-spider-monorepo/build-base-image.sh#L1-L54)
## 构建命令与工作流程
以下是使用 kami-spider 基础镜像的完整工作流程和命令示例。
### 构建命令
```bash
# 1. 无代理构建（使用默认 PyPI 源）
./build-base-image.sh
# 2. 使用代理构建（使用国内镜像源）
USE_PROXY=1 ./build-base-image.sh
# 3. 推送到私有仓库
DOCKER_REGISTRY=your-registry.com USE_PROXY=1 ./build-base-image.sh
```
### 工作流程
1. **准备**：确保 Docker 守护进程正在运行。
2. **构建**：执行上述构建命令。脚本会输出构建日志，包括使用的注册表、版本和代理设置。
3. **验证**：构建完成后，脚本会显示成功信息和镜像大小，可通过 `docker images` 命令验证。
4. **使用**：在应用的 Dockerfile 中，使用 `FROM kami-spider-base:latest` 作为基础镜像，即可继承所有预配置的环境和依赖。
**Section sources**
- [README.md](file://kami-spider-monorepo/README.md#L12-L23)
- [build-base-image.sh](file://kami-spider-monorepo/build-base-image.sh#L1-L54)
## 安全实践与性能优化
kami-spider 基础镜像在设计上充分考虑了安全性和性能。
### 安全实践
- **非 root 用户运行**：这是最重要的安全措施。通过在 Dockerfile 中创建 `appuser` 并使用 `USER appuser` 指令，确保了容器内的进程以最小权限运行。即使应用存在漏洞，攻击者也难以获得 root 权限，从而限制了潜在的损害。
- **精简基础镜像**：使用 `python:3.13-slim` 作为基础，减少了不必要的软件包和潜在的攻击面。
- **环境变量保护**：通过设置 `PYDEVD_DISABLE=1` 等变量，禁用了调试功能，防止生产环境中意外暴露调试接口。
### 性能优化
- **依赖缓存**：`uv` 包管理器本身具有高效的缓存机制。通过将 `UV_CACHE_DIR` 设置为 `/tmp/uv-cache` 并在安装后清理，可以在多阶段构建中利用 Docker 的构建缓存，加速后续构建。
- **Playwright 资源优化**：将 `PLAYWRIGHT_BROWSERS_PATH` 指向 `/app/.browsers`，允许在 CI/CD 流水线或本地开发中将此目录挂载为卷，从而避免每次构建都重新下载庞大的 Chromium 浏览器，节省时间和带宽。
**Section sources**
- [Dockerfile.base](file://kami-spider-monorepo/Dockerfile.base#L4-L14)
- [Dockerfile.base](file://kami-spider-monorepo/Dockerfile.base#L41-L47)
- [Dockerfile.base](file://kami-spider-monorepo/Dockerfile.base#L49)
- [Dockerfile.base](file://kami-spider-monorepo/Dockerfile.base#L10-L11)
## 高级部署与最佳实践
为了在大规模爬虫部署中发挥 kami-spider 基础镜像的最大价值，建议遵循以下最佳实践。
### 大规模部署最佳实践
- **私有镜像仓库**：将构建好的 `kami-spider-base:latest` 镜像推送到组织的私有 Docker 仓库（如 Harbor 或 Nexus），作为所有爬虫项目的标准基础镜像，确保环境一致性。
- **CI/CD 集成**：将 `build-base-image.sh` 脚本集成到 CI/CD 流水线中。当 `pyproject.toml` 或 `uv.lock` 发生变更时，自动触发基础镜像的构建和推送，保证所有应用都能及时使用最新的依赖。
- **资源限制**：在 Kubernetes 或 Docker Swarm 等编排系统中部署时，为爬虫容器设置 CPU 和内存限制，防止单个爬虫任务耗尽节点资源。
### 性能调优建议
- **依赖缓存策略**：在 CI/CD 环境中，可以配置一个持久化的缓存卷来存储 `/tmp/uv-cache` 和 `/app/.browsers` 目录，实现跨构建的缓存复用。
- **Playwright 配置**：在运行爬虫时，通过环境变量配置 Playwright 以使用无头模式和禁用图片加载等，进一步提升爬取效率。
- **监控与日志**：利用镜像中预装的 `opentelemetry` 等库，集成分布式追踪和监控，以便于分析爬虫性能瓶颈。
kami-spider 基础镜像通过其全面的预配置和现代化的工具链，为自动化数据采集提供了坚实、高效且安全的基础，是构建复杂爬虫应用的理想起点。
**Section sources**
- [build-base-image.sh](file://kami-spider-monorepo/build-base-image.sh#L30-L33)
- [pyproject.toml](file://kami-spider-monorepo/pyproject.toml#L20-L27)

261
.qoder/repowiki/zh/content/项目概述/项目概述.md Normal file
View File

@@ -0,0 +1,261 @@
# 项目概述
<cite>
**本文档引用的文件**
- [alpine-base/README.md](file://alpine-base/README.md)
- [kami-gateway/README.md](file://kami-gateway/README.md)
- [kami-spider-monorepo/README.md](file://kami-spider-monorepo/README.md)
- [alpine-base/build-base-image.sh](file://alpine-base/build-base-image.sh)
- [kami-gateway/build-base-image.sh](file://kami-gateway/build-base-image.sh)
- [kami-spider-monorepo/build-base-image.sh](file://kami-spider-monorepo/build-base-image.sh)
- [alpine-base/Dockerfile.base](file://alpine-base/Dockerfile.base)
- [kami-gateway/Dockerfile.base](file://kami-gateway/Dockerfile.base)
- [kami-spider-monorepo/Dockerfile.base](file://kami-spider-monorepo/Dockerfile.base)
</cite>
## 目录
1. [项目简介](#项目简介)
2. [项目结构](#项目结构)
3. [核心模块分析](#核心模块分析)
4. [架构设计](#架构设计)
5. [构建流程与使用方法](#构建流程与使用方法)
6. [安全与优化实践](#安全与优化实践)
7. [CI/CD集成](#cicd集成)
8. [总结](#总结)
## 项目简介
`docker-registry` 项目是一个为不同技术栈提供优化基础镜像的容器化构建系统。该项目通过三个核心模块——`alpine-base`、`kami-gateway` 和 `kami-spider-monorepo`，为 Alpine、Go 和 Python 技术栈提供高度优化的 Docker 基础镜像。其核心设计理念是通过分层继承、构建脚本复用和非 root 安全运行机制，实现快速、安全、一致的容器化部署。
该项目的主要功能包括：
- **加速镜像构建**：通过预下载依赖和缓存基础层，显著缩短构建时间
- **统一开发环境**：为团队提供一致的运行时环境，避免“在我机器上能运行”的问题
- **中国镜像源优化**：配置阿里云等国内镜像源，大幅提升依赖下载速度
- **自定义证书集成**：预装 Comodo AAA 证书，解决特定环境下的 SSL/TLS 信任问题
- **轻量化设计**：基于 Alpine Linux 和 slim 镜像，保持最小化体积
在微服务架构中，这些基础镜像作为所有服务的共同起点，确保了技术栈的一致性、安全性和部署效率。
## 项目结构
项目采用模块化设计，每个技术栈拥有独立的目录，包含其特定的构建文件和配置。
```mermaid
graph TD
A[docker-registry] --> B[alpine-base]
A --> C[kami-gateway]
A --> D[kami-spider-monorepo]
B --> B1[README.md]
B --> B2[build-base-image.sh]
B --> B3[Dockerfile.base]
C --> C1[README.md]
C --> C2[build-base-image.sh]
C --> C3[Dockerfile.base]
C --> C4[go.mod]
C --> C5[go.sum]
D --> D1[README.md]
D --> D2[build-base-image.sh]
D --> D3[Dockerfile.base]
D --> D4[pyproject.toml]
D --> D5[uv.lock]
```
**Diagram sources**
- [alpine-base/README.md](file://alpine-base/README.md)
- [kami-gateway/README.md](file://kami-gateway/README.md)
- [kami-spider-monorepo/README.md](file://kami-spider-monorepo/README.md)
**Section sources**
- [alpine-base/README.md](file://alpine-base/README.md)
- [kami-gateway/README.md](file://kami-gateway/README.md)
- [kami-spider-monorepo/README.md](file://kami-spider-monorepo/README.md)
## 核心模块分析
### alpine-base 模块
`alpine-base` 模块是整个项目的基础，为所有其他镜像提供一个优化的 Alpine Linux 运行时环境。
**核心特性**：
- **基础镜像**：基于 `alpine:latest`，保证了最小化体积（约 50MB）
- **中国镜像源**：配置阿里云镜像源，加速 `apk` 包管理器的下载速度
- **时区配置**：默认设置为 `Asia/Shanghai`
- **预装工具**：包含 `curl`、`wget`、`git`、`bash` 等常用工具
- **安全机制**：创建非 root 用户 `appuser` (UID: 1001)，强制应用以最小权限运行
- **证书管理**：预装 CA 证书和 Comodo AAA 自定义证书
该模块生成的镜像标记为 `alpine-base:latest`，可作为其他自定义镜像的基础。
**Section sources**
- [alpine-base/README.md](file://alpine-base/README.md)
- [alpine-base/Dockerfile.base](file://alpine-base/Dockerfile.base)
- [alpine-base/build-base-image.sh](file://alpine-base/build-base-image.sh)
### kami-gateway 模块
`kami-gateway` 模块专为 Go 语言应用设计，构建了一个包含 Go 1.25 编译环境和 Alpine 运行时的完整基础镜像。
**核心特性**：
- **Go 编译环境**：基于 `golang:1.25-alpine`，提供完整的 Go 开发工具链
- **依赖预下载**：在构建过程中执行 `go mod download`，缓存所有依赖，使后续应用构建时间缩短至 10-30 秒
- **中国镜像源**：配置 `GOPROXY=https://goproxy.cn,direct`，加速 Go 模块下载
- **安全运行**：同样使用非 root 用户 `appuser` 运行应用
- **多阶段构建**：虽然未在基础镜像中体现，但其设计支持通过 `Dockerfile.improved` 实现多阶段构建以优化最终镜像
该模块生成的镜像标记为 `kami-gateway-base:latest`。
**Section sources**
- [kami-gateway/README.md](file://kami-gateway/README.md)
- [kami-gateway/Dockerfile.base](file://kami-gateway/Dockerfile.base)
- [kami-gateway/build-base-image.sh](file://kami-gateway/build-base-image.sh)
### kami-spider-monorepo 模块
`kami-spider-monorepo` 模块为 Python 应用，特别是网络爬虫类应用，提供了一个功能完备的基础镜像。
**核心特性**：
- **Python 运行时**：基于 `python:3.13-slim`，平衡了功能和体积
- **UV 包管理器**：使用现代的 `uv` 工具替代 `pip`，显著提升依赖安装速度
- **Playwright 支持**：预装 Playwright 运行时库和 Chromium 浏览器，开箱即用
- **系统依赖**：安装了 Playwright 所需的所有系统级库（如 `libnss3`、`libatk-bridge2.0-0` 等）
- **代理支持**：通过 `USE_PROXY` 构建参数，支持使用清华源等国内镜像加速 PyPI 包下载
- **安全配置**：创建非 root 用户 `appuser`，并正确设置文件权限
该模块生成的镜像标记为 `kami-spider-base:latest`。
**Section sources**
- [kami-spider-monorepo/README.md](file://kami-spider-monorepo/README.md)
- [kami-spider-monorepo/Dockerfile.base](file://kami-spider-monorepo/Dockerfile.base)
- [kami-spider-monorepo/build-base-image.sh](file://kami-spider-monorepo/build-base-image.sh)
## 架构设计
该项目的架构设计体现了清晰的分层和继承思想。
```mermaid
graph TD
subgraph "基础层"
A[alpine:latest] --> B[alpine-base:latest]
end
subgraph "技术栈层"
B --> C[golang:1.25-alpine]
C --> D[kami-gateway-base:latest]
B --> E[python:3.13-slim]
E --> F[kami-spider-base:latest]
end
subgraph "应用层"
D --> G[具体 Go 应用镜像]
F --> H[具体 Python 应用镜像]
end
```
**Diagram sources**
- [alpine-base/Dockerfile.base](file://alpine-base/Dockerfile.base)
- [kami-gateway/Dockerfile.base](file://kami-gateway/Dockerfile.base)
- [kami-spider-monorepo/Dockerfile.base](file://kami-spider-monorepo/Dockerfile.base)
**Section sources**
- [alpine-base/Dockerfile.base](file://alpine-base/Dockerfile.base)
- [kami-gateway/Dockerfile.base](file://kami-gateway/Dockerfile.base)
- [kami-spider-monorepo/Dockerfile.base](file://kami-spider-monorepo/Dockerfile.base)
**设计要点**：
1. **分层继承**：`alpine-base` 作为最底层的通用优化镜像，被 `kami-gateway` 和 `kami-spider-monorepo` 继承，避免了重复配置。
2. **构建脚本复用**：所有模块的 `build-base-image.sh` 脚本结构高度一致，实现了构建逻辑的标准化。
3. **环境变量控制**：通过 `DOCKER_REGISTRY`、`VERSION`、`USE_PROXY` 等环境变量，灵活控制构建行为。
4. **非 root 安全机制**：所有镜像都创建了 `appuser` 用户，强制应用以非特权用户身份运行，提升了容器安全性。
## 构建流程与使用方法
### 构建流程
所有模块的构建流程都通过 `build-base-image.sh` 脚本自动化完成。
```mermaid
flowchart TD
Start([开始构建]) --> SetEnv["设置环境变量\n(DOCKER_REGISTRY, VERSION)"]
SetEnv --> Build["执行 docker build"]
Build --> Tag["打标签\n(local 和 registry)"]
Tag --> Push{"是否推送至远程仓库?"}
Push --> |是| PushToRegistry["执行 docker push"]
Push --> |否| SkipPush["跳过推送"]
PushToRegistry --> Complete["构建完成"]
SkipPush --> Complete
Complete --> ShowSize["显示镜像大小"]
ShowSize --> End([结束])
```
**Diagram sources**
- [alpine-base/build-base-image.sh](file://alpine-base/build-base-image.sh)
- [kami-gateway/build-base-image.sh](file://kami-gateway/build-base-image.sh)
- [kami-spider-monorepo/build-base-image.sh](file://kami-spider-monorepo/build-base-image.sh)
**Section sources**
- [alpine-base/build-base-image.sh](file://alpine-base/build-base-image.sh)
- [kami-gateway/build-base-image.sh](file://kami-gateway/build-base-image.sh)
- [kami-spider-monorepo/build-base-image.sh](file://kami-spider-monorepo/build-base-image.sh)
### 使用方法
#### 构建基础镜像
```bash
# 构建 alpine-base 镜像
cd alpine-base && ./build-base-image.sh
# 构建并推送到指定镜像仓库
DOCKER_REGISTRY=git.oceanpay.cc/danial ./build-base-image.sh
```
#### 在应用中使用
```Dockerfile
# 使用 alpine-base 作为基础
FROM git.oceanpay.cc/danial/alpine-base:latest
COPY --chown=appuser:appuser . /app/
USER appuser
CMD ["./your-app"]
```
```Dockerfile
# 使用 kami-gateway-base 作为基础
FROM git.oceanpay.cc/danial/kami-gateway-base:latest
# 复制源码并构建
COPY --chown=appuser:appuser . .
RUN go build -o main .
CMD ["./main"]
```
## 安全与优化实践
### 安全实践
- **非 root 用户**：所有镜像都创建了 UID 为 1001 的 `appuser`，并通过 `USER` 指令切换，遵循最小权限原则。
- **文件权限**：应用目录 `/app` 及其内容的所有权被正确设置为 `appuser`。
- **镜像来源**：基础镜像均来自官方仓库（`alpine`, `golang`, `python`），保证了来源可信。
### 优化实践
- **中国镜像源**：Alpine、Go 和 Python 的依赖下载均配置了国内镜像源，解决了网络延迟问题。
- **依赖预下载**：Go 模块和 Python 依赖在构建基础镜像时就已下载，避免了每次构建应用时的重复下载。
- **轻量化**：使用 `--no-cache` 和 `rm -rf` 清理构建缓存，保持镜像体积最小化。
- **环境变量**：通过 `CGO_ENABLED=0` 等 Go 环境变量，构建静态链接的二进制文件，减少对系统库的依赖。
## CI/CD集成
`kami-gateway` 模块明确提到了使用 Drone CI 进行自动化构建。其 CI/CD 流程如下：
1. **触发条件**：检测到 `kami-gateway/` 目录下的代码变更。
2. **自动构建**：CI 系统自动执行 `build-base-image.sh` 脚本。
3. **条件推送**：根据配置，将新构建的 `kami-gateway-base:latest` 镜像推送到远程镜像仓库。
4. **资源优化**：采用条件构建策略，避免不必要的资源消耗。
这种自动化流程确保了基础镜像的及时更新和一致性，是 DevOps 实践的重要组成部分。
**Section sources**
- [kami-gateway/README.md](file://kami-gateway/README.md)
## 总结
`docker-registry` 项目通过精心设计的模块化架构，为不同技术栈提供了高效、安全、一致的基础镜像解决方案。其核心价值在于：
- **提升效率**：通过预构建和缓存，将应用构建时间从分钟级缩短到秒级。
- **保障安全**：强制非 root 用户运行，降低了安全风险。
- **统一环境**：消除了开发、测试、生产环境之间的差异。
- **优化网络**：针对中国网络环境进行了专门优化。
该项目是现代微服务架构中不可或缺的基础设施，为团队的快速迭代和稳定部署提供了坚实的基础。

1
.qoder/repowiki/zh/meta/repowiki-metadata.json Normal file
View File

File diff suppressed because one or more lines are too long

2
kami-gateway/Dockerfile.base
View File

@@ -6,7 +6,7 @@ FROM golang:1.25-alpine
# Set environment variables # Set environment variables
ENV TZ=Asia/Shanghai \ ENV TZ=Asia/Shanghai \
GO111MODULE=on \ GO111MODULE=on \
GOPROXY=https://goproxy.cn,direct \ GOPROXY=https://goproxy.io,direct \
CGO_ENABLED=0 \ CGO_ENABLED=0 \
GOOS=linux \ GOOS=linux \
GOARCH=amd64 GOARCH=amd64

18
kami-spider-monorepo/Dockerfile.base
View File

@@ -7,6 +7,7 @@ ENV PYTHONUNBUFFERED=1 \
UV_LINK_MODE=copy \ UV_LINK_MODE=copy \
PATH="/app/.venv/bin:$PATH" \ PATH="/app/.venv/bin:$PATH" \
UV_CACHE_DIR=/tmp/uv-cache \ UV_CACHE_DIR=/tmp/uv-cache \
PLAYWRIGHT_BROWSERS_PATH=/app/.browsers \
PYDEVD_DISABLE=1 \ PYDEVD_DISABLE=1 \
PYDEVD_DISABLE_FILE_VALIDATION=1 \ PYDEVD_DISABLE_FILE_VALIDATION=1 \
PYCHARM_DEBUG="false" \ PYCHARM_DEBUG="false" \
@@ -40,6 +41,7 @@ COPY --from=ghcr.io/astral-sh/uv:latest /uv /usr/local/bin/uv
# Create non-root user with home directory and set up directories # Create non-root user with home directory and set up directories
RUN groupadd -r appuser && useradd -r -g appuser -d /home/appuser -m appuser \ RUN groupadd -r appuser && useradd -r -g appuser -d /home/appuser -m appuser \
&& mkdir -p /app \ && mkdir -p /app \
&& mkdir -p /app/.browsers \
&& mkdir -p /home/appuser/.cache \ && mkdir -p /home/appuser/.cache \
&& chown -R appuser:appuser /app /home/appuser && chown -R appuser:appuser /app /home/appuser
@@ -64,13 +66,21 @@ RUN if [ "$USE_PROXY" = "1" ]; then \
# Switch back to root user to install Playwright system dependencies # Switch back to root user to install Playwright system dependencies
USER root USER root
# Install Playwright browsers with dependencies (requires root) # Install Playwright system dependencies for chromium
RUN /app/.venv/bin/playwright install chromium --with-deps && \ RUN /app/.venv/bin/playwright install-deps chromium
/app/.venv/bin/playwright install-deps chromium
# Switch back to non-root user # Switch to appuser to install browsers (must be done by the user who will run them)
USER appuser USER appuser
# Install Playwright browsers to the shared path
RUN /app/.venv/bin/playwright install chromium
# Switch back to root for final cleanup
USER root
# Ensure browser cache directory has correct permissions for appuser
RUN chmod -R 755 /app/.browsers
# Label the image # Label the image
LABEL maintainer="kami-spider-team" \ LABEL maintainer="kami-spider-team" \
version="1.0.0" \ version="1.0.0" \