fix(ci): 绑定分支与部署环境并加固 IMAGE_TAG 传递

- dev 仅允许 dev 分支，prod 仅允许 master/main，防止 master 代码进 lpt-dev
- IMAGE_TAG 同时写 GITHUB_ENV/GITEA_ENV 与工作区文件兜底
- 更新部署说明文档

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

DEPLOYMENT_PROGRESS.md

@@ -1,100 +1,72 @@
 # 部署流水线问题排查进度
 
-**日期**: 2026-07-19
+**日期**: 2026-07-20（更新）
 
-## 问题概述
+## 当前部署方式
 
-K8s 部署时出现 `ImagePullBackOff` 错误，容器无法拉取私有 Registry 镜像。
+- **Jenkinsfile / Jenkinsfile-dev**：历史方案，已不再作为主路径
+- **现行方案**：Gitea Actions（`.gitea/workflows/deploy.yml`）  
+  手动 `workflow_dispatch` → 构建镜像 → 推私有 Registry → `kubectl set image` 到 K8s
 
-## 根本原因
+## 分支 ↔ 环境约定（已写入 workflow 强制校验）
 
-**Docker Registry 认证问题**：
-- Registry (`192.168.123.199:5000`) 需要认证（用户名: `admin`）
-- Gitea Actions workflow 使用 `secrets.REGISTRY_USERNAME` 和 `secrets.REGISTRY_PASSWORD`
-- **这两个 secrets 在 Gitea 项目中尚未配置**，导致：
-  1. workflow 的 `docker login` 失败
-  2. `docker push` 虽然执行但实际未推送成功
-  3. K8s 拉取镜像时认证失败 → `authorization failed: no basic auth credentials`
+| 仓库 | 部署 dev (`lpt-dev`) | 部署 prod (`lpt-prod`) |
+|------|----------------------|-------------------------|
+| **lpt-fe** | 必须在 **`dev` 分支** 上 Run | 必须在 **`master`/`main`** 上 Run |
+| **lpt-be** | 必须在 **`dev` 分支** 上 Run | 必须在 **`master`/`main`** 上 Run |
+| **lpt-ai** | 仅有 **`main`**，从 main 部署到 dev | 从 **main** 部署到 prod |
 
-## 已完成的修复
+在错误分支上选择 environment 会在第一步直接失败，避免「dev 环境跑了 master 代码」。
 
-### 1. Gitea Actions 配置修复（已推送）
-- ✅ **lpt-fe**: 修复 `github.sha` → `gitea.sha`
-- ✅ **lpt-be**: 修复 `github.sha` → `gitea.sha`，kubectl 版本改为 `v1.30.0`
-- ✅ **lpt-ai**: 修复 `github.sha` → `gitea.sha`，kubectl 版本改为 `v1.30.0`
+### 正确操作
 
-### 2. K8s Deployment 修复（已推送）
-- ✅ 所有 Deployment YAML 添加 `imagePullSecrets: [name: regcred]`
-- ✅ workflow 自动创建 `regcred` secret（使用 Gitea secrets）
+1. Gitea 仓库页面切换到目标分支（fe/be 的 dev 或 master）
+2. Actions → 对应 workflow → Run workflow
+3. 选择 `environment` = `dev` 或 `prod`（须与当前分支匹配）
 
-### 3. Git 合并冲突
-- ⚠️ **lpt-ai** 和 **lpt-be** 的 workflow 文件存在合并冲突标记
-- 需要手动解决冲突后重新提交
+## 已修复项（2026-07-20）
 
-## 待完成任务
+1. **分支与环境绑定校验** — 三个仓库的 `deploy.yml` 增加 Validate 步骤  
+2. **`IMAGE_TAG` 持久化** — 除 `GITHUB_ENV` 外，写入 `GITEA_ENV`（若存在）+ 临时文件兜底，Deploy 步读取失败则明确报错  
+3. **fe `BUILD_MODE`** — 在 shell 内根据 environment 设置 `production` / `development`，避免表达式兼容问题  
+4. **lpt-fe `dev` 分支同步** — 将 master 合并进 dev，保证 dev 上也有完整 workflow 与最新代码  
 
-### 关键步骤：配置 Gitea Secrets
+## 历史问题（部分仍可能相关）
 
-需要在 Gitea 中为每个项目添加 Registry 认证信息：
+### Registry / Secrets
 
-**项目列表**:
-- `lpt-fe`
-- `lpt-be`
-- `lpt-ai`
+若出现 `ImagePullBackOff` / `docker login` 失败，检查各仓库 Gitea Secrets：
 
-**操作步骤**（每个项目重复）:
-1. 进入项目页面（如 `http://192.168.123.199:3000/cat/lpt-fe`）
-2. Settings → Secrets
-3. 添加两个 secrets：
-   - Name: `REGISTRY_USERNAME`, Value: `admin`
-   - Name: `REGISTRY_PASSWORD`, Value: `<htpasswd 对应的明文密码>`
+- `REGISTRY_USERNAME`（如 `admin`）
+- `REGISTRY_PASSWORD`
+- `KUBECONFIG_B64`（kubeconfig 的 base64）
 
-**Registry 密码位置**: `/vol1/1000/registry/auth/htpasswd`（服务器 `192.168.123.199`）
+Registry: `192.168.123.199:5000`
 
-### 次要任务
+### K8s
 
-1. **解决 Git 合并冲突**
-   - 文件: `lpt-ai/.gitea/workflows/deploy.yml:34-40`
-   - 文件: `lpt-be/.gitea/workflows/deploy.yml:43-48`
-   - 清理 `<<<<<<< HEAD`, `=======`, `>>>>>>> xxx` 标记
+- 共享清单：`k8s/dev/*`、`k8s/prod/*`（按环境）
+- 各服务仓库内 `k8s/` 仍多为 `lpt-dev` 模板；日常 CI 只 `set image`，不 `apply` 整份 YAML
+- Deployment 需有 `imagePullSecrets: [regcred]`；workflow 每次会 create/update `regcred`
 
-2. **验证部署**
-   - 配置 secrets 后触发一次提交
-   - 检查 workflow 日志中 `docker login` 和 `docker push` 是否成功
-   - 检查 K8s Pod 是否正常启动：`kubectl get pods -n lpt`
+## 镜像与命名空间
 
-## 其他发现的问题（非紧急）
+| environment | 镜像 tag（浮动） | 不可变 tag | namespace |
+|-------------|------------------|------------|-----------|
+| dev | `app:dev` | `app:<sha>-<unix>` | `lpt-dev` |
+| prod | `app:prod` | `app:<sha>-<unix>` | `lpt-prod` |
 
-### Jenkins 流水线（lpt-fe, lpt-be）
-- 硬编码镜像标签（`0.0`），无法追溯版本
-- lpt-be 健康检查时间过短（5秒），Spring Boot 启动通常需要 10-30 秒
-- lpt-be Docker 网络配置可能冲突
+部署使用不可变 tag，避免 `imagePullPolicy` 与缓存导致未更新。
 
-### 流水线通用问题
-- 缺少镜像清理机制
-- 缺少部署失败回滚机制
+## 验证清单
 
-## 技术细节
-
-### Registry 认证验证
-```bash
-curl -I http://192.168.123.199:5000/v2/
-# 返回: 401 Unauthorized
-# Www-Authenticate: Basic realm="Registry Realm"
-```
-
-### htpasswd 文件内容
-```
-admin:$2y$05$PlW.emHsl9qePGTsQPNAzecCkyNWKFO252EpjcRNV9vC8Z9AkGGZ.
-```
-
-## 下一步操作清单
-
-1. [ ] 在 Gitea 中配置 3 个项目的 Registry secrets
-2. [ ] 解决 lpt-ai 和 lpt-be 的 workflow 合并冲突
-3. [ ] 提交修复并触发 workflow
-4. [ ] 验证部署成功
+1. [ ] 三仓库 Secrets 已配置  
+2. [ ] lpt-fe：在 **dev** 分支 Run → environment=dev 成功  
+3. [ ] lpt-fe：在 **master** 上选 environment=dev 应 **失败**（校验）  
+4. [ ] lpt-be：同上  
+5. [ ] lpt-ai：在 **main** 上 Run → dev / prod  
+6. [ ] `kubectl get pods -n lpt-dev` / `lpt-prod` 正常  
 
 ---
 
-**备注**: 所有 K8s 配置文件修改已完成并推送到 Gitea，核心问题在于 Gitea Secrets 配置缺失。
+**备注**: 主路径为 Gitea Actions + K8s；Jenkins 配置可保留作参考，勿与现行流程混用。