# npreview **Repository Path**: haukzero/npreview ## Basic Information - **Project Name**: npreview - **Description**: No description available - **Primary Language**: Unknown - **License**: Not specified - **Default Branch**: main - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-11-18 - **Last Updated**: 2026-11-21 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # npreview 把 SSH 主机、WSL 或容器里能通过 `127.0.0.1` 访问的 TCP 服务转发到本机。用浏览器或其他客户端打开 npreview 给出的本机地址即可访问。 ## 安装 在源码目录运行 `cargo build --release --locked`,把 `target/release/` 下的 `npreview`(Windows 上是 `npreview.exe`)放入本机 PATH。运行 `npreview --version` 确认安装。 - **SSH 主机**需要本机可以运行 `ssh`,目标主机上无需安装 npreview。 - **WSL、Docker 和 WSL Containers** 还需要把同版本的 Linux 可执行文件放入目标环境的 PATH。比如在 Docker 宿主机执行 `docker cp ./npreview web:/usr/local/bin/npreview`,把 Linux 版复制到名为 `web` 的容器。 ## 启动转发 ```sh npreview ssh:devbox 15500:5500 ``` 这会把 `devbox` 上的 `127.0.0.1:5500` 转发到本机的 15500。转发在后台运行。访问网页服务时,使用命令打印的 `http://127.0.0.1:15500/`。如果原始 URL 带有路径或查询参数,把它们加到这个本机地址上。 | 服务所在位置 | 目标写法 | | --- | --- | | SSH 主机 | `ssh:devbox` | | SSH 主机上的 Docker | `ssh:devbox/web` | | 本机 Docker | `docker:web`,也可简写为 `web` | | 本机 WSL | `wsl:Ubuntu` | | 本机 WSL Containers | `wslc:web` | SSH 目标可用主机名、IP 或 OpenSSH 别名,例如 `ssh:alice@devbox:2222/web`。IPv6 地址带端口时加方括号。连接时按提示核对主机指纹、输入密码或解锁密钥。脚本可用 `--batch` 禁用提示,并通过密钥或 SSH agent 认证。 转发 WSL 服务时,在 Windows 上运行 npreview。用 `wsl.exe -l -q` 查看发行版名称,名称含空格时给整个目标加引号。 ### 选择端口 - **省略端口**时转发目标的 5500,本机也优先用 5500。本机端口不可用时自动选空闲端口,以启动结果为准。 - **指定一个端口**,如 `5501`,则两边都用该端口。**指定两个端口**,如 `15500:5500`,则依次为本机端口和目标端口。 - **只指定目标端口**时用 `--remote-port 5501`。本机优先用同一端口,遇到冲突时自动选空闲端口。完整选项见 `npreview --help`。 ## 管理转发 | 命令 | 用途 | | --- | --- | | `npreview list` | 查看活动转发和实际本机端口 | | `npreview stop 15500` | 停止本机端口为 15500 的转发 | | `npreview stop` | 停止最近启动且仍在运行的转发 | | `npreview stop --all` | 停止所有活动转发 | 运行 `npreview ui` 可以在终端中选择目标、启动和停止转发、查看日志。点击顶部标签或按 `Alt+1` 到 `Alt+4` 切换面板。 - 在 **Targets** 选连接类型和目标。按 `/` 搜索,`m` 手动输入,`r` 刷新列表。选远端 Docker 时先选 SSH 主机,再选容器。 - 选好目标和端口后,点击 **Start forward** 或按 `F6` 启动。成功后界面会显示本机访问地址。 - 在 **Forwards** 选中转发,按 Enter 看日志,按 `d` 后确认停止。在 **Logs** 按 `f` 可查看已保存的日志,包括启动失败的记录。 ## 动态端口 若目标服务支持 npreview 动态端口,可加 `--dynamic` 自动转发它提供的附加端口。例如 `npreview --dynamic ssh:devbox 15500:5500`。停止主转发时,附加转发也会关闭。Windows 上通过 SSH 使用动态端口时,请先配置密钥或 SSH agent。 为自己的服务添加支持时,可参阅[动态端口接入](docs/dynamic-ports.md)。 ## 排查 - **转发启动失败**。查看报错给出的日志路径,或到终端控制面板的 **Logs** 中查找。WSL 和容器目标需要从目标环境的 PATH 找到 npreview。Docker 可用 `docker exec web npreview --version` 检查。 - **本机端口无法绑定**。启动时若提示 `bind local`,换一个本机端口,目标端口保持与服务一致。 - **浏览器打不开页面**。先确认服务在目标环境里能通过 `127.0.0.1` 和指定的目标端口访问,再核对浏览器使用的是 npreview 打印的本机端口。 - **SSH 断开后无法恢复**。后台重连使用密钥或 SSH agent。如果目标只能用密码登录,停止这条转发后从终端重新启动。 在 **Log config** 中可以调整日志级别和保留行数,保存后对新启动的转发生效。默认每个日志文件保留最近 512 条。 也可以设置环境变量 `NPREVIEW_LOG` 临时调整日志级别,例如 `DEBUG`,或用 `NPREVIEW_CONFIG` 指定 JSON 配置文件,文件内容可写为 ```json { "log": { "max_lines": 512, "level": "INFO" } } ```