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

title, source, author, published, created, description, tags

title	source	author	published	created	description	tags
Gitea + SSH 完整配置指南（含排错）		shenwei				git gitea obsidian ssh

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

#git #gitea #ssh #obsidian

一、整体目标

实现：

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

---

二、Gitea 部署与 SSH 配置

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

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 服务

进入容器：

docker exec -it gitea /bin/sh

检查配置：

cat /data/gitea/conf/app.ini

确保：

[server]
START_SSH_SERVER = true
SSH_PORT = 22

---

4. 重启服务

docker compose down
docker compose up -d

---

三、客户端 SSH Key 配置

1. 生成 SSH Key

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

默认路径：

~/.ssh/id_ed25519
~/.ssh/id_ed25519.pub

---

2. 启动 SSH Agent

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

---

3. 添加公钥到 Gitea

cat ~/.ssh/id_ed25519.pub

复制内容 → 登录 Gitea：

• Settings
• SSH Keys
• Add Key

---

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

正确命令

ssh -T git@192.168.3.17 -p 2222

ssh -T git@gitea.ishenwei.online -p 12222

---

返回结果解析

✅ 成功

Hi username! You've successfully authenticated...

👉 可以开始使用 Git

---

❌ Connection refused

connect to host ... port 2222: Connection refused

👉 原因：

• Docker 没映射端口

✔ 修复：

- "2222:22"

---

❌ Connection closed

Connection closed by ... port 2222

👉 原因：

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

---

❌ Permission denied (publickey)

Permission denied (publickey)

👉 原因：

• SSH key 未加载或未添加

✔ 修复：

ssh-add ~/.ssh/id_ed25519

---

❌ 错误写法（常见坑）

ssh -T git@192.168.3.189:3000   ❌

👉 错误原因：

• SSH 不支持 IP:PORT 写法

---

五、Git 仓库改为 SSH

1. 查看当前 remote

git remote -v

你当前是：

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

2. 修改为 SSH

git remote set-url origin ssh://git@192.168.3.17:2222/ishenwei/nexus.git

3. 验证

git pull

4. 查看配置

git config --list

---

六、VS Code 使用说明

在 Visual Studio Code 中：

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

👉 优势：

• 不再输入密码
• 不受 proxy 影响
• clone / pull 不会卡住

---

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

1. SSH Host 别名

编辑：

~/.ssh/config

Host macmini
  HostName 192.168.3.189
  Port 2222
  User git
  IdentityFile ~/.ssh/id_ed25519

2. 使用简化地址

git clone ssh://git@192.168.3.45:2222/admin/nexus.git

---

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

实际问题链路

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

---

正确架构

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 = 无痛开发环境

这是一个关于从 Windows 客户端通过 SSH 连接 Mac mini 上 Gitea 仓库的排错笔记。你可以将其保存为 Markdown 文件（如 Gitea_SSH_Troubleshooting.md）以便日后查阅。

---

📝 Git 排错笔记：解决 Gitea SSH 连接断开与权限问题

1. 问题现象

在 Windows 终端执行 git clone 或 git pull 时，出现以下错误：

• 现象 A: Connection closed by 192.168.3.189 port 22 或 fatal: Could not read from remote repository.

• 现象 B: ishen@192.168.3.189: Permission denied (publickey).

---

2. 核心原因分析

经过排查，导致问题的根源有三点：

1. 端口冲突：默认 SSH 使用 22 端口（指向 macOS 系统 SSH），而 Gitea 运行在 2222 端口。

2. 用户混淆：Git 默认尝试使用 Windows 当前用户名（ishen），但 Gitea 的 SSH 验证强制要求使用 git 用户。

3. 协议格式：在非标准端口（非 22）下，必须使用特定的 ssh:// 前缀格式。

---

3. 修复步骤

第一步：验证 SSH 连通性

首先确认公钥是否已在 Gitea 中生效，并指定正确端口：

Bash

ssh -vT git@192.168.3.189 -p 2222

• 预期输出：Hi there, admin! You've successfully authenticated... but Gitea does not provide shell access.

• 结论：只要看到这段话，说明密钥（Key）和端口（Port）是通的。

第二步：修正远程仓库地址 (Remote URL)

如果已经克隆了仓库但无法 Pull/Push，需要更新 origin 的地址：

Bash

# 切换到项目目录
cd D:\Workspace\nexus

# 重新设置远程地址，强制指定 git 用户和 2222 端口
git remote set-url origin ssh://git@192.168.3.17:2222/ishenwei/nexus.git

第三步：验证修改

查看当前的远程配置是否正确：

Bash

git remote -v

• 正确结果应包含：ssh://git@192.168.3.189:2222/...

---

4. 终极解决方案：配置 SSH Config (推荐)

为了避免每次都要手动输入端口和用户，在 Windows 本地创建或修改 C:\Users\ishen\.ssh\config 文件：

Plaintext

# Mac mini Gitea 配置
Host 192.168.3.189
    HostName 192.168.3.189
    User git
    Port 2222
    IdentityFile ~/.ssh/id_rsa

配置后的效果：

以后只需执行简单的命令，Git 会自动映射 git 用户和 2222 端口：

• git clone ssh://git@192.168.3.45:2222/admin/nexus.git

• git pull

---

5. 总结备忘

• 不要使用系统用户名：无论你的 Gitea 账户叫什么，SSH 连接用户名统一用 git。

• 非标端口必须加协议：如果端口不是 22，地址必须写成 ssh://git@host:port/repo.git。

• 优先检查端口：Mac 系统的 SSH (22) 和 Gitea 的 SSH (通常是 2222 或 10022) 是两码事。

---

记录时间：2026-03-25

设备环境：Windows ThinkBook -> Mac mini (192.168.3.189)