176 lines
4.8 KiB
Markdown
176 lines
4.8 KiB
Markdown
# Registry 模块设计文档
|
||
|
||
## 概述
|
||
|
||
kit 的 registry 模块用于对接 Registry 配置管理中心（`D:\workbench\registry`），提供命令行方式管理微服务配置。
|
||
|
||
Registry 是一个基于 REST API 的配置管理系统，支持项目隔离、三维配置（机房/环境/分组）、规划/编辑/只读三种模式。
|
||
|
||
## 对接方式
|
||
|
||
kit 通过 HTTP 请求调用 Registry REST API，使用 Node 内置 `http`/`https` 模块，不引入新依赖。
|
||
|
||
## 配置存储
|
||
|
||
registry 的连接信息复用 kit 已有的 `kit config` 机制：
|
||
|
||
```shell
|
||
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、维度启用状态、配置数量。
|
||
|
||
```shell
|
||
$ 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）
|
||
|
||
```shell
|
||
# 查看整个项目
|
||
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）
|
||
|
||
```shell
|
||
kit registry config CommonExternalService:CF_R2_BUCKET
|
||
# 输出: store
|
||
```
|
||
|
||
**3. 设置值**（指定 key + value）
|
||
|
||
```shell
|
||
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 示例
|
||
|
||
```shell
|
||
# 导出整个项目
|
||
kit registry export CommonExternalService ./backup.json
|
||
|
||
# 仅导出 data/windows 下的配置
|
||
kit registry export CommonExternalService:data/windows ./backup-windows.json
|
||
```
|
||
|
||
导出文件格式：
|
||
|
||
```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 示例
|
||
|
||
```shell
|
||
# 从备份文件导入整个项目
|
||
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 当前为只读模式`
|