@chenpu17/tcpmapping 2.1.1 → 2.4.1

package/CHANGELOG.md

@@ -0,0 +1,108 @@
+# Changelog
+
+## v2.4.1
+
+### 新增
+
+- CLI 支持 `-p, --port <port>` 与 `-H, --host <host>` 选项，可直接指定 WebUI 端口和监听地址：
+  - `tcpmapping start --host 0.0.0.0 --port 5000` 直接对外提供服务；
+  - 选项对 `start`、`restart`、`status`、`init` 生效；
+  - 优先级：命令行选项 > 环境变量 > `config.json`。
+- 监听 `0.0.0.0` 时，启动输出会列出 `localhost` 与本机局域网 IPv4 访问地址。
+- 新增 `--listen` 作为 `--host` 的别名，便于记忆。
+
+### 修复
+
+- 使用 `WEBUI_PORT` / `WEBUI_HOST` 启动时，CLI 输出的 WebUI 地址未反映环境变量，导致提示端口与实际监听端口不一致。
+- `init --host/--port` 现在会将指定值写入生成的 `config.json`。
+
+## v2.4.0
+
+### 新增
+
+- WebUI 新增「服务资源」面板，实时展示服务进程自身的资源占用：
+  - CPU 使用率（按核心数归一化为整机占比）与核心数；
+  - 进程内存占用（RSS）、占系统内存比例与 V8 堆用量；
+  - 实时上行 / 下行速率与进程启动以来的累计流量；
+  - 最近采样时间与顶部实时指示点。
+- `GET /api/status` 新增 `resources` 字段，包含 `cpuPercent`、`cpuCount`、`memory`、`traffic` 与 `sampledAt`。
+
+### 改进
+
+- 进程累计流量独立于映射统计，删除映射后仍可看到服务整体流量。
+- 资源面板随界面语言与主题切换，移动端自动堆叠为单列布局，进度条提供 `progressbar` 无障碍语义。
+- 系统状态卡片的累计流量改为上行 / 下行整行换行，避免窄卡片中「B」单位单独折行。
+
+## v2.3.0
+
+### 新增
+
+- WebUI 支持中文 / English 切换，语言偏好保存在浏览器本地，静态与动态文案同步切换。
+- 深色 / 浅色主题切换，首次访问跟随系统偏好，之后记住用户选择。
+- API 提示信息支持 `X-Language` / `Accept-Language`，英文界面下返回英文错误提示。
+- 登录页新增密码显示/隐藏按钮。
+- 标记连接的实际监听地址，IPv6 地址统一显示为 `[addr]:port`。
+
+### 改进
+
+- 重新设计 WebUI：统一颜色、圆角、阴影设计变量，半透明吸顶导航、图标化统计卡片。
+- 表格、状态徽章、按钮、连接卡片、空状态与弹窗全面美化，支持深色模式。
+- 操作反馈由 `alert` 改为轻量 Toast 提示。
+- 移动端布局优化，表单与连接信息自适应换行。
+- 最近连接记录支持按映射筛选，并随界面语言转换关闭原因。
+- 辅助文字对比度提升至 WCAG AA，表头、空状态、占位符在明暗主题下更清晰。
+- 表格中的地址与端口不再从中间折行；内联 favicon，消除 `/favicon.ico` 404。
+- `Accept-Language` 按首选语言解析，语言切换后历史关闭原因立即重新获取。
+
+## v2.2.0
+
+### 新增
+
+- WebUI 支持编辑已有映射（修改名称、监听地址/端口、目标地址/端口）。
+- 每个映射展示累计连接数、累计上下行流量，以及当前活跃连接流量。
+- 连接监控展示连接持续时间，并记录客户端实际连接的本地地址。
+- 新增最近连接记录（`GET /api/connections/history`），保存已关闭连接的源地址、目的地址、起止时间、持续时长、流量和关闭原因，WebUI 可按映射筛选查看。
+- 连接关闭日志包含持续时长与双向流量，便于审计。
+- 映射列表、连接状态和系统状态每 5 秒自动刷新，页面隐藏时自动暂停。
+- `timeouts.connect` / `timeouts.idle` 配置项，支持自定义连接与空闲超时（`idle: 0` 可禁用）。
+- `WEBUI_PORT`、`WEBUI_HOST`、`SESSION_SECRET` 环境变量支持。
+- `npm test` 冒烟测试，覆盖登录、映射增删改、TCP 转发与统计。
+
+### 修复与改进
+
+- **安全**：移除 `admin/admin123` 默认凭据，未配置密码时 WebUI 不再启动。
+- **安全**：登录成功后重新生成会话 ID，防止会话固定攻击。
+- **安全**：Cookie 增加 `HttpOnly`、`SameSite=Lax`，并支持自定义会话超时。
+- **安全**：增加跨站请求来源校验与安全响应头（CSP、X-Frame-Options、nosniff）。
+- **安全**：会话密钥迁移到 `~/.tcpmapping/.session-secret`，权限 0600。
+- **安全**：`auth-config.json` 使用原子写入并设置为 0600。
+- **安全**：WebUI 默认只监听 `127.0.0.1`（可在 config.json 中修改）。
+- **稳定性**：配置写入改为原子操作，避免异常退出导致配置损坏。
+- **稳定性**：映射启动失败（如端口被占用）时不再显示为"运行中"。
+- **稳定性**：停止映射会主动断开该映射下的所有活跃连接。
+- **稳定性**：优雅关闭会关闭 HTTP 服务与所有转发连接。
+- **性能**：TCP 转发使用 `pipe` 处理背压，避免慢速对端导致内存无限增长。
+- **性能**：启用 TCP_NODELAY 与 KeepAlive，降低转发延迟并检测死连接。
+- **体验**：编辑映射名称或目标地址时无需重启监听，已有连接不会被中断。
+- **协议**：支持 TCP 半关闭（half-close）。
+- **兼容**：CLI 停止服务不再依赖 `sleep` 命令，日志跟踪兼容 Windows。
+- **兼容**：CLI 使用当前 Node.js 可执行文件启动服务。
+- **UI**：修复 XSS 风险（映射名称等字段统一转义）。
+- **UI**：登录状态失效时自动跳转登录页；修复登录页回车可能重复提交的问题。
+- **UI**：新增监听地址输入项，可配置映射只监听指定网卡。
+
+## v2.1.1
+
+- 修复 Windows 下密码输入显示问题。
+
+## v2.1.0
+
+- 配置持久化与双语 README。
+
+## v2.0.0
+
+- 支持 CLI 工具，发布 npm 包 `@chenpu17/tcpmapping`。
+
+## v1.0.0
+
+- TCP 端口转发服务器，支持 WebUI 管理与实时连接监控。

package/README.md

@@ -10,9 +10,12 @@ TCP端口转发服务器，支持WebUI管理界面和实时连接监控。
 
 - **TCP Port Forwarding** - Forward TCP traffic to backend servers | TCP端口转发
 - **Multiple Mappings** - Manage multiple forwarding rules simultaneously | 多端口映射
-- **WebUI Management** - Modern web interface for real-time monitoring | WebUI管理界面
-- **Connection Monitoring** - Real-time connection count and traffic statistics | 实时连接监控
-- **Secure Authentication** - bcrypt password hashing, login protection | 安全认证
+- **WebUI Management** - Add, edit, start, stop and delete mappings in real time | WebUI管理界面
+- **Bilingual & Themes** - Simplified Chinese / English UI, dark and light themes | 中英文界面与深色模式
+- **Connection Monitoring** - Live connection details, per-mapping cumulative traffic and a searchable history of closed connections | 实时连接、累计流量与已关闭连接记录
+- **Service Resources** - Live CPU, memory and traffic usage of the forwarding process itself | 服务进程自身的 CPU、内存与实时流量
+- **Robust Forwarding** - Backpressure handling, TCP half-close support and idle timeouts | 背压控制、半关闭与空闲超时
+- **Secure by Default** - bcrypt hashing, login lockout, session hardening, no default password | 默认安全
 
 ---
 
@@ -28,6 +31,14 @@ tcpmapping init             # Create config file | 创建配置文件
 tcpmapping start            # Start server | 启动服务
 ```
 
+To allow remote access on port 5000 | 如需对外提供 5000 端口访问：
+
+```bash
+tcpmapping setup-password
+tcpmapping init  --host 0.0.0.0 --port 5000
+tcpmapping start --host 0.0.0.0 --port 5000
+```
+
 ### Local Install | 本地安装
 
 ```bash
@@ -53,6 +64,23 @@ npm start
 | `tcpmapping setup-password` | Set admin password | 设置管理员密码 |
 | `tcpmapping init` | Create config file | 创建配置文件 |
 
+### CLI Options | 命令行选项
+
+| Option | Description |
+|--------|-------------|
+| `-p, --port <port>` | WebUI port (default: 9999) | WebUI端口（默认9999） |
+| `-H, --host <host>` | Listen address (default: 127.0.0.1, use 0.0.0.0 for remote access) | 监听地址（默认127.0.0.1，远程访问用0.0.0.0） |
+
+Options apply to `start`, `restart`, `status` and `init`, and take precedence over environment variables and `config.json`.
+
+选项对 `start`、`restart`、`status`、`init` 生效，优先级高于环境变量和 `config.json`。
+
+```bash
+tcpmapping start --host 0.0.0.0 --port 5000   # Public access on port 5000 | 对外监听 5000
+tcpmapping status --port 5000                 # Check that instance | 查看该实例状态
+tcpmapping restart --port 5000                # Restart with the same port | 以该端口重启
+```
+
 ---
 
 ## WebUI
@@ -61,8 +89,29 @@ After starting, visit **http://localhost:9999**
 
 启动后访问 **http://localhost:9999**
 
+### Screenshots | 界面预览
+
+![管理面板 · 中文浅色 | Dashboard · Chinese light](docs/screenshots/dashboard-zh-light.webp)
+
+| English · Dark | Mobile · 中文 |
+|:---:|:---:|
+| ![English dark dashboard](docs/screenshots/dashboard-en-dark.webp) | ![移动端资源面板](docs/screenshots/dashboard-mobile-zh.webp) |
+
+<details>
+<summary>Login page | 登录页</summary>
+
+![登录页](docs/screenshots/login-zh-light.webp)
+
+</details>
+
+> Screenshots use demo data from an isolated instance | 截图使用独立演示实例的数据
+
 Default username | 默认用户名: `admin`
 
+> For security, the WebUI listens on `127.0.0.1` by default. To access it from another machine, start with `--host 0.0.0.0` (or set `webui.host` in `config.json`) and restrict access with a firewall.
+>
+> 出于安全考虑，WebUI 默认只监听 `127.0.0.1`。如需远程访问，请使用 `--host 0.0.0.0` 启动（或修改 `config.json` 中的 `webui.host`），并通过防火墙限制访问来源。公网部署请务必设置强密码，建议使用 HTTPS 反向代理。
+
 ---
 
 ## Configuration | 配置
@@ -87,11 +136,16 @@ Config file location (priority order) | 配置文件位置（优先级）:
       "target": { "host": "db.example.com", "port": 3306 }
     }
   ],
-  "webui": { "port": 9999 },
-  "logging": { "level": "info" }
+  "webui": { "enabled": true, "host": "127.0.0.1", "port": 9999 },
+  "logging": { "enabled": true, "level": "info" },
+  "timeouts": { "connect": 30000, "idle": 300000 }
 }
 ```
 
+For remote WebUI access, set `webui.host` to `"0.0.0.0"` and protect the port with a firewall.
+
+如需远程访问 WebUI，请将 `webui.host` 设为 `"0.0.0.0"`，并使用防火墙保护该端口。
+
 ### Config Options | 配置项
 
 | Option | Description |
@@ -101,8 +155,26 @@ Config file location (priority order) | 配置文件位置（优先级）:
 | `mappings[].listen.port` | Listen port | 监听端口 |
 | `mappings[].target.host` | Target host IP or domain | 目标主机 |
 | `mappings[].target.port` | Target port | 目标端口 |
+| `webui.enabled` | Enable the WebUI (default: true) | 是否启用 WebUI |
+| `webui.host` | WebUI bind address (default: 127.0.0.1) | WebUI监听地址 |
 | `webui.port` | WebUI port (default: 9999) | WebUI端口 |
+| `logging.enabled` | Enable logging (default: true) | 是否输出日志 |
 | `logging.level` | Log level: debug/info/warn/error | 日志级别 |
+| `timeouts.connect` | Target connect timeout in ms (default: 30000) | 连接超时（毫秒） |
+| `timeouts.idle` | Idle timeout in ms, 0 disables (default: 300000) | 空闲超时（毫秒，0为禁用） |
+
+### Environment Variables | 环境变量
+
+| Variable | Description |
+|----------|-------------|
+| `TCPMAPPING_DATA_DIR` | Override the data directory | 覆盖数据目录 |
+| `WEBUI_PORT` | Override the WebUI port | 覆盖WebUI端口 |
+| `WEBUI_HOST` | Override the WebUI bind address | 覆盖WebUI监听地址 |
+| `SESSION_SECRET` | Override the session secret | 覆盖会话密钥 |
+
+Priority | 优先级: CLI options > environment variables > `config.json` default.
+
+优先级：命令行选项 > 环境变量 > `config.json` 默认值。
 
 ---
 
@@ -114,6 +186,7 @@ User configuration is stored in `~/.tcpmapping/`:
 
 - `config.json` - Port mapping configuration | 端口映射配置
 - `auth-config.json` - Authentication configuration | 认证配置
+- `.session-secret` - Session signing secret (0600) | 会话签名密钥（0600）
 - `tcpmapping.log` - Log file | 日志文件
 - `tcpmapping.pid` - PID file | PID文件
 
@@ -125,10 +198,15 @@ User configuration is stored in `~/.tcpmapping/`:
 
 ## Security | 安全特性
 
-- **Strong Password Policy** - 8+ chars, uppercase, lowercase, numbers | 强密码策略
+- **No Default Password** - The WebUI will not start until `setup-password` is run | 无默认密码
+- **Strong Password Policy** - Length, character classes and expiry are configurable | 可配置的强密码策略
 - **Login Protection** - Lock after 5 failed attempts for 30 minutes | 登录保护
-- **Session Timeout** - 24 hours auto expiration | 会话超时
-- **Password Encryption** - bcrypt with 12 rounds | bcrypt加密
+- **Session Hardening** - Session ID regeneration on login, HttpOnly + SameSite cookies | 会话加固
+- **CSRF Protection** - Cross-origin state-changing requests are rejected | 跨站请求防护
+- **Security Headers** - CSP, X-Frame-Options, nosniff and no-store API responses | 安全响应头
+- **Localhost by Default** - The WebUI listens on 127.0.0.1 unless configured otherwise | 默认仅本机访问
+- **Atomic Config Writes** - Configuration files are written atomically | 配置原子写入
+- **Password Encryption** - bcrypt hashing | bcrypt加密
 
 ---
 
@@ -174,9 +252,34 @@ tcpmapping status
 
 ### Port already in use? | 端口被占用？
 
-Edit `webui.port` or `mappings[].listen.port` in config.json.
+Start with another port, or edit `webui.port` / `mappings[].listen.port` in config.json.
+
+使用 `--port` 指定其他端口启动，或修改 config.json 中的 `webui.port` / `mappings[].listen.port`。
+
+```bash
+tcpmapping restart --port 8080
+```
+
+---
+
+## Development | 开发
+
+Run the smoke test (starts an isolated server, verifies login, CRUD, TCP forwarding and statistics):
+
+运行冒烟测试（启动独立实例，验证登录、映射增删改、TCP 转发与统计）：
+
+```bash
+npm install
+npm test
+```
+
+---
+
+## Changelog | 更新日志
+
+See [CHANGELOG.md](CHANGELOG.md) for details.
 
-修改 config.json 中的 `webui.port` 或 `mappings[].listen.port`。
+详见 [CHANGELOG.md](CHANGELOG.md)。
 
 ---