@feng3d/ctc 0.0.19 → 0.1.0

package/README.md

@@ -6,173 +6,149 @@
 
 ## 特性
 
+- 极简设计，仅两步：`set` 配置服务端 → `-p <端口>` 映射
+- 远程端口由服务端自动分配，无需手动指定
 - **每个代理端口同时支持 HTTP/WebSocket/TCP/UDP 四种协议**
 - 三通道架构：WebSocket 控制通道 + TCP 二进制数据通道 + UDP 数据通道
 - 自动重连机制
-- 多代理支持
-- 单实例模式：通过 IPC 机制支持动态添加代理映射
 
 ## 快速开始
 
-推荐使用 `npx` 直接运行，无需全局安装：
+推荐使用 `npx` 直接运行，无需全局安装。两步即可完成映射：
 
-```bash
-# 启动客户端（连接本地服务器测试）
-npx @feng3d/ctc start -s ws://localhost:9000 -t "my-token" -p "8080:3000:localhost"
+### 1. 配置服务端访问信息
 
-# 查询状态与代理列表
-npx @feng3d/ctc status
+从服务端启动时打印的命令中复制（服务端 `start` 会自动给出）：
 
-# 停止客户端
-npx @feng3d/ctc stop
+```bash
+npx @feng3d/ctc set -ip 203.0.113.10 -p 9000 -t a1b2c3d4-e5f6-7890-abcd-ef1234567890
 ```
 
-## 命令说明
+服务端启用 TLS 时追加 `--tls`。配置保存在 `~/.chuantou/config.json`。
 
-### `start` - 启动客户端（别名：`ks`）
+### 2. 映射本地端口
 
 ```bash
-npx @feng3d/ctc start [选项]
+npx @feng3d/ctc -p 3000
 ```
 
-**单实例模式**：只允许一个客户端实例运行。如果客户端已运行，后续的 `start` 命令会向已运行的进程添加新的代理映射。
+服务端自动分配远程端口，映射成功后打印访问地址：
 
-**常用示例：**
+```
+  端口映射成功
+  ───────────────────────────────────
+  本地端口: 3000
+  服务端映射端口: 9123
+  访问地址: http://203.0.113.10:9123
+  ───────────────────────────────────
+```
 
-```bash
-# 指定服务器地址和认证令牌
-npx @feng3d/ctc start -s ws://your-server.com:9000 -t "my-token"
+访问 `http://<服务端IP>:<映射端口>` 即可访问本地的 3000 端口服务。
 
-# 添加单个代理映射：远程8080端口代理到本地3000端口
-npx @feng3d/ctc start -s ws://your-server.com:9000 -t "my-token" -p "8080:3000:localhost"
+## 命令说明
 
-# 添加多个代理映射
-npx @feng3d/ctc start -s ws://your-server.com:9000 -t "my-token" -p "8080:3000:localhost,8081:3001,8082:8080"
+### `set` - 配置服务端访问信息
 
-# 完整参数示例：指定服务器、令牌、代理和重连配置
-npx @feng3d/ctc start -s ws://your-server.com:9000 -t "my-token" -p "8080:3000:localhost" --reconnect-interval 5000 --max-reconnect 10
+```bash
+npx @feng3d/ctc set [选项]
 ```
 
 **参数说明：**
 
-| 参数 | 说明 | 示例 | 默认值 |
-|------|------|------|--------|
-| `-s, --server <url>` | 服务器地址（必填） | `ws://your-server.com:9000` | - |
-| `-t, --token <token>` | 认证令牌（必填） | `my-token` | - |
-| `-p, --proxies <proxies>` | 代理配置（逗号分隔），格式：`远程端口:本地端口:本地地址` | `8080:3000:localhost` | - |
-| `--reconnect-interval <ms>` | 重连间隔（毫秒） | `5000` | `5000` |
-| `--max-reconnect <number>` | 最大重连次数 | `10` | `10` |
-| `--no-daemon` | 前台运行（不作为后台守护进程） | - | - |
-| `--no-autostart` | 不注册开机启动 | - | - |
-| `-o, --open` | 启动后在浏览器中打开管理页面 | - | - |
+| 参数 | 说明 | 默认值 |
+|------|------|--------|
+| `-ip <ip>` | 服务端 IP 或域名（简写，标准形式 `--ip`） | （必填） |
+| `-p, --server-port <port>` | 服务端控制端口 | （必填） |
+| `-t, --token <token>` | 认证 token（与服务端一致） | （必填） |
+| `--tls` | 服务端启用 TLS（使用 wss/https） | `false` |
 
-### `status` - 查询客户端状态与代理列表（别名：`zt`）
+**示例：**
 
 ```bash
-npx @feng3d/ctc status
-```
+# 标准用法（推荐直接复制服务端打印的命令）
+npx @feng3d/ctc set -ip 203.0.113.10 -p 9000 -t my-token
 
-**输出示例：**
-
-```
-穿透客户端状态
-  PID: 12345
-  服务器: ws://your-server.com:9000
-  管理页面: http://127.0.0.1:9001/
-  开机启动: 已启用
-  连接状态: 已认证
-  运行时长: 5分30秒
-  代理映射: 2 个
-    :8080 -> localhost:3000
-    :8081 -> localhost:3001
+# 使用域名 + TLS
+npx @feng3d/ctc set -ip your.domain.com -p 9000 -t my-token --tls
 ```
 
-### `stop` - 停止客户端（别名：`tz`）
+> 说明：`-ip` 是用户习惯的简写（commander 短选项本是单字符，内部会自动重写为 `--ip`）。`set` 上下文中的 `-p` 指服务端控制端口，与映射命令的 `-p`（本地端口）含义不同。
+
+### 映射本地端口（默认动作）
 
 ```bash
-npx @feng3d/ctc stop
+npx @feng3d/ctc -p <本地端口> [选项]
 ```
 
-停止客户端并清理所有代理映射。
-
-## Web 管理页面
-
-客户端启动后，可以通过浏览器访问本地管理页面：
-
-```
-http://127.0.0.1:9001/
-```
+**参数说明：**
 
-管理页面提供以下功能：
-- 查看客户端连接状态（服务器地址、连接状态、认证状态）
-- 查看运行时长和重连次数
-- 查看所有已注册的代理映射
-- 动态添加新的代理映射
-- 删除现有代理映射
-- 每 3 秒自动刷新状态
+| 参数 | 说明 | 默认值 |
+|------|------|--------|
+| `-p, --port <localPort>` | 要映射的本地端口 | （必填） |
+| `-d, --detach` | 后台运行（终端关闭不停止） | 前台运行 |
 
-使用 `--open` 参数启动时可自动打开浏览器：
+**示例：**
 
 ```bash
-npx @feng3d/ctc start --open
-```
+# 前台运行，映射本地 3000 端口
+npx @feng3d/ctc -p 3000
 
-## 单实例模式
+# 后台运行
+npx @feng3d/ctc -p 3000 -d
+```
 
-客户端采用单实例模式设计：
+不带任何参数运行会显示帮助。
 
-1. **首次启动**：启动后台守护进程，建立与服务器的连接
-2. **再次启动**：如果客户端已运行，则向已运行进程添加新的代理映射
-3. **不同服务器**：如果尝试连接到不同的服务器，会提示错误
+## 运行模式
 
-这种设计简化了多代理的管理，无需为每组代理配置单独启动客户端。
+默认前台运行，Ctrl+C 或关闭终端即停止。
 
-## 代理配置格式
+追加 `-d` 后台运行（脱离终端），日志写入 `~/.chuantou/client.log`：
 
+```bash
+npx @feng3d/ctc -p 3000 -d
 ```
-remotePort:localPort[:localHost]
-```
-
-- `remotePort` - 公网端口
-- `localPort` - 本地端口
-- `localHost` - 本地地址（可选，默认：localhost）
 
-**推荐**：本地地址为 localhost 时推荐省略，使用 `8080:3000` 而非 `8080:3000:localhost`。
+后台进程停止用 `kill <pid>`（Linux）或 `taskkill /F /PID <pid>`（Windows），PID 在启动时打印。
 
-每个代理端口同时支持 HTTP/WebSocket/TCP/UDP 协议。
+## 配置文件
 
-**示例：**
+`set` 命令将服务端访问信息写入 `~/.chuantou/config.json`：
 
+```json
+{
+  "serverIp": "203.0.113.10",
+  "serverPort": 9000,
+  "token": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
+  "tls": false
+}
 ```
-# 单个代理（同时支持 HTTP/WebSocket/TCP/UDP）
-8080:3000:localhost
 
-# 完整格式
-8082:8080:192.168.1.100
-
-# 多个代理（逗号分隔）
-8080:3000:localhost,8081:3001,8082:8080
-```
+映射命令（`-p`）启动时读取该配置连接服务端。如需切换服务端，重新执行 `set` 即可覆盖。
 
 ## 作为库使用
 
 ```typescript
 import { Controller, ProxyManager } from '@feng3d/ctc';
-import type { Config } from '@feng3d/chuantou-shared';
 
-const config: Config = {
-  serverUrl: 'ws://your-server.com:9000',
+const controller = new Controller({
+  serverUrl: 'ws://203.0.113.10:9000/control',
   token: 'my-token',
   reconnectInterval: 5000,
-  maxReconnectAttempts: 10,
-  proxies: [
-    { remotePort: 8080, localPort: 3000, localHost: 'localhost' },
-    { remotePort: 8081, localPort: 3001, localHost: 'localhost' }
-  ]
-};
-
-const controller = new Controller(config);
+  maxReconnectAttempts: Infinity,
+});
+
+const proxyManager = new ProxyManager(controller);
+
 await controller.connect();
+// 认证成功后注册代理，服务端自动分配远程端口
+controller.on('authenticated', async () => {
+  await proxyManager.registerProxy({ localPort: 3000 });
+});
+
+proxyManager.on('registered', (assignedPort: number) => {
+  console.log(`已映射，访问地址: http://203.0.113.10:${assignedPort}`);
+});
 ```
 
 ## 许可证

package/dist/cli.d.ts

@@ -1,18 +1,20 @@
 #!/usr/bin/env node
 /**
  * @module cli
- * @description 穿透客户端 CLI - 简洁的命令行工具
  *
- * 使用方法：
- *   npx @feng3d/cts start          # 启动客户端（后台守护进程）
- *   npx @feng3d/cts stop           # 停止客户端
- *   npx @feng3d/cts restart        # 重启客户端
- *   npx @feng3d/cts status         # 查看状态
- *   npx @feng3d/cts proxies        # 管理代理映射
- *   npx @feng3d/cts config         # 管理配置
- *   npx @feng3d/cts boot           # 管理开机自启动
- *   npx @feng3d/cts logs           # 查看日志
- *   npx @feng3d/cts open           # 打开管理页面
+ * 穿透客户端命令行入口。
+ *
+ * 提供两条命令：
+ *
+ *   1. 设置服务端访问信息（写入配置文件）：
+ *      npx @feng3d/ctc set -ip <serverip> -p <serverport> -t <token> [--tls]
+ *
+ *   2. 映射本地端口到服务端（服务端自动分配端口并返回）：
+ *      npx @feng3d/ctc -p <localPort> [-d]
+ *
+ * 运行模式：
+ *   - 默认前台：进程依附终端，终端关闭即停止
+ *   - -d / --detach：后台运行，脱离终端；停止用系统 kill <pid>
  */
 export {};
 //# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAEA;;;;;;;;;;;;;;GAcG"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;;;;;GAgBG"}