Jenkins 是自动化构建与持续集成工具，ONES 通过原生流水线集成读取 Jenkins 流水线的状态、运行步骤和日志，并把流水线关联到项目与迭代。本文针对国内版公有云产品手册所述条件，私有部署按文内条件执行；所读手册标注的 Jenkins 版本区间为 2.176.4 至 2.433，目标环境版本是否在当前支持矩阵内仍需核验。
要点总览（TL;DR）
- 先分清现象：状态不更新、日志打不开、项目下找不到流水线、迭代下无运行记录，分别对应服务接入、查看权限、项目关联、迭代匹配四层。
- 项目管理员身份与流水线查看权限是两个条件，缺一都可能表现为状态或日志不可见。
- 处置按服务接入、账号权限、项目关联、迭代规则顺序推进，前三步只核对，第四步才改规则。
- 移除 Jenkins 关联会清理已同步数据，删除流水线可能同步删除 Jenkins 任务，排查阶段不要用移除再添加的方式重置。
- 所读手册标注 Jenkins 2.176.4 至 2.433，目标版本是否在支持矩阵内需先核验。
先定位现象：看不到的是状态、日志还是迭代归属
“看不到”在 ONES 里至少有四种不同表现，对应的排查入口并不相同。先把现象说清楚，再决定从哪一层查，能避免把权限问题当成同步故障处理。
| 可观察现象 | 通常先查的层级 | 需要记录的信息 |
|---|---|---|
| 流水线已出现在项目中，但状态一直为空或不更新 | 服务接入层：Jenkins 服务关联与凭据是否有效 | 流水线名称与任务类型、账号、项目、发生时间 |
| 能看到状态，但运行步骤或日志打不开、内容缺失 | 权限层：当前账号是否拥有该流水线的查看权限 | 流水线名称、账号、具体运行记录、发生时间 |
| 项目下根本找不到这条流水线 | 关联层：流水线是否已关联到该项目 | 流水线名称与任务类型、项目、操作人 |
| 流水线在项目中可见，但迭代下没有对应运行记录 | 匹配层：迭代关联脚本规则是否命中 | 迭代名称、分支信息、运行时间 |
记录时尽量把流水线名称、任务类型（Pipeline、多分支流水线、文件夹或自由风格任务）、账号、项目、迭代和发生时间一并写下。多分支流水线还要注明是哪条分支流水线，因为分支流水线的归属关系与主流水线不同。
四类原因假设与各自的排除证据
下面四层假设按从底层到上层的顺序排列。每层都给出一个可执行的核对动作，核对结果能排除该层，再进入下一层；核对结果指向该层，就直接进入处置。
服务接入层：ONES 是否真的连上了 Jenkins
手册给出的接入方式是在流水线配置中心关联 Jenkins 服务，配置服务器地址以及用户名密码或 Token，前提是双方网络可达、凭据有效。核对动作：确认服务关联记录存在，地址指向目标 Jenkins 实例，凭据未过期或被撤销。若凭据失效或网络不通，状态和日志都取不到，现象往往表现为整条流水线的信息都缺失，而非单条运行记录缺失。
权限层：项目管理员身份与流水线查看权限是两个条件
手册明确：项目管理员可关联已有流水线，但须拥有该流水线的查看权限。这意味着“我是项目管理员”并不自动等于“我能看到这条流水线”。核对动作：用当前账号确认在 Jenkins 侧对该任务有读取权限，同时在 ONES 侧具备该流水线的查看权限。两个条件缺一，都可能表现为状态或日志不可见。
关联层：流水线是否已关联到目标项目
流水线需要由具备查看权限的项目管理员关联到项目后，才会出现在项目视图中。多分支流水线关联后，其分支流水线随之关联项目，因此主流水线关联成功时，分支通常不需要单独操作。核对动作：在项目下确认该流水线是否在已关联列表中；若不在，说明问题在关联层而非同步层。
匹配层：迭代关联依赖可配置脚本规则
迭代与流水线运行的关联通过可配置脚本规则匹配，例如按迭代名称和分支信息关联。核对动作：检查规则中使用的迭代名称写法与分支命名是否与实际一致，包括大小写、分隔符和前后缀。规则未命中时，流水线运行本身可见，只是不会出现在对应迭代下。
版本前提
所读手册标注 Jenkins 2.176.4 至 2.433，不能自动外推到更新版本。目标 Jenkins 版本是否在当前 ONES 支持矩阵内属于待核验项，排查前应先确认这一点，避免在不受支持的组合上反复调整配置。
按顺序处置：从服务接入到迭代匹配
处置顺序遵循“先核对、后改动，先低风险、后高风险”的原则。前三步只做确认，第四步才涉及规则调整。
- 核对 Jenkins 服务关联与凭据。在流水线配置中心确认服务器地址、用户名密码或 Token 有效，并确认双方网络可达。凭据更新后，观察状态是否恢复刷新。
- 确认账号权限。分别确认当前账号在 Jenkins 侧对目标任务有读取权限、在 ONES 侧拥有该流水线的查看权限。权限不足时由有权限的管理员补充授权，再以该账号复查。
- 确认项目关联。在目标项目下检查流水线是否已关联。未关联时，由同时具备项目管理员身份和该流水线查看权限的账号完成关联；多分支流水线关联主流水线后，确认分支流水线是否随之出现。
- 核对迭代关联规则。检查脚本规则中的迭代名称与分支匹配条件，与实际迭代命名、分支命名逐项比对，修正不一致处后重新观察迭代下的运行记录。
需要设置停止点的两类操作：移除 Jenkins 关联会清理已同步的流水线数据；删除流水线可能同步删除 Jenkins 上的任务。这两项都不是排查手段，执行前必须确认影响范围并取得相关方同意。排查阶段优先使用核对与重新关联，避免用移除再添加的方式“重置”。
恢复验证与复发预防
处置完成后逐项验证，不要只看一个指标就结束。验证项包括：流水线状态是否正常显示并随新运行更新、运行步骤是否可展开、日志是否可读取、流水线是否出现在目标项目下、对应运行是否归入正确的迭代。
验证时选一条已知成功的流水线运行作为对照，用同一账号、同一项目查看，能区分“整体接入恢复”与“个别运行记录异常”。若状态恢复但迭代下仍无记录，问题仍在匹配层，回到规则核对。
减少复发的日常约定可以落在两处：一是把迭代命名与分支命名规则写进团队约定，让脚本规则的匹配条件有稳定依据；二是把流水线关联、移除关联、删除流水线三类操作区分权限归属，关联由项目管理员执行，移除与删除设置更严格的确认环节。
按上述顺序核对后仍无法恢复时，保留流水线名称与任务类型、账号、项目与迭代、发生时间、已执行的核对步骤及结果，连同目标 Jenkins 版本信息一并提交给管理员或支持渠道，便于在支持矩阵与配置层面继续定位。
常见问题
项目管理员为什么仍然看不到某条 Jenkins 流水线的状态和日志？
项目管理员身份解决的是“能否把流水线关联到项目”，查看流水线本身还需要该流水线的查看权限。手册把这两个条件分开列出：项目管理员可关联已有流水线，但须拥有该流水线的查看权限。因此先确认当前账号在 ONES 侧对该流水线是否有查看权限，再确认在 Jenkins 侧对目标任务是否有读取权限，两个条件都满足后再判断是否为接入或同步问题。
多分支流水线关联主流水线后，分支流水线还需要逐条关联吗？
按手册说明，多分支流水线关联后，其分支流水线随之关联项目，通常不需要对每条分支单独操作。排查时如果主流水线已出现在项目中而某条分支没有，先确认该分支流水线在 Jenkins 侧是否存在、当前账号是否有查看权限，再考虑关联或匹配层的问题。
流水线在项目里能看到，但迭代下没有运行记录，是同步故障吗？
这种情况更可能出在迭代匹配层。迭代关联流水线运行通过可配置脚本规则匹配，例如按迭代名称和分支信息关联，前提是流水线已先关联到项目、迭代按团队规则命名。规则中的迭代名称写法或分支命名与实际不一致时，流水线运行本身可见，只是不会归入对应迭代。核对规则条件与实际命名后再判断是否需要调整。
排查时可以直接移除 Jenkins 关联再重新添加来“重置”吗？
不建议把移除关联当作排查手段。移除 Jenkins 关联会清理已同步的流水线数据，删除流水线还可能同步删除 Jenkins 上的任务，两者影响范围不同。排查阶段优先核对服务地址与凭据、账号权限、项目关联和迭代规则；确需移除或删除时，先确认影响范围并取得相关方同意。
目标 Jenkins 版本较新，排查前需要先确认什么？
所读手册标注的版本区间为 Jenkins 2.176.4 至 2.433，不能自动外推到更新版本。目标环境版本是否在当前 ONES 支持矩阵内属于待核验项，建议在调整配置前先确认这一点，避免在不受支持的组合上反复修改。手册列出的任务类型包括 Pipeline、多分支流水线、文件夹和自由风格任务，实际可用范围仍以当前兼容情况为准。
官方参考资料
- 流水线集成（ONES）
- Jenkins 集成配置（ONES）
