254 lines
5.4 KiB
Markdown
254 lines
5.4 KiB
Markdown
# SSH 密钥管理
|
||
|
||
完整的 SSH 密钥创建、部署和配置流程，支持跨设备使用。
|
||
|
||
## 命令
|
||
|
||
### `/gitea-setup-ssh`
|
||
创建 SSH 密钥对，部署公钥到 Gitea 服务器，配置本地 SSH 客户端。
|
||
|
||
## 功能概述
|
||
|
||
1. **生成 SSH 密钥对** (RSA 4096 位)
|
||
2. **部署公钥到 Gitea 服务器** (通过 API)
|
||
3. **配置本地 SSH 客户端**
|
||
4. **验证 SSH 连接**
|
||
|
||
## 详细流程
|
||
|
||
### 1. 生成 SSH 密钥对
|
||
|
||
```bash
|
||
ssh-keygen -t rsa -b 4096 -f ~/.ssh/gitea_server_key -N ""
|
||
```
|
||
|
||
**生成的密钥文件：**
|
||
- 私钥：`~/.ssh/gitea_server_key`
|
||
- 公钥：`~/.ssh/gitea_server_key.pub`
|
||
|
||
### 2. 部署公钥到 Gitea
|
||
|
||
通过 Gitea API 将公钥添加到用户账户：
|
||
|
||
```bash
|
||
curl -s -X POST -H "Authorization: token $GITEA_TOKEN" \
|
||
-H "Content-Type: application/json" \
|
||
-d "{\"title\":\"server-key\",\"key\":\"$(cat ~/.ssh/gitea_server_key.pub)\"}" \
|
||
"$GITEA_URL/api/v1/user/keys"
|
||
```
|
||
|
||
### 3. 配置本地 SSH 客户端
|
||
|
||
在 `~/.ssh/config` 中添加配置：
|
||
|
||
```bash
|
||
cat >> ~/.ssh/config << 'EOF'
|
||
|
||
Host git.refining.app
|
||
HostName git.refining.app
|
||
User git
|
||
IdentityFile ~/.ssh/gitea_server_key
|
||
IdentitiesOnly yes
|
||
EOF
|
||
```
|
||
|
||
### 4. 添加服务器主机密钥
|
||
|
||
```bash
|
||
ssh-keyscan git.refining.app >> ~/.ssh/known_hosts
|
||
```
|
||
|
||
### 5. 验证连接
|
||
|
||
```bash
|
||
ssh -T git@git.refining.app
|
||
```
|
||
|
||
成功输出：
|
||
```
|
||
Hi there, username! You've successfully authenticated with the key named server-key...
|
||
```
|
||
|
||
## 跨设备使用
|
||
|
||
### 复制密钥到新设备
|
||
|
||
1. **复制私钥文件**到新设备的 `~/.ssh/` 目录
|
||
```bash
|
||
# 在源设备上查看私钥内容
|
||
cat ~/.ssh/gitea_server_key
|
||
|
||
# 在新设备上创建文件
|
||
echo "-----BEGIN OPENSSH PRIVATE KEY-----" > ~/.ssh/gitea_server_key
|
||
echo "MIIEog..." >> ~/.ssh/gitea_server_key
|
||
echo "...cQ=" >> ~/.ssh/gitea_server_key
|
||
echo "-----END OPENSSH PRIVATE KEY-----" >> ~/.ssh/gitea_server_key
|
||
```
|
||
|
||
2. **设置正确的权限**
|
||
```bash
|
||
chmod 600 ~/.ssh/gitea_server_key
|
||
```
|
||
|
||
3. **配置 SSH 客户端**
|
||
```bash
|
||
# 在新设备上编辑 ~/.ssh/config
|
||
cat >> ~/.ssh/config << 'EOF'
|
||
|
||
Host git.refining.app
|
||
HostName git.refining.app
|
||
User git
|
||
IdentityFile ~/.ssh/gitea_server_key
|
||
IdentitiesOnly yes
|
||
EOF
|
||
```
|
||
|
||
4. **添加服务器主机密钥**
|
||
```bash
|
||
ssh-keyscan git.refining.app >> ~/.ssh/known_hosts
|
||
```
|
||
|
||
5. **测试连接**
|
||
```bash
|
||
ssh -T git@git.refining.app
|
||
```
|
||
|
||
|
||
## 密钥位置说明
|
||
|
||
### 源设备（当前已配置）
|
||
```
|
||
~/.ssh/
|
||
├── gitea_server_key # 私钥 (权限 600)
|
||
├── gitea_server_key.pub # 公钥 (已部署到 Gitea)
|
||
├── config # SSH 配置
|
||
└── known_hosts # 服务器主机密钥
|
||
```
|
||
|
||
### 新设备（需要配置）
|
||
需要从源设备复制：
|
||
1. `gitea_server_key` - **私钥**（核心文件）
|
||
2. `~/.ssh/config` - SSH 配置（相关部分）
|
||
3. `known_hosts` - 服务器主机密钥（可选，会自动获取）
|
||
|
||
## 安全注意事项
|
||
|
||
### ✅ 推荐做法
|
||
1. **私钥权限设置为 600**
|
||
```bash
|
||
chmod 600 ~/.ssh/gitea_server_key
|
||
```
|
||
|
||
2. **不分享私钥**
|
||
- 私钥应保持在个人设备上
|
||
- 仅在有信任关系的设备间复制
|
||
|
||
3. **使用强密码保护**
|
||
- 生成密钥时可添加密码：`ssh-keygen -t rsa -b 4096 -f ~/.ssh/gitea_server_key`
|
||
- 每次使用时需要输入密码
|
||
|
||
### ❌ 禁止行为
|
||
1. 不要将私钥提交到 Git 仓库
|
||
2. 不要通过不安全渠道传输私钥
|
||
3. 不要设置过于宽松的权限（如 644、777）
|
||
|
||
## 故障排除
|
||
|
||
### 1. 权限错误
|
||
```
|
||
Permissions 0644 for '/Users/username/.ssh/gitea_server_key' are too open.
|
||
```
|
||
**解决方案**：
|
||
```bash
|
||
chmod 600 ~/.ssh/gitea_server_key
|
||
```
|
||
|
||
### 2. 主机密钥验证失败
|
||
```
|
||
Host key verification failed.
|
||
```
|
||
**解决方案**：
|
||
```bash
|
||
ssh-keyscan git.refining.app >> ~/.ssh/known_hosts
|
||
```
|
||
|
||
### 3. 认证失败
|
||
```
|
||
git@git.refining.app: Permission denied (publickey).
|
||
```
|
||
**检查步骤**：
|
||
1. 确认私钥文件存在且权限正确
|
||
2. 确认 SSH 配置正确
|
||
3. 确认公钥已添加到 Gitea
|
||
```bash
|
||
curl -s -H "Authorization: token $GITEA_TOKEN" \
|
||
"$GITEA_URL/api/v1/user/keys" | jq -r '.[].title'
|
||
```
|
||
|
||
## Git 使用示例
|
||
|
||
### 克隆仓库
|
||
```bash
|
||
git clone git@git.refining.app:username/repository.git
|
||
```
|
||
|
||
### 更新现有仓库的 remote URL
|
||
```bash
|
||
git remote set-url origin git@git.refining.app:username/repository.git
|
||
```
|
||
|
||
### 查看当前 remote URL
|
||
```bash
|
||
git remote -v
|
||
```
|
||
|
||
|
||
|
||
## 撤销密钥访问
|
||
|
||
如果密钥泄露或设备丢失：
|
||
|
||
1. **登录 Gitea Web 界面**
|
||
2. 进入 **Settings → SSH/GPG Keys**
|
||
3. 找到对应的密钥并删除
|
||
|
||
2. **通过 API 删除**
|
||
```bash
|
||
# 首先获取密钥 ID
|
||
curl -s -H "Authorization: token $GITEA_TOKEN" \
|
||
"$GITEA_URL/api/v1/user/keys" | jq '.[] | select(.title=="server-key").id'
|
||
|
||
# 删除密钥（将 {id} 替换为实际 ID）
|
||
curl -s -X DELETE -H "Authorization: token $GITEA_TOKEN" \
|
||
"$GITEA_URL/api/v1/user/keys/{id}"
|
||
```
|
||
|
||
3. **在受影响的设备上删除私钥**
|
||
```bash
|
||
rm ~/.ssh/gitea_server_key
|
||
rm ~/.ssh/gitea_server_key.pub
|
||
```
|
||
|
||
## 相关命令
|
||
|
||
### 查看 Gitea 上的所有 SSH 密钥
|
||
```bash
|
||
curl -s -H "Authorization: token $GITEA_TOKEN" \
|
||
"$GITEA_URL/api/v1/user/keys" | jq -r '.[] | "\(.id): \(.title) (\(.fingerprint))"'
|
||
```
|
||
|
||
### 测试 SSH 连接（详细模式）
|
||
```bash
|
||
ssh -T -v git@git.refining.app
|
||
```
|
||
|
||
### 检查 SSH 配置语法
|
||
```bash
|
||
ssh -G git.refining.app
|
||
```
|
||
|
||
---
|
||
|
||
*文档版本：1.1*
|
||
*最后更新：2026-01-28*
|
||
*集成到 Gitea Skill v1.2* |