Koji

开发编程

管理 Koji 构建系统的任务、软件包、标签、仓库、用户、SRPM/RPM，并提供完整的 API 支持用于构建和任务操作。

后端开发脚本工具

430

下载量

安装量

收藏量

★ 5.0

综合评分ⓘ

概述

更多信息

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

bash

# 从 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

bash

# 列出用户构建
# 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

bash

# 搜索包
# 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

bash

# 列出所有标签
# 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

bash

# 列出标签下的包
# 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

bash

# 查看任务状态
# 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

bash

# 查看用户信息
# 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

bash

# 上传 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

bash

# 下载 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

bash

# 列出所有目标
# 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

bash

# 列出构建根
# 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

bash

# 列出所有仓库
# 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

bash

# 列出标签的外部仓库
# 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

bash

# 列出归档
# 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

bash

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

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

4️⃣ DistGit 集成 | DistGit Integration#

DistGit 构建 | DistGit Build

bash

# 从 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

ini

[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#

bash

# 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#

bash

# 检查 KRB5 票据
# Check KRB5 ticket
klist

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

# 查看配置
# Check config
koji config show

SSL 证书认证 | SSL Certificate Authentication#

bash

# 生成证书 | 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#

命令描述Descriptionbuild创建构建Create buildbuild-info构建信息Build infobuild-state构建状态Build statebuild-logs构建日志Build logscancel-build取消构建Cancel buildretry-build重试构建Retry buildcancel-all取消所有构建Cancel all builds

包命令 | Package Commands#

命令描述Descriptionlist-packages列出包List packagespackage-info包信息Package infolist-owners列出维护者List ownersadd-owner添加维护者Add ownerremove-owner删除维护者Remove owner

标签命令 | Tag Commands#

命令描述Descriptionlist-tags列出标签List tagstag-info标签信息Tag infocreate-tag创建标签Create tagdelete-tag删除标签Delete tagclone-tag复制标签Clone taglist-tag-packages标签包列表Tag packagesadd-to-tag添加到标签Add to tagremove-from-tag从标签删除Remove from taglist-tag-ext-repos标签外部仓库Tag ext repos

任务命令 | Task Commands#

命令描述Descriptiontask-info任务信息Task infotask-results任务结果Task resultscancel-task取消任务Cancel tasktask-logs任务日志Task logsretry-task重试任务Retry tasklist-tasks列出任务List tasks

用户命令 | User Commands#

命令描述Descriptionuser-info用户信息User infouser-permissions用户权限User permissionslist-builds用户构建User buildscreate-user创建用户Create userdelete-user删除用户Delete usergrant-perm授予权限Grant permissionrevoke-perm撤销权限Revoke permission

SRPM/RPM 命令 | SRPM/RPM Commands#

命令描述Descriptionupload-srpm上传 SRPMUpload SRPMdownload-srpm下载 SRPMDownload SRPMdownload-rpm下载 RPMDownload RPMdownload-build下载构建产物Download buildlist-rpms列出 RPMList 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#

bash

# 检查 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#

bash

# 查看构建日志
# 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#

bash

# 测试服务器连接
# 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#

bash

# 检查用户权限
# 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#

bash

# 检查构建状态
# 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#

bash

# 检查用户权限
# 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#

bash

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

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

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