ci(docker): prune old image versions

docs/docker-image-ci.md

@@ -23,6 +23,8 @@
 | `REGISTRY_IMAGE` | `gitea.banlv-ai.com/admin/cozsweet-web` | 完整镜像仓库名，不包含 tag |
 | `REGISTRY_USERNAME` | `cozsweet-bot` | 镜像仓库用户名 |
 | `REGISTRY_PASSWORD` | `***` | 镜像仓库密码或访问令牌 |
+| `GITEA_API_BASE_URL` | `https://gitea.banlv-ai.com/api/v1` | Gitea API 地址，用于清理旧镜像版本 |
+| `GITEA_PACKAGE_TOKEN` | `***` | 具备 package 删除权限的 Gitea token |
 | `TEST_ENV_FILE` | `.env.local` 的完整内容 | 测试环境构建期环境变量 |
 | `PRODUCTION_ENV_FILE` | `.env.production` 的完整内容 | 生产环境构建期环境变量 |
 
@@ -106,3 +108,13 @@ 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 部署成功后，服务器本机只保留当前正在运行的一个 `prod-*` 镜像；测试环境服务器本机暂不限制保留数量。