135ea99deb
- Add comprehensive SSH key management with macOS Keychain - Include troubleshooting for password prompt issues - Document 1Password agent conflicts and solutions
210 lines
4.8 KiB
Markdown
210 lines
4.8 KiB
Markdown
---
|
||
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 配置 |
|