Koji Expert 技能 - Koji 构建系统专家（完整版）

技能描述 | Skill Description

名称 | Name: koji

版本 | Version: 2.0.0

作者 | Author: OS Build Agent

领域 | Domain: Koji Build System (Fedora/CentOS/RHEL)

专业级 Koji 构建系统管理技能，提供完整的构建任务、包管理、标签、仓库、用户、归档、构建根等所有核心功能管理能力。

Professional-level Koji Build System management skill with comprehensive API coverage for build tasks, package management, tags, repositories, users, archives, buildroots, and all core functionalities.

⭐ 核心特性 | Key Features

1. 构建管理 | Build Management

✅ 创建构建任务 | Create build tasks
✅ 查看构建状态 | View build status
✅ 取消构建 | Cancel builds
✅ 重试失败构建 | Retry failed builds
✅ 获取构建日志 | Get build logs
✅ 列出构建历史 | List build history
✅ 构建标签管理 | Build tag management

2. 包管理 | Package Management

✅ 列出包 | List packages
✅ 获取包信息 | Get package info
✅ 包所有权管理 | Package ownership
✅ 包列表管理 | Package list management
✅ 添加/删除包 | Add/Remove packages

3. 标签管理 | Tag Management

✅ 创建/删除标签 | Create/Delete tags
✅ 标签继承配置 | Tag inheritance
✅ 标签包列表 | Tag package list
✅ 标签外部仓库 | Tag external repos

4. 目标管理 | Target Management

✅ 创建构建目标 | Create build targets
✅ 目标配置管理 | Target configuration
✅ 构建根管理 | Buildroot management

5. 用户管理 | User Management

✅ 用户信息查询 | User info query
✅ 用户权限管理 | User permissions
✅ 用户组管理 | User groups
✅ KRB5 认证 | Kerberos authentication

6. 仓库管理 | Repository Management

✅ 仓库列表 | Repository list
✅ 外部仓库配置 | External repo config
✅ 仓库分发 | Repository distribution

7. 任务管理 | Task Management

✅ 任务状态查询 | Task status query
✅ 任务结果获取 | Task results
✅ 任务取消 | Task cancellation
✅ 任务重试 | Task retry

8. SRPM/RPM 管理 | SRPM/RPM Management

✅ SRPM 上传 | SRPM upload
✅ RPM 下载 | RPM download
✅ 构建根查询 | Buildroot query
✅ 归档管理 | Archive management

9. 构建系统集成 | Build System Integration

✅ DistGit 集成 | DistGit integration
✅ 自动化构建 | Automated building
✅ CI/CD 支持 | CI/CD support

📁 本文档结构 | Document Structure

1️⃣ 核心能力 | Core Capabilities

构建管理、包管理、标签管理、目标管理
用户管理、仓库管理、任务管理
SRPM/RPM 管理、构建系统集成

2️⃣ 基础功能 | Basic Functions

构建操作、包管理操作、标签管理操作
任务管理操作、用户管理操作

3️⃣ 高级功能 | Advanced Functions

目标管理、仓库管理、归档管理
构建根管理、DistGit 集成

4️⃣ 配置与最佳实践 | Configuration & Best Practices

Koji 配置、环境变量、认证方式
最佳实践、故障排除

🔧 基础功能 | Basic Functions

1️⃣ 构建管理 | Build Management

构建操作 | Build Operations

# 从 SRPM 构建
# Build from SRPM
koji build --target "f39" "./package-1.0-1.fc39.src.rpm"

# 从 Git 构建 (DistGit)
# Build from Git (DistGit)
koji build --target "f39" --git "https://src.fedoraproject.org/rpms/package.git"

# 查看构建信息
# View build info
koji build-info 123456

# 查看构建状态
# View build status
koji build-state 123456

# 查看构建日志
# View build logs
koji build-logs 123456

# 查看构建产物
# View build artifacts
koji list-builds --package "mypackage"

# 取消构建
# Cancel build
koji cancel-build 123456

# 重试构建
# Retry build
koji retry-build 123456

# 取消所有待处理构建
# Cancel all pending builds
koji cancel-all --user "username"

批量构建操作 | Batch Build Operations

# 列出用户构建
# List user builds
koji list-builds --user "username"

# 列出构建历史
# List build history
koji list-builds --package "mypackage" --quiet

# 查看构建任务
# View build tasks
koji list-task --owner "username" --state "open"

2️⃣ 包管理 | Package Management

包操作 | Package Operations

# 搜索包
# Search packages
koji list-packages --query "mypackage"

# 获取包信息
# Get package info
koji package-info "mypackage"

# 列出包维护者
# List package owners
koji list-owners "mypackage"

# 添加包维护者
# Add package owner
koji add-owner "mypackage" "username"

# 删除包维护者
# Remove package owner
koji remove-owner "mypackage" "username"

# 列出所有包
# List all packages
koji list-packages

# 列出包组
# List package groups
koji list-groups --tag "f39"

3️⃣ 标签管理 | Tag Management

标签操作 | Tag Operations

# 列出所有标签
# List all tags
koji list-tags

# 获取标签信息
# Get tag info
koji tag-info "f39-updates"

# 创建标签
# Create tag
koji create-tag --name "f39-custom" --parent "f39"

# 删除标签
# Delete tag
koji delete-tag "f39-custom"

# 复制标签
# Clone tag
koji clone-tag --name "f39-custom" --clone "f39-updates"

# 列出标签继承关系
# List tag inheritance
koji list-tag-inheritance "f39-custom"

标签包管理 | Tag Package Management

# 列出标签下的包
# List packages in tag
koji list-tag-packages "f39-updates"

# 添加包到标签
# Add package to tag
koji add-to-tag "f39-updates" "mypackage-1.0-1"

# 从标签删除包
# Remove package from tag
koji remove-from-tag "f39-updates" "mypackage-1.0-1"

# 设置包的标签权限
# Set package tag permissions
koji set-pkg-perm "f39-updates" --perms "read/write" "mypackage"

# 列出标签的外部仓库
# List tag external repos
koji list-tag-ext-repos "f39-updates"

# 添加外部仓库到标签
# Add external repo to tag
koji add-ext-repo "f39-updates" --url "https://example.com/repo" --priority 1

4️⃣ 任务管理 | Task Management

任务操作 | Task Operations

# 查看任务状态
# View task status
koji task-info 789012

# 查看任务结果
# View task results
koji task-results 789012

# 取消任务
# Cancel task
koji cancel-task 789012

# 查看任务日志
# View task logs
koji task-logs 789012

# 重试任务
# Retry task
koji retry-task 789012

# 列出任务
# List tasks
koji list-tasks --user "username" --state "open"

5️⃣ 用户管理 | User Management

用户操作 | User Operations

# 查看用户信息
# View user info
koji user-info "username"

# 查看用户权限
# View user permissions
koji user-permissions "username"

# 列出用户构建
# List user builds
koji list-builds --user "username"

# 创建用户
# Create user
koji create-user --name "username" --email "user@example.com"

# 删除用户
# Delete user
koji delete-user "username"

# 设置用户权限
# Set user permissions
koji grant-perm "perm-name" --user "username"

# 撤销用户权限
# Revoke user permissions
koji revoke-perm "perm-name" --user "username"

6️⃣ SRPM/RPM 管理 | SRPM/RPM Management

SRPM 操作 | SRPM Operations

# 上传 SRPM
# Upload SRPM
koji upload-srpm "./package-1.0-1.fc39.src.rpm"

# 下载 SRPM
# Download SRPM
koji download-srpm "mypackage-1.0-1.fc39.src.rpm"

# 下载构建的 SRPM
# Download build SRPM
koji download-build 123456 --srpm

RPM 操作 | RPM Operations

# 下载 RPM
# Download RPM
koji download-rpm "mypackage-1.0-1.fc39.x86_64.rpm"

# 下载构建产物
# Download build artifacts
koji download-build 123456 --arch "x86_64"

# 列出构建的 RPM
# List build RPMs
koji list-rpms --build-id 123456

🚀 高级功能 | Advanced Functions

1️⃣ 目标管理 | Target Management

目标操作 | Target Operations

# 列出所有目标
# List all targets
koji list-targets

# 获取目标信息
# Get target info
koji target-info "f39-build"

# 创建构建目标
# Create build target
koji create-target --name "f39-custom" --build "f39-build" --destination "f39"

# 删除目标
# Delete target
koji delete-target "f39-custom"

# 复制目标
# Clone target
koji clone-target --name "f39-custom" --clone "f39-build"

# 设置目标的构建根
# Set target buildroot
koji set-buildquota "f39-custom" --quota 100

构建根管理 | Buildroot Management

# 列出构建根
# List buildroots
koji list-buildroots --target "f39-build"

# 获取构建根信息
# Get buildroot info
koji buildroot-info 123456

# 列出构建根内容
# List buildroot contents
koji buildroot-list 123456

# 清理构建根
# Clean buildroot
koji clean-buildroot --id 123456

2️⃣ 仓库管理 | Repository Management

仓库操作 | Repository Operations

# 列出所有仓库
# List all repos
koji list-repos

# 获取仓库信息
# Get repo info
koji repo-info "f39"

# 创建仓库
# Create repo
koji create-repo --name "f39-custom" --tag "f39-custom"

# 删除仓库
# Delete repo
koji delete-repo "f39-custom"

# 刷新仓库
# Refresh repo
koji refresh-repo "f39"

外部仓库配置 | External Repo Configuration

# 列出标签的外部仓库
# List tag external repos
koji list-tag-ext-repos "f39-updates"

# 添加外部仓库到标签
# Add external repo to tag
koji add-ext-repo "f39-updates" --url "https://example.com/repo" --priority 1

# 删除外部仓库
# Delete external repo
koji remove-ext-repo "f39-updates" --repo-id 1

3️⃣ 归档管理 | Archive Management

归档操作 | Archive Operations

# 列出归档
# List archives
koji list-archives --build-id 123456

# 获取归档信息
# Get archive info
koji archive-info 123456

# 下载归档
# Download archive
koji download-archive 123456

# 删除归档
# Delete archive
koji delete-archive 123456

归档类型 | Archive Types

# 列出归档类型
# List archive types
koji list-archive-types

# 搜索归档
# Search archives
koji search-archives --type "tar" --name "mypackage"

4️⃣ DistGit 集成 | DistGit Integration

DistGit 构建 | DistGit Build

# 从 DistGit 构建
# Build from DistGit
koji build --target "f39" --git "https://src.fedoraproject.org/rpms/package.git"

# 从 DistGit 特定分支构建
# Build from DistGit specific branch
koji build --target "f39" --git "https://src.fedoraproject.org/rpms/package.git" --branch "main"

# 从 DistGit 特定提交构建
# Build from DistGit specific commit
koji build --target "f39" --git "https://src.fedoraproject.org/rpms/package.git" --revision "abc123"

# 创建 DistGit 仓库
# Create DistGit repo
koji clone-repo --name "mypackage" --source "source-package"

⚙️ 配置 | Configuration

Koji 配置文件 | Koji Config File

位置 | Location: ~/.koji/config

[koji]
server = https://koji.fedoraproject.org/kojihub
weburl = https://koji.fedoraproject.org/koji
topdir = ~/koji

# 认证方式 | Authentication Methods

# 方法 1: Kerberos
auth_method = kerberos

# 方法 2: SSL 证书
# auth_method = ssl
# ssl_ca_cert = /etc/koji/koji_ca.crt
# ssl_cert = ~/.koji/client.crt
# ssl_key = ~/.koji/client.key

# 方法 3: GSSAPI
# auth_method = gssapi

# 其他配置 | Other config
ca_cert = /etc/koji/koji_ca.crt
client_cert = ~/.koji/client.crt
server_cert = ~/.koji/server.crt
cert_cn = Koji Client
krb_principal = username@FEDORAPROJECT.ORG
krb_keytab = /etc/krb5.keytab

环境变量 | Environment Variables

# Koji 配置文件路径
export KOJI_CONF=~/.koji/config

# Koji 目录
export KOJI_DIR=~/koji

# 调试模式
export KOJI_DEBUG=1

# 禁用 SSL 验证（不推荐）
export KOJI_SSL_VERIFY=0

🔐 认证 | Authentication

Kerberos 认证 | Kerberos Authentication

# 检查 KRB5 票据
# Check KRB5 ticket
klist

# 刷新票据
# Refresh ticket
kinit username@FEDORAPROJECT.ORG

# 查看配置
# Check config
koji config show

SSL 证书认证 | SSL Certificate Authentication

# 生成证书 | Generate certificate
koji create-cert --cn "username" --email "user@example.com"

# 导出证书 | Export certificate
koji export-cert --cn "username" --output "~/.koji/client.crt"

# 配置文件配置 | Config file setup
[koji]
auth_method = ssl
ssl_cert = ~/.koji/client.crt
ssl_key = ~/.koji/client.key
ssl_ca_cert = /etc/koji/koji_ca.crt

📊 命令参考 | Command Reference

构建命令 | Build Commands

命令	描述	Description
------	------	-------------
`build`	创建构建	Create build
`build-info`	构建信息	Build info
`build-state`	构建状态	Build state
`build-logs`	构建日志	Build logs
`cancel-build`	取消构建	Cancel build
`retry-build`	重试构建	Retry build
`cancel-all`	取消所有构建	Cancel all builds

包命令 | Package Commands

命令	描述	Description
------	------	-------------
`list-packages`	列出包	List packages
`package-info`	包信息	Package info
`list-owners`	列出维护者	List owners
`add-owner`	添加维护者	Add owner
`remove-owner`	删除维护者	Remove owner

标签命令 | Tag Commands

命令	描述	Description
------	------	-------------
`list-tags`	列出标签	List tags
`tag-info`	标签信息	Tag info
`create-tag`	创建标签	Create tag
`delete-tag`	删除标签	Delete tag
`clone-tag`	复制标签	Clone tag
`list-tag-packages`	标签包列表	Tag packages
`add-to-tag`	添加到标签	Add to tag
`remove-from-tag`	从标签删除	Remove from tag
`list-tag-ext-repos`	标签外部仓库	Tag ext repos

任务命令 | Task Commands

命令	描述	Description
------	------	-------------
`task-info`	任务信息	Task info
`task-results`	任务结果	Task results
`cancel-task`	取消任务	Cancel task
`task-logs`	任务日志	Task logs
`retry-task`	重试任务	Retry task
`list-tasks`	列出任务	List tasks

用户命令 | User Commands

命令	描述	Description
------	------	-------------
`user-info`	用户信息	User info
`user-permissions`	用户权限	User permissions
`list-builds`	用户构建	User builds
`create-user`	创建用户	Create user
`delete-user`	删除用户	Delete user
`grant-perm`	授予权限	Grant permission
`revoke-perm`	撤销权限	Revoke permission

SRPM/RPM 命令 | SRPM/RPM Commands

命令	描述	Description
------	------	-------------
`upload-srpm`	上传 SRPM	Upload SRPM
`download-srpm`	下载 SRPM	Download SRPM
`download-rpm`	下载 RPM	Download RPM
`download-build`	下载构建产物	Download build
`list-rpms`	列出 RPM	List RPMs

📚 最佳实践 | Best Practices

1. 构建前检查 | Pre-build Checks

✅ 确保 spec 文件符合打包规范
✅ 在本地 mock 环境中测试构建
✅ 检查依赖关系
✅ 验证 DistGit 仓库状态
✅ 确认目标标签存在

2. 标签策略 | Tag Strategy

✅ 使用标准标签命名（如 f39, f39-updates）
✅ 正确配置标签继承
✅ 管理好外部仓库
✅ 定期清理 unused tags
✅ 使用 clone-tag 进行标签模板

3. 错误处理 | Error Handling

✅ 检查构建失败原因
✅ 查看完整构建日志
✅ 在本地重现问题
✅ 使用 retry-build 重试临时失败
✅ 了解不同构建状态的含义

4. 性能优化 | Performance Optimization

✅ 批量操作使用脚本
✅ 合理使用缓存
✅ 避免重复构建
✅ 使用 --quiet 选项减少输出
✅ 并行执行独立构建

5. 安全性 | Security

✅ 使用 SSL 证书认证
✅ 定期更新 Kerberos 票据
✅ 限制用户权限
✅ 使用 HTTPS 连接
✅ 定期清理敏感数据

⚠️ 常见问题 | Common Issues

认证失败 | Authentication Failed

# 检查 KRB5 票据
# Check KRB5 ticket
klist

# 刷新票据
# Refresh ticket
kinit username@FEDORAPROJECT.ORG

# 检查配置文件
# Check config file
koji config show

# 重启 D-Bus
# Restart D-Bus
systemctl --user restart dbus

构建失败 | Build Failed

# 查看构建日志
# View build logs
koji build-logs 123456

# 查看失败原因
# View failure reason
koji build-info 123456

# 重试构建
# Retry build
koji retry-build 123456

# 检查构建任务
# Check build task
koji list-task --build 123456

连接问题 | Connection Issues

# 测试服务器连接
# Test server connection
koji server ping

# 检查服务器状态
# Check server status
koji server status

# 检查网络连接
# Check network connection
curl https://koji.fedoraproject.org/kojihub

# 检查防火墙
# Check firewall
firewall-cmd --list-ports

权限问题 | Permission Issues

# 检查用户权限
# Check user permissions
koji user-permissions "username"

# 检查包权限
# Check package permissions
koji list-owners "mypackage"

# 检查标签权限
# Check tag permissions
koji list-tag-packages "f39-updates" --perms

🔧 故障排除 | Troubleshooting

构建挂起 | Build Hangs

# 检查构建状态
# Check build status
koji build-state 123456

# 检查任务状态
# Check task status
koji list-task --build 123456

# 检查构建根
# Check buildroot
koji buildroot-info <buildroot_id>

# 查看完整日志
# View complete logs
koji build-logs 123456 --all

权限拒绝 | Permission Denied

# 检查用户权限
# Check user permissions
koji user-permissions "username"

# 检查包所有权
# Check package ownership
koji list-owners "mypackage"

# 检查标签权限
# Check tag permissions
koji list-tag-packages "f39-updates" --perms

# 联系管理员
# Contact admin
koji contact-admin

构建失败 - 依赖问题 | Build Failed - Dependency Issues

# 检查依赖
# Check dependencies
koji build-logs 123456 | grep "Cannot find"

# 解析依赖
# Resolve dependencies
dnf whatprovides "required-package"

# 添加缺失的依赖
# Add missing dependency
koji add-owner "missing-package" "username"

📖 参考资料 | References

官方文档 | Official Documentation

工具 | Tools

社区 | Community

📅 版本历史 | Changelog

v2.0.0 (2026-04-17) ⭐⭐⭐ 重大更新 | Major Update

功能合并： 整合 koji-expert 的全部高级功能
全新结构： 重新组织文档结构，清晰分类
目标管理： 添加完整的构建目标和构建根管理
归档管理： 添加归档管理功能
DistGit 集成： 添加 DistGit 构建和仓库管理
命令参考： 添加完整的命令参考表格
最佳实践： 添加详细的 Best Practices 章节

v1.0.0 (2026-03-23)

初始版本，完整的 Koji API 支持
支持构建、包、标签、任务、用户管理
基础的 SRPM/RPM 管理
中英文双语文档

📄 许可证 | License

MIT License - 与 OpenClaw AgentSkills 规范兼容

MIT License - Compatible with OpenClaw AgentSkills specification

Koji

概述