opencode/skill/gitea/ssh-key-management.md

SSH 密钥管理

完整的 SSH 密钥创建、部署和配置流程，支持跨设备使用。

命令

/gitea-setup-ssh

创建 SSH 密钥对，部署公钥到 Gitea 服务器，配置本地 SSH 客户端。

功能概述

1. 生成 SSH 密钥对 (RSA 4096 位)
2. 部署公钥到 Gitea 服务器 (通过 API)
3. 配置本地 SSH 客户端
4. 验证 SSH 连接

详细流程

1. 生成 SSH 密钥对

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 将公钥添加到用户账户：

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 中添加配置：

cat >> ~/.ssh/config << 'EOF'

Host git.refining.app
    HostName git.refining.app
    User git
    IdentityFile ~/.ssh/gitea_server_key
    IdentitiesOnly yes
EOF

4. 添加服务器主机密钥

ssh-keyscan git.refining.app >> ~/.ssh/known_hosts

5. 验证连接

ssh -T git@git.refining.app

成功输出：

Hi there, username! You've successfully authenticated with the key named server-key...

跨设备使用

复制密钥到新设备

1. 复制私钥文件到新设备的 ~/.ssh/ 目录

   # 在源设备上查看私钥内容
   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. 设置正确的权限

   chmod 600 ~/.ssh/gitea_server_key
   

3. 配置 SSH 客户端

   # 在新设备上编辑 ~/.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. 添加服务器主机密钥

   ssh-keyscan git.refining.app >> ~/.ssh/known_hosts
   

5. 测试连接

   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

   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.

解决方案：

chmod 600 ~/.ssh/gitea_server_key

2. 主机密钥验证失败

Host key verification failed.

解决方案：

ssh-keyscan git.refining.app >> ~/.ssh/known_hosts

3. 认证失败

git@git.refining.app: Permission denied (publickey).

检查步骤：

1. 确认私钥文件存在且权限正确
2. 确认 SSH 配置正确
3. 确认公钥已添加到 Gitea

   curl -s -H "Authorization: token $GITEA_TOKEN" \
     "$GITEA_URL/api/v1/user/keys" | jq -r '.[].title'
   

Git 使用示例

克隆仓库

git clone git@git.refining.app:username/repository.git

更新现有仓库的 remote URL

git remote set-url origin git@git.refining.app:username/repository.git

查看当前 remote URL

git remote -v

撤销密钥访问

如果密钥泄露或设备丢失：

1. 登录 Gitea Web 界面

2. 进入 Settings → SSH/GPG Keys

3. 找到对应的密钥并删除

4. 通过 API 删除

# 首先获取密钥 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. 在受影响的设备上删除私钥

rm ~/.ssh/gitea_server_key
rm ~/.ssh/gitea_server_key.pub

相关命令

查看 Gitea 上的所有 SSH 密钥

curl -s -H "Authorization: token $GITEA_TOKEN" \
  "$GITEA_URL/api/v1/user/keys" | jq -r '.[] | "\(.id): \(.title) (\(.fingerprint))"'

测试 SSH 连接（详细模式）

ssh -T -v git@git.refining.app

检查 SSH 配置语法

ssh -G git.refining.app

---

文档版本：1.1 最后更新：2026-01-28 集成到 Gitea Skill v1.2