SSH 免密 + 主机指纹登录完整安装步骤（macOS）

本文档目标：

• 让你可以通过 ssh root@tsh 免密登录远程主机（实际主机名为 sh）。

• 让你可以直接输入 tsh，先走本机 Touch ID，再发起 SSH 登录。

1. 前置条件

• 本机：macOS（已安装 OpenSSH，默认自带）。

• 远端：可通过 sh 这个主机名访问（DNS 或 hosts 已配置）。

• 你知道远端 root 密码（仅首次下发公钥时需要）。

2. 生成 SSH 密钥（如已有可跳过）

先检查是否已有密钥：

ls -la ~/.ssh/id_rsa ~/.ssh/id_rsa.pub

如果不存在，执行：

ssh-keygen -t rsa -b 4096 -f ~/.ssh/id_rsa

说明：

• 可以设置口令，也可以不设置。

• 本文后续方案不依赖私钥口令，而是用 Touch ID 网关脚本做登录前验证。

3. 配置 ~/.ssh/config 的 tsh 主机

编辑 ~/.ssh/config，追加（或修改）如下配置：

Host tsh
    HostName sh
    User root
    IdentityFile /Users/wuqiyue/.ssh/id_rsa
    IdentitiesOnly yes
    PreferredAuthentications publickey
    PubkeyAuthentication yes
    UseKeychain yes
    AddKeysToAgent yes

注意：

• HostName sh 表示真实主机是 sh，但你本地可用 tsh 作为别名。

• IdentityFile 路径要和你的私钥文件一致。

4. 首次下发公钥到远端（实现免密）

执行：

ssh-copy-id root@tsh

第一次会提示输入远端 root 密码。成功后测试：

ssh root@tsh 'echo ok'

返回 ok 即表示免密生效。

5. 可选：把密钥加入 Keychain/ssh-agent

ssh-add --apple-use-keychain ~/.ssh/id_rsa

6. 配置 Touch ID 登录前验证脚本

创建脚本 ~/.local/bin/ssh-touchid-gate：

mkdir -p ~/.local/bin
cat > ~/.local/bin/ssh-touchid-gate <<'EOF'
#!/usr/bin/env bash
set -euo pipefail
​
/usr/bin/swift - <<'SWIFT'
import LocalAuthentication
import Foundation
​
let context = LAContext()
var error: NSError?
​
if !context.canEvaluatePolicy(.deviceOwnerAuthenticationWithBiometrics, error: &error) {
  fputs("Touch ID 不可用，请检查系统设置。\n", stderr)
  exit(2)
}
​
let sem = DispatchSemaphore(value: 0)
var authOK = false
​
context.evaluatePolicy(
  .deviceOwnerAuthenticationWithBiometrics,
  localizedReason: "使用指纹验证后登录远程主机"
) { success, _ in
  authOK = success
  sem.signal()
}
​
_ = sem.wait(timeout: .now() + 120)
exit(authOK ? 0 : 1)
SWIFT
EOF
​
chmod +x ~/.local/bin/ssh-touchid-gate

7. 在 ~/.zshrc 配置 tsh 命令

将下面内容追加到 ~/.zshrc（如果已有旧的 alias tsh='ssh tsh'，请先删除或 unalias）：

# SSH quick login with Touch ID
unalias tsh 2>/dev/null
tsh() {
  /Users/wuqiyue/.local/bin/ssh-touchid-gate || {
    echo "指纹验证失败，已取消登录"
    return 1
  }
  ssh tsh "$@"
}

加载配置：

source ~/.zshrc

8. 验证

1. 免密验证：

ssh -o BatchMode=yes root@tsh 'echo ok'

1. 指纹流程验证：

tsh

预期行为：

• 会弹出 Touch ID 验证框。

• 指纹通过后进入远端 shell。

• 取消/失败时提示"指纹验证失败，已取消登录"。

9. 常见问题

9.1 Permission denied (publickey...)

• 检查远端是否已写入 ~/.ssh/authorized_keys。

• 重新执行：

ssh-copy-id root@tsh

9.2 Could not resolve hostname tsh

• 这是本地 SSH 别名未配置或未加载：

ssh -G tsh | head
source ~/.zshrc

9.3 Touch ID 不弹窗

• 检查 macOS 的 Touch ID 是否可用。

• 直接运行脚本看报错：

~/.local/bin/ssh-touchid-gate

9.4 代理不可用导致安装依赖失败

• 先验证代理端口通不通：

nc -z -w 3 x.x.x.x 7890

• 再检查当前 shell 是否设置代理环境变量（如需要）：

env | grep -i proxy

---

完成后，你日常只需要执行：

tsh