kit.program/docs/registry-design.md

Registry 模块设计文档

概述

kit 的 registry 模块用于对接 Registry 配置管理中心（D:\workbench\registry），提供命令行方式管理微服务配置。

Registry 是一个基于 REST API 的配置管理系统，支持项目隔离、三维配置（机房/环境/分组）、规划/编辑/只读三种模式。

对接方式

kit 通过 HTTP 请求调用 Registry REST API，使用 Node 内置 http/https 模块，不引入新依赖。

配置存储

registry 的连接信息复用 kit 已有的 kit config 机制：

kit config registryUrl http://bh.vps.honor3.com:8008
kit config registryToken abc123

命令设计

配置管理

复用 kit config，无需新增命令。

项目与配置操作

命令	说明	示例
kit registry list	列出所有项目（含详情）	kit registry list
kit registry config <project>[:path]	查看/设置配置项	见下方

kit registry list

列出 Registry 上所有项目，输出项目名称、ID、维度启用状态、配置数量。

$ kit registry list

ID                    名称                      维度
proj-abc-123          CommonExternalService     IDC=✓ Env=✓ Group=✓
proj-def-456          OrderService              IDC=✗ Env=✓ Group=✓

共 2 个项目

kit registry config <project>[:path]

三种用法：

1. 查看配置列表（不指定 key）

# 查看整个项目
kit registry config CommonExternalService

# 查看路径下的配置
kit registry config CommonExternalService:data/windows

输出：

路径                              值                          类型
CF_API_TOKEN                      ****                        string
CF_R2_BUCKET                      store                       string
CF_R2_PUBLIC_URL                  https://pub-xxx.r2.dev      string

2. 获取单个值（指定 key）

kit registry config CommonExternalService:CF_R2_BUCKET
# 输出: store

3. 设置值（指定 key + value）

kit registry config CommonExternalService:CF_R2_BUCKET my-new-bucket

导入导出

命令	说明	示例
kit registry export <project>[:path] [file]	导出为 JSON	kit registry export CommonExternalService:data ./backup.json
kit registry import <project>[:path] <file>	从 JSON 导入	kit registry import CommonExternalService:data ./backup.json

project:path 语法

project:path 中的 path 对应 Registry 中配置的路径前缀（由维度映射 + key 构成）。

语法	含义
proj	整个项目的所有配置
proj:data	路径以 data 开头的配置
proj:data/windows	路径以 data/windows 开头的配置
proj:data/windows/kit.exe	精确匹配单个配置

export 示例

# 导出整个项目
kit registry export CommonExternalService ./backup.json

# 仅导出 data/windows 下的配置
kit registry export CommonExternalService:data/windows ./backup-windows.json

导出文件格式：

{
  "project": "CommonExternalService",
  "path": "data/windows",
  "exportedAt": "2026-09-11T02:00:00Z",
  "configs": [
    {
      "key": "kit.exe",
      "value": "...",
      "type": "string",
      "description": "Windows 二进制下载地址",
      "idc": "",
      "environment": "",
      "group": ""
    }
  ]
}

import 示例

# 从备份文件导入整个项目
kit registry import CommonExternalService ./backup.json

# 将备份导入到指定路径下
kit registry import CommonExternalService:data/windows ./backup-windows.json

import 行为：

• 已存在的 key（按路径匹配）→ 更新 value
• 不存在的 key → 新增
• 远程有但本地没有的 → 保留不动（不删除）

API 映射

kit 命令	Registry API
kit registry list	GET /api/projects
kit registry config <project>	GET /api/projects/:id/configs
kit registry config <project>:<key>	GET /api/projects/:id/configs → 按 path 匹配
kit registry config <project>:<key> <value>	GET → 匹配后 PUT 或 POST
kit registry export	GET /api/projects/:id/configs → 写文件
kit registry import	读文件 → 逐项 PUT/POST

文件结构

kit/src/registry/
├── index.js          # 命令注册入口
├── client.js         # HTTP 客户端（调用 Registry API）
└── sync.js           # export/import 逻辑

错误处理

• 未配置 registryUrl → 提示 请先运行 kit config registryUrl <url>
• 连接失败 → 输出 Registry 不可达: <url>
• 认证失败 → 输出 认证失败，请检查 registryToken
• 项目不存在 → 输出 项目不存在: <name>
• 只读模式下写入 → 输出 Registry 当前为只读模式