gary
166ffdecbf
Add idempotent ktui sync, managed host keys, recoverable SSH sessions, resumable SFTP transfers, and mouse interactions. Enable background tunnels and staged self-updates on Windows with broader lifecycle tests.
398 lines
15 KiB
Markdown
398 lines
15 KiB
Markdown
# klink
|
||
|
||
`klink` 是一个使用 Go 编写的终端 TUI SSH 节点和端口转发管理器。它保存结构化节点配置，
|
||
使用系统 OpenSSH 建立连接，并提供本地、远程和动态 SOCKS5 转发。
|
||
|
||
|
||
## 当前能力
|
||
|
||
- 节点新增、编辑、复制、删除、搜索和标签
|
||
- IPv6 优先，网络不可达时回退 IPv4
|
||
- SSH Agent、私钥文件、系统凭据存储中的密码、ProxyJump 和 HostKey 策略
|
||
- Host key 指纹扫描、确认后写入或移除统一的 known_hosts
|
||
- 可恢复的 tmux SSH 会话与 Tunnel 启动状态自愈
|
||
- 本地转发 `-L`、远程转发 `-R`、动态转发 `-D`
|
||
- 隧道专用会话 `-N`、后台 worker、状态恢复和持续自动重连
|
||
- ktui 节点幂等同步、klink JSON 和 OpenSSH `ssh_config` 导入
|
||
- 版本化 JSON 导出
|
||
- TUI 宽屏双栏和窄屏单栏布局
|
||
- Nodes、Tunnels、SFTP、Settings 和 About 使用一致的单宽语义图标，无需 Nerd Font
|
||
- 可持久化的主题、SSH、地址优先级和隧道默认设置
|
||
- TUI 配置导入、导出、重载和本机 SSH 环境诊断
|
||
- SFTP 本地/远程双栏文件浏览、文件与目录递归上传下载
|
||
- About 应用信息、Gitea Release 更新检查和应用内更新
|
||
|
||
## 环境要求
|
||
|
||
- PATH 中可用的 OpenSSH `ssh`
|
||
- macOS、Linux 和 Windows：支持前台和后台隧道
|
||
|
||
保存密码依赖操作系统凭据存储：macOS 使用 Keychain，Windows 使用 Credential Manager，
|
||
Linux/BSD 使用 Secret Service（例如 GNOME Keyring 或 KWallet）。klink 不会把密码写入 `config.json`。
|
||
|
||
## 安装
|
||
|
||
macOS 和 Linux：
|
||
|
||
```sh
|
||
curl -fsSL https://gitea.bytevibe.dev/gary/klink/raw/branch/main/install.sh | sh
|
||
```
|
||
|
||
Windows PowerShell 5.1 或更高版本：
|
||
|
||
```powershell
|
||
irm https://gitea.bytevibe.dev/gary/klink/raw/branch/main/install.ps1 | iex
|
||
```
|
||
|
||
安装器会自动识别操作系统和 CPU 架构，从公开的 Gitea Release 下载最新版，并在安装前校验
|
||
`checksums.txt` 中的 SHA256。macOS/Linux 默认安装到可写的 `/usr/local/bin`，否则使用
|
||
`~/.local/bin`；Windows 默认安装到 `%LOCALAPPDATA%\Programs\klink\bin` 并加入用户 `PATH`。
|
||
|
||
安装指定版本或覆盖安装目录：
|
||
|
||
```sh
|
||
curl -fsSL https://gitea.bytevibe.dev/gary/klink/raw/branch/main/install.sh | \
|
||
KLINK_VERSION=v0.1.0 KLINK_INSTALL_DIR="$HOME/.local/bin" sh
|
||
```
|
||
|
||
```powershell
|
||
$env:KLINK_VERSION="v0.1.0"
|
||
$env:KLINK_INSTALL_DIR="$HOME\bin"
|
||
irm https://gitea.bytevibe.dev/gary/klink/raw/branch/main/install.ps1 | iex
|
||
```
|
||
|
||
## 构建
|
||
|
||
从源码构建需要 Go 1.25 或更高版本。
|
||
|
||
```sh
|
||
make build
|
||
./bin/klink version
|
||
```
|
||
|
||
也可以直接运行：
|
||
|
||
```sh
|
||
go run ./cmd/klink
|
||
```
|
||
|
||
## 快速开始
|
||
|
||
添加节点：
|
||
|
||
```sh
|
||
klink add Tokyo \
|
||
--ipv6 2001:db8::10 \
|
||
--ipv4 203.0.113.10 \
|
||
--user root \
|
||
--identity ~/.ssh/id_ed25519 \
|
||
--tags production,asia
|
||
```
|
||
|
||
在 Nodes 页面新增或编辑节点时，`Authentication` 可以选择 `SSH Agent`、`Key file` 或
|
||
`Password`。选择密码后输入的内容会保存到系统凭据存储，表单和配置文件中都不会显示明文；
|
||
再次编辑时密码留空会保留现有凭据。命令行可用 `--auth agent|key|password` 选择认证方式，
|
||
密码本身需要在 TUI 节点编辑器中保存。
|
||
|
||
打开 TUI：
|
||
|
||
```sh
|
||
klink
|
||
```
|
||
|
||
连接或预览实际执行的 OpenSSH 命令：
|
||
|
||
```sh
|
||
klink connect Tokyo
|
||
klink connect Tokyo --dry-run
|
||
klink connect Tokyo --ipv4
|
||
klink connect Tokyo --session
|
||
```
|
||
|
||
TUI 连接默认在系统安装了 `tmux` 时使用节点专属会话。SSH 中按 `Ctrl-b d` 可暂时分离并返回
|
||
klink，再次选择同一节点会恢复原会话；未安装 `tmux`、已经位于 tmux 内，或设置
|
||
`KLINK_NO_SESSION=1` 时自动使用普通 SSH 连接。
|
||
|
||
```sh
|
||
klink session list
|
||
klink session attach Tokyo
|
||
klink session kill Tokyo
|
||
```
|
||
|
||
检查服务器当前提供的 host key 指纹，再接受或移除 known_hosts 记录：
|
||
|
||
```sh
|
||
klink host-key inspect Tokyo --ipv6
|
||
klink host-key accept Tokyo --ipv6 --algorithm ssh-ed25519
|
||
klink host-key remove Tokyo --ipv6
|
||
```
|
||
|
||
## TUI 操作
|
||
|
||
| 按键 | 操作 |
|
||
| --- | --- |
|
||
| `Tab` / `Shift+Tab` | 切换下一个/上一个主页标签 |
|
||
| `←` / `→` 或 `h` / `l` | 在当前页面切换焦点或调整选项 |
|
||
| `↑` / `↓` 或 `j` / `k` | 移动选择 |
|
||
| `Enter` | 连接当前节点 |
|
||
| `/` | 搜索节点 |
|
||
| `a` / `e` / `c` / `d` | 新增、编辑、复制、删除 |
|
||
| `s` | 启动或停止当前隧道 |
|
||
| `r` | 重启当前隧道 |
|
||
| `Ctrl+S` | 保存编辑表单 |
|
||
| 空格 | 在设置页和编辑器中调整当前选项 |
|
||
| `Esc` | 取消或返回 |
|
||
| `q` | 退出 |
|
||
|
||
支持鼠标单击标签、列表项和 SFTP 面板，使用滚轮移动指针所在的列表。双击节点、隧道、
|
||
设置项、SFTP 文件或弹窗列表项会执行对应操作；表单字段和弹窗按钮可以直接点击。
|
||
|
||
设置 `NO_COLOR=1` 可以禁用颜色。
|
||
|
||
### About 页面
|
||
|
||
About 页面展示 klink Logo、版本、构建信息、运行平台、配置路径和项目地址。
|
||
使用 `↑/↓` 或 `j/k` 选择操作，按 `Enter` 检查更新或安装已经发现的新版本。
|
||
更新来自 [gitea.bytevibe.dev/gary/klink](https://gitea.bytevibe.dev/gary/klink) 的最新 Release；
|
||
klink 只会安装与当前系统、架构匹配且通过 `checksums.txt` SHA256 校验的附件。安装完成后需要重新启动 klink。
|
||
Windows 无法覆盖正在运行的可执行文件，因此会先把新版本暂存到当前程序旁边；退出 klink 后，
|
||
后台 PowerShell 助手会完成替换，再次启动即使用新版本。若替换失败，错误会写入
|
||
`klink.exe.update-error.log`。
|
||
|
||
当前仓库尚未发布 Release 时，检查结果会显示“尚未发布”，不会被当作网络故障。
|
||
|
||
### Settings 页面
|
||
|
||
在 Settings 页面使用 `↑/↓` 或 `j/k` 选择项目，使用 `←/→`、`h/l` 或空格修改，
|
||
操作项目按 `Enter` 执行。修改会立即保存。
|
||
|
||
可配置项目：
|
||
|
||
- `system`、`dark`、`light` 主题和颜色开关
|
||
- 新节点默认使用 SSH Agent、HostKey 策略和连接超时
|
||
- IPv6 优先或 IPv4 优先的连接顺序
|
||
- 新隧道默认模式和自动重连
|
||
- 从 ktui 同步节点，或导入 klink JSON 和 OpenSSH `ssh_config`
|
||
- 导出包含全局设置、节点和隧道的完整 JSON 备份
|
||
- 从磁盘重新加载当前配置
|
||
- 检查本机 `ssh` 路径、版本、`SSH_AUTH_SOCK` 和 Agent 身份状态
|
||
- 扫描所选节点的 host key 指纹，展示算法和 SHA256 指纹，并在用户确认后接受或移除记录
|
||
|
||
默认设置只影响之后新建的节点和隧道，不会静默改写已有项目。
|
||
严格校验和 `accept-new` 都显式使用同一个 known_hosts 文件，默认是 `~/.ssh/known_hosts`；
|
||
可通过 `KLINK_KNOWN_HOSTS` 指定其他路径。SSH、SFTP、隧道和 Settings 中的 Host Key 操作
|
||
都会使用这一路径。
|
||
|
||
### SFTP 页面
|
||
|
||
SFTP 页面左侧浏览本地文件，右侧浏览所选节点的远程文件。宽度不足时只显示当前焦点面板，
|
||
使用 `←/→` 或 `h/l` 切换本地和远程面板。
|
||
按 `n` 打开节点选择框，使用 `↑/↓` 或 `j/k` 选择节点并按 `Enter` 连接；当前节点名称显示在远程面板标题中。
|
||
按 `g` 可输入路径并跳转当前面板，相对路径以当前目录为起点，本地和远端都支持 `~` 家目录写法。
|
||
上传或下载开始后会显示进度、实时速度和已传输大小。使用 `←/→` 或 `h/l` 选择“取消”或“隐藏”，
|
||
按 `Enter` 执行；`Esc` 可直接隐藏。隐藏不会中断传输，按 `t` 打开任务列表后可重新查看排队中、运行中、已完成、失败或已取消的任务。
|
||
传输按加入顺序串行执行；任务列表中选择失败或取消的任务后按 `r` 会使用 klink 管理的 partial 文件断点续传。
|
||
|
||
| 按键 | 操作 |
|
||
| --- | --- |
|
||
| `↑/↓` 或 `j/k` | 移动文件选择 |
|
||
| `Tab` / `Shift+Tab` | 切换下一个/上一个主页标签 |
|
||
| `←/→` 或 `h/l` | 聚焦本地/远程面板 |
|
||
| `Enter` | 进入目录；选择文件时上传或下载 |
|
||
| `Backspace` / `Esc` | 返回当前面板的上级目录 |
|
||
| `u` | 上传左侧选中的文件或目录 |
|
||
| `d` | 下载右侧选中的文件或目录 |
|
||
| `f` | 在当前面板新建空文件 |
|
||
| `m` | 在当前面板新建目录 |
|
||
| `e` | 重命名当前文件或目录 |
|
||
| `x` | 确认后递归删除当前文件或目录 |
|
||
| `g` | 输入绝对或相对路径并跳转当前面板 |
|
||
| `r` | 刷新两侧目录 |
|
||
| `n` | 打开包含全部节点的选择框 |
|
||
| `t` | 打开 SFTP 传输任务列表 |
|
||
| 任务列表 `r` | 重试失败或已取消任务并断点续传 |
|
||
|
||
新建和重命名不会覆盖同名目标，删除目录前必须确认。文件夹会递归传输，目标已存在时必须确认后才会覆盖；文件先写入临时路径，完成后再重命名，
|
||
避免中断后留下看似完整的文件。启用断点续传的任务会保留带传输身份后缀的 `.klink-part-*` 文件；
|
||
下载任务同时保存只含传输身份、大小和 SHA256 的 sidecar 元数据。重试时会先校验本地 partial，
|
||
再让 SFTP 从远端对应偏移继续读取，不会重新传输已完成的前缀；成功后原子重命名为目标文件并清理元数据。
|
||
为避免密码提示破坏全屏界面，SFTP 使用非交互认证：
|
||
可以使用 SSH Agent（包括 Bitwarden SSH Agent）、无需交互输入口令的私钥，或节点中已保存的密码。
|
||
密码节点没有已保存凭据时，SFTP 会给出错误并要求先编辑节点。符号链接不会被传输。
|
||
文件操作完成后仅刷新受影响的面板；刷新中的列表会暂时显示加载状态，另一侧面板仍可继续浏览。
|
||
远端目录列表会在当前 klink 进程内按节点、连接地址和路径缓存。再次进入已访问目录或离开后返回
|
||
SFTP 页面时会直接使用缓存；远端标题会显示 `cached`。上传和远端增删改会自动失效相关缓存，
|
||
按 `r` 可忽略缓存并立即从服务器重新同步。缓存不会写入磁盘，退出 klink 后自动清除。
|
||
|
||
从 Nodes 页面或 `klink connect` 启动 SSH 时，klink 会在 OpenSSH 接管终端前显示 Logo 和感谢语。
|
||
|
||
## 发布与应用内更新
|
||
|
||
推送 `v*` tag 会触发 `.gitea/workflows/release.yml`，使用 GoReleaser 构建 Linux、macOS、Windows
|
||
的 amd64/arm64 压缩包以及 `checksums.txt`。仓库 Actions Secret 中需要配置具有 Release 写权限的 `GITEA_TOKEN`。
|
||
|
||
```sh
|
||
git tag -a v0.1.0 -m "klink v0.1.0"
|
||
git push origin v0.1.0
|
||
```
|
||
|
||
本地构建也可以注入版本信息：
|
||
|
||
```sh
|
||
make build VERSION=0.1.0 COMMIT=local BUILD_DATE=2026-07-19
|
||
```
|
||
|
||
发布前建议执行 `make check`，并确认 Gitea Actions 中的 Release 工作流成功上传所有平台附件和
|
||
`checksums.txt`。首次发布完成后，上面的安装命令即可直接使用。
|
||
|
||
## 端口转发
|
||
|
||
隧道专用模式开启自动重连后，会在网络故障或服务器重启后持续尝试恢复，退避时间从 1 秒
|
||
逐步增加并封顶为 32 秒；手动停止会立即取消等待。认证失败、Host Key 失败等不可恢复错误
|
||
仍会直接进入失败状态，避免无意义地重复认证。
|
||
|
||
本地数据库转发：
|
||
|
||
```sh
|
||
klink tunnel add database \
|
||
--node Tokyo \
|
||
--type local \
|
||
--bind 127.0.0.1:5432 \
|
||
--target db.internal:5432 \
|
||
--reconnect
|
||
```
|
||
|
||
远程转发：
|
||
|
||
```sh
|
||
klink tunnel add webhook \
|
||
--node Tokyo \
|
||
--type remote \
|
||
--bind 127.0.0.1:8080 \
|
||
--target localhost:3000
|
||
```
|
||
|
||
动态 SOCKS5 代理：
|
||
|
||
```sh
|
||
klink tunnel add socks-dev \
|
||
--node Tokyo \
|
||
--type dynamic \
|
||
--bind 127.0.0.1:1080
|
||
```
|
||
|
||
管理运行状态：
|
||
|
||
```sh
|
||
klink tunnel list
|
||
klink tunnel start database --dry-run
|
||
klink tunnel start database --background
|
||
klink tunnel stop database
|
||
klink tunnel restart database
|
||
```
|
||
|
||
一个配置可以包含多条转发规则：
|
||
|
||
```sh
|
||
klink tunnel forward add database \
|
||
--type local \
|
||
--bind 127.0.0.1:6379 \
|
||
--target redis.internal:6379
|
||
|
||
klink tunnel forward remove database 2
|
||
```
|
||
|
||
本地和动态转发默认绑定 `127.0.0.1`。绑定 `0.0.0.0`、`::` 或其他非回环地址时，
|
||
启动命令会拒绝继续；确认风险后显式传入 `--allow-public`。远程公开监听还取决于 SSH
|
||
服务器的 `GatewayPorts` 配置。
|
||
|
||
后台隧道和 TUI SFTP 依赖非交互式认证，可以使用 SSH Agent、无需手工输入口令的私钥，
|
||
或节点中已保存到系统凭据存储的密码。运行日志和 PID 状态保存在配置目录的 `runtime/` 子目录中，
|
||
权限为当前用户私有。Windows 后台 worker 使用脱离控制台的进程、命名停止事件和 Job Object；
|
||
关闭 klink 不会中断 Tunnel，停止时会优雅取消 SSH，强制终止也会清理整个 SSH 子进程树。
|
||
|
||
## 导入和导出
|
||
|
||
### 从 ktui 同步
|
||
|
||
在 TUI 的 Settings 页面选择 `Sync from ktui` 并按 `Enter`，或者直接运行：
|
||
|
||
```sh
|
||
klink sync ktui
|
||
```
|
||
|
||
klink 会执行：
|
||
|
||
```sh
|
||
ktui export json
|
||
```
|
||
|
||
然后根据 ktui UUID 同步节点名称、IPv4、IPv6、区域、分组和标签。已有节点会保留 klink 中的
|
||
SSH 用户、认证方式、密码凭据关联、密钥、端口、Host Key 策略、ProxyJump、连接记录和隧道引用；
|
||
只对首次出现的新节点应用当前默认 SSH 设置。重复执行同步不会创建副本。
|
||
|
||
如果旧版本导入的节点没有稳定 UUID，klink 只会在带有 `ktui-` ID 或 `Imported from ktui`
|
||
标记的节点中按名称或已有 IP 迁移匹配，不会覆盖同名的手工节点。ktui 中已经消失的节点不会
|
||
被自动删除，避免连带删除本地隧道或遗留凭据，需要时可在 Nodes 页面手工确认后删除。
|
||
|
||
也可以先保存 ktui 导出文件，再通过 `Import configuration` 或命令行同步：
|
||
|
||
```sh
|
||
ktui export json -o ktui-nodes.json
|
||
klink import ktui-nodes.json
|
||
```
|
||
|
||
首次同步后在 Nodes 页面选择新节点并按 `e` 填写 SSH `User`，再选择 Agent、密钥或密码认证。
|
||
保存的密码只进入系统凭据存储，不会出现在 klink JSON、导出文件或进程参数中。
|
||
|
||
同步 ktui JSON 或导入 klink JSON：
|
||
|
||
```sh
|
||
klink import nodes.json
|
||
```
|
||
|
||
导入 OpenSSH 配置：
|
||
|
||
```sh
|
||
klink import ~/.ssh/config --format ssh-config
|
||
```
|
||
|
||
只有具体的 `Host` 别名会被转换为节点。`Host *`、通配规则和 Match 块不会展开成节点；
|
||
导入结果会逐项报告跳过内容和名称/ID 冲突。
|
||
|
||
导出包含全局设置、节点和隧道的版本化 JSON：
|
||
|
||
```sh
|
||
klink export klink-backup.json
|
||
klink export -
|
||
```
|
||
|
||
导出只包含节点的认证方式和私钥路径，不包含系统凭据存储中的密码。将备份导入另一台设备后，
|
||
密码节点需要重新输入并保存密码。
|
||
|
||
## 配置与安全
|
||
|
||
查看配置路径：
|
||
|
||
```sh
|
||
klink config path
|
||
```
|
||
|
||
可以用全局参数或环境变量指定其他配置：
|
||
|
||
```sh
|
||
klink --config ./demo.json list
|
||
KLINK_CONFIG=./demo.json klink list
|
||
```
|
||
|
||
- 配置文件以 `0600` 权限原子写入
|
||
- 密码和私钥内容不会写入配置；只保存私钥路径
|
||
- 默认使用严格 HostKey 校验
|
||
- `accept-new` 允许首次写入主机密钥
|
||
- `insecure` 会禁用 HostKey 校验，仅应在明确理解风险时使用
|
||
- OpenSSH 参数通过结构化参数数组执行，不经过 shell 插值
|
||
|
||
## 许可证
|
||
|
||
klink 使用 [MIT License](LICENSE)。
|