82 lines
2.5 KiB
Markdown
82 lines
2.5 KiB
Markdown
# Docker 镜像持续构建与发布
|
|
|
|
本文档说明 Gitea Actions 中 Docker 镜像构建与发布 workflow 的使用方式。对应脚本为 [.gitea/workflows/docker-image.yml](../.gitea/workflows/docker-image.yml)。
|
|
|
|
## 职责划分
|
|
|
|
当前持续集成拆成两条链路：
|
|
|
|
| Workflow | 触发时机 | 职责 |
|
|
| --- | --- | --- |
|
|
| `.gitea/workflows/ci.yml` | `dev`、`main`、`test` push / PR | 安装依赖、Lint、单元测试、Next.js 构建 |
|
|
| `.gitea/workflows/docker-image.yml` | `main`、`test` push / 手动触发 | 构建 Docker 镜像并推送到镜像仓库 |
|
|
|
|
这样可以避免所有开发分支都发布镜像，也能让代码检查失败时不污染镜像仓库。
|
|
|
|
## 必需 Secrets
|
|
|
|
在 Gitea 仓库的 Actions Secrets 中配置以下变量：
|
|
|
|
| Secret | 示例 | 说明 |
|
|
| --- | --- | --- |
|
|
| `REGISTRY_HOST` | `registry.example.com` | `docker login` 使用的镜像仓库地址 |
|
|
| `REGISTRY_IMAGE` | `registry.example.com/cozsweet/cozsweet-web` | 完整镜像仓库名，不包含 tag |
|
|
| `REGISTRY_USERNAME` | `cozsweet-bot` | 镜像仓库用户名 |
|
|
| `REGISTRY_PASSWORD` | `***` | 镜像仓库密码或访问令牌 |
|
|
| `TEST_ENV_FILE` | `.env.local` 的完整内容 | 测试环境构建期环境变量 |
|
|
| `PRODUCTION_ENV_FILE` | `.env.production` 的完整内容 | 生产环境构建期环境变量 |
|
|
|
|
Next.js 的 `NEXT_PUBLIC_*` 会在构建期固化到产物中，因此测试环境和生产环境会分别构建镜像。
|
|
|
|
## 镜像 Tag 规则
|
|
|
|
`test` 分支发布：
|
|
|
|
```bash
|
|
REGISTRY_IMAGE:test-<short_sha>
|
|
REGISTRY_IMAGE:test-latest
|
|
```
|
|
|
|
`main` 分支发布：
|
|
|
|
```bash
|
|
REGISTRY_IMAGE:prod-<short_sha>
|
|
REGISTRY_IMAGE:prod-latest
|
|
```
|
|
|
|
`<short_sha>` 用于精确回滚，`*-latest` 用于普通部署拉取最新版本。
|
|
|
|
## Runner 要求
|
|
|
|
当前 workflow 使用：
|
|
|
|
```yaml
|
|
runs-on: gitea-label
|
|
```
|
|
|
|
自托管 runner 需要满足：
|
|
|
|
1. 安装 Node.js，确保 `node` 在 runner 执行环境的 `PATH` 中。
|
|
2. 安装 Docker CLI。
|
|
3. 当前 runner 用户可以访问 Docker daemon。
|
|
4. 能访问配置的镜像仓库。
|
|
5. 支持 Docker BuildKit secret，即 `DOCKER_BUILDKIT=1 docker build --secret ...`。
|
|
|
|
## 验证方式
|
|
|
|
推送到 `test` 分支后，检查 Actions 日志中是否出现：
|
|
|
|
```text
|
|
Build Docker image
|
|
Push Docker image
|
|
```
|
|
|
|
服务器上可查看镜像：
|
|
|
|
```bash
|
|
docker pull REGISTRY_IMAGE:test-latest
|
|
docker image ls | grep cozsweet-web
|
|
```
|
|
|
|
如果使用 Gitea 自带 Container Registry，需要确认 Gitea 服务已开启 packages / container registry，并且 `REGISTRY_HOST` 与 Docker 登录地址一致。
|