746 lines
15 KiB
Markdown
746 lines
15 KiB
Markdown
---
|
||
title: Gitea 完整配置指南（SSH + frp + Caddy）
|
||
author: shenwei
|
||
created: 2026-06-04
|
||
description: 涵盖 Gitea SSH 配置、frp 转发、Caddy 反代、以及客户端配置的完整指南
|
||
tags: [git, gitea, ssh, frp, caddy, docker]
|
||
---
|
||
#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
|