@cjwddz/mirror 1.2.0 → 2.0.0

package/README.md

@@ -1,14 +1,15 @@
-# Mirror —— HTTP 隧道工具
+# Mirror - HTTP 隧道工具
 
-HTTP 隧道工具，将本地服务暴露到公网，无需公网 IP 或配置路由器。
+将本地服务暴露到公网，支持多服务代理。
 
-## 功能特性
+## 特性
 
-- ✅ 将本地 HTTP 服务暴露到公网
-- ✅ WebSocket 隧道，低延迟高性能
-- ✅ 支持自定义端口和认证令牌
-- ✅ 自动重连机制
-- ✅ 支持并发请求
+- ✅ 支持多个本地服务同时代理
+- ✅ 基于路径长度的优先级匹配（路径越长优先级越高）
+- ✅ 规则持久化存储
+- ✅ Token 认证
+- ✅ 单客户端连接（新连接自动踢出旧连接）
+- ✅ 支持 WebSocket 协议
 
 ## 安装
 
@@ -16,195 +17,225 @@ HTTP 隧道工具，将本地服务暴露到公网，无需公网 IP 或配置
 npm install -g @cjwddz/mirror
 ```
 
-## 使用方法
+## 快速开始
 
-### 1. 启动服务端（公网服务器）
+### 1. 启动服务端
 
-在有公网 IP 的服务器上运行：
+在公网服务器上运行：
 
 ```bash
-mirror server --port 80 --tunnel-port 7332
+mirror server -p 80 -t 7332 --token your-token
 ```
 
-可选参数：
+参数说明：
+- `-p, --port`: HTTP 服务端口（默认 80）
+- `-t, --tunnel-port`: WebSocket 隧道端口（默认 7332）
+- `--host`: 监听地址（默认 0.0.0.0）
+- `--token`: 认证令牌（可选）
+
+### 2. 添加代理规则
+
+在本地机器上添加规则：
+
+```bash
+# 添加 API 规则（路径较长，优先级高）
+mirror add example.com/api localhost:3001
 
-- `--port <port>`: HTTP 服务端口（默认: 80）
-- `--tunnel-port <port>`: WebSocket 隧道端口（默认: 7332）
-- `--host <host>`: 监听地址（默认: 0.0.0.0）
-- `--token <token>`: 认证令牌（可选，建议设置）
-- `--timeout <ms>`: 请求超时时间（毫秒，默认: 30000）
+# 添加用户 API 规则（路径最长，优先级最高）
+mirror add example.com/api/users localhost:3002
 
-### 2. 启动客户端（本地开发机）
+# 添加前端规则（根路径，优先级低）
+mirror add example.com localhost:5173
+```
 
-在本地开发机上运行：
+### 3. 连接服务端
 
 ```bash
-mirror client ws://your-server.com:7332 http://localhost:3000
+mirror link mirror.tri-bank.online --token your-token
 ```
 
-参数说明：
+连接后，规则会自动同步到服务端。
 
-- `serverUrl`: 服务端 WebSocket 地址，格式: `ws://host[:port]`
-- `targetUrl`: 本地服务地址，格式: `http://localhost:port`
+### 4. 查看状态
 
-可选参数：
+```bash
+mirror status
+```
 
-- `--token <token>`: 认证令牌（与服务端设置的一致）
-- `--reconnect-interval <ms>`: 重连间隔（毫秒，默认: 5000）
-- `--max-retries <number>`: 最大重试次数（默认: 10）
+输出示例：
 
-### 3. 访问服务
+```
+Mirror - Connection Status
+==========================
 
-客户端连接成功后，访问服务端地址即可访问本地服务：
+✓ Mirror client is running
+    PID: 12345
+
+Server Configuration:
+    Server: mirror.tri-bank.online
+    Token: your-toke...
+
+Proxy Rules (3 configured):
+    [3] example.com/api/users -> localhost:3002 (高)
+    [1] example.com/api -> localhost:3001 (高)
+    [2] example.com/ -> localhost:5173 (低)
+```
+
+### 5. 查看规则
 
 ```bash
-# 例如，本地运行了一个服务在 localhost:3000
-# 服务端地址是 your-server.com
-# 现在可以通过 http://your-server.com 访问本地服务
+mirror list
 ```
 
-## 使用示例
+输出示例：
 
-### 基本用法
+```
+Mirror - Proxy Rules
+====================
 
-```bash
-# 服务端（服务器）
-mirror server --port 80 --tunnel-port 7332
+Total: 3 rule(s)
+
+[3] example.com/api/users -> localhost:3002
+     Priority: 高（路径规则）
+     Created: 2/18/2026, 11:57:20 AM
 
-# 客户端（本地）
-mirror client ws://your-server.com:7332 http://localhost:3000
+[1] example.com/api -> localhost:3001
+     Priority: 高（路径规则）
+     Created: 2/18/2026, 11:57:14 AM
+
+[2] example.com/ -> localhost:5173
+     Priority: 低（域名规则）
+     Created: 2/18/2026, 11:57:17 AM
 ```
 
-### 使用认证令牌
+### 6. 删除规则
 
 ```bash
-# 服务端
-mirror server --port 80 --tunnel-port 7332 --token my-secret-token
+# 删除指定规则
+mirror remove 1
 
-# 客户端
-mirror client ws://your-server.com:7332 http://localhost:3000 --token my-secret-token
+# 删除所有规则
+mirror remove
 ```
 
-### 自定义端口
+### 7. 断开连接
 
 ```bash
-# 服务端监听 8080 端口，隧道端口 7332
-mirror server --port 8080 --tunnel-port 7332
-
-# 客户端连接到 7332 端口
-mirror client ws://your-server.com:7332 http://localhost:3000
+mirror stop
 ```
 
-### 使用 Nginx 反向代理
+## 命令参考
 
-```nginx
-server {
-    listen 80;
-    server_name tunnel.example.com;
+### `mirror link <server> [options]`
 
-    location / {
-        proxy_pass http://127.0.0.1:80;
-        proxy_http_version 1.1;
+连接到 Mirror 服务端。
 
-        # WebSocket 升级
-        proxy_set_header Upgrade $http_upgrade;
-        proxy_set_header Connection "upgrade";
+- `server`: 服务端地址（如 `mirror.tri-bank.online`）
+- `-t, --token`: 认证令牌
 
-        # 传递原始信息
-        proxy_set_header Host $host;
-        proxy_set_header X-Real-IP $remote_addr;
-        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
-        proxy_set_header X-Forwarded-Proto $scheme;
+### `mirror add <domain/path> <target>`
 
-        # 超时设置
-        proxy_connect_timeout 7d;
-        proxy_send_timeout 7d;
-        proxy_read_timeout 7d;
-    }
+添加代理规则。
 
-    location /tunnel {
-        proxy_pass http://127.0.0.1:7332;
-        proxy_http_version 1.1;
+- `domain/path`: 域名和路径组合（如 `example.com/api`）
+- `target`: 目标服务地址（如 `localhost:3001`）
 
-        proxy_set_header Upgrade $http_upgrade;
-        proxy_set_header Connection "upgrade";
+**规则格式说明：**
+- 域名和路径写在一起，使用 `/` 分隔
+- 路径可以省略，省略时默认为 `/`
+- 示例：
+  - `example.com/api` - 匹配 `example.com/api` 开头的请求
+  - `example.com` 或 `example.com/` - 匹配 `example.com` 域名的所有请求
 
-        proxy_set_header Host $host;
-        proxy_set_header X-Real-IP $remote_addr;
-        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+### `mirror remove [ruleId]`
 
-        proxy_connect_timeout 7d;
-        proxy_send_timeout 7d;
-        proxy_read_timeout 7d;
-    }
-}
-```
+删除代理规则。
 
-客户端连接时使用域名：
+- `ruleId`: 规则 ID（可选，不指定则删除所有规则）
 
-```bash
-mirror client ws://tunnel.example.com/tunnel http://localhost:3000
-```
+### `mirror list`
 
-## 工作原理
+查看所有代理规则。
 
-Mirror 通过 WebSocket 建立隧道，将客户端和服务端连接起来：
+### `mirror status`
 
-1. **服务端**：监听 HTTP 端口，接收外部请求
-2. **客户端**：连接到服务端 WebSocket 隧道
-3. **请求转发**：服务端将 HTTP 请求通过隧道转发给客户端
-4. **响应返回**：客户端将请求转发给本地服务，获取响应后返回给服务端
-5. **外部访问**：用户访问服务端地址，实际访问的是本地服务
+查看当前连接状态和配置。
 
-```
-用户 → 服务端 (HTTP) → WebSocket 隧道 → 客户端 → 本地服务
-```
+### `mirror stop`
 
-## 注意事项
+断开与服务端的连接。
 
-- ⚠️ 服务端需要有公网 IP 或可访问的网络地址
-- ⚠️ 使用认证令牌可以提高安全性
-- ⚠️ 建议使用 Nginx 等 Web 服务器做反向代理
-- ⚠️ 确保防火墙开放相应端口
-- ℹ️ 仅用于开发和测试，不建议在生产环境中使用
+### `mirror server [options]`
 
-## 故障排查
+启动 HTTP 隧道服务端。
 
-### 无法连接
+- `-p, --port`: HTTP 服务端口（默认 80）
+- `-t, --tunnel-port`: WebSocket 隧道端口（默认 7332）
+- `--host`: 监听地址（默认 0.0.0.0）
+- `--token`: 认证令牌（可选）
+- `--timeout`: 请求超时时间（毫秒，默认 30000）
 
-1. 检查服务端是否正常运行
-2. 检查防火墙是否开放端口
-3. 检查 WebSocket 隧道端口是否正确
-4. 检查认证令牌是否匹配
+## 规则匹配逻辑
 
-### 请求超时
+1. 规则按路径长度降序排序（路径越长优先级越高）
+2. 同长度的规则，后添加的优先级更高
+3. 路径规则：请求路径以规则路径开头即匹配
+4. 根路径规则（`/`）：匹配该域名的所有路径
 
-1. 检查本地服务是否正常运行
-2. 增加 `--timeout` 参数值
-3. 检查网络连接是否稳定
+### 示例
 
-### 频繁断线
+假设有以下规则：
 
-1. 检查网络稳定性
-2. 调整 `--reconnect-interval` 参数
-3. 检查服务端资源使用情况
+```
+[1] example.com/api -> localhost:3001 (路径长度: 4)
+[2] example.com/ -> localhost:5173 (路径长度: 1)
+[3] example.com/api/users -> localhost:3002 (路径长度: 10)
+```
 
-## 开发
+请求匹配结果（按优先级排序）：
+1. `example.com/api/users/v1` → `localhost:3002`（匹配规则 3，路径长度 10）
+2. `example.com/api/products` → `localhost:3001`（匹配规则 1，路径长度 4）
+3. `example.com/` → `localhost:5173`（匹配规则 2，路径长度 1）
+4. `example.com/about` → `localhost:5173`（匹配规则 2，路径长度 1）
+
+## 配置文件
+
+规则存储在 `~/.mirror/rules.json` 中：
+
+```json
+{
+  "server": "mirror.tri-bank.online",
+  "token": "your-token",
+  "rules": [
+    {
+      "id": 1,
+      "domain": "example.com",
+      "path": "/api",
+      "target": "localhost:3001",
+      "priority": "high",
+      "createdAt": "2026-02-18T03:50:18.627Z"
+    }
+  ]
+}
+```
 
-```bash
-# 安装依赖
-npm install
+断开连接后规则会保留，下次连接时自动同步。
 
-# 构建
-npm run build
+## 进程管理
 
-# 测试
-npm test
+Mirror 客户端使用锁文件机制确保同一时间只有一个实例在运行。锁文件位于 `~/.mirror/.lock`。
 
-# Lint
-npm run lint
-```
+- 如果尝试启动第二个实例，会提示已有进程在运行
+- 如果进程异常退出，锁文件会被自动清理
+- 使用 `mirror stop` 命令可以安全停止运行中的客户端
+
+## 注意事项
+
+- 服务端和客户端必须使用相同的 token（如果配置了）
+- 端口需要开放防火墙访问
+- 建议在生产环境使用 HTTPS
+- WebSocket 隧道使用 wss:// 协议，需要 SSL 证书
 
-## License
+## 许可证
 
 MIT

package/dist/cli/cli-commands.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Mirror CLI 命令实现
+ */
+/**
+ * link 命令：连接服务端
+ */
+export declare function linkCommand(server: string, options: {
+    token?: string;
+}): Promise<void>;
+/**
+ * add 命令：添加代理规则
+ */
+export declare function addCommand(domainPath: string, target: string): Promise<void>;
+/**
+ * remove 命令：删除代理规则
+ */
+export declare function removeCommand(ruleId?: string): Promise<void>;
+/**
+ * list 命令：查看代理规则
+ */
+export declare function listCommand(): Promise<void>;
+/**
+ * stop 命令：断开连接
+ */
+export declare function stopCommand(): Promise<void>;
+/**
+ * status 命令：查看连接状态
+ */
+export declare function statusCommand(): Promise<void>;
+//# sourceMappingURL=cli-commands.d.ts.map

package/dist/cli/cli-commands.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-commands.d.ts","sourceRoot":"","sources":["../../src/cli/cli-commands.ts"],"names":[],"mappings":"AAAA;;GAEG;AAmEH;;GAEG;AACH,wBAAsB,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CA8F5F;AAED;;GAEG;AACH,wBAAsB,UAAU,CAAC,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CA0DlF;AAED;;GAEG;AACH,wBAAsB,aAAa,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAoClE;AAED;;GAEG;AACH,wBAAsB,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC,CAsBjD;AAED;;GAEG;AACH,wBAAsB,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC,CA+BjD;AAED;;GAEG;AACH,wBAAsB,aAAa,IAAI,OAAO,CAAC,IAAI,CAAC,CAyDnD"}