docs/测试环境Jenkins部署指南.md

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

最后核对：2026-08-25

只适用于当前开发、测试阶段。生产环境启用后必须重新收紧权限、轮换并移除开发 Token。

1. 使用场景

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

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

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

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

2. 本机一次性配置

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

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

文件格式：

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。

连通性检查：

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 前端

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 后端

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

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 是队列地址：

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：

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。

失败时读取：

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、Jenkins CSRF Protection。