opencode/skill/git/ssh-keychain.md

name, description

name	description
ssh-keychain	SSH key management with macOS Keychain for password-protected keys

SSH 密钥与 macOS Keychain 管理

处理带密码的 SSH 密钥，配置自动解锁避免重复输入密码。

问题场景

生成带密码的 SSH 密钥后，每次使用都需要输入密码：

git pull
# Enter passphrase for /Users/xxx/.ssh/id_xxx:

解决方案

1. 生成带密码的 SSH 密钥

# 生成密钥（推荐使用 ed25519）
ssh-keygen -t ed25519 -f ~/.ssh/id_custom -N "your-passphrase"

# 或使用随机密码
PASSPHRASE=$(openssl rand -base64 32)
ssh-keygen -t ed25519 -f ~/.ssh/id_custom -N "$PASSPHRASE"

2. 配置 SSH 使用 Keychain（关键步骤）

编辑 ~/.ssh/config：

Host gitea.example.com
    HostName gitea.example.com
    User git
    IdentityFile ~/.ssh/id_custom
    IdentitiesOnly yes
    AddKeysToAgent yes
    UseKeychain yes

重要配置项：

• AddKeysToAgent yes - 自动添加到 ssh-agent
• UseKeychain yes - 使用 macOS Keychain 存储密码
• 不要使用 IdentityAgent none（会禁用 Keychain）

3. 添加密钥到 ssh-agent 并保存到 Keychain

# 方法 1：使用 --apple-use-keychain (macOS 12+)
ssh-add --apple-use-keychain ~/.ssh/id_custom

# 方法 2：使用 -K 选项 (macOS 11 及更早)
ssh-add -K ~/.ssh/id_custom

输入密码后，系统会保存到 Keychain，以后自动解锁。

4. 验证配置

# 检查已加载的密钥
ssh-add -l

# 测试 SSH 连接
ssh -T git@gitea.example.com

如果显示 Hi there, xxx! You've successfully authenticated 且没有提示输入密码，则配置成功。

完整工作流程示例

场景：配置 Gitea SSH 访问

# 1. 生成带密码的密钥
PASSPHRASE="bkt/52MFsLVSRSHvIXv2WTCKEUaPhD0btDghUY6RnQI="
ssh-keygen -t ed25519 -f ~/.ssh/id_gitea_new -N "$PASSPHRASE"

# 2. 配置 SSH
# 编辑 ~/.ssh/config，添加：
cat >> ~/.ssh/config << 'EOF'
Host gitea.refining.dev
    HostName gitea.refining.dev
    User git
    IdentityFile ~/.ssh/id_gitea_new
    IdentitiesOnly yes
    AddKeysToAgent yes
    UseKeychain yes
EOF

# 3. 添加到 Keychain
ssh-add --apple-use-keychain ~/.ssh/id_gitea_new
# 输入密码: bkt/52MFsLVSRSHvIXv2WTCKEUaPhD0btDghUY6RnQI=

# 4. 验证
ssh -T git@gitea.refining.dev

# 5. 后续使用 git 无需输入密码
git pull
git push

常见错误与解决

错误 1：仍然提示输入密码

原因： ~/.ssh/config 中配置了 IdentityAgent none

解决： 移除 IdentityAgent none，添加 UseKeychain yes

# ❌ 错误配置
Host gitea.example.com
    IdentityFile ~/.ssh/id_custom
    IdentityAgent none  # 这会禁用 Keychain

# ✅ 正确配置
Host gitea.example.com
    IdentityFile ~/.ssh/id_custom
    AddKeysToAgent yes
    UseKeychain yes

错误 2：1Password SSH agent 冲突

如果系统使用 1Password 的 SSH agent（IdentityAgent "~/Library/Group Containers/.../agent.sock"）：

Host *
    IdentityAgent "~/Library/Group Containers/2BUA8C4S2C.com.1password/t/agent.sock"

Host gitea.example.com
    HostName gitea.example.com
    User git
    IdentityFile ~/.ssh/id_custom
    IdentitiesOnly yes
    AddKeysToAgent yes
    UseKeychain yes
    # 不使用 1Password agent，直接使用系统 Keychain

错误 3：ssh-add 命令不存在

某些 macOS 版本可能不支持 --apple-use-keychain：

# 创建或编辑 ~/.ssh/config，添加全局配置
Host *
    UseKeychain yes
    AddKeysToAgent yes

# 然后直接使用
ssh-add ~/.ssh/id_custom

密钥管理最佳实践

文件保存位置

将密钥备份到安全位置（如 iCloud）：

# 复制到 iCloud Key 文件夹
KEY_FOLDER="$HOME/Library/Mobile Documents/com~apple~CloudDocs/key"
cp ~/.ssh/id_custom "$KEY_FOLDER/id_custom_$(date +%Y%m%d)"
cp ~/.ssh/id_custom.pub "$KEY_FOLDER/id_custom_$(date +%Y%m%d).pub"

# 创建密码说明文件
cat > "$KEY_FOLDER/id_custom_$(date +%Y%m%d)_info.txt" << EOF
SSH Key: id_custom
Generated: $(date)
Passphrase: $PASSPHRASE
Host: gitea.example.com
EOF

定期检查

# 列出所有已加载的密钥
ssh-add -l

# 检查 SSH 配置
ssh -G gitea.example.com

# 测试连接
ssh -vT git@gitea.example.com

安全建议

1. 始终使用带密码的密钥 - 防止私钥泄露后被直接使用
2. 不要将私钥提交到 Git - 添加到 .gitignore
3. 定期轮换密钥 - 建议每 6-12 个月
4. 为不同服务使用不同密钥 - 隔离风险

快速参考

命令	用途
ssh-add --apple-use-keychain ~/.ssh/id_custom	添加密钥到 Keychain
ssh-add -l	列出已加载的密钥
ssh-add -D	删除所有已加载的密钥
ssh -T git@host	测试 SSH 连接
ssh -G host	查看 SSH 配置