Gitea+SSH 完整配置指南

openclaw/knowledgebase/Gitea + SSH 完整配置指南（含排错）.md

@@ -0,0 +1,306 @@
+# 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 = 无痛开发环境
+