docs(docker): 添加基础镜像 Dockerfile 使用说明文档

新增 README.md 文件,详细说明 Dockerfile.base 的作用、构建流程、与其他 Dockerfile 的关系以及维护注意事项。旨在为团队提供清晰的基础镜像构建和使用指南,提升 Docker 镜像构建的一致性和可维护性。
This commit is contained in:
augushong
2026-04-24 23:42:47 +08:00
parent 67bb1f0785
commit 0b2b89c3ae

View File

@@ -0,0 +1,96 @@
# Dockerfile.base 使用说明
## 1. 文件作用
`source/stack/base-build/docker/Dockerfile.base`**ulthon_admin 的基础镜像构建文件**,用于提前固化这些“低频变更但构建耗时高”的基础层:
- Debian 源与系统包(如 `nginx`
- PHP 扩展安装能力(`install-php-extensions`
- 常用 PHP 扩展(`pdo_mysql``gd``redis``imagick` 等)
- Composer 二进制与全局仓库配置
这个文件**不包含业务代码**(不会 `COPY .` 项目代码),只负责构建底座环境。
---
## 2. 与其他 Dockerfile 的关系
当前模式设计下有三类 Dockerfile
- `source/stack/full/Dockerfile`:全量构建(历史兼容方案)
- `source/stack/base-build/docker/Dockerfile.base`:基础镜像构建(本文件)
- `source/stack/base-build/Dockerfile`:应用镜像构建(`FROM <base-image>`,再拷贝业务代码)
推荐流程是:
1. 先构建并推送基础镜像(用本文件)
2. 应用构建基于基础镜像进行(减少重复安装依赖)
---
## 3. 你该如何做(标准步骤)
以下以 DockerHub 仓库 `ulthon/ulthon_admin-base` 为例。
### 3.1 登录 DockerHub
```bash
docker login
```
### 3.2 构建基础镜像latest + 时间戳)
在项目根目录执行:
```bash
docker build -f source/stack/base-build/docker/Dockerfile.base -t ulthon/ulthon_admin-base:latest .
docker build -f source/stack/base-build/docker/Dockerfile.base -t ulthon/ulthon_admin-base:20260424233000 .
```
### 3.3 推送基础镜像
```bash
docker push ulthon/ulthon_admin-base:latest
docker push ulthon/ulthon_admin-base:20260424233000
```
### 3.4 应用构建引用基础镜像
当前项目 `Dockerfile`(默认)已支持:
```dockerfile
ARG BASE_IMAGE=ulthon/ulthon_admin-base:latest
FROM ${BASE_IMAGE}
```
如果要固定版本,构建应用时可指定:
```bash
docker build --build-arg BASE_IMAGE=ulthon/ulthon_admin-base:20260424233000 -t ulthon/ulthon_admin-app:test .
```
---
## 4. 何时需要重建基础镜像
出现以下情况时,建议重建并推送 `Dockerfile.base`
- 新增/删除 PHP 扩展
- 修改系统依赖apt 包)
- 调整 Composer 全局配置
- 需要安全更新(基础镜像、系统包漏洞修复)
如果只是业务代码变化,一般不需要重建基础镜像。
---
## 5. 注意事项
- `Dockerfile.base` 建议由框架作者维护(避免业务方随意改底座导致环境漂移)。
- 标签建议同时维护:
- `latest`:默认引用
- 时间戳:可追溯、可回滚
- 若默认模式为 `base-build`,请保持:
- 根目录 `Dockerfile`
- `source/stack/default/Dockerfile`
二者内容一致(符合 `source/stack` 目录规范)。