diff --git a/source/stack/base-build/docker/README.md b/source/stack/base-build/docker/README.md new file mode 100644 index 0000000..2c5f0a4 --- /dev/null +++ b/source/stack/base-build/docker/README.md @@ -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 `,再拷贝业务代码) + +推荐流程是: + +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` 目录规范)。