# 部署流水线问题排查进度

**日期**: 2026-07-20（更新）

## 当前部署方式

- **Jenkinsfile / Jenkinsfile-dev**：历史方案，已不再作为主路径
- **现行方案**：Gitea Actions（`.gitea/workflows/deploy.yml`）  
  手动 `workflow_dispatch` → 构建镜像 → 推私有 Registry → `kubectl set image` 到 K8s

## 分支 ↔ 环境约定（已写入 workflow 强制校验）

| 仓库 | 部署 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 仓库页面切换到目标分支（fe/be 的 dev 或 master）
2. Actions → 对应 workflow → Run workflow
3. 选择 `environment` = `dev` 或 `prod`（须与当前分支匹配）

## 已修复项（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 与最新代码  

## 历史问题（部分仍可能相关）

### Registry / Secrets

若出现 `ImagePullBackOff` / `docker login` 失败，检查各仓库 Gitea Secrets：

- `REGISTRY_USERNAME`（如 `admin`）
- `REGISTRY_PASSWORD`
- `KUBECONFIG_B64`（kubeconfig 的 base64）

Registry: `192.168.123.199:5000`

### K8s

- 共享清单：`k8s/dev/*`、`k8s/prod/*`（按环境）
- 各服务仓库内 `k8s/` 仍多为 `lpt-dev` 模板；日常 CI 只 `set image`，不 `apply` 整份 YAML
- Deployment 需有 `imagePullSecrets: [regcred]`；workflow 每次会 create/update `regcred`

## 镜像与命名空间

| environment | 镜像 tag（浮动） | 不可变 tag | namespace |
|-------------|------------------|------------|-----------|
| dev | `app:dev` | `app:<sha>-<unix>` | `lpt-dev` |
| prod | `app:prod` | `app:<sha>-<unix>` | `lpt-prod` |

部署使用不可变 tag，避免 `imagePullPolicy` 与缓存导致未更新。

## 验证清单

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` 正常  

---

**备注**: 主路径为 Gitea Actions + K8s；Jenkins 配置可保留作参考，勿与现行流程混用。