自建 Gitea 与 Nginx 反向代理：从 502 到可访问

2026-11-06运维

起因是想把手里几个项目的代码从单纯的本地目录往前推进一步，需要一个能自己掌控的 Git 服务。服务器是台 2 核 2G 的轻量云主机，跑 CentOS 7，内存不宽裕，所以方案上优先考虑轻量：二进制部署、SQLite 存储、Nginx 兜在前面。

端口怎么规划

这台机器上已经有别的服务在用端口，其中 3000、5173、8000 被内网穿透预留了，所以新服务不能占。Gitea 的 Web 端口改用 3001，SSH 端口用 2222 避开系统 sshd 的 22，两个都不直接对外，Web 只监听回环：

[server]
PROTOCOL         = http
HTTP_ADDR        = 127.0.0.1
HTTP_PORT        = 3001
ROOT_URL         = http://example.com/
SSH_PORT         = 2222
START_SSH_SERVER = true

这里有个容易忽略的点：ROOT_URL 必须写成最终对外访问的地址，而不是 127.0.0.1:3001。它决定了页面里静态资源、克隆地址的前缀，写错了会出现页面能打开但样式全丢、或者其他地方复制出来的仓库地址不可用。

Nginx 前置

反代配置本身不复杂，关键是几个头要带对，尤其是升级连接和超时：

location / {
    proxy_pass http://127.0.0.1:3001;
    proxy_set_header Host              $host;
    proxy_set_header X-Real-IP         $remote_addr;
    proxy_set_header X-Forwarded-For   $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_http_version 1.1;
    proxy_set_header Upgrade    $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_read_timeout 300s;
    proxy_buffering off;
}

client_max_body_size 别忘了调，默认 1M，推一个稍大的仓库就会 413。

502 的三条排查路径

配置写完第一次访问直接 502，按顺序查下来：

后端有没有真在监听：ss -tlnp | grep 3001。如果只是 systemd 显示 active 但端口没起来，说明进程启动后又退了，去看 journalctl -u gitea -n 50，而不是盯着 Nginx 日志。
进程启动失败的真实原因：这次踩到的是配置文件权限。app.ini 设成了 root:git 640，Gitea 启动时会往配置里回写 JWT_SECRET，写不进去就直接退出，日志只留下一行 failed to save app.ini: permission denied。systemd 那边只报 status=1/FAILURE，很有迷惑性。
upstream 地址写错：反代目标写成 localhost 而服务只监听了 IPv6，或者反过来，都会 502。统一写 127.0.0.1 最稳。

经验：服务起不来先看应用自己的日志，systemd 的失败状态几乎没有信息量。

验证顺序

排查时按「本机端口 → 本机 HTTP → 经 Nginx 带 Host 头 → 外网真实访问」四级验证，每一级都过一遍，能快速定位问题落在哪一层：

curl -s -o /dev/null -w "%{http_code}\n" http://127.0.0.1:3001/
curl -s -o /dev/null -w "%{http_code}\n" -H "Host: example.com" http://127.0.0.1/
curl -s -o /dev/null -w "%{http_code}\n" http://example.com/

最后一级如果和前三级表现不一致，问题就在网络入口（安全组、备案拦截、DNS），不在服务本身。

← 返回首页