kkRepo 是一款社区驱动、完全开源的自托管制品仓库,旨在解决 Sonatype Nexus 社区版的各类限制与痛点,为社区提供开放、可靠且可持续演进的制品管理方案。目前已支持 Maven、npm、OHPM/HarmonyOS、PyPI、Go、Helm、Cargo/Rust、Dart/Pub、Composer/PHP、Terraform、Swift Package Registry、Ansibl
版权所有:中国计算机学会技术支持:开源发展技术委员会
京ICP备13000930号-9
京公网安备 11010802047560号
kkRepo
English | 中文
kkRepo 是一款社区驱动、完全开源的自托管制品仓库,旨在解决 Sonatype Nexus 社区版的各类限制与痛点,为社区提供开放、可靠且可持续演进的制品管理方案。目前已支持 Maven、npm、OHPM/HarmonyOS、PyPI、Go、Helm、Cargo/Rust、Dart/Pub、Composer/PHP、Terraform、Swift Package Registry、Ansible Galaxy、Conda、APT/Debian、Conan 2、Alpine/APK、R/CRAN、Hugging Face Models、Git LFS、Docker/OCI、NuGet、RubyGems、Yum 和 Raw 等制品格式。
功能特性
/repository/<repo>/...URL 布局。商标声明
Sonatype、Nexus 和 Nexus Repository 是 Sonatype, Inc. 的商标。kkRepo 是独立开源项目,不隶属于 Sonatype, Inc.,也未获得其认可、赞助或背书。文档中对 Sonatype Nexus Repository 的引用仅用于准确说明兼容性、迁移或互操作性。
快速开始
使用公开发行镜像和 MySQL 在本地启动一个试用环境:
使用同一镜像和默认 PostgreSQL 16 quickstart 启动(运行时兼容 PostgreSQL 12+):
如需从默认 JVM 镜像切换到多架构 Native 镜像:
KKREPO_RUNTIME和KKREPO_DATABASE_TYPE可以独立选择,也可以组合使用,例如KKREPO_RUNTIME=native KKREPO_DATABASE_TYPE=postgresql。启动后访问:
http://127.0.0.1:19090/admin/http://127.0.0.1:19090/browse/http://127.0.0.1:19091/actuator/health首次进入页面时,在 UI 中创建初始
Local/admin管理员密码。quickstart 使用 File blob storage 作为本地试用存储;生产环境请改用 OSS/S3,并替换为自己的加密密钥。如果希望先检查脚本内容,可以先下载
scripts/quickstart.sh,确认后再用bash执行。构建和部署
本地快速启动、Spring Boot 可执行 jar、Docker 镜像、压缩包、生产部署架构、资源规格和升级流程见 构建部署指南。
默认 JVM 与显式开启的 Native Image 在启动、内存、镜像体积和预热后吞吐方面的实测差异见 Native Image 与 JVM 选型指南。
如果 kkRepo 部署在 Nginx 或其他 HTTPS 反向代理后面,请参考 Nginx 反向代理配置注意事项,确保 npm
dist.tarball等生成的仓库 URL 保持公网https://scheme 和 host。本地开发热重载和测试说明见 中文开发指南。
支持能力
npm publish、dist-tag 和管理台上传ohpm publish、ohpm install、普通/流式 HAR/HSP、tag、下架及 UI/API 上传(使用指南)<version>.zipPUT 与 UI/API 上传;Go 客户端可通过同一 group 解析私有 hosted 和公共 proxy modulecargo publish、yank/unyank、CargoToken认证和 UI/API.crate上传cargo searchdart pub publish、dart pub get、flutter pub get、PubToken认证和 UI/API.tar.gz上传terraform init可通过 group 解析 hosted 与 proxy module/providerswift package-registry publish、Basic/Bearer 登录和 UI/API source archive 上传FULL;shape 漂移或 proxy secret 不可用时需人工处理ansible-galaxy collection publish、Nexus 兼容 raw PUT、route-scoped Base64 Bearer/Ansible 2.9 Token 凭据、GenericToken 和 UI/API collection 上传(使用指南).tar.bz2/.conda的 UI/API 上传.deb上传,以及真实apt update、下载、安装和升级(使用指南)conan upload、Conan bearer 登录和 UI/API revision file 上传(使用指南)apk update、search、policy、fetch、install 和 upgrade(使用指南)APKINDEX.tar.gz、passthrough/验签后 re-sign proxy、有序 group source binding、Browse/Search 和 Usage.tar.gzPUT 与 UI/Components API 上传,以及真实available.packages()、安装和更新(使用指南)PACKAGES.gz、任意文件 proxy、snapshot-bound group、Browse/Search、Cleanup、扫描和 UsageHF_ENDPOINT使用hf download、hf_hub_download、snapshot_download、Transformers 与 Diffusers(使用指南)从 Sonatype Nexus Repository 迁移
迁移入口在管理控制台
/admin/:Nexus Metadata页面先执行Run preflight,确认无阻塞问题后执行Run migration。Nexus Repository Data页面先执行Sync metadata迁移仓库元数据,再执行Sync packages迁移 blob 真实数据。Metadata since保持为空,扫描全量数据;后续迁移可以指定Metadata since做增量。/repository/<repo>/...URL;Docker 客户端应保持相同/v2/...registry 入口、仓库名和 connector/path-based routing 形态。迁移支持中断后继续,已迁移完成的数据会跳过。完整流程见 Nexus 迁移说明。
兼容与迁移背景
/repository/<repo>/...URL 布局兼容,同时采用共享关系数据库、OSS/S3-first、适合多副本部署的架构选型建议
UI 展示
前台
前台面向制品使用者,提供仓库列表、包搜索、目录浏览、制品详情和上传入口。
仓库列表展示 hosted、proxy、group 仓库的格式、状态和访问 URL,便于用户直接复制客户端配置地址。
按格式搜索组件,支持 Maven、npm、OHPM/HarmonyOS、PyPI、Go、Helm、Cargo/Rust、Dart/Pub、Composer/PHP、Terraform、Swift Package Registry、Ansible Galaxy、Conda、APT/Debian、Conan 2、Alpine/APK、R/CRAN、Hugging Face Models、Git LFS、Docker/OCI、NuGet、RubyGems、Yum 和 Raw 等仓库类型的制品检索。
目录浏览展示仓库路径树、制品摘要、checksum、content-type、更新时间和客户端使用片段。
上传页面提供按仓库选择文件和 asset path 的入口,用于 hosted 仓库的手工制品发布。
后台
后台面向仓库管理员,聚焦仓库配置、存储健康、安全配置、审计和迁移。
Blob Store 页面支持 OSS Native SDK、AWS S3 SDK 和 File 引擎配置,并展示读写探测健康状态。
OIDC 页面管理 issuer、JWKS、client、scope、claim 映射和 token 校验参数,便于接入统一身份系统。
Nexus Metadata 迁移入口用于迁移用户、角色、权限、blob store 和 repository 定义,并支持 preflight。
Nexus Repository Data 迁移页面展示 hosted 仓库数据迁移任务、并发参数、进度统计、失败数量和仓库级明细。
AI agent 和贡献者的开发说明见 AGENTS.md。
路线图
基础设施路线图:
persistence-jdbc公共契约、语义化 dialect SPI、backend 自有 Flyway migration、双库 contract test 和多副本 server smoke test 隔离并验证差异;MySQL 继续作为默认后端(数据库后端指南、设计方案)。仓库格式路线图:
.tar.bz2/.conda发布、JSON/BZ2/ZSTD channel 元数据、UI/API 上传、Browse/Search、多副本协同、真实 Conda 客户端 E2E、Nexus 黑盒 fixture,以及 shape-gated Nexus 3.92.x-3.94.x hosted 数据迁移 E2E(设计说明)PACKAGES.gz、延迟校验 proxy、snapshot-bound group、UI/API 上传、Browse/Search、Cleanup、partial-coverage 扫描、shape-gated Nexus 3.94 迁移、R 4.5/4.6 客户端 E2E、双数据库高效索引和可复现 Nexus 性能门禁(使用指南、设计说明、性能基线)。用户和管理端 UI 已暴露的 token 类型包括协议专用 token(
NpmToken、CargoToken、PubToken、NuGetApiKey、RubyGemsApiKey),以及面向 Terraform 服务 URL、Ansible Galaxy 客户端、CI、脚本和自定义 HTTP 客户端的GenericToken;GenericToken适用于能够发送已配置 API-key header 或 bearer token 的调用方。 OHPM 客户端使用GenericToken作为原始 Authorization 值;RSA 签名登录是默认关闭的可选功能。谁在使用 kkRepo?
如果你的公司、企业或组织正在使用 kkRepo,欢迎前往用户登记 Issue留下部署信息。该 Issue 仅用于使用方登记;Bug 和功能建议请使用常规 Issue 模板提交。
参与贡献
欢迎提交 issue 和 pull request。贡献流程、PR 要求、兼容性测试要求和多副本设计约束见 CONTRIBUTING.md。社区行为准则见 CODE_OF_CONDUCT.md。
本地开发和测试说明见 中文开发指南;构建部署说明见 构建部署指南;AI agent 和贡献者约束见 AGENTS.md。
支持
加入 kkRepo Telegram 群 获取社区支持和使用交流。Issue 分类、支持范围和安全问题报告边界见 SUPPORT.md。
赞助者
感谢所有支持 kkRepo 持续开发和维护的赞助者。你可以通过 GitHub Sponsors 支持本项目。
你也可以通过支付宝或微信支付赞助 kkRepo。
企业赞助者
当前企业赞助者的 Logo 和链接将在此展示。
项目支持者
当前项目支持者的名称或 Logo 及可选链接将在此展示。
安全
如果发现安全问题,请按 SECURITY.md 说明优先通过 GitHub Security Advisory 报告,避免在公开 issue 中直接披露可利用细节。普通 bug、兼容性问题和功能建议可以直接提交 issue。
许可证
kkRepo 使用 Apache License 2.0 开源。
文档