sshctl 0.2.5

Manage SSH hosts in SQLite and connect via ssh

sshctl（重写版）

sshctl 是一个命令行小工具：用 SQLite 管理你的 SSH 服务器别名（name），并且不使用 ~/.ssh/config。

适合新人/日常使用：

• 你不用记 IP、端口、用户名；主要用 id 选择（更直观）
• 支持“向导式输入”（--wizard）：跟着提示一步步填
• 支持“懒人连接”（sshctl ssh 不传参数）：先列出现有服务器，再让你输入要连哪个

---

0. 依赖（第一次使用前先装）

系统依赖（必须）

因为 SSH 密码自动登录需要 sshpass：

apt update
apt install -y sshpass

如果你不保存密码，也可以不用 sshpass（纯手动输密码/或用密钥）。

Python 依赖

项目会通过 pip 自动安装：rich。

---

1. 快速开始（新人 3 分钟上手）

第一步：进入目录

你现在把源码放在：

cd /mnt/sshctl-rewrite

第二步：安装（生成 sshctl 命令）

推荐用虚拟环境（更干净，不污染系统 Python）：

python3 -m venv .venv
source .venv/bin/activate
pip install -U pip
pip install -e .

装完之后就应该能看到：

sshctl -h

如果你不想安装，也可以临时运行：

python3 -m sshctl.cli -h

注意：Python 包目录名是 sshctl/。

---

2. 常用命令（照着抄就能用）

2.1 初始化数据库

默认数据库路径：~/.local/share/sshctl/servers.db

sshctl init

2.2 添加服务器（推荐用向导）

你可以选择是否保存登录密码：

• 保存：会以明文写入数据库（list 里不会显示明文，但 DB 文件里是明文）
• 不保存：连接时每次手动输入密码

最省事：

sshctl add --wizard

它会提示你依次输入：

• name（别名，唯一，比如 hk1、prod、test）
• host（IP 或域名）
• port（默认 22）
• user（默认 root，也常用 ubuntu）
• identity_file（私钥路径，可空，比如 ~/.ssh/id_rsa）
• password（登录密码，可空；若填写会加密保存，不会明文显示）
• note（备注，可空）

你也可以参数式添加（适合熟练后）：

sshctl add --name hk1 --host 1.2.3.4 --user root --port 22 --identity-file ~/.ssh/id_rsa

2.3 查看已有服务器

sshctl list

2.4 搜索服务器（记不清 name 时用）

sshctl search hk
sshctl search 192.168
sshctl search ubuntu

2.5 连接服务器

推荐：用序号连接（更快，不用记 name）：

sshctl ssh 1

懒人模式（不传参数）：

sshctl ssh

它会：

1. 先列出数据库里的服务器（带 id 列）
2. 让你直接输入 id 连接
3. 如果你直接回车，它会退回到“手动输入 name”的方式（兜底）

你仍然可以用 name 连接（兼容/兜底）：

sshctl ssh hk1

---

3. 密码保存方式（重要）

如果你在 add/edit 或 ssh 时提供了 password，sshctl 会把密码以明文写入数据库字段 password（不安全）。

• list 不会显示明文，只会显示“已设置”。
• 连接时会用 sshpass 自动登录。

强烈建议：仅在你完全信任机器且不共享账号/不外传数据库的情况下使用。

---

4. 关于 ~/.ssh/config（说明）

按你的需求：不使用 ~/.ssh/config。

• sshctl 连接时只会从数据库读取 host/user/port/identity_file/password 拼装 ssh 命令
• 如果保存了 password，会用 sshpass 自动登录；否则走手动输入

---

4. 修改 / 删除

修改（推荐用序号；也支持 name）：

sshctl edit 1 --wizard
# 或
sshctl edit hk1 --wizard

删除（推荐用 id；也支持 name）：

sshctl del 1
# 或
sshctl del hk1

注意：本工具会在删除后自动把 id 重新编号为 1..N。

---

5. 连接逻辑说明（新人必读）

• 如果该服务器记录保存了 password：
  • 会用 sshpass 自动把密码喂给 ssh（无需手动输入）
• 如果没有保存 password：
  • sshctl 会在连接前主动提示你输入一次密码
  • 默认会把该密码保存到数据库（下次自动登录）
  • 如果你不想保存，可加：

sshctl ssh <id> --no-save-password

说明：你在 ssh 自己弹出的 root@x.x.x.x's password: 里输入的内容，程序是拿不到的。 所以要实现“输入一次并保存”，必须由 sshctl 在连接前主动问你一次。

提醒：要能手动输密码，必须在真实终端里运行（有 TTY）。 如果你用脚本/CI 这种非交互方式运行，ssh 可能无法提示你输入密码。

---

6. 帮助（随时查）

总帮助：

sshctl -h
# 或
sshctl help

查看某个子命令怎么用：

sshctl help add
sshctl help ssh
sshctl help edit

---

6. 常见问题（新人容易卡的点）

Q1：为什么我输入 sshctl 提示 command not found？

因为你还没安装。

在项目目录执行：

pip install -e .

或用虚拟环境安装（推荐）。

Q2：数据库文件在哪？能换地方吗？

默认在：~/.local/share/sshctl/servers.db

也可以自定义：

sshctl --db /path/to/servers.db list

---

7. 目录结构（给开发者/以后扩展用）

• sshctl/cli.py：CLI 入口（生成命令 sshcli）
• sshctl/db.py：SQLite 连接与初始化表结构
• sshctl/repo.py：CRUD
• sshctl/ssh.py：连接逻辑（不读取 ~/.ssh/config）
• sshctl/model.py：数据模型