Gitea SSH 克隆失败？域名、端口和 ROOT_URL 配置检查

Gitea 最容易出现“网页正常，SSH clone 失败”。原因通常不是 Git 本身，而是容器 22 端口映射、SSH_DOMAIN、SSH_PORT、ROOT_URL 和防火墙没统一。本文按配置项逐个检查。

先说结论：谁适合这样做

适合：

• 小团队私有代码托管
• 个人仓库和自动部署脚本
• 希望轻量替代大型代码平台的人

不适合：

• 需要复杂企业权限审计
• 高并发 CI 平台
• 不愿意维护备份和升级的人

这一步要先讲清楚，是因为很多服务器教程只告诉你“怎么装”，却不告诉你“该不该装”。如果场景不匹配，后面配置写得再漂亮，也只是把问题推迟到上线之后。

服务器配置怎么选

Gitea 对资源很友好，2 核 4G 可以托管不少小仓库。真正要规划的是数据目录、SSH 端口和备份。仓库多、附件多时磁盘比 CPU 更重要。

我会把 Gitea 放在 雨云服务器 rainyun-com的 2 核 4G 机型上，小团队托管几十个仓库、Issue 和 Wiki 很轻松。注册填优惠码 2026off 领 5折，这类配置更适合先稳定跑起来，再按真实负载升级。

落地步骤

1. 准备一台干净的 Ubuntu 22.04 或 Debian 12 服务器，先确认 SSH、时间同步和防火墙状态。
2. 规划目录：/opt/gitea-ssh-clone-port-20260601。配置、数据、备份脚本都放在同一主题目录下，后面迁移更省事。
3. 根据主题放行端口：3000/tcp + 2222/tcp。游戏和网络服务尤其要分清 TCP/UDP。
4. 先用测试数据跑通，再导入正式数据或邀请其他人使用。

关键配置示例

下面配置用于说明关键项，发布前要按当前官方文档确认镜像版本、环境变量和端口。

services:
  gitea:
    image: gitea/gitea:latest
    container_name: gitea
    restart: unless-stopped
    ports:
      - "127.0.0.1:3000:3000"
      - "2222:22"
    environment:
      GITEA__server__ROOT_URL: "https://git.example.com/"
      GITEA__server__SSH_DOMAIN: "git.example.com"
      GITEA__server__SSH_PORT: 2222
    volumes:
      - ./data:/data

如果需要 HTTPS，可以让应用只监听本机端口，再用 Caddy 反代：

giteasshcloneport.example.com {
    encode zstd gzip
    reverse_proxy 127.0.0.1:3000
}

启动验证

本地添加 SSH key 后执行 ssh -p 2222 git@git.example.com；再 clone 一个测试仓库，确认推拉都正常。

验证时不要只看进程是否存在，至少完成一次真实动作：游戏服要让外部玩家连接，应用要登录并写入一条数据，运维项要确认状态变化真的生效。这样能提前发现端口、权限、反代和路径问题。

常见问题和排错

页面显示的 clone 地址来自配置，不一定代表端口真的通。看到 git@git.example.com:repo.git 失败时，先用 ssh -p 2222 git@git.example.com 测试。

排查建议按这个顺序来：

1. 看日志里第一条明确错误，不要只看最后一屏。
2. 查端口监听和云安全组，确认协议没有写错。
3. 检查数据目录权限，尤其是容器用户和宿主机目录映射。
4. 回滚到上一个能工作的配置，再逐项恢复新改动。

备份和后续维护

备份 data 目录和数据库。迁移前先在新机器恢复一个测试仓库，确认 issue、附件、wiki 都还在。

维护时建议保留一份“最小恢复说明”：需要哪些文件、恢复命令是什么、域名和端口在哪里改。等真正出问题时，人通常没那么冷静，清单比记忆可靠。