3.6 KiB
Docker 镜像持续构建与发布
本文档说明 Gitea Actions 中 Docker 镜像构建与发布 workflow 的使用方式。对应脚本为 .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 分支发布：
REGISTRY_IMAGE:test-<short_sha>
REGISTRY_IMAGE:test-latest
main 分支发布：
REGISTRY_IMAGE:prod-<short_sha>
REGISTRY_IMAGE:prod-latest
<short_sha> 用于精确回滚，*-latest 用于普通部署拉取最新版本。
Runner 要求
当前 workflow 使用：
runs-on: gitea-label
自托管 runner 需要满足：
- 安装 Node.js，确保
node在 runner 执行环境的PATH中。 - 安装 Docker CLI。
- 当前 runner 用户可以访问 Docker daemon。
- 能访问配置的镜像仓库。
- 支持 Docker BuildKit secret，即
DOCKER_BUILDKIT=1 docker build --secret ...。
当前 Docker 镜像发布 workflow 会使用 node:24-bookworm 作为 job 容器，确保 actions/checkout@v4 执行时已经存在 Node.js。runner 仍然需要挂载宿主机 Docker socket：
volumes:
- /var/run/docker.sock:/var/run/docker.sock
验证方式
推送到 test 分支后，检查 Actions 日志中是否出现：
Build Docker image
Push Docker image
服务器上可查看镜像：
docker pull REGISTRY_IMAGE:test-latest
docker image ls | grep cozsweet-web
如果使用 Gitea 自带 Container Registry，需要确认 Gitea 服务已开启 packages / container registry，并且 REGISTRY_HOST 与 Docker 登录地址一致。
部署服务器拉取镜像
部署服务器需要先登录镜像仓库：
docker login REGISTRY_HOST
然后在部署服务器工作树中创建 .deploy.env：
cp env-example/.deploy.env.example .deploy.env
配置示例：
COZSWEET_DEPLOY_IMAGE_SOURCE=pull
COZSWEET_REGISTRY_IMAGE=registry.example.com/cozsweet/cozsweet-web
post-receive 会根据当前分支和 commit 自动拉取：
registry.example.com/cozsweet/cozsweet-web:test-<short_sha>
registry.example.com/cozsweet/cozsweet-web:prod-<short_sha>
如果需要改用 latest tag，可以在服务器 .deploy.env 中显式设置：
COZSWEET_REMOTE_IMAGE_TAG=prod-latest
推荐优先使用默认的 <env>-<short_sha> 精确 tag，这样发布和回滚都更可控。