ulthon_admin/source/stack/base-build/docker/README.md

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

docker login

3.2 构建基础镜像（latest + 时间戳）

在项目根目录执行：

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 推送基础镜像

docker push ulthon/ulthon_admin-base:latest
docker push ulthon/ulthon_admin-base:20260424233000

3.4 应用构建引用基础镜像

当前项目 Dockerfile（默认）已支持：

ARG BASE_IMAGE=ulthon/ulthon_admin-base:latest
FROM ${BASE_IMAGE}

如果要固定版本，构建应用时可指定：

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 目录规范）。