cozsweet-frontend-nextjs/docs/docker-image-ci.md

Docker 镜像持续构建与发布

本文档说明 Gitea Actions 中 Docker 镜像构建、发布与 SSH 部署 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 镜像、推送到镜像仓库，并通过 SSH 部署

这样可以避免所有开发分支都发布镜像，并确保生产镜像通过发布门禁。

main 分支发布前会执行 Docker workflow 内的质量和 bundle 门禁。test 分支为快速部署测试环境，会跳过该门禁；独立的 ci.yml 仍会照常执行测试分支检查， 但不会阻塞测试镜像构建与部署。

必需 Secrets

在 Gitea 仓库的 Actions Secrets 中配置以下变量：

Secret	示例	说明
REGISTRY_HOST	gitea.banlv-ai.com	docker login 使用的镜像仓库地址
REGISTRY_IMAGE	gitea.banlv-ai.com/admin/cozsweet-web	完整镜像仓库名，不包含 tag
REGISTRY_USERNAME	cozsweet-bot	镜像仓库用户名
REGISTRY_PASSWORD	***	镜像仓库密码或访问令牌
REGISTRY_API_BASE_URL	https://gitea.banlv-ai.com/api/v1	Gitea API 地址，用于清理旧镜像版本
REGISTRY_PACKAGE_TOKEN	***	具备 package 删除权限的 Gitea token
REGISTRY_PACKAGE_OWNER	banlv	可选；Registry 镜像名不含 owner 时用于指定 package owner
REGISTRY_PACKAGE_NAME	cozsweet-web	可选；Registry 镜像名不含 owner 或包名不一致时用于指定 package name
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 需要满足：

1. 可以拉取并运行 job 容器镜像。
2. 当前 runner 用户可以访问 Docker daemon。
3. 能访问配置的镜像仓库。
4. 支持 Docker BuildKit secret，即 DOCKER_BUILDKIT=1 docker build --secret ...。

当前 Docker 镜像发布 workflow 会使用 cozsweet-act-runner-node24-docker:latest 作为 job 容器，确保 actions/checkout@v4 执行时已经存在 Node.js，并且容器内已经包含 Docker CLI。runner 仍然需要挂载宿主机 Docker socket：

volumes:
  - /var/run/docker.sock:/var/run/docker.sock

自定义 runner job 镜像的构建方式见 Gitea Runner Job 镜像。

验证方式

推送到 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 登录地址一致。

部署服务器拉取镜像

当前推荐由 Gitea Actions 通过 SSH 登录部署服务器并执行部署脚本，不再依赖服务器 Git remote 的 post-receive hook。完整说明见 Gitea Actions SSH 部署流程。

如果需要在服务器上手动验证镜像拉取，可先登录镜像仓库：

docker login REGISTRY_HOST

Actions 部署时会根据当前分支和 commit 自动拉取：

gitea.banlv-ai.com/admin/cozsweet-web:test-<short_sha>
gitea.banlv-ai.com/admin/cozsweet-web:prod-<short_sha>

推荐优先使用默认的 <env>-<short_sha> 精确 tag，这样发布和回滚都更可控。

镜像保留策略

镜像推送成功后，workflow 会调用 Gitea Package API 清理远端 Container Registry：

• test-* 精确 tag 只保留最近 3 个，test-latest 不计入也不删除。
• prod-* 精确 tag 只保留最近 3 个，prod-latest 不计入也不删除。
• 当前刚推送的 IMAGE_VERSION_TAG 永远不会被删除。

SSH 部署成功后，服务器本机只保留当前环境正在运行的一个精确版本镜像；测试环境清理旧 test-*，生产环境清理旧 prod-*。