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-*` 镜像；测试环境服务器本机暂不限制保留数量。

docs/gitea-actions-ssh-deploy.md

@@ -29,6 +29,8 @@ push test/main
 | `REGISTRY_IMAGE` | 镜像仓库，例如 `gitea.banlv-ai.com/admin/cozsweet-web` |
 | `REGISTRY_USERNAME` | registry 用户名 |
 | `REGISTRY_PASSWORD` | registry 密码或 token |
+| `GITEA_API_BASE_URL` | Gitea API 地址，例如 `https://gitea.banlv-ai.com/api/v1` |
+| `GITEA_PACKAGE_TOKEN` | 具备 package 删除权限的 Gitea token，用于清理旧镜像 tag |
 | `TEST_ENV_FILE` | 测试环境 `.env.local` 内容 |
 | `PRODUCTION_ENV_FILE` | 生产环境 `.env.production` 内容 |
 
@@ -61,6 +63,19 @@ deploy-docker-image.sh
 .env.local 或 .env.production
 ```
 
+## 镜像保留策略
+
+Actions 推送镜像后会清理 Gitea Container Registry，同一环境只保留最近 3 个精确版本 tag：
+
+```text
+test-<short_sha> 最近 3 个
+prod-<short_sha> 最近 3 个
+```
+
+`test-latest` / `prod-latest` 不计入保留数量，也不会主动删除。
+
+生产环境部署脚本会在 `docker compose up` 成功后清理服务器本机旧镜像，只保留当前 `prod-<short_sha>` 镜像。测试环境服务器本机镜像暂不限制保留数量。
+
 ## 本地发布入口
 
 本地发布脚本现在只负责推送 Gitea 分支，触发 Actions：