From 31b50f9f433d02dbec66ed9d9bebd7229dda5eb2 Mon Sep 17 00:00:00 2001
From: "jif2.zhang" <jif2.zhang>
Date: Fri, 11 Sep 2026 11:26:57 +0800
Subject: [PATCH] =?UTF-8?q?docs:=20registry=20=E6=A8=A1=E5=9D=97=E8=AE=BE?=
 =?UTF-8?q?=E8=AE=A1=E6=96=87=E6=A1=A3=20+=20=E7=BD=91=E7=AB=99=E4=BD=BF?=
 =?UTF-8?q?=E7=94=A8=E4=BB=8B=E7=BB=8D?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 docs/registry-design.md  | 175 +++++++++++++++++++++++++++++++++++++++
 website/docs/registry.md | 116 ++++++++++++++++++++++++++
 website/sidebars.js      |   1 +
 3 files changed, 292 insertions(+)
 create mode 100644 docs/registry-design.md
 create mode 100644 website/docs/registry.md

diff --git a/docs/registry-design.md b/docs/registry-design.md
new file mode 100644
index 0000000..db2734f
--- /dev/null
+++ b/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 当前为只读模式`
diff --git a/website/docs/registry.md b/website/docs/registry.md
new file mode 100644
index 0000000..f026237
--- /dev/null
+++ b/website/docs/registry.md
@@ -0,0 +1,116 @@
+---
+sidebar_position: 3
+---
+
+# Registry 配置管理
+
+kit 可对接 [Registry](https://git.honor3.com/Fullstack/registry) 配置管理中心，通过命令行管理微服务配置。
+
+## 配置连接
+
+使用 `kit config` 设置 Registry 地址和认证信息：
+
+```shell
+# 设置 Registry 服务地址
+kit config registryUrl http://your-registry-host:8008
+
+# 设置认证 Token（Registry 设置中获取）
+kit config registryToken your-token-here
+```
+
+验证连接：
+
+```shell
+kit registry list
+```
+
+## 查看项目
+
+```shell
+# 列出所有项目
+kit registry list
+
+# 输出示例：
+# ID                    名称                      维度
+# proj-abc-123          CommonExternalService     IDC=✓ Env=✓ Group=✓
+# proj-def-456              OrderService              IDC=✗ Env=✓ Group=✓
+```
+
+## 管理配置
+
+`kit registry config` 支持查看和修改配置项。
+
+### 查看配置
+
+```shell
+# 查看整个项目的所有配置
+kit registry config CommonExternalService
+
+# 查看指定路径下的配置
+kit registry config CommonExternalService:data/windows
+
+# 获取单个配置值
+kit registry config CommonExternalService:CF_R2_BUCKET
+```
+
+### 设置配置值
+
+```shell
+kit registry config CommonExternalService:CF_R2_BUCKET new-value
+```
+
+### 路径语法
+
+`project:path` 中的 `path` 对应配置的路径前缀：
+
+| 语法 | 含义 |
+|------|------|
+| `project` | 整个项目 |
+| `project:data` | 路径以 `data` 开头的配置 |
+| `project:data/windows` | 路径以 `data/windows` 开头的配置 |
+| `project:data/windows/kit.exe` | 精确匹配单个配置 |
+
+## 导入导出
+
+### 导出
+
+```shell
+# 导出整个项目到文件
+kit registry export CommonExternalService ./backup.json
+
+# 仅导出指定路径下的配置
+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": "https://pub-xxx.r2.dev/data/windows/kit.exe",
+      "type": "string",
+      "description": "Windows 二进制下载地址"
+    }
+  ]
+}
+```
+
+### 导入
+
+```shell
+# 从备份文件导入
+kit registry import CommonExternalService ./backup.json
+
+# 导入到指定路径下
+kit registry import CommonExternalService:data ./backup.json
+```
+
+导入规则：
+- 已存在的 key → 更新值
+- 不存在的 key → 新增
+- 远程有但本地没有的 → 保留不动
diff --git a/website/sidebars.js b/website/sidebars.js
index ea02e30..437bc1e 100644
--- a/website/sidebars.js
+++ b/website/sidebars.js
@@ -3,6 +3,7 @@ const sidebars = {
   tutorialSidebar: [
     'intro',
     'features',
+    'registry',
     'more',
   ],
 };