160 lines
6.4 KiB
Markdown
160 lines
6.4 KiB
Markdown
# 开发/测试环境 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/)。
|