# Gitea + SSH 完整配置指南（含排错）

#git #gitea #ssh #obsidian 

```table-of-contents
```
## 一、整体目标

实现：
- 使用 Gitea 作为 Git 服务器
- 使用 SSH Key 替代 username/password
- 在 Visual Studio Code 中无感使用 Git
- 避免 HTTP + Proxy 带来的问题

---

# 二、Gitea 部署与 SSH 配置

## 1. Docker 部署（推荐标准配置）

```yaml
version: "3"

services:
  gitea:
    image: gitea/gitea:latest
    container_name: gitea
    restart: always
    ports:
      - "3000:3000"   # Web UI
      - "2222:22"     # SSH（关键）
    volumes:
      - ./gitea:/data
```

---

## 2. 为什么要用 2222

- 宿主机 22 端口通常已被系统 SSH 占用
- 使用 `2222 → 22` 映射避免冲突

---
## 3. 启用 Gitea SSH 服务

进入容器：

```bash
docker exec -it gitea /bin/sh
```

检查配置：

```bash
cat /data/gitea/conf/app.ini
```

确保：

```ini
[server]
START_SSH_SERVER = true
SSH_PORT = 22
```

---
## 4. 重启服务

```bash
docker compose down
docker compose up -d
```

---

# 三、客户端 SSH Key 配置

## 1. 生成 SSH Key

```bash
ssh-keygen -t ed25519 -C "ishenwei@gmail.com"
```

默认路径：

```bash
~/.ssh/id_ed25519
~/.ssh/id_ed25519.pub
```

---
## 2. 启动 SSH Agent

```bash
eval "$(ssh-agent -s)"
ssh-add ~/.ssh/id_ed25519
```

---

## 3. 添加公钥到 Gitea

```bash
cat ~/.ssh/id_ed25519.pub
```

复制内容 → 登录 Gitea：

- Settings
- SSH Keys
- Add Key

---

# 四、SSH 连接测试（关键步骤）

## 正确命令

```bash
ssh -T git@192.168.3.189 -p 2222
```

---
## 返回结果解析

### ✅ 成功

```bash
Hi username! You've successfully authenticated...
```

👉 可以开始使用 Git

---

### ❌ Connection refused

```bash
connect to host ... port 2222: Connection refused
```

👉 原因：

- Docker 没映射端口

✔ 修复：

```yaml
- "2222:22"
```
---

### ❌ Connection closed

```bash
Connection closed by ... port 2222
```
👉 原因：

- SSH 服务存在，但不是 Gitea 在处理
- 或 Gitea SSH 未启用

---

### ❌ Permission denied (publickey)

```bash
Permission denied (publickey)
```

👉 原因：

- SSH key 未加载或未添加

✔ 修复：

```bash
ssh-add ~/.ssh/id_ed25519
```

---

### ❌ 错误写法（常见坑）

```bash
ssh -T git@192.168.3.189:3000   ❌
```

👉 错误原因：

- SSH 不支持 `IP:PORT` 写法
---
# 五、Git 仓库改为 SSH

## 1. 查看当前 remote

```bash
git remote -v
```

你当前是：

```bash
http://192.168.3.189:3000/admin/nexus.git   ❌
```

## 2. 修改为 SSH

```bash
git remote set-url origin ssh://git@192.168.3.189:2222/admin/nexus.git
```
## 3. 验证

```bash
git pull
```
## 4. 查看配置

```bash
git config --list
```

---
# 六、VS Code 使用说明

在 Visual Studio Code 中：

- 无需额外配置
- 只要 Git + SSH 正常即可

👉 优势：
- 不再输入密码
- 不受 proxy 影响
- clone / pull 不会卡住

---
# 七、进阶优化（强烈推荐）

## 1. SSH Host 别名

编辑：

```bash
~/.ssh/config
```

```bash
Host macmini
  HostName 192.168.3.189
  Port 2222
  User git
  IdentityFile ~/.ssh/id_ed25519
```
## 2. 使用简化地址

```bash
git clone git@macmini:admin/nexus.git
```

---
# 八、你这次问题的根因总结

## 实际问题链路

```text
HTTP Git + Proxy → 卡住
        ↓
尝试 SSH（但用错端口）
        ↓
未映射 Docker SSH 端口
        ↓
连接到了错误的 SSH 服务
```

---
## 正确架构

```text
VS Code
   ↓
Git (SSH)
   ↓
Gitea (Docker)
   ↓
SSH Port 2222 → Container 22
```

---
# 九、最佳实践总结

- 使用 SSH 替代 HTTP + Password
- Docker 映射 SSH 端口（2222）
- 使用 ed25519 key
- 使用 SSH config 做多环境管理
- 避免代理干扰 Git
---

# 十、一句话结论

👉 **Git 的本质是：**
- user.name / email → 标识身份
- SSH Key → 认证身份

👉 **最稳定方案：**
> Gitea + SSH（2222）+ VS Code = 无痛开发环境