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

title, author, created, description, tags

title	author	created	description	tags
Gitea 完整配置指南（SSH + frp + Caddy）	shenwei	2026-06-04	涵盖 Gitea SSH 配置、frp 转发、Caddy 反代、以及客户端配置的完整指南	git gitea ssh frp caddy docker

Gitea 完整配置指南（SSH + frp + Caddy）

这是一份综合指南，涵盖 Gitea 的完整配置，包括 SSH 设置、通过 frp 和 Caddy 进行远程访问、以及 Git 客户端配置。

目录

1. 第一部分：Gitea 部署与基础 SSH 配置
2. 第二部分：远程访问架构（frp + Caddy）
3. 第三部分：客户端配置
4. 第四部分：故障排除
5. 第五部分：最佳实践

---

第一部分：Gitea 部署与基础 SSH 配置

1. Docker 部署（推荐标准配置）

基础 Docker Compose 配置

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 服务启用

检查配置

进入容器检查配置：

docker exec -it gitea /bin/sh
cat /data/gitea/conf/app.ini

确保 [server] 部分包含：

[server]
START_SSH_SERVER = true
SSH_PORT = 22

• START_SSH_SERVER = true：启用 SSH 服务
• SSH_PORT = 22：容器内监听 22 端口（通过 Docker 映射到外部端口）

重启服务

docker compose down
docker compose up -d

---

3. 基础 SSH 连接测试

测试 SSH 连通性（本地网络）

# 使用指定端口连接
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 中添加或未加载

修复：

# 确保公钥已添加到 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 配置文件

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 配置文件

bindAddr = "0.0.0.0"
bindPort = 7000
auth.method = "token"
auth.token = "your-token"

防火墙配置

在 VPS 上放行端口：

# 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 配置

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：

[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 根路径，通常指向域名

重启应用

docker compose down
docker compose up -d

---

第三部分：客户端配置

1. SSH Key 生成

生成密钥对

ssh-keygen -t ed25519 -C "your-email@example.com"

为什么用 ed25519？

• 更安全、密钥更短
• 现代标准推荐

默认路径：

~/.ssh/id_ed25519      # 私钥
~/.ssh/id_ed25519.pub  # 公钥

启动 SSH Agent

# 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

复制公钥内容

cat ~/.ssh/id_ed25519.pub

将输出内容完整复制到 Gitea，包括前缀 ssh-ed25519 AAA...

---

3. SSH Config 配置（推荐）

简化 SSH 连接

编辑 ~/.ssh/config：

# 本地网络 - 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

使用简化命令

配置后，可以用更简洁的命令：

# 本地网络
ssh -T gitea-local

# 远程（通过 frp）
ssh -T gitea.yourdomain.com

---

4. Git 仓库配置

方式一：Clone 时使用 SSH

# 本地
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

# 查看当前 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

验证连接

git pull

---

5. VS Code / IDE 集成

在配置好 SSH 和 Git Remote 后：

• VS Code：无需额外配置，自动使用 Git + SSH
• JetBrains IDE：自动识别 SSH Config
• 其他 IDE：通常也会自动识别系统 SSH 配置

优势：

• 无需输入密码
• 不受代理干扰
• Clone / Pull 不会卡住

---

第四部分：故障排除

1. SSH 连接测试

测试不同场景

# 本地网络测试
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

详细调试信息

# -v 显示调试信息
# -vv 显示更详细信息
# -vvv 显示最详细信息
ssh -vvv git@gitea.ishenwei.online -p 12222

---

2. 常见问题

问题：Permission denied (publickey)

可能原因：

1. SSH key 未加载
2. 公钥未在 Gitea 中添加
3. 使用了错误的用户名（应该是 git，不是账户名）

检修步骤：

# 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. 防火墙未放行端口

检修步骤：

# 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. 网络问题

检修步骤：

# 1. 重启 Gitea 容器
docker restart gitea

# 2. 检查容器日志
docker logs -f gitea

# 3. 测试基本连通性
ping gitea.ishenwei.online

问题：Bad owner or permissions on ~/.ssh/config

原因： SSH config 文件权限不正确

修复：

chmod 600 ~/.ssh/config
chmod 600 ~/.ssh/id_ed25519
chmod 644 ~/.ssh/id_ed25519.pub

---

3. 防火墙排查

本地网络（NAS/局域网）

# 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

# 测试 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 日志

# 查看 frpc 日志
journalctl -u frpc -f

# 或直接运行 frpc 查看输出
./frpc -c frpc.toml

验证 frps 连接

# 在 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 添加连接复用：

Host *
    ControlMaster auto
    ControlPath ~/.ssh/control-%C
    ControlPersist 600
    ServerAliveInterval 60
    ServerAliveCountMax 3

Git 相关优化

# 配置 SSH 超时
git config --global core.sshCommand "ssh -o ConnectTimeout=10"

# 配置代理（如需要）
git config --global https.proxy [proxy-url]

---

3. 多环境管理

SSH Config 示例

# 本地 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 配置管理

# 查看当前配置
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. 监控与维护

定期检查

# 检查 SSH key 过期情况
ssh-keygen -l -f ~/.ssh/id_ed25519.pub

# 查看 Gitea 日志
docker logs -f gitea

# 查看 frp 连接状态
journalctl -u frpc -f

日志轮转

确保日志不会占满磁盘：

# 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