chore: custom registry (#793)

docs/sync-setup.md

@@ -1,14 +1,17 @@
 # 🚀 开启包同步服务
+
 > 我们将以 `127.0.0.1:7001` 为例，演示如何开启包同步服务，在实际部署中请替换对应的 registry 站点，更多部署相关内容可以参考 [deploy-in-docker](./deploy-in-docker.md)
 
 ## 🔌 确保 registry 服务已开启
 
 cnpmcore 实现了所有 registry 相关 api 这意味着我们可以直接使用 npm 客户端进行相关验证工作。
+
 ```bash
 npm ping --registry=http://127.0.0.1:7001
 ```
 
 预期输出
+
 ```bash
 npm notice PING http://127.0.0.1:7001/
 npm notice PONG 19ms
@@ -22,11 +25,13 @@ npm notice PONG }
 
 在默认配置中，我们内置了 `cnpmcore_admin` 作为管理员账号，你可以通过修改不同环境对应的配置文件来定义对应管理员账号。
 此外，我们默认开启了 webAuth，只需执行 npm login 即可在命令行进行登录相关操作
+
 ```shell
 npm login --registry=http://127.0.0.1:7001
 ```
 
 预期将在浏览器唤起登录相关页面，输入账号 `cnpmcore_admin` 及密码即可（未创建时会自动注册）
+
 ```bash
 Login at:
 http://localhost:7001/-/v1/login/request/session/ada5af3e-773d-4e64-b8bb-e98ffe25d1c0
@@ -34,10 +39,12 @@ Press ENTER to open in the browser...
 ```
 
 查看本地对应授权信息，注意服务端将不会存储 token 值，请妥善保存，或者进行对应 revoke 操作
+
 ```shell
 cat ~/.npmrc
 # //127.0.0.1:7001/:_authToken=cnpm_1byTg6qJuZZm3ZnMpFl43fz6DsbhwN2rH_373PXC
 ```
+
 其中，`cnpm_1byTg6qJuZZm3ZnMpFl43fz6DsbhwN2rH_373PXC` 就是我们的管理员 token，后续我们将用这个 token 来进行同步任务初始化，我们可以通过 `whoami` 来验证 token 是否有效
 
 ```bash
@@ -75,7 +82,7 @@ npm registry 将通过服务实时广播相关包变更，也就是 `changesStre
 changesStream 内包含了包所有版本变更信息，在存量同步场景存在大量冗余，我们可以通过一个脚本来快速创建同步任务。
 
 ```typescript
-import { load } from "all-package-names";
+import { load } from 'all-package-names';
 import urllib from 'urllib';
 import { setTimeout } from 'timers/promises';
 
@@ -93,7 +100,7 @@ async function main() {
   const total = data.packageNames.length;
   console.log('Total %d packages', total);
   const lastIndex = 0;
-  for (const [ index, fullname ] of data.packageNames.entries()) {
+  for (const [index, fullname] of data.packageNames.entries()) {
     if (index < lastIndex) continue;
     let success = false;
 
@@ -104,13 +111,33 @@ async function main() {
         const data = result.data;
         if (data && data.id) {
           const logUrl = `${url}/${data.id}/log`;
-          console.log('[%s/%s] %s, status: %s, log: %s', index, total, fullname, result.status, logUrl);
+          console.log(
+            '[%s/%s] %s, status: %s, log: %s',
+            index,
+            total,
+            fullname,
+            result.status,
+            logUrl
+          );
         } else {
-          console.log('[%s/%s] %s, status: %s, data: %j', index, total, fullname, result.status, data);
+          console.log(
+            '[%s/%s] %s, status: %s, data: %j',
+            index,
+            total,
+            fullname,
+            result.status,
+            data
+          );
         }
         success = true;
       } catch (err: any) {
-        console.error('[%s/%s] %s, error: %s', index, total, fullname, err.message);
+        console.error(
+          '[%s/%s] %s, error: %s',
+          index,
+          total,
+          fullname,
+          err.message
+        );
         await setTimeout(1000);
       }
     }
@@ -133,3 +160,53 @@ sourceRegistryIsCNpm: true,
 changesStreamRegistry: 'https://registry.npmmirror.com/_changes',
 changesStreamRegistryMode: ChangesStreamMode.json,
 ```
+
+## 🎯 为 scope 指定单独同步源
+
+在某些场景下，我们可能需要为特定的 scope 指定单独的同步源。例如，公司内部的一些私有包需要从特定的 registry 同步。以下是具体操作步骤：
+
+### 1. 创建 Registry
+
+首先需要创建一个新的 registry，并指定其 changesStream 信息：
+
+```bash
+# 创建新的 registry
+curl -H "Authorization: Bearer cnpm_1byTg6qJuZZm3ZnMpFl43fz6DsbhwN2rH_373PXC" \
+  -X POST http://127.0.0.1:7001/-/registry \
+  -H "Content-Type: application/json" \
+  -d '{
+    "name": "custom-registry",
+    "host": "https://custom.registry.com/",
+    "changeStream": "https://custom.registry.com/_changes",
+    "type": "cnpmcore"
+  }'
+```
+
+### 2. 创建 Scope 并关联 Registry
+
+创建完 registry 后，我们可以为特定的 scope 指定这个 registry：
+
+```bash
+# 创建 scope 并关联到指定的 registry
+curl -H "Authorization: Bearer cnpm_1byTg6qJuZZm3ZnMpFl43fz6DsbhwN2rH_373PXC" \
+  -X POST http://127.0.0.1:7001/-/scope \
+  -H "Content-Type: application/json" \
+  -d '{
+    "name": "@custom",
+    "registryId": "REGISTRY_ID"  # 替换为上一步创建的 registry ID
+  }'
+```
+
+### 3. 开启自动同步
+
+创建完 registry 和 scope 后，需要开启自动同步功能：
+
+```bash
+# 为指定的 registry 开启同步任务
+curl -H "Authorization: Bearer cnpm_1byTg6qJuZZm3ZnMpFl43fz6DsbhwN2rH_373PXC" \
+  -X POST http://127.0.0.1:7001/-/registry/REGISTRY_ID/sync \
+  -H "Content-Type: application/json" \
+  -d '{
+    "since": "1"  # 可选参数，指定从哪个序列号开始同步
+  }'
+```