ishenwei/nexus
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

合并文档并更新

Browse Source
This commit is contained in:
admin
2026-06-04 15:12:25 +08:00
parent b147c5730f
commit 836bbdd90d
3 changed files with 1291 additions and 980 deletions
Download Patch File Download Diff File Expand all files Collapse all files

745
knowledgebase/Gitea 完整配置指南（SSH + frp + Caddy）.md Normal file
View File

@@ -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