docs: registry 模块设计文档 + 网站使用介绍

docs/registry-design.md

@@ -0,0 +1,175 @@
+# 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 当前为只读模式`