欢迎使用 Acme Registry

灵活的组件注册表，支持公开分享和私有保护，专为团队协作设计

欢迎使用 Acme Registry！这是一个功能完善的 shadcn/ui 组件注册表，支持公开和私有两种模式，专为团队协作和企业使用而设计。

什么是组件 Registry？

组件 Registry 允许您：

🔒 可选的访问控制 - 支持公开或私有模式，灵活保护组件
🎨 共享设计系统 - 在团队和项目间复用组件
📦 管理组件库 - 集中管理和版本控制
🚀 加速开发 - 快速安装预构建组件
🌐 支持多注册表 - 同时使用公共和私有源

核心特性

灵活的认证

可选的认证保护：公开分享或使用 Bearer Token、API Key 等方式保护敏感组件

组件管理

轻松添加、更新和分享 React 组件到注册表

命名空间支持

支持多个注册表源，灵活组织和引用组件

完整文档

详细的使用指南和 API 文档，快速上手

开始使用

我是用户 👤

如果您想使用私有 Registry 中的组件：

快速参考

快速配置和使用指南

入门指南

从零开始创建和使用注册表

认证配置

配置私有认证和访问控制

客户端配置

在项目中集成私有 Registry

我是维护者 🔧

如果您想部署和维护 Registry：

部署指南

生产环境部署完整指南

贡献指南

了解项目结构和开发规范

快速开始

公开注册表（最简单）

# 1. 构建注册表
pnpm registry:build

# 2. 启动服务
pnpm dev

# 3. 使用组件（客户端）
npx shadcn@latest add https://your-domain.com/r/button.json

私有注册表（需要认证）

服务端设置：

# 1. 生成令牌
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

# 2. 配置环境变量
echo "REGISTRY_TOKEN=your_token" > .env.local

# 3. 启动服务
pnpm registry:build && pnpm dev

客户端使用：

components.json

{
  "registries": {
    "@acme": {
      "url": "https://your-domain.com/r/{name}.json",
      "headers": {
        "Authorization": "Bearer ${REGISTRY_TOKEN}"
      }
    }
  }
}

.env.local

REGISTRY_TOKEN=your_token

npx shadcn@latest add @acme/button

架构概览

组件 Registry 由以下几部分组成：

认证层 🔒（可选）

灵活配置：支持公开模式或私有模式
Middleware：可选的 /r/ 静态文件保护
多种认证：Bearer Token、API Key、查询参数（仅私有模式）

组件存储 📦

源码目录：registry/ - 组件源代码
配置文件：registry.json - 组件元数据和依赖
生成文件：public/r/*.json - 构建后的 JSON（受保护）

文档系统 📚

Fumadocs：基于 MDX 的文档系统
自动导航：从文件结构生成导航
搜索功能：全文搜索文档内容

认证方式

公开访问（无需认证）

# 不设置 REGISTRY_TOKEN 环境变量
curl https://your-domain.com/r/button.json

私有访问（需要认证）

设置 REGISTRY_TOKEN 环境变量后，支持以下认证方式：

Bearer Token（推荐）

curl -H "Authorization: Bearer YOUR_TOKEN" \
  https://your-domain.com/r/button.json

API Key

curl -H "X-API-Key: YOUR_TOKEN" \
  https://your-domain.com/r/button.json

查询参数（仅测试）

curl "https://your-domain.com/r/button.json?token=YOUR_TOKEN"

详见认证文档。

工作流程

维护者：发布组件

用户：安装组件

安全最佳实践

公开注册表

公开注册表无需特殊安全配置，任何人都可以访问组件。

私有注册表

如果使用私有模式，请遵循以下安全措施：

✅ 使用 Middleware - 必须保护 /r/ 静态文件（参见 proxy.ts）
✅ 强随机令牌 - 使用至少 32 字节的随机令牌
✅ HTTPS 传输 - 生产环境必须使用 HTTPS
✅ 环境变量 - 不要将令牌提交到版本控制系统
✅ 定期轮换 - 建议每 3-6 个月更新令牌

详见认证文档和部署指南。

常见用例

开源组件库（公开）

{
  "@mylib": "https://components.mylib.com/r/{name}.json"
}

企业设计系统（私有）

{
  "@design-system": {
    "url": "https://design.company.com/r/{name}.json",
    "headers": {
      "Authorization": "Bearer ${DESIGN_TOKEN}"
    }
  }
}

多团队协作（混合模式）

{
  "@public": "https://public.company.com/r/{name}.json",
  "@frontend": {
    "url": "https://frontend.company.com/r/{name}.json",
    "headers": { "Authorization": "Bearer ${FRONTEND_TOKEN}" }
  },
  "@backend": {
    "url": "https://backend.company.com/r/{name}.json",
    "headers": { "Authorization": "Bearer ${BACKEND_TOKEN}" }
  }
}

混合公共/私有

{
  "@shadcn": "https://ui.shadcn.com/r/{name}.json",
  "@internal": {
    "url": "https://internal.company.com/r/{name}.json",
    "headers": { "Authorization": "Bearer ${TOKEN}" }
  }
}