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