com.jimuwd.xian.registry-proxy 1.0.1 → 1.0.2

package/README.MD

@@ -3,14 +3,14 @@
 
 ## 项目简介
 
-`com.jimuwd.xian.registry-proxy` 是一个轻量级的 npm 代理服务器，旨在为 Node.js 项目提供多 registry 的代理和 fallback 机制。它通过读取 Yarn 的配置文件（`.yarnrc.yml`），将多个 npm registry（如公共 registry、私有仓库等）代理到一个本地端口（默认 `4873`），并支持在本地 token 缺失时从全局配置文件回退获取认证信息。  
+`com.jimuwd.xian.registry-proxy` 是一个轻量级的 npm 代理服务器，旨在为 Node.js 项目提供多 registry 的代理和 fallback 机制。它通过读取独立的配置文件 `.registry-proxy.yml`，将多个 npm registry（如公共 registry、私有仓库等）代理到一个本地端口（默认 `4873`），并支持在 `.registry-proxy.yml` 中 token 缺失时从 Yarn 配置文件（本地 `.yarnrc.yml` 和全局 `~/.yarnrc.yml`）回退获取认证信息。  
 主要功能：
 - **多 registry 代理**：将多个 npm registry 统一代理到本地端口，提供单一访问入口。
 - **Fallback 机制**：按配置顺序尝试多个 registry，直到找到可用包。
-- **灵活的 token 管理**：优先使用本地配置文件中的 `npmAuthToken`，缺失时从全局配置文件读取。
+- **灵活的 token 管理**：优先使用 `.registry-proxy.yml` 中的 `npmAuthToken`，缺失时从 Yarn 配置文件读取。
 - **优雅关闭**：支持通过 SIGTERM 信号优雅停止服务。
 
-这个工具特别适合需要同时访问多个 npm 源（例如公司私有仓库和公共 npm registry）的开发场景，尤其在 CI/CD 或本地开发中，能显著提高依赖安装的稳定性和效率。
+这个工具特别适合需要同时访问多个 npm 源的开发场景，尤其在 CI/CD 或本地开发中，能提高依赖安装的稳定性和效率。
 
 ---
 
@@ -24,25 +24,29 @@ yarn add --dev com.jimuwd.xian.registry-proxy --registry https://your-private-re
 ```
 
 ### 配置
-1. **本地 `.yarnrc.yml`**  
-   在业务项目根目录创建或编辑 `.yarnrc.yml`，指定需要代理的 registry 和本地代理地址。对于需要认证的 registry，建议添加 `npmAlwaysAuth: true`：
+1. **代理配置文件 `.registry-proxy.yml`**  
+   在业务项目根目录创建 `.registry-proxy.yml`，指定需要代理的 registry 列表：
    ```yaml
-   npmRegistries:
+   registries:
      "http://localhost:4873/":
        npmAuthToken: "local-token" # 可选
      "https://registry.npmjs.org/":
-       # token 可省略，从全局读取
+       # token 可省略，从 Yarn 配置读取
      "https://your-private-registry.example.com/":
        npmAuthToken: "private-token" # 可选
        npmAlwaysAuth: true          # 强制要求认证
+   ```
 
+2. **本地 `.yarnrc.yml`**  
+   在项目根目录创建或编辑 `.yarnrc.yml`，指定 Yarn 使用本地代理地址：
+   ```yaml
    npmRegistryServer: "http://localhost:4873/"
    unsafeHttpWhitelist:
      - "localhost"
    ```
 
-2. **全局 `~/.yarnrc.yml`（可选）**  
-   如果本地未提供某些 registry 的 token，可以在用户主目录下的 `.yarnrc.yml` 配置回退 token：
+3. **全局 `~/.yarnrc.yml`（可选）**  
+   如果 `.registry-proxy.yml` 未提供某些 registry 的 token，可以在用户主目录下的 `.yarnrc.yml` 配置回退 token：
    ```yaml
    npmRegistries:
      "https://registry.npmjs.org/":
@@ -59,7 +63,7 @@ yarn add --dev com.jimuwd.xian.registry-proxy --registry https://your-private-re
    #!/bin/bash
 
    # 启动代理服务器并记录 PID
-   yarn run registry-proxy .yarnrc.yml ~/.yarnrc.yml &
+   yarn run registry-proxy .registry-proxy.yml .yarnrc.yml ~/.yarnrc.yml &
    PROXY_PID=$!
 
    # 等待代理服务器启动，最多 10 秒
@@ -94,7 +98,7 @@ yarn add --dev com.jimuwd.xian.registry-proxy --registry https://your-private-re
    ```json
    {
      "scripts": {
-       "start-proxy": "registry-proxy .yarnrc.yml ~/.yarnrc.yml",
+       "start-proxy": "registry-proxy .registry-proxy.yml .yarnrc.yml ~/.yarnrc.yml",
        "install": "bash start-proxy.sh"
      }
    }
@@ -105,7 +109,7 @@ yarn add --dev com.jimuwd.xian.registry-proxy --registry https://your-private-re
    ```bash
    yarn install
    ```
-    - 代理会在安装完成后自动停止。
+   - 代理会在安装完成后自动停止。
 
 ### 输出示例
 运行后，你会看到类似以下输出：
@@ -134,60 +138,71 @@ com.jimuwd.xian.registry-proxy/
 
 ### 功能实现
 1. **配置加载（`loadRegistries`）**：
-    - **本地配置文件**：从指定路径（默认 `./.yarnrc.yml`）读取 `npmRegistries`，提取 `registryUrl` 和 `npmAuthToken`。
-    - **全局配置文件**：如果本地 token 缺失，从指定路径（默认 `~/.yarnrc.yml`）读取对应 `registryUrl` 的 token。
-    - **安全设计**：本地 token 缺失时回退到全局 token 的设计，是为了避免将敏感的 `npmAuthToken` 写入项目配置文件并提交到代码仓库，从而降低安全隐患。全局配置文件（如 `~/.yarnrc.yml`）通常存储在用户主目录，不会被版本控制系统追踪。
-    - **优先级**：本地 token > 全局 token > 无 token。
-    - **错误处理**：本地配置文件必须存在且包含 `npmRegistries`，否则退出。
+   - **代理配置文件**：从指定路径（默认 `./.registry-proxy.yml`）读取 `registries`，提取 `registryUrl` 和 `npmAuthToken`。
+   - **Yarn 配置文件回退**：如果 `.registry-proxy.yml` 中 token 缺失，依次从本地 `.yarnrc.yml`（默认 `./.yarnrc.yml`）和全局 `~/.yarnrc.yml`（默认 `~/.yarnrc.yml`）读取对应 `registryUrl` 的 `npmAuthToken`。
+   - **安全设计**：将 `registryUrl` 和 token 配置独立于 `.registry-proxy.yml`，避免敏感信息直接写入 Yarn 配置文件并提交到代码仓库。回退到 Yarn 配置的 token（尤其是全局配置）进一步降低安全隐患。
+   - **优先级**：`.registry-proxy.yml` token > 本地 `.yarnrc.yml` token > 全局 `~/.yarnrc.yml` token > 无 token。
+   - **错误处理**：`.registry-proxy.yml` 必须存在且包含 `registries`，否则退出。
 
 2. **代理逻辑**：
-    - **服务器**：使用 Node.js 的 `http.createServer` 创建本地 HTTP 服务，默认监听 `4873` 端口。
-    - **请求转发**：将所有请求按配置顺序转发到目标 registry，附带对应的 `Authorization: Bearer <token>`（如果存在）。
-    - **Fallback**：依次尝试每个 registry，直到返回成功响应（`response.ok`）或全部失败（返回 404）。
+   - **服务器**：使用 Node.js 的 `http.createServer` 创建本地 HTTP 服务，默认监听 `4873` 端口。
+   - **请求转发**：将所有请求按配置顺序转发到目标 registry，附带对应的 `Authorization: Bearer <token>`（如果存在）。
+   - **Fallback**：依次尝试每个 registry，直到返回成功响应（`response.ok`）或全部失败（返回 404）。
 
 3. **进程管理**：
-    - **优雅关闭**：监听 `SIGTERM` 信号，关闭服务器并退出进程。
-    - **脚本集成**：通过 shell 脚本记录 PID，安装完成后发送 SIGTERM 停止服务。
+   - **优雅关闭**：监听 `SIGTERM` 信号，关闭服务器并退出进程。
+   - **脚本集成**：通过 shell 脚本记录 PID，安装完成后发送 SIGTERM 停止服务。
 
 ### 技术栈
 - **语言**：TypeScript（ES Modules）。
 - **模块系统**：`"module": "nodenext"`，兼容 Node.js v20+。
 - **依赖**：
-    - `node-fetch@^3.3.2`：发起 HTTP 请求。
-    - `js-yaml@^4.1.0`：解析 `.yarnrc.yml` 文件。
+   - `node-fetch@^3.3.2`：发起 HTTP 请求。
+   - `js-yaml@^4.1.0`：解析 `.registry-proxy.yml` 和 `.yarnrc.yml` 文件。
 - **Node.js 版本**：推荐 v14+，测试于 v20.17.0。
 
 ### CLI 参数
 ```bash
-registry-proxy [localConfigPath] [globalConfigPath] [port]
+registry-proxy [proxyConfigPath] [localYarnConfigPath] [globalYarnConfigPath] [port]
 ```
-- `localConfigPath`：本地 `.yarnrc.yml` 路径，默认 `./.yarnrc.yml`。
-- `globalConfigPath`：全局 `.yarnrc.yml` 路径，默认 `~/.yarnrc.yml`。
+- `proxyConfigPath`：代理配置文件路径，默认 `./.registry-proxy.yml`。
+- `localYarnConfigPath`：本地 Yarn 配置文件路径，默认 `./.yarnrc.yml`。
+- `globalYarnConfigPath`：全局 Yarn 配置文件路径，默认 `~/.yarnrc.yml`。
 - `port`：代理服务器端口，默认 `4873`。
 
 示例：
 ```bash
-yarn run registry-proxy ./custom.yml ~/.custom.yml 54321
+yarn run registry-proxy ./custom-registry.yml ./custom-yarn.yml ~/.custom-yarn.yml 54321
 ```
 
 ### 配置说明
+- **`.registry-proxy.yml`**：
+   - 使用 `registries` 字段定义代理的 registry 列表，与 Yarn 的 `npmRegistries` 区分。
+   - 示例：
+     ```yaml
+     registries:
+       "https://your-private-registry.example.com/":
+         npmAuthToken: "private-token"
+         npmAlwaysAuth: true
+     ```
 - **`npmAlwaysAuth: true`**：
-    - 在 `.yarnrc.yml` 中为需要认证的 registry 添加此配置，表示对该 registry 的所有请求都必须携带 `npmAuthToken`。
-    - **原因**：某些私有 npm 仓库（例如 Nexus 或 Artifactory）要求即使访问公共包，也需要认证。设置 `npmAlwaysAuth: true` 确保代理在转发请求时始终附带 token，避免因缺少认证导致的 401 错误。
-    - 如果不设置此项，Yarn 可能只在下载受限包时发送 token，而对公开包跳过认证，可能导致请求失败。
+   - 在需要认证的 registry 下添加此配置，表示所有请求必须携带 `npmAuthToken`。
+   - **原因**：某些私有仓库要求即使访问公共包也需要认证，设置此项避免因缺少 token 导致的 401 错误。
+- **Yarn 配置**：
+   - `.yarnrc.yml` 仅用于设置 `npmRegistryServer` 和回退 token，不定义代理的 registry 列表。
 
 ### 注意事项
 1. **端口冲突**：
-    - 默认端口 `4873` 是 Verdaccio 的惯用端口，可能与其他工具冲突。
-    - 检查端口占用：`lsof -i :4873`。
-    - 可通过参数指定其他端口（如 `54321`）。
+   - 默认端口 `4873` 是 Verdaccio 的惯用端口，可能与其他工具冲突。
+   - 检查端口占用：`lsof -i :4873`。
+   - 可通过参数指定其他端口（如 `54321`）。
 2. **配置文件格式**：
-    - 确保 `.yarnrc.yml` 遵循 Yarn 的格式，`npmRegistries` 为必填项。
+   - 确保 `.registry-proxy.yml` 包含 `registries` 字段，`.yarnrc.yml` 包含 `npmRegistryServer`。
 3. **日志**：
-    - 当前通过 `console.log` 输出启动信息，可扩展为文件日志。
+   - 当前通过 `console.log` 输出启动信息，可扩展为文件日志。
 4. **安全性**：
-    - 代理运行于本地，未开放外部访问，确保 `unsafeHttpWhitelist` 配置正确。
-    - 避免将 token 写入本地 `.yarnrc.yml`，优先使用全局配置或环境变量。
+   - 代理运行于本地，未开放外部访问，确保 `unsafeHttpWhitelist` 配置正确。
+   - 优先将 token 放入 `.registry-proxy.yml` 或全局 `.yarnrc.yml`，避免提交到代码仓库。
 
 ### 开发与发布
 1. **构建**：
@@ -200,3 +215,42 @@ yarn run registry-proxy ./custom.yml ~/.custom.yml 54321
    ```
 
 ---
+
+### 测试流程
+1. **构建并发布**：
+   ```bash
+   cd registry-proxy
+   yarn install
+   yarn build
+   yarn publish --registry https://your-private-registry.example.com/
+   ```
+2. **业务项目配置**：
+   - `.registry-proxy.yml`：
+     ```yaml
+     registries:
+       "http://localhost:4873/":
+         npmAuthToken: "local-token"
+       "https://registry.npmjs.org/":
+         # 无 token，回退到 Yarn 配置
+       "https://your-private-registry.example.com/":
+         npmAuthToken: "private-token"
+         npmAlwaysAuth: true
+     ```
+   - `.yarnrc.yml`：
+     ```yaml
+     npmRegistryServer: "http://localhost:4873/"
+     unsafeHttpWhitelist:
+       - "localhost"
+     ```
+   - `~/.yarnrc.yml`：
+     ```yaml
+     npmRegistries:
+       "https://registry.npmjs.org/":
+         npmAuthToken: "global-npm-token"
+     ```
+3. **运行**：
+   ```bash
+   yarn install
+   ```
+
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "com.jimuwd.xian.registry-proxy",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "type": "module",
   "description": "A lightweight npm registry proxy with fallback support",
   "main": "dist/index.js",