437 lines
7.0 KiB
Markdown
437 lines
7.0 KiB
Markdown
---
|
||
title: Gitea + SSH 完整配置指南（含排错）
|
||
source:
|
||
author: shenwei
|
||
published:
|
||
created:
|
||
description:
|
||
tags: [git, gitea, obsidian, ssh]
|
||
---
|
||
|
||
# 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.17 -p 2222
|
||
```
|
||
|
||
```
|
||
ssh -T git@gitea.ishenwei.online -p 12222
|
||
```
|
||
---
|
||
## 返回结果解析
|
||
|
||
### ✅ 成功
|
||
|
||
```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.17:2222/ishenwei/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 ssh://git@192.168.3.45:2222/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 = 无痛开发环境
|
||
|
||
|
||
|
||
这是一个关于从 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) |