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