第 56 章
提交到官方 Marketplace：claude-plugins-official 审核流程与 101 个官方插件分析
第五十六章：企业级 Plugin 部署：私有注册表与访问控制
56.1 企业环境的特殊需求
clawhub.ai 公共市场对于个人开发者和开源项目来说是理想的发布平台，但企业环境有着截然不同的需求：
数据安全：企业内部 Plugin 可能包含专有业务逻辑、内部 API 集成、甚至业务数据的连接凭证。这些内容绝不应该上传到公共注册表。
合规要求：金融、医疗、政府等行业有严格的软件供应链安全要求（如 SBOM、代码签名、漏洞扫描），公共市场的审核流程未必满足这些要求。
访问控制：企业需要精确控制哪些团队、哪些人员可以安装哪些 Plugin，并需要完整的操作审计日志。
版本锁定：生产环境需要锁定 Plugin 版本，防止自动更新带来的意外变更。
内网部署：某些企业环境完全隔离外网，无法访问 clawhub.ai，需要在内网部署完整的注册表服务。
私有 Plugin 注册表（Private Plugin Registry）正是为解决这些问题而设计的。
56.2 私有注册表架构
企业私有注册表架构
┌─────────────────────────────────────────────────────────┐
│ 企业内网 │
│ │
│ ┌──────────────┐ ┌──────────────────────────────┐ │
│ │ 开发者工作站 │ │ 私有注册表服务 │ │
│ │ │ │ │ │
│ │ claude-plugin│───▶│ ┌──────────────────────┐ │ │
│ │ push/publish │ │ │ Package Storage │ │ │
│ └──────────────┘ │ │ (S3/MinIO/NFS) │ │ │
│ │ └──────────────────────┘ │ │
│ ┌──────────────┐ │ │ │
│ │ Claude Code │ │ ┌──────────────────────┐ │ │
│ │ (用户终端) │───▶│ │ Registry API Server │ │ │
│ └──────────────┘ │ │ (registry.corp.com) │ │ │
│ │ └──────────────────────┘ │ │
│ ┌──────────────┐ │ │ │
│ │ CI/CD 系统 │ │ ┌──────────────────────┐ │ │
│ │ (GitHub/ │───▶│ │ Auth Service │ │ │
│ │ Jenkins) │ │ │ (LDAP/OIDC/SAML) │ │ │
│ └──────────────┘ │ └──────────────────────┘ │ │
│ │ │ │
│ │ ┌──────────────────────┐ │ │
│ │ │ Audit Log Store │ │ │
│ │ │ (PostgreSQL) │ │ │
│ │ └──────────────────────┘ │ │
│ └──────────────────────────────┘ │
└─────────────────────────────────────────────────────────┘
56.3 部署私有注册表
使用 Official Registry Server
Anthropic 提供了开源的私有注册表实现 claude-registry-server，可以自托管：
# 使用 Docker 部署
docker run -d \
--name claude-registry \
-p 3000:3000 \
-v /data/registry:/data \
-e DATABASE_URL="postgresql://user:pass@db:5432/registry" \
-e STORAGE_BACKEND="s3" \
-e S3_BUCKET="my-claude-plugins" \
-e S3_REGION="cn-north-1" \
-e AUTH_PROVIDER="oidc" \
-e OIDC_ISSUER="https://sso.corp.com" \
-e OIDC_CLIENT_ID="claude-registry" \
anthropic/claude-registry-server:latest
使用 Docker Compose 完整部署
# docker-compose.yml
version: "3.9"
services:
registry:
image: anthropic/claude-registry-server:latest
ports:
- "3000:3000"
environment:
DATABASE_URL: postgresql://registry:${DB_PASSWORD}@postgres:5432/registry
STORAGE_BACKEND: s3
S3_ENDPOINT: http://minio:9000
S3_BUCKET: claude-plugins
S3_ACCESS_KEY: ${MINIO_ACCESS_KEY}
S3_SECRET_KEY: ${MINIO_SECRET_KEY}
AUTH_PROVIDER: oidc
OIDC_ISSUER: https://sso.corp.com
OIDC_CLIENT_ID: claude-registry
OIDC_CLIENT_SECRET: ${OIDC_CLIENT_SECRET}
SIGNING_KEY_PATH: /secrets/registry-signing.key
AUDIT_LOG_ENABLED: "true"
volumes:
- ./secrets:/secrets:ro
depends_on:
- postgres
- minio
postgres:
image: postgres:16
environment:
POSTGRES_DB: registry
POSTGRES_USER: registry
POSTGRES_PASSWORD: ${DB_PASSWORD}
volumes:
- postgres_data:/var/lib/postgresql/data
minio:
image: minio/minio:latest
command: server /data --console-address ":9001"
ports:
- "9001:9001"
environment:
MINIO_ROOT_USER: ${MINIO_ACCESS_KEY}
MINIO_ROOT_PASSWORD: ${MINIO_SECRET_KEY}
volumes:
- minio_data:/data
volumes:
postgres_data:
minio_data:
56.4 访问控制模型
基于角色的访问控制（RBAC）
私有注册表支持精细的 RBAC 权限模型：
# registry-config.yaml
rbac:
roles:
viewer:
permissions:
- registry:package:read
- registry:package:install
description: "Can view and install packages"
developer:
inherit: viewer
permissions:
- registry:package:publish
- registry:package:deprecate
description: "Can publish and deprecate packages"
namespace_admin:
inherit: developer
permissions:
- registry:namespace:manage
- registry:package:delete
- registry:package:transfer
description: "Full control over a namespace"
registry_admin:
inherit: namespace_admin
permissions:
- registry:admin:manage_users
- registry:admin:manage_namespaces
- registry:admin:view_audit_logs
- registry:admin:manage_policies
description: "Full registry administration"
namespaces:
# 平台团队的命名空间
platform:
admins: ["platform-team"]
developers: ["platform-team", "senior-engineers"]
viewers: ["@all"] # 所有人可见
# 数据团队的命名空间（限制访问）
data-team:
admins: ["data-team-leads"]
developers: ["data-team"]
viewers: ["data-team", "analytics-team"]
# 安全插件命名空间（高度受限）
security:
admins: ["security-team"]
developers: ["security-team"]
viewers: ["security-team"] # 仅安全团队可见
策略引擎（Policy Engine）
除了 RBAC，注册表还支持基于 Open Policy Agent（OPA）的策略规则：
# policies/install-policy.rego
package registry.install
# 默认拒绝
default allow = false
# 允许安装：用户有 viewer 权限 且 包已审核通过
allow {
has_permission(input.user, "registry:package:install")
input.package.reviewStatus == "approved"
not is_blacklisted(input.package)
}
# 额外条件：高风险包需要额外审批
allow {
has_permission(input.user, "registry:package:install")
input.package.riskLevel == "high"
has_approval(input.user, input.package.id)
}
# 黑名单检查
is_blacklisted(package) {
data.blacklist[package.name]
}
56.5 配置 Claude Code 使用私有注册表
用户级别配置
# 添加私有注册表
claude config registry add \
--name corp \
--url https://registry.corp.com \
--auth-type oidc \
--oidc-issuer https://sso.corp.com \
--priority 1 # 优先级高于公共市场
# 验证连接
claude registry ping corp
# ✓ Connected to registry.corp.com
# ✓ Authenticated as: [email protected]
# ✓ Available namespaces: platform, data-team
# 查看可安装的包
claude plugin search --registry corp "database"
组织级别配置（锁定）
企业管理员可以通过组织策略文件强制所有员工使用特定的注册表配置：
// /etc/claude/org-policy.json（管理员通过 MDM 或 GPO 部署）
{
"registries": {
"required": [
{
"name": "corp",
"url": "https://registry.corp.com",
"auth": "oidc",
"priority": 1
}
],
"allowPublic": false, // 禁止访问公共市场
"allowUnlisted": false // 禁止安装 unlisted 包
},
"plugins": {
"allowList": null, // null = 允许所有注册表中的包
// 或者：
// "allowList": ["corp/security-*", "corp/platform-*"],
"blockList": ["*:dangerous-*"]
}
}
56.6 发布到私有注册表
配置发布目标
# 登录到私有注册表
claude-plugin login --registry https://registry.corp.com
# 发布到私有注册表（替代公共市场）
claude-plugin publish \
--registry https://registry.corp.com \
--namespace platform \
weather-plugin-1.0.0.clpkg
CI/CD 中的私有注册表发布
# .github/workflows/publish-private.yml
name: Publish to Private Registry
on:
push:
tags: ['v*.*.*']
jobs:
publish:
runs-on: self-hosted # 使用内网 Runner
steps:
- uses: actions/checkout@v4
- name: Setup Node.js
uses: actions/setup-node@v4
with:
node-version: '20'
- name: Build
run: |
npm ci
npm run build
npm install -g @claude/plugin-cli
- name: Security Scan
run: |
# 内部安全扫描（SBOM 生成、依赖漏洞扫描）
npx @cyclonedx/cyclonedx-npm --output-file sbom.json
npm audit --audit-level=high
- name: Pack
run: claude-plugin pack
- name: Publish to Internal Registry
env:
REGISTRY_TOKEN: ${{ secrets.INTERNAL_REGISTRY_TOKEN }}
run: |
claude-plugin login \
--registry https://registry.corp.com \
--token $REGISTRY_TOKEN
claude-plugin publish \
--registry https://registry.corp.com \
--namespace platform \
*.clpkg
56.7 版本锁定与升级策略
锁定文件（Plugin Lock File）
类似 package-lock.json，企业可以使用 Plugin 锁定文件确保版本一致性：
// .claude-plugin-lock.json（提交到版本控制）
{
"lockVersion": 1,
"generatedAt": "2026-04-28T10:00:00Z",
"registry": "https://registry.corp.com",
"plugins": {
"corp/database-plugin": {
"version": "2.1.3",
"integrity": "sha256-abc123...",
"resolved": "https://registry.corp.com/corp/database-plugin/-/2.1.3.clpkg"
},
"corp/security-plugin": {
"version": "1.4.0",
"integrity": "sha256-def456...",
"resolved": "https://registry.corp.com/corp/security-plugin/-/1.4.0.clpkg"
}
}
}
应用锁定文件：
# 从锁定文件安装（不自动升级）
claude plugin install --frozen-lockfile
# 更新到最新版本并更新锁定文件
claude plugin update
受控升级流程
企业中的 Plugin 升级应当经过受控流程：
1. 测试环境验证
└── 在隔离的测试工作区中安装新版本
└── 运行自动化测试套件
2. 金丝雀部署
└── 向 5% 的用户推送新版本
└── 监控错误率和性能指标 24 小时
3. 灰度扩展
└── 向 50% 的用户推送
└── 监控 48 小时
4. 全量发布
└── 向所有用户推送
└── 更新锁定文件
5. 回滚备案
└── 保留旧版本 30 天
└── 回滚命令：claude plugin pin corp/[email protected]
56.8 供应链安全
SBOM 集成
软件物料清单（SBOM）是零信任供应链安全的基础。私有注册表要求所有上传的包附带 SBOM：
# 生成 CycloneDX 格式的 SBOM
npx @cyclonedx/cyclonedx-npm \
--output-format json \
--output-file sbom.json \
--spec-version 1.4
# 发布时附带 SBOM
claude-plugin publish \
--registry https://registry.corp.com \
--sbom sbom.json \
*.clpkg
注册表会自动将 SBOM 与包关联存储，并在漏洞数据库（如 OSV、NVD）有新 CVE 时主动通知受影响包的维护者。
代码签名验证
私有注册表支持配置受信任的签名密钥：
# registry-config.yaml
signing:
trustedKeys:
- id: "platform-team-key"
publicKey: |
-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA...
-----END PUBLIC KEY-----
namespaces: ["platform", "security"]
- id: "external-vendor-key"
publicKey: |
-----BEGIN PUBLIC KEY-----
...
-----END PUBLIC KEY-----
namespaces: ["vendors"]
# 强制要求签名（拒绝未签名的包）
requireSigning: true
# 指定命名空间的包必须由特定密钥签名
namespaceKeyRequirements:
security: ["platform-team-key"]
vendors: ["external-vendor-key"]
56.9 审计日志
企业级注册表记录所有操作到审计日志，满足合规要求：
// 审计日志条目示例
{
"eventId": "audit_abc123",
"timestamp": "2026-04-28T14:23:45.678Z",
"actor": {
"userId": "[email protected]",
"ipAddress": "10.1.2.3",
"userAgent": "claude-plugin-cli/1.5.0"
},
"action": "package.install",
"resource": {
"registry": "https://registry.corp.com",
"namespace": "platform",
"package": "database-plugin",
"version": "2.1.3"
},
"outcome": "success",
"workspaceId": "ws_prod_012"
}
审计日志查询
# 查询某用户的安装记录
claude registry audit query \
--actor [email protected] \
--action package.install \
--since 2026-01-01 \
--format csv > installs.csv
# 查询某包的所有安装记录
claude registry audit query \
--package platform/database-plugin \
--action package.install \
--since 2026-01-01
# 查询失败的发布尝试
claude registry audit query \
--action package.publish \
--outcome failure \
--since 2026-04-01
56.10 灾备与高可用
多地域部署
# docker-compose.ha.yml（高可用配置）
services:
registry-primary:
image: anthropic/claude-registry-server:latest
environment:
REPLICA_ROLE: primary
REPLICATION_TARGETS: "https://registry-dr.corp.com"
registry-dr: # 灾备站点
image: anthropic/claude-registry-server:latest
environment:
REPLICA_ROLE: replica
REPLICA_SOURCE: "https://registry.corp.com"
READ_ONLY: "true" # 灾备站点只读，主站故障时切换
离线缓存
Claude Code 支持在本地缓存已安装的 Plugin 包，在网络中断时继续工作：
# 预缓存关键 Plugin（在有网络时执行）
claude plugin cache pre-warm \
corp/[email protected] \
corp/[email protected]
# 查看缓存状态
claude plugin cache list
小结
企业级 Plugin 部署是整个 Plugin 生态系统的终点，也是生产可靠性的基础。私有注册表通过四个核心能力服务于企业需求：访问控制（RBAC + OPA 策略引擎）确保"正确的人安装正确的包"；供应链安全（SBOM + 代码签名）确保"安装的包是安全可信的"；版本锁定与受控升级确保"生产环境的稳定性"；完整的审计日志满足"合规与可追溯性"要求。从第四十九章到本章，我们完整地走过了 Claude Plugin 从架构设计到生产运营的全链路。掌握这套体系，你就具备了在任何规模的组织中构建和运营 Claude Plugin 生态的能力。