# 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*