feat(git): add SSH keychain configuration guide
- Add comprehensive SSH key management with macOS Keychain - Include troubleshooting for password prompt issues - Document 1Password agent conflicts and solutions
This commit is contained in:
voson
209
skill/git/ssh-keychain.md
Normal file
209
skill/git/ssh-keychain.md
Normal file
@@ -0,0 +1,209 @@
|
||||
---
|
||||
name: ssh-keychain
|
||||
description: SSH key management with macOS Keychain for password-protected keys
|
||||
---
|
||||
|
||||
# SSH 密钥与 macOS Keychain 管理
|
||||
|
||||
处理带密码的 SSH 密钥，配置自动解锁避免重复输入密码。
|
||||
|
||||
## 问题场景
|
||||
|
||||
生成带密码的 SSH 密钥后，每次使用都需要输入密码：
|
||||
```bash
|
||||
git pull
|
||||
# Enter passphrase for /Users/xxx/.ssh/id_xxx:
|
||||
```
|
||||
|
||||
## 解决方案
|
||||
|
||||
### 1. 生成带密码的 SSH 密钥
|
||||
|
||||
```bash
|
||||
# 生成密钥（推荐使用 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`：
|
||||
|
||||
```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
|
||||
|
||||
```bash
|
||||
# 方法 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. 验证配置
|
||||
|
||||
```bash
|
||||
# 检查已加载的密钥
|
||||
ssh-add -l
|
||||
|
||||
# 测试 SSH 连接
|
||||
ssh -T git@gitea.example.com
|
||||
```
|
||||
|
||||
如果显示 `Hi there, xxx! You've successfully authenticated` 且**没有提示输入密码**，则配置成功。
|
||||
|
||||
## 完整工作流程示例
|
||||
|
||||
### 场景：配置 Gitea SSH 访问
|
||||
|
||||
```bash
|
||||
# 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`
|
||||
|
||||
```ssh-config
|
||||
# ❌ 错误配置
|
||||
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"`）：
|
||||
|
||||
```ssh-config
|
||||
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`：
|
||||
|
||||
```bash
|
||||
# 创建或编辑 ~/.ssh/config，添加全局配置
|
||||
Host *
|
||||
UseKeychain yes
|
||||
AddKeysToAgent yes
|
||||
|
||||
# 然后直接使用
|
||||
ssh-add ~/.ssh/id_custom
|
||||
```
|
||||
|
||||
## 密钥管理最佳实践
|
||||
|
||||
### 文件保存位置
|
||||
|
||||
将密钥备份到安全位置（如 iCloud）：
|
||||
|
||||
```bash
|
||||
# 复制到 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
|
||||
```
|
||||
|
||||
### 定期检查
|
||||
|
||||
```bash
|
||||
# 列出所有已加载的密钥
|
||||
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 配置 |
|
||||
Reference in New Issue
Block a user