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

TEST 环境 Jenkins 部署指南

更新日期：2026-09-29。本指南描述唯一 TEST 单机目标；仓库配置已收敛不表示实际服务器已部署。统一架构切换与验收以测试环境单机部署与配置契约为准。

授权与边界

默认只做本地修改与离线检查。实际Jenkins构建发布、Nacos发布、SQL和清理分别落实本轮授权范围；本指南不授予持续部署权限。不得读取或覆盖其他任务维护的真实生产/测试凭据。运行事实与本目标不一致时先核对，不自行改名或删除运行环境。

唯一发布入口

对象	入口
后端总控	backend-java，仓库 baiyue-firstleg/Jenkinsfile
后端单服务	baiyue-firstleg-<module>，Jenkinsfile.service
构建/部署节点	java-builder / 同机 java-test
环境凭据	Jenkins Secret File firstleg-test-env，真实值不入库
服务与镜像列表	service-map.yml
Compose	docker-compose.yml，项目 firstleg-test
环境模板	.env.test.example
Nacos	config/nacos/test，14个Data ID、一个实际Namespace ID
执行顺序与恢复	TEST单机部署执行清单

保留13个服务：gateway、auth、iam、order、firstleg、finance、warehouse、warehouse-overseas-service、lastleg-service、file、print、audit-service、integration-service。Gateway Overseas、两区Event Bridge不在新发布清单。停旧服务必须等统一认证、直接投递、撤销和四端切换验证完成；源码退役不等于获准停止当前服务。

旧开发/生产Job不再匹配当前流水线，不能借环境参数使本版本执行生产部署。已有其他环境应由其独立明确授权任务处理，不在本次TEST发布中操作。

参数与门禁

总控支持AUTO、SELECT、ALL。AUTO保留失败服务重试与直接依赖识别；架构首次切换使用审核后的完整匹配发布清单，不以AUTO遗漏服务。ENVIRONMENT仅test，下游前缀仅baiyue-firstleg-。DEPLOY默认false；IMAGE_REPOSITORY首次在各Job参数默认值中配置已核镜像仓库，后续流水线沿用当前Job参数值，不在每次构建后重置为空；总控仍明确向下游传递本次地址。更换仓库才需修改，空值、示例域名与格式校验仍保留，不在源码固定环境地址。DOCKER_BASE_IMAGE由构建节点可访问的Java17镜像提供。不得将凭据拼入参数、URL或日志。

默认执行Maven测试；仅明确选择SKIP_TESTS时跳过执行，仍编译测试源码。总控先统一测试，再向固定commit的单服务任务传递跳过重复执行。发布前还须完成网关路由、部署拓扑、失败回滚和受影响前端合同。离线检查不能证明镜像健康或HTTP闭环。

总控 TEST_SCOPE=AUTO 在单个 Lastleg 的可追踪局部 Java 变更中，按反向类型引用、接口实现、测试夹具和变更写入 SQL 的同表消费者选择测试；公开契约变更追加相关静态合同。基线仅取带有新门禁通过标记、确实测试了目标服务的成功构建；跳过测试、失败、取消或仅测过其他服务的构建均不能作基线。公共模块、共享模型、配置、Schema、未知路径、多服务、其他服务或基线不可用时保持完整模块测试；TEST_SCOPE=MODULE 可显式执行完整回归，临时灰度始终保持 MODULE。完整生产和测试源码编译及既有 1GB/单 fork/类隔离不变。定向测试必须逐类取得本轮非零执行报告；真实环境 opt-in 类单独列为未执行，不计为通过，仍由完整模块/专项授权入口负责。此静态筛选不能发现所有运行时耦合，涉及未被 Java/SQL 引用表达的跨业务影响时须选 MODULE。首次发布本次流水线变更需先执行完整模块测试建立新基线。流水线/发布脚本变化仍命中既有 AUTO 全服务规则，首次可使用 SELECT 仅选 Lastleg、TEST_SCOPE=MODULE 建立基线；后续 AUTO 才按关联范围执行。精确耗时以部署后 Jenkins 为准。

同机测试代理的执行器数量固定为1，避免构建与其他重任务挤占业务服务。总控测试和单服务打包还必须共用 firstleg-test-maven 跨Job锁，经 deploy/scripts/run-ci-maven.sh 执行；仅 disableConcurrentBuilds() 不能限制不同Job并发。入口按同一构建账号使用本机flock，控制端掉线后已有任务仍持锁时拒绝再起Maven，不删除锁文件绕过互斥。部署的SOURCE_COMMIT必须包含此入口及 ci-bounded POM配置，旧提交缺少防护时应失败，不能回退到裸mvn。

当前初始预算：Maven堆768MiB、测试堆1GiB、单测试fork，并分别限制元空间和直接内存；Surefire保留JaCoCo，启用父进程心跳检查、停止时kill、fork运行20分钟和退出30秒上限。宿主机GNU timeout提供45分钟期限及30秒强制终止，Jenkins内部另设50分钟上限。预算不是总RSS保证，须在真实Linux节点核对代理内存、memory.events/pressure和完整服务测试峰值；不足时按证据调整，不能重新放开三个Maven并发，也不能仅提高MemoryHigh挤占业务服务。代理服务保持 KillMode=control-group、SendSIGKILL=yes；代理掉线或构建中止后，先检查该服务cgroup是否仍有构建/测试子进程，确认退出再恢复，不把Job的ABORTED当作进程已清理。

单服务任务在取目标节点执行器前锁定对应服务，目标节点通过同一env文件拉镜像并更新容器。没有HEALTHCHECK、启动失败、不健康、退出或超时均判失败。只有同协议同Schema版本才可显式启用ALLOW_SAME_CONTRACT_ROLLBACK；架构切换保持false，恢复原则见执行清单。

配置与端侧

容器共用firstleg-test-network；同网络Web Nginx使用http://gateway:9000。Gateway宿主机发布仅127.0.0.1，业务服务只内部expose。Auth使用http://auth:9100，不能把Nacos应用名当Docker DNS。宿主机中间件通过host.docker.internal访问，不能使用容器localhost。

所有服务使用同一Nacos Namespace ID/Group、Redis DB与会话前缀。Auth独占签名私钥；JWKS和内部会话验证共用Auth。EVENT_OPERATIONS_TOKEN独立于内部业务令牌，留空禁用运维操作。现有文件卷和非桥业务MQ保留，topic/group使用test-前缀。

Admin与Client各自Compose项目共接后端网络，发布必须给出CLIENT_WEB_URL/VITE_ADMIN_WEB_ORIGIN；两个PDA保留独立产物及仓绑定。域名、Namespace ID、MQ范围、数据卷和主机容量必须据实际清单核实，不能用模板默认值充当验收。

发布与验收

按执行清单记录镜像、配置、SQL与四端版本，在停写窗口发布完整匹配版本。SQL不由Compose/Jenkins自动运行，初始化脚本仅接受两份显式审核的空库基线并受授权开关保护。禁止整机清空Redis/MQ/文件。

启动就绪后先验证统一登录/撤销/隔离/仓绑定、资源查询和文件，再用新造数据验证装柜至尾程、资金指令结果回传及故障恢复。真实API通过后还需页面/PDA验收。未部署、未验证项目必须明确标记；不能以Job成功替代整条业务链完成。