合并文档并更新

knowledgebase/Gitea 完整配置指南（SSH + frp + Caddy）.md

@@ -0,0 +1,745 @@
+---
+title: Gitea 完整配置指南（SSH + frp + Caddy）
+author: shenwei
+created: 2026-06-04
+description: 涵盖 Gitea SSH 配置、frp 转发、Caddy 反代、以及客户端配置的完整指南
+tags: [git, gitea, ssh, frp, caddy, docker]
+---
+
+# Gitea 完整配置指南（SSH + frp + Caddy）
+
+这是一份综合指南，涵盖 Gitea 的完整配置，包括 SSH 设置、通过 frp 和 Caddy 进行远程访问、以及 Git 客户端配置。
+
+## 目录
+
+1. [第一部分：Gitea 部署与基础 SSH 配置](#第一部分gitea-部署与基础-ssh-配置)
+2. [第二部分：远程访问架构（frp + Caddy）](#第二部分远程访问架构frp--caddy)
+3. [第三部分：客户端配置](#第三部分客户端配置)
+4. [第四部分：故障排除](#第四部分故障排除)
+5. [第五部分：最佳实践](#第五部分最佳实践)
+
+---
+
+# 第一部分：Gitea 部署与基础 SSH 配置
+
+## 1. Docker 部署（推荐标准配置）
+
+### 基础 Docker Compose 配置
+
+```yaml
+version: "3"
+
+services:
+  gitea:
+    image: gitea/gitea:latest
+    container_name: gitea
+    restart: always
+    ports:
+      - "3000:3000"   # Web UI HTTP
+      - "2222:22"     # SSH（宿主机 2222 -> 容器内 22）
+    volumes:
+      - ./gitea:/data
+    environment:
+      - ROOT_URL=http://localhost:3000
+```
+
+**为什么用 2222？**
+- 宿主机的 22 端口通常已被系统 SSH 占用
+- 使用 `2222 → 22` 映射避免冲突
+- 容器内 Gitea SSH 服务依然运行在 22，外部通过 2222 访问
+
+---
+
+## 2. Gitea SSH 服务启用
+
+### 检查配置
+
+进入容器检查配置：
+
+```bash
+docker exec -it gitea /bin/sh
+cat /data/gitea/conf/app.ini
+```
+
+确保 `[server]` 部分包含：
+
+```ini
+[server]
+START_SSH_SERVER = true
+SSH_PORT = 22
+```
+
+- `START_SSH_SERVER = true`：启用 SSH 服务
+- `SSH_PORT = 22`：容器内监听 22 端口（通过 Docker 映射到外部端口）
+
+### 重启服务
+
+```bash
+docker compose down
+docker compose up -d
+```
+
+---
+
+## 3. 基础 SSH 连接测试
+
+### 测试 SSH 连通性（本地网络）
+
+```bash
+# 使用指定端口连接
+ssh -T git@192.168.3.17 -p 2222
+```
+
+**预期输出（成功）：**
+```
+Hi username! You've successfully authenticated with the key named ...
+Gitea does not provide shell access.
+```
+
+### 常见错误与修复
+
+#### ❌ Connection refused
+```
+ssh: connect to host ... port 2222: Connection refused
+```
+**原因：** Docker 未正确映射端口
+
+**修复：** 检查 docker-compose.yml 中是否有 `- "2222:22"`
+
+#### ❌ Connection closed
+```
+Connection closed by 192.168.3.17 port 2222
+```
+**原因：** SSH 服务存在但不是 Gitea 在处理，或 Gitea SSH 未启用
+
+**修复：**
+1. 检查 `app.ini` 中 `START_SSH_SERVER = true`
+2. 重启 Docker 容器
+
+#### ❌ Permission denied (publickey)
+```
+Permission denied (publickey)
+```
+**原因：** SSH key 未在 Gitea 中添加或未加载
+
+**修复：**
+```bash
+# 确保公钥已添加到 Gitea
+# 在 Gitea Web UI → Settings → SSH Keys 中验证
+# 或重新加载 SSH Agent
+ssh-add ~/.ssh/id_ed25519
+```
+
+---
+
+# 第二部分：远程访问架构（frp + Caddy）
+
+## 1. 整体架构
+
+### 正确的访问方式
+
+```
+┌─────────────────────────────────────────────────────────┐
+│                     远程访问架构                          │
+├─────────────────────────────────────────────────────────┤
+│                                                         │
+│  HTTP 访问（通过 Caddy 反代）                          │
+│  浏览器 → Caddy :443 → frps :13000 → Gitea :3000      │
+│                                                         │
+│  SSH 访问（直接转发，绕过 Caddy）                      │
+│  Git Client → frps :12222 → Gitea :2222               │
+│                                                         │
+└─────────────────────────────────────────────────────────┘
+```
+
+### 核心原则
+
+1. **HTTP 走 Caddy**：Web 浏览器通过 Caddy 反代访问 Gitea Web UI
+2. **SSH 直接转发**：SSH 流量不经过 Caddy（Caddy 是 HTTP 代理，无法处理 SSH TCP 流量）
+3. **防火墙放行**：frps 服务器必须在防火墙中放行相应端口
+
+---
+
+## 2. frpc 配置（本地端，如 NAS）
+
+### frpc.toml 配置文件
+
+```toml
+serverAddr = "your-vps.com"
+serverPort = 7000
+auth.method = "token"
+auth.token = "your-token"
+
+# HTTP 转发 - 给 Caddy 用
+[[proxies]]
+name = "gitea-http"
+type = "tcp"
+localIP = "127.0.0.1"
+localPort = 3000
+remotePort = 13001
+
+# SSH 转发 - 直接暴露
+[[proxies]]
+name = "gitea-ssh"
+type = "tcp"
+localIP = "127.0.0.1"
+localPort = 2222
+remotePort = 12222
+```
+
+**配置说明：**
+- `remotePort = 13001`：Caddy 通过此端口访问 Gitea Web UI
+- `remotePort = 12222`：Git 客户端通过此端口连接 SSH
+
+---
+
+## 3. frps 配置（服务器端，如 VPS）
+
+### frps.toml 配置文件
+
+```toml
+bindAddr = "0.0.0.0"
+bindPort = 7000
+auth.method = "token"
+auth.token = "your-token"
+```
+
+### 防火墙配置
+
+**在 VPS 上放行端口：**
+
+```bash
+# UFW（Ubuntu/Debian）
+ufw allow 7000/tcp   # frp 通信
+ufw allow 13001/tcp  # Gitea Web（给 Caddy）
+ufw allow 12222/tcp  # Gitea SSH
+
+# iptables
+iptables -A INPUT -p tcp --dport 7000 -j ACCEPT
+iptables -A INPUT -p tcp --dport 13001 -j ACCEPT
+iptables -A INPUT -p tcp --dport 12222 -j ACCEPT
+```
+
+**AWS/阿里云/腾讯云等云服务：**
+- 需要同时配置安全组（云控制台）和系统防火墙
+- 缺一不可
+
+---
+
+## 4. Caddy 反代配置
+
+### Caddyfile 配置
+
+```caddy
+gitea.yourdomain.com {
+    reverse_proxy 127.0.0.1:13001
+}
+```
+
+**关键点：**
+- 反代目标是 `127.0.0.1:13001`（frps 转发来的 HTTP 流量）
+- **不要将 SSH 端口（12222）配进 Caddy**
+- Caddy 只负责 HTTP/HTTPS，不处理 SSH
+
+---
+
+## 5. Gitea app.ini 配置
+
+### SSH 相关配置
+
+编辑 `/data/gitea/conf/app.ini`：
+
+```ini
+[server]
+ROOT_URL = https://gitea.ishenwei.online/
+SSH_DOMAIN = gitea.ishenwei.online
+SSH_PORT = 12222
+START_SSH_SERVER = true
+```
+
+**配置说明：**
+- `SSH_DOMAIN = gitea.ishenwei.online`：Web 界面显示的 SSH 地址
+- `SSH_PORT = 12222`：对外暴露的 SSH 端口（影响 Web 上显示的 Clone 地址）
+- `ROOT_URL`：Web UI 根路径，通常指向域名
+
+### 重启应用
+
+```bash
+docker compose down
+docker compose up -d
+```
+
+---
+
+# 第三部分：客户端配置
+
+## 1. SSH Key 生成
+
+### 生成密钥对
+
+```bash
+ssh-keygen -t ed25519 -C "your-email@example.com"
+```
+
+**为什么用 ed25519？**
+- 更安全、密钥更短
+- 现代标准推荐
+
+**默认路径：**
+```
+~/.ssh/id_ed25519      # 私钥
+~/.ssh/id_ed25519.pub  # 公钥
+```
+
+### 启动 SSH Agent
+
+```bash
+# Linux/macOS
+eval "$(ssh-agent -s)"
+ssh-add ~/.ssh/id_ed25519
+
+# Windows (PowerShell)
+# 通常自动运行，无需手动启动
+ssh-add $env:USERPROFILE\.ssh\id_ed25519
+```
+
+---
+
+## 2. 添加公钥到 Gitea
+
+### 在 Gitea Web UI 中添加
+
+1. 登录 Gitea Web UI
+2. 点击右上角头像 → Settings
+3. 选择 SSH Keys
+4. 点击 Add Key
+
+### 复制公钥内容
+
+```bash
+cat ~/.ssh/id_ed25519.pub
+```
+
+将输出内容完整复制到 Gitea，包括前缀 `ssh-ed25519 AAA...`
+
+---
+
+## 3. SSH Config 配置（推荐）
+
+### 简化 SSH 连接
+
+编辑 `~/.ssh/config`：
+
+```bash
+# 本地网络 - Gitea（Docker）
+Host gitea-local
+    HostName 192.168.3.17
+    User git
+    Port 2222
+    IdentityFile ~/.ssh/id_ed25519
+
+# 远程 - Gitea（通过 frp）
+Host gitea.ishenwei.online
+    HostName gitea.ishenwei.online
+    User git
+    Port 12222
+    IdentityFile ~/.ssh/id_ed25519
+```
+
+### 使用简化命令
+
+配置后，可以用更简洁的命令：
+
+```bash
+# 本地网络
+ssh -T gitea-local
+
+# 远程（通过 frp）
+ssh -T gitea.yourdomain.com
+```
+
+---
+
+## 4. Git 仓库配置
+
+### 方式一：Clone 时使用 SSH
+
+```bash
+# 本地
+git clone ssh://git@192.168.3.17:2222/username/repo.git
+
+# 远程（通过 frp）
+git clone ssh://git@gitea.ishenwei.online:12222/username/repo.git
+
+# 使用 SSH Config 别名
+git clone ssh://gitea-local/username/repo.git
+git clone ssh://gitea.ishenwei.online/username/repo.git
+```
+
+### 方式二：修改已有仓库的 Remote URL
+
+```bash
+# 查看当前 remote
+git remote -v
+
+# 修改为 SSH
+git remote set-url origin ssh://git@192.168.3.17:2222/username/repo.git
+
+# 远程版本
+git remote set-url origin ssh://git@gitea.ishenwei.online:12222/username/repo.git
+
+# 验证修改
+git remote -v
+```
+
+### 验证连接
+
+```bash
+git pull
+```
+
+---
+
+## 5. VS Code / IDE 集成
+
+在配置好 SSH 和 Git Remote 后：
+
+- **VS Code**：无需额外配置，自动使用 Git + SSH
+- **JetBrains IDE**：自动识别 SSH Config
+- **其他 IDE**：通常也会自动识别系统 SSH 配置
+
+**优势：**
+- 无需输入密码
+- 不受代理干扰
+- Clone / Pull 不会卡住
+
+---
+
+# 第四部分：故障排除
+
+## 1. SSH 连接测试
+
+### 测试不同场景
+
+```bash
+# 本地网络测试
+ssh -vT git@192.168.3.17 -p 2222
+
+# 远程（通过 frp）测试
+ssh -vT git@gitea.ishenwei.online -p 12222
+
+# 使用 SSH Config 别名测试
+ssh -vT gitea-local
+ssh -vT gitea.ishenwei.online
+```
+
+### 详细调试信息
+
+```bash
+# -v 显示调试信息
+# -vv 显示更详细信息
+# -vvv 显示最详细信息
+ssh -vvv git@gitea.ishenwei.online -p 12222
+```
+
+---
+
+## 2. 常见问题
+
+### 问题：Permission denied (publickey)
+
+**可能原因：**
+1. SSH key 未加载
+2. 公钥未在 Gitea 中添加
+3. 使用了错误的用户名（应该是 `git`，不是账户名）
+
+**检修步骤：**
+```bash
+# 1. 查看已加载的 key
+ssh-add -l
+
+# 2. 如果列表为空，重新加载
+ssh-add ~/.ssh/id_ed25519
+
+# 3. 验证 Gitea Web UI 中是否已添加该公钥
+
+# 4. 确认使用 git 用户
+ssh -vT git@gitea.ishenwei.online -p 12222
+```
+
+### 问题：Connection refused
+
+**可能原因：**
+1. Gitea 未运行
+2. SSH 端口未正确映射
+3. 防火墙未放行端口
+
+**检修步骤：**
+```bash
+# 1. 检查 Docker 容器状态
+docker ps | grep gitea
+
+# 2. 检查端口映射
+docker port gitea
+
+# 3. 检查防火墙（本地）
+ss -tlnp | grep 2222
+
+# 4. 检查防火墙（远程 VPS）
+ufw status
+```
+
+### 问题：Connection closed by remote
+
+**可能原因：**
+1. SSH 服务异常关闭
+2. 连接超时
+3. 网络问题
+
+**检修步骤：**
+```bash
+# 1. 重启 Gitea 容器
+docker restart gitea
+
+# 2. 检查容器日志
+docker logs -f gitea
+
+# 3. 测试基本连通性
+ping gitea.ishenwei.online
+```
+
+### 问题：Bad owner or permissions on ~/.ssh/config
+
+**原因：** SSH config 文件权限不正确
+
+**修复：**
+```bash
+chmod 600 ~/.ssh/config
+chmod 600 ~/.ssh/id_ed25519
+chmod 644 ~/.ssh/id_ed25519.pub
+```
+
+---
+
+## 3. 防火墙排查
+
+### 本地网络（NAS/局域网）
+
+```bash
+# Windows - 测试端口连通性
+Test-NetConnection -ComputerName 192.168.3.17 -Port 2222
+
+# macOS/Linux - 测试端口连通性
+nc -zv 192.168.3.17 2222
+
+# 或使用 telnet
+telnet 192.168.3.17 2222
+```
+
+### 远程 VPS
+
+```bash
+# 测试 frp 通信端口
+telnet your-vps.com 7000
+
+# 测试 Gitea HTTP 端口（给 Caddy）
+telnet your-vps.com 13000
+
+# 测试 Gitea SSH 端口
+telnet your-vps.com 12222
+```
+
+### 群晖 NAS 防火墙
+
+NAS 无 UFW，防火墙配置在：
+- DSM → 控制面板 → 安全性 → 防火墙
+- 需手动添加规则放行 frp 和 SSH 端口
+
+---
+
+## 4. frp 故障排除
+
+### 检查 frp 日志
+
+```bash
+# 查看 frpc 日志
+journalctl -u frpc -f
+
+# 或直接运行 frpc 查看输出
+./frpc -c frpc.toml
+```
+
+### 验证 frps 连接
+
+```bash
+# 在 VPS 上检查已连接的隧道
+netstat -tlnp | grep 13000
+netstat -tlnp | grep 12222
+
+# 或使用 frp 的状态查询（如果启用了 admin 功能）
+curl http://localhost:7400/api/serverinfo
+```
+
+---
+
+# 第五部分：最佳实践
+
+## 1. 安全建议
+
+### SSH Key 管理
+- ✅ 使用 ed25519 算法
+- ✅ 为私钥设置强密码
+- ✅ 定期轮换密钥
+- ✅ 不同用途使用不同密钥（添加 `-C "标签"` 区分）
+
+### 防火墙配置
+- ✅ 只放行必要的端口
+- ✅ 使用 VPN 或跳板机访问敏感服务
+- ✅ 监控 SSH 连接日志
+- ✅ 禁用密码认证，仅允许密钥认证
+
+### Gitea 配置
+- ✅ 设置强密码
+- ✅ 启用 2FA（双因素认证）
+- ✅ 定期备份仓库
+- ✅ 监控访问日志
+
+---
+
+## 2. 性能优化
+
+### SSH 连接复用
+
+编辑 `~/.ssh/config` 添加连接复用：
+
+```bash
+Host *
+    ControlMaster auto
+    ControlPath ~/.ssh/control-%C
+    ControlPersist 600
+    ServerAliveInterval 60
+    ServerAliveCountMax 3
+```
+
+### Git 相关优化
+
+```bash
+# 配置 SSH 超时
+git config --global core.sshCommand "ssh -o ConnectTimeout=10"
+
+# 配置代理（如需要）
+git config --global https.proxy [proxy-url]
+```
+
+---
+
+## 3. 多环境管理
+
+### SSH Config 示例
+
+```bash
+# 本地 Gitea
+Host gitea-local
+    HostName 192.168.3.17
+    User git
+    Port 2222
+    IdentityFile ~/.ssh/id_ed25519_gitea
+
+# 远程 Gitea（通过 frp）
+Host gitea-remote
+    HostName gitea.ishenwei.online
+    User git
+    Port 12222
+    IdentityFile ~/.ssh/id_ed25519_gitea
+
+# GitHub
+Host github.com
+    HostName github.com
+    User git
+    IdentityFile ~/.ssh/id_ed25519_github
+
+# GitLab
+Host gitlab.com
+    HostName gitlab.com
+    User git
+    IdentityFile ~/.ssh/id_ed25519_gitlab
+```
+
+### Git 配置管理
+
+```bash
+# 查看当前配置
+git config --list
+
+# 全局配置
+git config --global user.name "Your Name"
+git config --global user.email "your-email@example.com"
+
+# 项目级配置（在仓库目录中）
+git config --local user.email "project-specific@example.com"
+```
+
+---
+
+## 4. 监控与维护
+
+### 定期检查
+
+```bash
+# 检查 SSH key 过期情况
+ssh-keygen -l -f ~/.ssh/id_ed25519.pub
+
+# 查看 Gitea 日志
+docker logs -f gitea
+
+# 查看 frp 连接状态
+journalctl -u frpc -f
+```
+
+### 日志轮转
+
+确保日志不会占满磁盘：
+
+```bash
+# Docker 日志轮转配置（docker-compose.yml）
+services:
+  gitea:
+    logging:
+      driver: "json-file"
+      options:
+        max-size: "100m"
+        max-file: "3"
+```
+
+---
+
+# 总结
+
+## 快速检查清单
+
+部署完成后，按以下顺序验证：
+
+- [ ] Docker 容器运行 `docker ps | grep gitea`
+- [ ] SSH 服务启用 `docker exec gitea cat /data/gitea/conf/app.ini | grep SSH`
+- [ ] 本地 SSH 连接 `ssh -T git@192.168.3.17 -p 2222`
+- [ ] frp 连接正常 `journalctl -u frpc -f`
+- [ ] SSH 端口放行（防火墙）`netstat -tlnp | grep 12222`
+- [ ] Web UI 访问 浏览器打开 `https://gitea.yourdomain.com`
+- [ ] 公钥已添加 Gitea Web UI 验证
+- [ ] Git Clone 测试 `git clone ssh://git@gitea.yourdomain.com:12222/username/repo.git`
+
+---
+
+## 一句话结论
+
+**Git 的本质：**
+- `user.name` / `email` → 标识身份
+- SSH Key → 认证身份
+
+**推荐方案：**
+> Gitea + Docker + SSH + frp + Caddy = 稳定可靠的远程 Git 服务
+
+---
+
+**记录时间：** 2026-06-04  
+**最后更新：** 2026-06-04

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

@@ -1,437 +0,0 @@
----
-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)