kkrepo

About

kkRepo 是一款社区驱动、完全开源、自托管的软件制品仓库。 它面向企业研发团队、私有化环境和自托管用户，提供 hosted、proxy、group 三类仓库能力，并支持 Maven、npm、PyPI、Docker/OCI、Helm、Cargo/Rust、Go、NuGet 等 15 种以上常见制品格式。 简单来说： hosted 保存公司内部发布的私有制品； proxy 代理 Maven Central、npm、PyPI、Docker Hub 等公共上游； group 把多个私服和代理仓库聚合为一个统一入口。 以前可能需要分别维护 Maven 私服、npm 私服、Docker Registry、Python 私有源和各种代理地址，现在可以用一套 kkRepo 统一管理。 对于已经使用 Sonatype Nexus Repository 的团队，kkRepo 还提供面向迁移场景的 API、权限模型和 /repository/<repo>/... URL 布局兼容，并内置 Nexus 元数据和真实制品数据迁移能力。 它解决了哪些痛点？ 1. 软件制品被不同技术栈切得七零八落 一个稍具规模的研发团队，通常会同时使用： Java / Kotlin：Maven JavaScript / TypeScript：npm Python：PyPI Go：Go Modules Rust：Cargo PHP：Composer Dart / Flutter：Pub .NET：NuGet Ruby：RubyGems 容器和云原生：Docker / OCI、Helm 基础设施：Terraform Linux 软件包：Yum 通用二进制文件：Raw 如果每种格式都部署一套独立服务，就会同时出现多套账号权限、多套域名、多套存储、多套备份方案，以及大量互不兼容的配置文件。 kkRepo 将这些格式放进同一个仓库管理平台中，统一管理用户、权限、存储、仓库地址、代理上游和运行状态。 2. 私服、代理源和聚合仓库各管一段 制品管理并不只是“把文件传到服务器”。 实际使用中通常同时需要三类能力： 内部项目发布到私有 hosted 仓库； 开发机和 CI 通过 proxy 仓库访问公共上游； 使用 group 仓库把内部制品和公共依赖合并成一个地址。 例如 Maven 项目可以把内部 Release、Snapshot 和 Maven Central 代理聚合为一个 maven-public；npm、PyPI、Cargo 也可以使用类似模式。 开发者只需要配置一个 group 地址，不需要关心某个包来自公司私服还是公共上游。 常见客户端地址可以保持统一的 Nexus 风格： text 3. Nexus 部署容易，真正迁移时却牵一发而动全身 很多团队早期使用 Nexus，等到业务规模扩大、需要升级、迁移存储或增加高可用能力时，才发现真正难迁移的并不只是制品文件。 还包括： 用户、角色和权限； 仓库定义和代理上游； Blob Store 配置； 组件和 Asset 元数据； hosted 仓库中的真实制品； proxy 仓库中的历史缓存； 原有仓库域名和 URL； 开发者本地配置； CI/CD 流水线中的仓库地址。 kkRepo 在管理后台中提供了完整的 Nexus 迁移入口，迁移过程分为预检、元数据迁移和仓库数据迁移。 它支持： 迁移用户、角色和权限； 迁移 Blob Store 和仓库定义； 迁移 hosted 仓库中的真实制品； 按需迁移部分 proxy 仓库历史数据； 首次执行全量同步； 后续按时间执行增量同步； 迁移中断后继续执行； 自动跳过已经完成的数据； 展示仓库级进度、成功数量和失败明细。 迁移完成后，可以把原来的仓库域名切换到 kkRepo。 非 Docker 客户端可以继续使用原来的： text /repository/<repo>/... Docker 客户端则可以继续沿用原有的 /v2/... Registry 入口、仓库名称和对应路由方式。 理想情况下，开发者本地配置、项目构建脚本和 CI 流水线不需要逐个修改，切换工作主要集中在服务端。 4. 单机、本地磁盘和内嵌状态难以支撑长期运行 很多制品仓库刚开始只有几十 GB，运行几年后可能增长到数 TB。 这时如果元数据、索引、会话、任务状态和制品 Blob 全部绑定在同一个本地目录中，扩容、故障切换、滚动升级和灾难恢复都会变得困难。 kkRepo 将数据分为两类： 仓库、组件、权限、Token、审计、迁移进度等结构化数据，存储在 MySQL 或 PostgreSQL； 大型软件包、容器 Blob 和制品文件，存储在 OSS、S3 或 File Blob Store。 MySQL 仍是默认数据库，同时也支持 PostgreSQL。 制品 Blob 可以使用： 阿里云 OSS 等兼容的对象存储； AWS S3 SDK 支持的 S3 服务； MinIO 等 S3 兼容存储； 本地 File 存储。 File 适合本地试用和开发环境，生产环境可以使用 OSS 或 S3，将计算节点与大文件存储解耦。 5. 单实例够用，但生产环境需要多副本 制品仓库通常位于整个研发供应链的核心位置。 一旦仓库不可用，开发者无法安装依赖，CI 无法构建，镜像无法发布，部署流程也可能被直接阻断。 kkRepo 从架构上支持多副本部署。 Session、认证票据、锁、迁移进度、目录水位和短生命周期的协同状态都会保存到共享的 MySQL 或 PostgreSQL 中。进程内缓存只作为可以重建的热缓存，不承担唯一状态。 这使 kkRepo 更适合： Kubernetes 多副本部署； 负载均衡； 节点故障自动摘除； 滚动升级； 共享对象存储； 跨节点迁移任务协调。 6. 账号、Token 和权限散落在每一种工具里 不同语言生态往往使用不同的认证方式。 kkRepo 提供统一的身份和访问控制能力，支持： Local 本地账号； LDAP； OIDC； 匿名访问策略； 用户、角色和细粒度权限； 面向不同协议的专用 Token； 面向 CI、脚本和自定义客户端的通用 Token。 目前管理端和用户端已经支持多种协议专用凭据，包括： NpmToken CargoToken PubToken NuGetApiKey RubyGemsApiKey GenericToken 团队可以将 kkRepo 接入现有统一身份系统，也可以为 CI 流水线创建权限受限、可以单独吊销的 Token，而不是在构建脚本里长期保存用户密码。 7. 仓库能运行，但运维看不到发生了什么 一个真正投入生产的软件制品仓库，除了能够上传和下载，还需要回答这些问题： 当前服务是否健康？ 对象存储是否可以正常读写？ 哪些仓库访问量最高？ 是否发生大量失败请求？ 哪个节点出现问题？ 数据迁移进行到了哪里？ 某次配置由谁修改？ 存储和数据库是否接近容量边界？ kkRepo 支持 Prometheus 指标导出，并提供 Grafana 面板。 管理后台还提供仓库配置、Blob Store 健康探测、安全配置、审计信息和迁移进度查看，便于把制品仓库纳入现有监控和告警系统。 当前支持的制品格式 kkRepo 目前已经覆盖以下常见格式： Maven npm PyPI Go Modules Helm Cargo / Rust Dart / Pub Composer / PHP Terraform Provider / Module Registry Swift Package Registry Docker / OCI NuGet RubyGems Yum Raw 不同格式支持的仓库类型和客户端行为有所区别。 大部分格式覆盖 hosted、proxy、group 仓库，以及上传、下载、浏览、搜索和 Nexus 迁移能力；Go 当前主要提供 proxy 和 group 读取代理能力。 项目采用独立协议模块实现不同格式，方便继续扩展和单独验证。 规划中的格式还包括： ohpm / HarmonyOS APT / Debian Conan Conda Nexus 一键迁移流程 迁移入口位于 kkRepo 管理控制台。 基本流程如下。 第一步：迁移前预检 在源 Nexus Repository 中开启 Script REST API 脚本创建能力，然后在 kkRepo 的 Nexus Metadata 页面执行 Run preflight。 预检会先发现版本、配置、权限和数据结构方面的阻塞问题，避免正式迁移运行一段时间后才失败。 第二步：迁移 Nexus 元数据 预检通过后执行 Run migration，迁移： 用户； 角色； 权限； Blob Store； hosted、proxy、group 仓库定义； 相关配置。 第三步：迁移真实制品数据 在 Nexus Repository Data 页面执行： text Sync metadata Sync packages 先同步仓库中的组件和 Asset 元数据，再迁移 Blob Store 中的真实软件包。 第四步：执行增量同步 第一次迁移可以扫描全部数据。 正式切换之前，再按照时间执行增量同步，把迁移期间新增或更新的制品同步到 kkRepo。 迁移任务支持中断后继续，已经完成的数据不会重复处理。 第五步：切换原有域名 完成验证后，将原 Nexus 仓库域名或反向代理入口切换到 kkRepo。 因为 kkRepo 保留了 Nexus 风格的仓库 URL 和客户端访问方式，原有 Maven、npm、PyPI、Cargo 等客户端配置可以继续使用。 这套流程的目标不是简单地“把文件复制出来”，而是尽量保持仓库定义、权限关系、制品元数据、真实 Blob 和客户端访问路径的一致性。 前台和管理后台 kkRepo 内置两套 Web 界面。 用户侧界面 用户侧页面主要面向制品使用者，提供： 仓库列表； hosted、proxy、group 类型展示； 仓库访问 URL； 跨格式制品搜索； 目录树浏览； 制品详情； Checksum 和 Content-Type； 更新时间； 客户端使用片段； hosted 仓库手工上传入口。 开发者可以直接复制仓库地址和使用方式，不需要每次向管理员询问配置。 管理后台 管理后台主要面向制品仓库管理员，提供： 仓库创建和配置； 代理上游管理； Blob Store 配置； OSS、S3 和 File 存储管理； 存储读写健康探测； 用户、角色和权限管理； LDAP 和 OIDC 配置； Token 管理； 审计信息； Nexus 元数据迁移； Nexus 仓库数据迁移； 迁移进度和失败明细。 客户端不需要学习新的使用方式 kkRepo 尽量遵循各个生态原生的客户端协议。 例如 npm 可以直接配置 group ini registry= always-auth=true 发布私有 npm 包： bash npm publish --registry= PyPI 可以通过 group 仓库安装依赖： bash pip install \ index-url \ demo-package Go Modules 可以设置统一代理入口： bash go env -w GOPROXY= Cargo 可以配置 Sparse Index： toml [registries.kkrepo] index = "sparse+ Maven、Helm、NuGet、RubyGems、Terraform、Docker/OCI 等客户端也可以继续使用各自原生的发布和下载方式。 kkRepo 负责在服务端统一处理身份认证、权限判断、上游代理、仓库聚合和制品存储。 部署非常简单 使用公开发行镜像和 MySQL 启动本地试用环境： bash curl -fsSL | bash 使用 PostgreSQL 16 启动 quickstart： bash curl -fsSL \ | KKREPODATABASETYPE=postgresql bash 启动后访问： text 管理控制台： 用户侧页面： 健康检查： 首次进入管理页面时，在 UI 中创建初始 Local/admin 管理员密码。 Quickstart 默认使用 File Blob Store，适合本地体验。生产环境建议： 使用 OSS、S3 或兼容对象存储； 使用独立 MySQL 或 PostgreSQL； 替换默认加密密钥； 配置定期备份； 使用 Nginx、Caddy 或网关提供 HTTPS； 根据可用性需求部署多个 kkRepo 实例； 接入 Prometheus 和 Grafana。 为什么值得推荐？ kkRepo 最有价值的地方，不只是“又实现了一个软件私服”。 它尝试把企业内部原本分散的软件制品链路，整理成一套完整的开源产品： 一套服务管理多种软件制品； 同时覆盖私有托管、上游代理和仓库聚合； 使用统一的账号、角色、权限和 Token； 提供开发者前台和管理员后台； 支持 MySQL 和 PostgreSQL； 支持 OSS、S3 和本地文件存储； 支持多副本和共享状态； 提供 Prometheus 指标和 Grafana 面板； 内置 Nexus 迁移预检和执行流程； 支持全量、增量和断点续传； 尽量保留原来的仓库域名、URL 和客户端配置； 采用 Apache License 2.0 完全开源。 它尤其适合： 同时使用多种编程语言的研发团队； 需要统一管理内部软件包和容器镜像的公司； 希望为开发机和 CI 提供统一代理源的团队； 已经运行 Nexus Repository，希望降低迁移改造成本的用户； 遇到 Nexus 社区版规模、升级或高可用限制的团队； 需要 LDAP、OIDC 和细粒度权限控制的企业； 希望使用对象存储和多副本部署的生产环境； 私有云、企业内网、离线网络和自托管场景。 项目定位与边界 kkRepo 并不是要把 Nexus 的全部历史功能和所有格式原样复制一遍。 它目前优先覆盖企业最常见的软件制品格式、客户端协议、仓库管理能力和 Nexus 迁移场景。不同格式支持的 hosted、proxy、group、上传、搜索和迁移能力可能存在区别，部分特殊格式的 Nexus 数据迁移也会受到源版本和数据结构限制。 正式迁移生产仓库前，建议先查看项目中的兼容性矩阵，执行迁移预检，并使用真实客户端和一份生产数据副本进行验证。 项目仍在持续开发，欢迎通过 Issue 和 Pull Request 提交实际使用场景、协议兼容问题和新的格式需求。 一句话总结 kkRepo 把软件私服、公共源代理加速、聚合仓库、权限控制、对象存储、高可用部署和 Nexus 数据迁移，统一成了一套完全开源的软件制品管理平台。 如果你的团队已经受够了多套私服、多套镜像源、多套账号权限，以及难以升级和迁移的 Nexus 实例，kkRepo 值得尝试。

Discovery history

1. 阮一峰周刊·用户投稿

   Jul 20, 2026 · 1 observations