当你的构建系统突然报告“package xxx is excluded”时，那可能正是一场由
koji regen-repo幕后操作的复杂仓库合并与模块优先级斗争的结果。
在现代软件构建系统Koji中，koji regen-repo命令是维护构建环境一致性的核心。它不仅仅是一个简单的仓库更新操作，更是一个涉及数据合并、依赖解析和模块化内容管理的复杂过程。
本文将深入剖析koji regen-repo的底层工作原理，特别是在面对多个模块化YUM仓库时如何处理冲突，并针对常见的“包被排除”问题提供系统的解决方案。
一、Koji 仓库生成机制概览
在Koji架构中，仓库生成是其核心功能之一，由专门的kojira组件负责监控和管理。kojira会周期性地（通常是每10-15秒）查询Koji Hub，检查自上次查询以来标签（tag）是否发生了变化。
一旦检测到变化，它就会将新的仓库生成任务排入队列。
在Koji 1.35版本中，仓库生成机制发生了重大变化，引入了全新的仓库处理方式。这个变化使得管理员需要重新配置一些设置，特别是那些原来在kojira.conf中配置现已移至Hub配置的选项。
二、regen-repo的两阶段核心流程
当执行koji regen-repo命令时，整个过程分为两个关键阶段：createrepo和mergerepos。这两个阶段协同工作，将分散的包集合整合为统一的、可供构建使用的仓库。
1. Createrepo 阶段：元数据生成
在这一阶段，Koji 会为每个标签下的软件包集合生成标准的YUM仓库元数据。它使用createrepo_c（或较旧版本的createrepo）工具来创建repodata目录，其中包含primary.xml、filelists.xml和其他必要的元数据文件。
值得注意的是，为了优化性能，Koji 通常会使用--update和--skip-stat参数来运行createrepo，这意味着它只会更新自上次运行以来发生变化的包，而不会每次都重新处理整个仓库。这种方式可以显著减少大型仓库的生成时间。
性能优化提示：仓库再生是一个内存密集型任务，当构建服务器同时处理多个createrepo/mergerepo作业时，可能会因内存不足而失败，并出现“killed by signal 9”的错误。确保您的构建服务器有足够的内存（如4GB或更多）来同时处理这些任务。
2. Mergerepos 阶段：多源合并
当构建标签关联了多个外部YUM仓库时，真正的复杂性就出现了。这时mergerepo_c工具被调用来合并这些仓库。您看到的命令形式通常如下：
/usr/bin/mergerepo_c --pkgorigins --all -o /tmp/koji/tasks/7577/27577/repo -g -r A_yum_URL -r B_yum_URL这个命令的核心任务是将来自不同源的包整合到一个统一的仓库视图中，而其中的关键是--pkgorigins和--all参数。--pkgorigins会保留包的来源信息，这在调试时非常有用；--all则确保合并所有包，包括不同版本的相同包。
三、多模块仓库合并的复杂性与优先级原则
当合并的仓库中包含模块化内容（即包含modules.yaml文件）时，情况变得更加复杂。Modulemd v2格式的模块定义文件包含了完整的模块元数据，如名称、流、版本、上下文、组件、过滤器和依赖关系等。
模块信息合并的基本规则
在合并多个包含模块化内容的仓库时，mergerepo_c会遵循以下优先级原则：
- 唯一性规则：对于同一模块（相同名称和流），最终只保留一个版本
- 优先级决定：由仓库的优先级设置决定保留哪个版本（数字越小优先级越高）
- 顺序覆盖：优先级相同的情况下，后添加的仓库会覆盖先添加的仓库中的模块定义
合并模式对模块的影响
Koji 提供了两种主要的仓库合并模式，它们对模块化内容的处理方式有显著差异：
| 合并模式 | 触发参数 | 处理原则 | 对模块化包的影响 |
|---|---|---|---|
| koji（默认） | mergerepo_c --koji | 同名包只保留一个版本，按仓库优先级选择，并递归包含该版本对应的所有模块化RPM | 如果高优先级仓库的modules.yaml过滤了某些RPM，即使其他仓库存在这些RPM，它们也不会出现在最终仓库中 |
| bare | mergerepo_c --pkgorigins --all | 允许同名但不同版本的包同时存在 | 不同仓库提供的、属于同一模块但版本不同的RPM包可能同时出现，可能导致依赖解析冲突 |
以下流程图直观地展示了在多模块仓库场景下，mergerepo_c的合并逻辑与优先级决策过程：
flowchart TD A[开始合并多个模块仓库] --> B{是否有同名模块<br>（相同 name 和 stream）？} B -->|否| C[保留所有模块<br>进入最终仓库] B -->|是| D[进入优先级仲裁流程] subgraph D [优先级仲裁流程] D1{比较仓库优先级} --> D2{优先级是否相同？} D2 -->|否| D3[保留高优先级仓库中的模块] D2 -->|是| D4[保留后添加仓库中的模块] end D3 --> E[确定最终保留的模块版本] D4 --> E C --> F[生成最终的统一仓库] E --> F F --> G{检查模块的 filter 字段} G -->|包在 filter 列表中| H[该包被排除<br>不会出现在最终仓库] G -->|包不在 filter 列表中| I[该包被包含<br>出现在最终仓库]模块过滤器（filter）的关键作用
模块定义中的filter字段是导致“包被排除”错误的直接原因之一。例如，在您提供的modules.yaml片段中，virt-devel模块显式过滤了多个RPM包：
filter:rpms:-ocaml-hivex-ocaml-hivex-debuginfo-ocaml-hivex-devel# ... 更多包当这样的模块定义被高优先级仓库采用时，即使低优先级仓库包含这些包，它们也会被排除在最终仓库之外。
四、常见“包被排除”问题全解析
从您遇到的错误信息可以看出，问题表现为多个模块化包被排除：
Problem 1: conflicting requests - package aqute-bnd-3.5.0-4.module+el8.2.0+10048+55533a4a.noarch is excluded这种问题通常由以下几个原因导致，每种原因的排查方法和解决方案各不相同：
问题根源分析表
| 问题根源 | 典型特征 | 排查方法 | 解决方案 |
|---|---|---|---|
| 模块过滤器排除 | 包名出现在模块的filter.rpms列表中 | 检查相关modules.yaml文件 | 修改模块定义，从过滤器中移除包 |
| 仓库优先级冲突 | 包在不同仓库的模块中有不同状态 | koji taginfo <tag>查看仓库优先级 | 调整仓库优先级或合并模式 |
| 架构排除列表 | 与特定架构不兼容 | 检查 Koji Builder 的excludelist配置 | 修改构建器配置，排除不必要的架构限制 |
| 模块流不匹配 | 依赖的模块流未激活或不可用 | 检查构建日志中的模块启用信息 | 确保正确的模块流被激活 |
系统性排查指南
定位包所属模块
使用grep在相关modules.yaml文件中搜索被排除的包名，确定它属于哪个模块：grep-l"aqute-bnd"*.yaml检查模块过滤器
找到模块后，立即检查其filter字段。如果包在过滤列表中，这就是问题所在。分析仓库配置
运行以下命令查看仓库优先级和合并模式：koji taginfo<build_tag>检查构建器配置
登录到执行构建的Koji Builder主机，检查/etc/kojid/kojid.conf或相关插件目录下的excludelist、ignorelist配置。
解决方案实施
根据排查结果，选择适当的解决方案：
修改模块定义（最直接的方法）：
如果模块定义由您控制，直接从filter.rpms列表中移除被排除的包，然后重新构建并发布模块仓库。调整仓库优先级：
如果包在低优先级仓库的模块中可用且未被过滤，可以调高该仓库的优先级：koji edit-external-repo --tag<build_tag>--priority<新优先级><repo_name>更改合并模式：
在某些情况下，将合并模式从默认的koji改为bare可能有助于解决问题，但这可能会引入其他冲突。刷新仓库（任何修改后必需）：
无论采取哪种解决方案，都必须重新生成仓库以使更改生效：koji regen-repo<build_tag># 等待仓库生成完成koji wait-repo<build_tag>
五、最佳实践与优化建议
基于对regen-repo机制的深入理解，我们提出以下最佳实践：
合理设置仓库优先级：明确规划外部仓库的优先级顺序，确保关键仓库具有适当的优先级。
精简模块过滤器：只在绝对必要时使用模块过滤器，避免过度排除包导致下游依赖问题。
监控仓库生成性能：定期检查仓库生成任务的执行时间和资源消耗，特别是对于大型仓库。
使用本地镜像：为外部仓库设置本地镜像可以减少网络依赖，加快仓库生成速度，并提高构建系统的可靠性。
定期清理无效标签：Koji 1.35后，如果标签没有常规构建活动，可能需要设置
repo.auto=True或通过API手动请求仓库再生。
结语
koji regen-repo远不止是一个简单的仓库更新命令，它是一个复杂的仓库管理和合并引擎，特别是在处理现代Linux发行版的模块化内容时。
理解其两阶段处理流程、多仓库合并的优先级规则以及模块过滤机制，对于诊断和解决“包被排除”这类构建问题至关重要。
当您下次遇到模块化包被排除的错误时，不妨按照本文提供的排查路线图，从模块过滤器检查开始，逐步深入到仓库优先级和构建器配置分析，相信您能够快速定位问题根源并找到合适的解决方案。
通过精心规划仓库结构、合理设置优先级和过滤器，并遵循最佳实践，您可以构建一个稳定、高效且可预测的Koji构建环境。
