9.3 KiB
测试环境 Jenkins 部署指南
最后核对：2026-08-08
本文供 Codex 对话和项目维护人员部署虫虫出海测试环境使用。只适用于测试环境，不适用于预发布或生产。
1. 持续授权与执行边界
用户已明确授权：当前任务确实需要把已完成的变更部署到测试环境时，Codex 可以直接触发与变更范围对应的 Jenkins 测试 Job，不必再次等待“是否部署”的确认。
出现以下任一情况，可以直接部署：
- 用户明确要求部署、发布测试环境或验证测试环境。
- 当前任务的完成标准包含远端联调、测试环境回归或浏览器验收。
- 已修复测试环境问题，必须部署后才能验证修复结果。
此授权不包含以下操作；遇到时必须单独取得用户明确确认：
- 部署
staging或production。 - 勾选
INITIALIZE_TEST_DATABASE，或执行任何数据库写入、迁移、初始化和测试数据修改。 - 勾选
SKIP_TESTS。 - 无法明确影响范围时执行后端
ALL全量部署。 - 修改 Jenkins Job、Credentials、节点、插件、权限或系统配置。
- 删除构建、停止他人正在执行的构建、回滚环境或清理容器/数据。
普通本地代码任务不因为存在 Jenkins 就自动部署。只有部署是用户要求或当前任务验收所必需时，才使用本授权。
2. 环境与认证
| 项目 | 地址或标识 |
|---|---|
| Jenkins | http://8.163.30.128:14808/ |
| Jenkins 用户 | admin |
| 测试 Gateway | http://8.163.30.128:9000 |
| Admin Web | http://8.163.30.128:9001 |
| Client Web | http://8.163.30.128:9002 |
| 后端 Git 分支 | test |
| Admin/Client Git 分支 | release/test |
本文不保存 Jenkins 密码、API Token 或 Cookie。优先复用已登录的受控浏览器会话；没有登录会话时，从用户明确提供的安全来源获取凭据。不得把凭据写入仓库、命令行历史、脚本、日志或交付说明。
Jenkins 页面会显示“系统管理”“新建任务”“配置”“删除 Pipeline”等管理入口。即使当前账号具有管理权限，也只能执行本任务所需的构建和只读检查。
3. Job 与部署单元
| 部署单元 | Jenkins Job | 源码目录 | 流水线行为 |
|---|---|---|---|
| Admin Web | admin-web-test |
apps/admin-web/ |
拉取 release/test，构建镜像，重建容器，执行容器内 /healthz |
| Client Web | client-web-test |
apps/client-web/ |
拉取 release/test，构建镜像，重建容器，执行容器内 /healthz |
| 后端总控 | backend-java |
baiyue-firstleg/ |
选择变更服务并行调度下游 Job；测试环境使用 Jenkins 节点本机镜像 |
后端下游 Job：
baiyue-firstleg-gatewaybaiyue-firstleg-authbaiyue-firstleg-iambaiyue-firstleg-firstlegbaiyue-firstleg-orderbaiyue-firstleg-warehousebaiyue-firstleg-filebaiyue-firstleg-printbaiyue-firstleg-integration-servicebaiyue-firstleg-event-bridge-servicebaiyue-firstleg-audit-service
正常部署后端时从 backend-java 总控 Job 发起。下游 Job 主要由总控调度；只有重跑同一提交的单个失败服务且已核对全部参数时，才直接操作下游 Job。
4. 部署前强制检查
- 阅读目标项目及目标模块的
AGENTS.md，确认任务允许修改和部署该单元。 - 检查工作区状态，区分当前任务变更与用户已有变更。不得擅自提交或部署无关改动。
- 运行目标项目声明的测试和构建门禁：
- Admin：至少运行受影响测试、
pnpm typecheck和pnpm build；交付部署前优先运行pnpm test。 - Client：至少运行
pnpm typecheck、受影响测试和pnpm build；交付部署前优先运行pnpm test。 - Backend：优先运行
mvn -pl <module> -am test；公共模块或跨服务变更按影响范围扩大验证。
- Admin：至少运行受影响测试、
- 确认待部署代码已经提交并推送到 Jenkins 实际拉取的远端分支。Jenkins 无法部署本地未提交或未推送的文件。
- 记录准备部署的仓库、分支、完整 commit SHA、Job 和后端服务列表。
- 在触发前通过 commentary 告知用户即将部署的 Job、commit 和范围。该通知不是等待确认；符合第 1 节授权时可继续执行。
- 检查 Jenkins 构建队列和执行器。不得覆盖或中断他人构建；同一 Job 正在构建时等待其结束，再重新核对远端提交。
如果当前工作区包含其他人的未提交改动，只有在能够证明远端目标 commit 仅包含本任务变更时才可部署。无法隔离时停止并说明阻断。
5. 前端部署
Admin 和 Client Job 无部署参数，触发后会直接构建并重建对应测试容器。因此触发前必须确认远端 release/test HEAD 就是目标提交。
Admin
- 打开
admin-web-test。 - 核对最近构建、当前队列和远端
release/test目标提交。 - 触发“立即构建”。
- 等待构建进入终态，不得只看到进入队列就结束任务。
- 成功后检查
http://8.163.30.128:9001/healthz返回 HTTP 200 和ok。
Client
- 打开
client-web-test。 - 核对最近构建、当前队列和远端
release/test目标提交。 - 触发“立即构建”。
- 等待构建进入终态。
- 成功后检查
http://8.163.30.128:9002/healthz返回 HTTP 200 和ok。
前端 /healthz 只证明容器和 Nginx 正常。任务涉及登录、接口或业务页面时，还必须按当前任务执行对应 Gateway 请求或浏览器业务验收。
6. 后端部署
打开 backend-java，选择 “Build with Parameters”。测试环境常规部署使用以下参数：
| 参数 | 常规值 | 说明 |
|---|---|---|
BUILD_MODE |
SELECT 或已核对后的 AUTO |
优先显式选择受影响服务；确认提交差异完整时可用 AUTO |
SERVICE_* |
仅勾选受影响服务 | SELECT 模式至少选择一个 |
ENVIRONMENT |
test |
本文禁止改为其他环境 |
DEPLOY |
true |
否则只构建镜像，不更新测试容器 |
INITIALIZE_TEST_DATABASE |
false |
修改数据库，未经单独确认不得开启 |
SKIP_TESTS |
false |
未经单独确认不得跳过测试 |
IMAGE_REPOSITORY |
保持测试默认值 | test 会解析为 baiyue-firstleg-test |
DOCKER_BASE_IMAGE |
保持 Job 默认值 | 除非任务明确要求变更基础镜像 |
DOWNSTREAM_JOB_PREFIX |
baiyue-firstleg- |
与现有 11 个下游 Job 对应 |
选择规则：
- 单服务业务代码：选择该服务，并检查内部客户端或契约消费者是否也需要部署。
common-*、父pom.xml、platform-bom/、Jenkinsfile*或deploy/变化：AUTO会选择全部 11 个服务；全量部署前仍需按第 1 节取得确认。- Gateway 路由、CORS 或访问域变化：选择
gateway，并检查受影响业务服务。 - 跨服务 DTO/OpenAPI/内部客户端变化：同时选择生产者和消费者。
- 数据库结构变化：不能仅部署服务。先按数据库变更规则取得明确授权并完成迁移，再部署依赖该结构的服务。
- File 服务部署依赖 Jenkins 文件凭据
firstleg-test-env中有效的ROCKETMQ_NAME_SERVER，且MQ_TOPIC_PREFIX必须为test-。
总控 Job 成功不应只看主任务颜色。必须核对描述或日志中的每个下游结果均为 SUCCESS。出现任一 FAILURE 时，总控可能显示 UNSTABLE；这种情况视为部署失败。
7. 部署后验证
每次部署至少完成以下检查：
- Jenkins Job 已进入终态，记录构建号、结果、commit 和耗时。
- 后端总控部署记录全部下游 Job 名称、构建号和结果。
- 前端健康检查：
GET http://8.163.30.128:9001/healthzGET http://8.163.30.128:9002/healthz
- 后端入口检查：
GET http://8.163.30.128:9000/actuator/health返回 HTTP 200。 - 执行与变更直接相关的真实 API 或浏览器流程。健康检查不能代替业务验收。
- 失败响应记录 HTTP 状态、业务错误码、
requestId、traceId和阻断原因。
不得因为 Jenkins 成功就宣称业务验收通过，也不得让测试失败回退为模拟成功。
8. 失败处理
- 构建失败：读取失败阶段和控制台日志，定位第一个有效错误；修复并完成本地验证后，用新 commit 重新部署。
- 下游服务失败：记录失败的服务 Job 和构建号，检查 Maven 测试、镜像构建、环境凭据及 Docker Compose 输出。
- 部署成功但健康检查失败：检查对应 Job 的容器状态和末尾日志，不切换为本地后端。
- 健康检查成功但业务失败：记录请求证据，核对数据库迁移、Nacos 配置、服务注册和真实接口契约。
- 不得在未确认影响的情况下通过跳过测试、初始化数据库、清理工作区外数据或全量重启来“试一下”。
失败后不要自动回滚、删除容器或修改测试数据。需要这些动作时先向用户说明具体目标、影响和恢复方案并取得确认。
9. 交付记录
部署完成后，最终回复至少包含：
- 部署的环境、Job 和服务范围。
- 分支与 commit SHA。
- Jenkins 构建号及最终结果。
- 健康检查和直接业务验证结果。
- 任何失败、跳过项、残余风险及
requestId/traceId。
不要在回复中输出密码、Token、Cookie、Jenkins Credential 内容或环境文件内容。