# 开发/测试环境 Jenkins API 自动部署指南

> 最后核对：2026-08-25
>
> 只适用于当前开发、测试阶段。生产环境启用后必须重新收紧权限、轮换并移除开发 Token。

## 1. 使用场景

本指南用于长时间全量测试或夜间任务。用户在当前对话明确要求“持续修复并部署”“自动部署并测试”或等价表述后，工具可以在本次授权范围内循环执行：

`定位失败 → 修改代码 → 本地门禁 → 提交并推送 → API 部署 → 等待终态 → 健康/业务验收 → 继续修复`

同一轮任务不需要每次提交或重试都重新询问。以下情况仍必须停下确认：

- 涉及预发布或生产环境。
- 需要执行 SQL、初始化数据库、修改真实数据或清理容器/数据。
- 需要跳过测试、停止他人构建或扩大到未授权服务。
- 缺少环境凭据，或连续三次遇到同一个外部阻断。

## 2. 本机一次性配置

Jenkins API 信息固定保存在以下未提交文件：

`C:/Users/BY-OY/.codex/jenkins-api.env`

文件格式：

```dotenv
JENKINS_URL=https://jenkins.example.com
JENKINS_USER=admin
JENKINS_API_TOKEN=replace-with-current-development-token
DEV_GATEWAY_URL=https://dev-api.example.com
TEST_GATEWAY_URL=https://test-api.example.com
```

工具直接读取该文件，不把 Token 输出到 commentary、最终回复、命令日志或仓库。使用 API Token 的 Jenkins 请求不需要 CSRF Crumb。

连通性检查：

```bash
curl -fsS --user "$JENKINS_USER:$JENKINS_API_TOKEN" \
  "${JENKINS_URL%/}/api/json?tree=nodeName,mode"
```

## 3. Job 对照

| 环境 | 后端总控 | Admin | Client | 后端分支 | 下游前缀 |
|---|---|---|---|---|---|
| 开发 | `backend-java-dev` | `admin-web-dev` | `client-web-dev` | `dev` | `baiyue-firstleg-dev-` |
| 测试 | `backend-java` | `admin-web-test` | `client-web-test` | `test` | `baiyue-firstleg-` |

后端可部署服务：

`gateway`、`gateway-overseas`、`auth`、`iam`、`firstleg`、`finance`、`order`、`warehouse`、`file`、`print`、`integration-service`、`lastleg-service`、`warehouse-overseas-service`、`event-bridge-service`、`audit-service`。海外安全投影随 `lastleg-service` 部署，不再有独立 Job。

正常从总控 Job 发起。只有重跑同一提交的单个失败服务时，才直接触发下游 Job。

## 4. API 触发

### 4.1 前端

```bash
curl -fsS -X POST \
  --user "$JENKINS_USER:$JENKINS_API_TOKEN" \
  -D build.headers -o /dev/null \
  "${JENKINS_URL%/}/job/admin-web-dev/build"
```

按目标环境和应用替换 Job 名称。

### 4.2 后端

开发环境选择两个服务的示例：

```bash
curl -fsS -X POST \
  --user "$JENKINS_USER:$JENKINS_API_TOKEN" \
  -D build.headers -o /dev/null \
  --data-urlencode 'BUILD_MODE=SELECT' \
  --data-urlencode 'SERVICE_GATEWAY_OVERSEAS=true' \
  --data-urlencode 'SERVICE_LASTLEG=true' \
  --data-urlencode 'ENVIRONMENT=development' \
  --data-urlencode 'DEPLOY=true' \
  --data-urlencode 'SKIP_TESTS=false' \
  --data-urlencode 'EVENT_BRIDGE_REGION=BOTH' \
  --data-urlencode 'DOWNSTREAM_JOB_PREFIX=baiyue-firstleg-dev-' \
  "${JENKINS_URL%/}/job/backend-java-dev/buildWithParameters"
```

规则：

- 日常优先 `AUTO`；明确修复单个或少量服务时使用 `SELECT`。
- `SELECT` 只把目标 `SERVICE_*` 设为 `true`，其余保持 `false`。
- `ALL` 只用于用户明确授权的全量部署。
- 开发环境固定 `ENVIRONMENT=development`；测试固定 `ENVIRONMENT=test`。
- 开发/测试默认 `DEPLOY=true`、`SKIP_TESTS=false`。
- 事件桥默认 `BOTH`；单区故障重跑才使用 `CN` 或 `OVERSEAS`。
- 不在 API 参数中传密码、数据库凭据或服务 Token。

## 5. 自动等待终态

触发响应的 `Location` 是队列地址：

```bash
QUEUE_URL="$(awk 'BEGIN{IGNORECASE=1} /^Location:/{gsub("\r",""); print $2}' build.headers)"
curl -fsS --user "$JENKINS_USER:$JENKINS_API_TOKEN" \
  "${QUEUE_URL%/}/api/json?tree=id,why,cancelled,executable[number,url]"
```

出现 `executable.url` 后，将其作为 `BUILD_URL`：

```bash
curl -fsS --user "$JENKINS_USER:$JENKINS_API_TOKEN" \
  "${BUILD_URL%/}/api/json?tree=number,building,result,url,duration,estimatedDuration"
```

每 5–10 秒轮询一次。只有 `building=false` 且 `result=SUCCESS` 才成功；进入队列、拿到构建号或 HTTP POST 成功都不算完成。后端总控还必须确认每个下游 Job 都是 `SUCCESS`。

失败时读取：

```bash
curl -fsS --user "$JENKINS_USER:$JENKINS_API_TOKEN" \
  "${BUILD_URL%/}/consoleText"
```

删除本次产生的临时 `*.headers` 文件，不提交。

## 6. 夜间自动闭环

1. 记录目标环境、服务和远端 commit。
2. 运行直接受影响的本地测试；签名变化必须编译测试源码。
3. 只提交当前修复文件并推送目标分支。
4. 用 API 触发对应 Job，保存队列 URL、构建 URL 和构建号。
5. 等待总控及全部下游进入终态。
6. 失败时读取第一个有效错误，修改后使用新 commit 再部署。
7. 网络抖动、镜像拉取等瞬时基础设施错误允许同一提交重试，最多两次。
8. 部署成功后检查 Gateway `/actuator/health`，再执行本轮真实 API/全量测试。
9. 全部通过后汇总 commit、构建号、服务结果和验收结果。

不要因为某个服务失败就盲目重跑全量；优先修复并只重跑失败服务。部署脚本会在新容器不健康时自动回滚，任务仍视为失败。

## 7. 快速故障判断

| 现象 | 处理 |
|---|---|
| `401` | 检查本机 API Token 和反向代理 `Authorization` 头 |
| `403` | 检查 Job Read/Build 权限；不要关闭 CSRF |
| `400` | 参数名或 Choice 值与当前 Job 不一致 |
| 队列长期等待 | 查询队列 `why`，检查节点、执行器和部署锁 |
| Maven/测试失败 | 修复代码并产生新 commit，不跳过测试 |
| 容器不健康 | 读取 Job 自动采集的容器日志和回滚结果 |
| 镜像被其他任务覆盖 | 核对同服务部署锁和实际运行镜像标签 |
| 总控成功但下游失败 | 整体仍按失败处理，只重跑失败服务 |

## 8. 完成记录

最终只需记录：环境、Job、服务、分支、commit、Jenkins 构建号、最终结果、健康检查、业务验收及剩余阻断。不得输出 Token、Cookie、Jenkins Credential 或环境文件内容。

参考：[Jenkins Remote Access API](https://www.jenkins.io/doc/book/using/remote-access-api/)、[Jenkins CSRF Protection](https://www.jenkins.io/doc/book/security/csrf-protection/)。