feat(gitea): 添加 SSH 密钥管理功能
This commit is contained in:
voson
254
skill/gitea/ssh-key-management.md
Normal file
254
skill/gitea/ssh-key-management.md
Normal file
@@ -0,0 +1,254 @@
|
||||
# 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*
|
||||
Reference in New Issue
Block a user