@cjwddz/mirror 1.1.0 → 2.0.0

package/README.md

@@ -1,15 +1,15 @@
-# Mirror —— 开发态远程工作空间镜像工具
+# Mirror - HTTP 隧道工具
 
-开发态远程工作空间镜像工具，将本地项目目录镜像到远程服务器，并在远程执行命令。
+将本地服务暴露到公网，支持多服务代理。
 
-## 功能特性
+## 特性
 
-- ✅ 全量文件同步（SNAPSHOT）
-- ✅ 增量文件同步（FILE_DIFF）
-- ✅ 远程命令执行（PTY 支持）
-- ✅ 文件变更实时监听
-- ✅ 状态机保证一致性
-- ✅ 一次性 workspace，完全可丢弃
+- ✅ 支持多个本地服务同时代理
+- ✅ 基于路径长度的优先级匹配（路径越长优先级越高）
+- ✅ 规则持久化存储
+- ✅ Token 认证
+- ✅ 单客户端连接（新连接自动踢出旧连接）
+- ✅ 支持 WebSocket 协议
 
 ## 安装
 
@@ -17,327 +17,225 @@
 npm install -g @cjwddz/mirror
 ```
 
-## 使用方法
+## 快速开始
 
-### 1. 启动 Host（远程服务器）
+### 1. 启动服务端
 
-```bash
-mirror host --port 7331
-```
-
-或者指定 token：
+在公网服务器上运行：
 
 ```bash
-mirror host --port 7331 --token my-custom-token
+mirror server -p 80 -t 7332 --token your-token
 ```
 
-可选参数：
-
-- `--port <port>`: 端口号（默认: 7331）
-- `--tmp-dir <dir>`: 临时目录（默认: /tmp）
-- `--ignore <patterns>`: 忽略的文件模式，逗号分隔（默认: node_modules,.git）
-- `--token <token>`: 指定 session token（不指定则自动生成）
+参数说明：
+- `-p, --port`: HTTP 服务端口（默认 80）
+- `-t, --tunnel-port`: WebSocket 隧道端口（默认 7332）
+- `--host`: 监听地址（默认 0.0.0.0）
+- `--token`: 认证令牌（可选）
 
-启动后会显示连接地址：
-
-```
-Mirror host started
-Listening on :7331
-
-Connect using:
-mirror link 192.168.1.100:7331?token=KJ82mZpX...
-```
+### 2. 添加代理规则
 
-### 2. 连接 Client（本地开发机）
+在本地机器上添加规则：
 
-在项目目录中执行：
+```bash
+# 添加 API 规则（路径较长，优先级高）
+mirror add example.com/api localhost:3001
 
-**使用 IP 和端口连接：**
+# 添加用户 API 规则（路径最长，优先级最高）
+mirror add example.com/api/users localhost:3002
 
-```bash
-mirror link 192.168.1.100:7331?token=KJ82mZpX...
+# 添加前端规则（根路径，优先级低）
+mirror add example.com localhost:5173
 ```
 
-**使用域名连接（支持反向代理）：**
+### 3. 连接服务端
 
 ```bash
-# HTTP (ws://)
-mirror link ws://mirror.example.com?token=KJ82mZpX...
-
-# HTTPS (wss://)
-mirror link wss://mirror.example.com?token=KJ82mZpX...
+mirror link mirror.tri-bank.online --token your-token
 ```
 
-**URL 格式说明：**
-
-- 格式：`[ws://|wss://]host[:port]?token=xxx`
-- `ws://` 或 `wss://` 协议前缀可选（默认 `ws://`）
-- `port` 可选，如果使用反向代理可以不指定端口
-- `token` 必需，用于身份验证
-
-连接成功后：
-
-1. 自动进行全量文件同步
-2. 启动文件监听（增量同步）
-3. 进入交互式终端
-
-在交互式终端中输入命令，命令会在远程服务器的工作空间中执行。
-
-输入 `exit` 或 `quit` 退出。
+连接后，规则会自动同步到服务端。
 
-## 工作原理
+### 4. 查看状态
 
-### 状态机（v0.1.0 简化版）
-
-Host 维护以下状态：
-
-- `EMPTY`: 无 client 连接
-- `SYNCING`: 初始全量文件同步中
-- `READY`: 就绪状态（可执行命令，可同步文件）
-
-**改进说明：**
-
-- 移除了 `RUNNING` 状态，使用独立标志位跟踪命令执行
-- 文件同步和命令执行完全解耦，互不干扰
-- 解决了长时间运行命令时文件同步卡死的问题
+```bash
+mirror status
+```
 
-### Workspace Version
+输出示例：
 
-- version 为单调递增整数
-- 由 client 生成
-- exec 时必须声明 version
-- host 仅在 `exec.version === currentVersion` 时允许执行
+```
+Mirror - Connection Status
+==========================
 
-### 文件同步
+✓ Mirror client is running
+    PID: 12345
 
-- **全量同步（SNAPSHOT）**: 连接时一次性同步所有文件
-- **增量同步（FILE_DIFF）**: 文件变更时实时同步
-  - 无论是否有命令在执行，文件变更都会**立即同步**到远程
-  - 使用原子写入保证文件一致性
-  - 不再使用 pending 队列机制
+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 (低)
+```
 
-- ✅ 修复了 `npm run start` 等长时间运行命令时文件同步卡死的问题
-- ✅ 文件变更实时生效，开发体验更流畅
-- ✅ 类似本地开发，文件保存后立即可用
+### 5. 查看规则
 
-### 进程管理
+```bash
+mirror list
+```
 
-- 使用 PTY 支持交互式命令
-- 命令执行在独立的进程组中
-- 断开连接时自动清理所有进程
+输出示例：
 
-## Nginx 反向代理配置
+```
+Mirror - Proxy Rules
+====================
 
-如果需要在生产环境中通过域名访问，可以使用 Nginx 作为反向代理。
+Total: 3 rule(s)
 
-### 基本配置（HTTP）
+[3] example.com/api/users -> localhost:3002
+     Priority: 高（路径规则）
+     Created: 2/18/2026, 11:57:20 AM
 
-```nginx
-server {
-    listen 80;
-    server_name mirror.example.com;
+[1] example.com/api -> localhost:3001
+     Priority: 高（路径规则）
+     Created: 2/18/2026, 11:57:14 AM
 
-    location / {
-        proxy_pass http://127.0.0.1:7331;
-        proxy_http_version 1.1;
+[2] example.com/ -> localhost:5173
+     Priority: 低（域名规则）
+     Created: 2/18/2026, 11:57:17 AM
+```
 
-        # WebSocket 升级
-        proxy_set_header Upgrade $http_upgrade;
-        proxy_set_header Connection "upgrade";
+### 6. 删除规则
 
-        # 传递原始信息
-        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;
+```bash
+# 删除指定规则
+mirror remove 1
 
-        # 超时设置
-        proxy_connect_timeout 7d;
-        proxy_send_timeout 7d;
-        proxy_read_timeout 7d;
-    }
-}
+# 删除所有规则
+mirror remove
 ```
 
-### HTTPS 配置（推荐）
+### 7. 断开连接
 
-```nginx
-server {
-    listen 443 ssl http2;
-    server_name mirror.example.com;
+```bash
+mirror stop
+```
 
-    # SSL 证书配置
-    ssl_certificate /path/to/cert.pem;
-    ssl_certificate_key /path/to/key.pem;
+## 命令参考
 
-    # SSL 优化
-    ssl_protocols TLSv1.2 TLSv1.3;
-    ssl_ciphers HIGH:!aNULL:!MD5;
-    ssl_prefer_server_ciphers on;
+### `mirror link <server> [options]`
 
-    location / {
-        proxy_pass http://127.0.0.1:7331;
-        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>`
 
-        # 超时设置（WebSocket 连接可能需要长时间保持）
-        proxy_connect_timeout 7d;
-        proxy_send_timeout 7d;
-        proxy_read_timeout 7d;
-    }
-}
+添加代理规则。
 
-# HTTP 重定向到 HTTPS
-server {
-    listen 80;
-    server_name mirror.example.com;
-    return 301 https://$server_name$request_uri;
-}
-```
+- `domain/path`: 域名和路径组合（如 `example.com/api`）
+- `target`: 目标服务地址（如 `localhost:3001`）
 
-### 配置说明
+**规则格式说明：**
+- 域名和路径写在一起，使用 `/` 分隔
+- 路径可以省略，省略时默认为 `/`
+- 示例：
+  - `example.com/api` - 匹配 `example.com/api` 开头的请求
+  - `example.com` 或 `example.com/` - 匹配 `example.com` 域名的所有请求
 
-1. **WebSocket 升级**：`proxy_set_header Upgrade` 和 `Connection "upgrade"` 是必需的，用于将 HTTP 连接升级为 WebSocket
-2. **超时设置**：WebSocket 连接可能需要长时间保持，建议设置较长的超时时间（如 7 天）
-3. **端口映射**：将 `127.0.0.1:7331` 替换为实际的 mirror host 服务地址和端口
-4. **SSL 证书**：使用 HTTPS 时，需要配置有效的 SSL 证书
+### `mirror remove [ruleId]`
 
-配置完成后，客户端可以使用以下方式连接：
+删除代理规则。
 
-```bash
-# HTTPS (推荐)
-mirror link wss://mirror.example.com?token=KJ82mZpX...
+- `ruleId`: 规则 ID（可选，不指定则删除所有规则）
 
-# HTTP (不推荐，仅用于测试)
-mirror link ws://mirror.example.com?token=KJ82mZpX...
-```
+### `mirror list`
 
-## 故障排查
+查看所有代理规则。
 
-### 502 Bad Gateway 错误
+### `mirror status`
 
-如果连接时遇到 502 错误，通常表示 Nginx 无法连接到后端 mirror host 服务。请检查：
+查看当前连接状态和配置。
 
-1. **mirror host 服务是否运行**：
+### `mirror stop`
 
-   ```bash
-   # 在服务器上检查
-   ps aux | grep mirror
-   netstat -tlnp | grep 7331
-   ```
+断开与服务端的连接。
 
-2. **Nginx 配置中的 proxy_pass 地址是否正确**：
+### `mirror server [options]`
 
-   ```nginx
-   proxy_pass http://127.0.0.1:7331;  # 确保端口和地址正确
-   ```
+启动 HTTP 隧道服务端。
 
-3. **查看 Nginx 错误日志**：
-   ```bash
-   tail -f /var/log/nginx/error.log
-   ```
+- `-p, --port`: HTTP 服务端口（默认 80）
+- `-t, --tunnel-port`: WebSocket 隧道端口（默认 7332）
+- `--host`: 监听地址（默认 0.0.0.0）
+- `--token`: 认证令牌（可选）
+- `--timeout`: 请求超时时间（毫秒，默认 30000）
 
-更多详细的排查步骤请参考 [TROUBLESHOOTING.md](./TROUBLESHOOTING.md)
+## 规则匹配逻辑
 
-### 协议选择
+1. 规则按路径长度降序排序（路径越长优先级越高）
+2. 同长度的规则，后添加的优先级更高
+3. 路径规则：请求路径以规则路径开头即匹配
+4. 根路径规则（`/`）：匹配该域名的所有路径
 
-- 如果域名配置了 HTTPS，**必须使用 `wss://` 协议**
-- 如果域名只配置了 HTTP，使用 `ws://` 协议
-- 使用 IP 地址连接时，根据实际情况选择协议
+### 示例
 
-示例：
+假设有以下规则：
 
-```bash
-# HTTPS 域名（推荐）
-mirror link wss://mirror.example.com?token=xxx
-
-# HTTP 域名（不推荐）
-mirror link ws://mirror.example.com?token=xxx
 ```
-
-## 新特性
-
-### 🎯 实时文件同步（v0.1.0）
-
-文件变更实时同步到远程，无论是否有命令在执行：
-
-```bash
-> npm run start
-Server listening on port 3000
-[同步] 同步中: src/index.ts (update)  ← 实时同步，不干扰命令输出
-[同步] ✓ 已同步: src/index.ts        ← 2秒后自动清除
+[1] example.com/api -> localhost:3001 (路径长度: 4)
+[2] example.com/ -> localhost:5173 (路径长度: 1)
+[3] example.com/api/users -> localhost:3002 (路径长度: 10)
 ```
 
-**优势：**
-
-- ✅ 不再有 pending 队列，文件立即同步
-- ✅ 长时间运行的命令不会阻塞文件同步
-- ✅ 开发体验更流畅，类似本地开发
-
-### 🎯 改进的 Ctrl+C 退出逻辑
-
-- **第一次 Ctrl+C**：发送中断信号给远程进程（中断命令）
-- **第二次 Ctrl+C**（3秒内）：退出 mirror 客户端
-- **无命令运行时**：第一次直接退出
-
-```bash
-> npm run start
-Server listening...
-^C (发送中断信号到远程进程，再次按 Ctrl+C 退出 mirror)
-Server shutting down...
-> _  # 命令中断，mirror 继续运行
-
-# 如需退出 mirror，再按一次 Ctrl+C
+请求匹配结果（按优先级排序）：
+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"
+    }
+  ]
+}
 ```
 
-### 🎯 命令输出与状态信息分离
+断开连接后规则会保留，下次连接时自动同步。
 
-- 状态信息使用灰色单行显示，不干扰命令输出
-- 状态信息会在 1 秒后自动清除
-- 命令输出正常显示，与状态信息互不干扰
+## 进程管理
 
-详细使用说明请参考：
+Mirror 客户端使用锁文件机制确保同一时间只有一个实例在运行。锁文件位于 `~/.mirror/.lock`。
 
-- [使用改进说明.md](./使用改进说明.md) - 中文详细说明
-- [IMPROVEMENTS.md](./IMPROVEMENTS.md) - English technical details
+- 如果尝试启动第二个实例，会提示已有进程在运行
+- 如果进程异常退出，锁文件会被自动清理
+- 使用 `mirror stop` 命令可以安全停止运行中的客户端
 
 ## 注意事项
 
-- ⚠️ 仅用于开发阶段，不适用于生产环境
-- ⚠️ 不支持多 client 并发（新连接会抢占旧连接）
-- ⚠️ workspace 是临时的，断开连接后自动清理
-- ⚠️ 不支持恢复，需要重新连接
-- ⚠️ 使用域名连接时，确保使用正确的协议（HTTPS 使用 wss://，HTTP 使用 ws://）
-- ⚠️ 使用反向代理时，确保 Nginx 配置了正确的 WebSocket 升级头
-- ℹ️ 新特性需要客户端和服务端版本匹配才能使用
-
-## 开发
-
-```bash
-# 安装依赖
-npm install
-
-# 构建
-npm run build
-
-# 测试
-npm test
-
-# Lint
-npm run lint
-```
+- 服务端和客户端必须使用相同的 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"}