# ssh-client-cli

**Repository Path**: rymaker/ssh-client-cli

## Basic Information

- **Project Name**: ssh-client-cli
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-07
- **Last Updated**: 2026-08-12

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# SSH 隧道 TUI

Linux 终端下的 SSH 端口映射工具：用 SSH 隧道把远程服务器上的服务映射到本机，或把本机
服务暴露给服务器，也可以直接开一个走服务器出口的 SOCKS5 代理。

**Node.js + TypeScript + Ink**，转发内核基于 [ssh2](https://github.com/mscdex/ssh2)，
纯 Node 实现，不依赖本机的 `ssh` 客户端。功能对标 Windows 上的 Electron 版
[`ssh-tool`](../../E:/code/ssh-tool)（SSH 端口映射工具 2.0），共用同一套同步服务端契约。

> **当前状态：M5 完成（TUI 与 CLI 都可用）。** M0–M5 已按
> [`docs/09-roadmap.md`](docs/09-roadmap.md) 完成，154 个测试全绿
> （含 08 文档 §4.1/§4.2/§4.3/§4.5 必测场景）；`scripts/smoke-m4-e2e.py`、
> `scripts/smoke-m5.sh` 可端到端验证。下一步是 M6（账号与端到端同步）。

## 与 Electron 版的关系

| | Electron 版（Windows） | 本项目（Linux TUI） |
|---|---|---|
| 界面 | Electron + Vue 3 | Ink（React for CLI） |
| 进程模型 | main / preload / renderer | daemon / IPC / TUI 客户端 |
| 转发内核 | `ssh2` | `ssh2`（逻辑基本照搬） |
| 本机凭据加密 | Electron safeStorage（DPAPI） | 主密码 → Argon2id → AES-256-GCM |
| 隧道存活 | 依赖窗口/托盘进程 | 独立 daemon，终端关掉照常跑 |
| 云端同步 | `/api/v1` 端到端加密 | **同一套服务端与同一套密文格式** |

同步文档格式（`SyncDocumentV1`）和加密封装与 Electron 版严格一致，因此同一个账号可以
在 Windows 桌面端与 Linux 终端之间双向同步。

## 文档索引

| 文档 | 内容 |
|------|------|
| [01-requirements.md](docs/01-requirements.md) | 需求、范围、非目标、验收标准 |
| [02-architecture.md](docs/02-architecture.md) | 进程模型、模块划分、目录结构、技术选型理由 |
| [03-data-model.md](docs/03-data-model.md) | 类型定义、配置文件布局、XDG 路径、迁移与导入导出 |
| [04-ipc-protocol.md](docs/04-ipc-protocol.md) | daemon ↔ 客户端的 Unix socket 协议与全部方法 |
| [05-security.md](docs/05-security.md) | 主密码密钥库、TOFU、内存卫生、socket 权限、威胁模型 |
| [06-sync.md](docs/06-sync.md) | 账号、端到端加密同步、三方合并、离线队列 |
| [07-tui-ux.md](docs/07-tui-ux.md) | 界面布局、快捷键、各屏幕交互与降级策略 |
| [11-ui-design.md](docs/11-ui-design.md) | **视觉规范（强制约束）**：间距、配色、曲线、反模式清单 |
| [08-testing.md](docs/08-testing.md) | 测试分层、模拟 SSH 服务器、WSL 调试手册 |
| [09-roadmap.md](docs/09-roadmap.md) | 里程碑拆分、任务清单、依赖顺序 |
| [10-packaging.md](docs/10-packaging.md) | 构建、分发、systemd 集成、版本策略 |
| [reference/api-v1.md](docs/reference/api-v1.md) | 同步服务端 API（自 Electron 版仓库复制，只读参考） |

参与开发（包括用 AI 编码助手）前**先读 [AGENTS.md](AGENTS.md)**，里面是不可协商的硬约束：
哪些文件必须原样复制、依赖上限、安全红线、UI 规范、协议版本规则。

## 命令

与 `sshtui --help` 的输出逐条一致：

```bash
sshtui                     # 启动 TUI（daemon 未运行时自动拉起）
sshtui daemon              # 前台运行 daemon（供 systemd 托管）
sshtui daemon --detached   # 后台 daemon 的拉起形态（一般由客户端自动唤起，无需手敲）
sshtui start <名称|id>     # 启动隧道（名称模糊匹配）
sshtui stop  <名称|id>     # 停止隧道
sshtui restart <名称|id>   # 重启隧道
sshtui status [--json] [--watch]                      # 查看状态
sshtui logs [--follow] [--level] [--tunnel] [--limit] # 查看日志
sshtui shutdown            # 停止全部隧道并退出 daemon
sshtui import <文件> [--replace]         # 导入配置备份（默认按 id 合并）
sshtui import --from-electron <文件>     # 从 Electron 版导入
sshtui import --template <文件>          # 导入配置模板
sshtui export <文件> [--include-secrets] # 导出配置备份
sshtui export --template <文件>          # 导出配置模板
sshtui sync now              # 立即同步（M6 提供）
sshtui install-service [--now] # 安装 systemd 用户服务（--now 立即启动）
sshtui uninstall-service       # 停用并删除 systemd 用户服务
sshtui --version             # 显示版本
sshtui --help                # 显示帮助
```

退出码：`0` 成功、`1` 一般失败、`2` 参数错误、`3` daemon 不可用、`4` 需要解锁。

## 开机自启（systemd）

```bash
sshtui install-service          # 安装 systemd 用户服务（打印写文件与 systemctl 动作）
sshtui install-service --now    # 顺带立即启动 daemon
sshtui uninstall-service        # 停用并删除 systemd 用户服务
```

需要开机自启（不登录也跑隧道）时，还要执行一次：

```bash
sudo loginctl enable-linger $USER
```

否则 SSH 登出后 `systemd --user` 会被回收，隧道跟着停止。
详见 [10-packaging.md](docs/10-packaging.md) §3。

## 卸载

```bash
sshtui shutdown
sshtui uninstall-service
npm uninstall -g ssh-client-tui
rm -rf ~/.config/ssh-client-tui ~/.local/share/ssh-client-tui ~/.local/state/ssh-client-tui
```

**注意**：`~/.local/share/ssh-client-tui` 里存有加密的本机凭据，删除后不可恢复
（云端有备份的除外）。

## 开发（计划）

```bash
npm install
npm run dev        # tsx 直接跑 TUI，daemon 以内联模式启动
npm run typecheck
npm test           # vitest；隧道用例使用本机模拟 SSH 服务器
npm run build      # 产出 dist/
```

开发与调试在 WSL Ubuntu-24.04 中进行，详见 [08-testing.md](docs/08-testing.md)。