Linux系统安装配置Gitea 轻量级Git私服部署

Linux系统安装配置Gitea：轻量级Git私服部署

最稳妥的部署方式是二进制部署，因其省资源、免编译、高安全性；必须创建专用低权限用户（如git）并严格限定目录所有权，避免root运行导致权限泛滥，同时需正确配置GITEA_WORK_DIR、WorkingDirectory、Environment及端口监听等关键参数。

在资源有限的云服务器上（比如只有1GB内存），直接使用二进制文件部署Gitea，往往是那个最稳妥、也最高效的选择。相比Docker，它更省资源；相比源码编译，它更省事；而相比直接用root权限运行，它的安全性又高出一大截。

为什么不用 root 用户运行 gitea

让Gitea以root身份运行，无异于主动敞开系统最高权限的大门。一旦Web界面或SSH入口存在漏洞被利用，攻击者几乎可以长驱直入。这可不是危言耸听，Gitea官方文档白纸黑字地建议：务必使用专用的低权限用户。

实际操作中，常见的“翻车”现场通常表现为以下几种：

• 启动命令gitea web执行后，直接报错permission denied。这多半是因为日志目录或数据库文件之前被root用户创建了，新建的git用户没有写入权限。
• Web界面倒是能打开，可一到创建仓库就失败，提示failed to init repository。根源往往出在数据目录（比如/home/git/data）的所有者不是git用户。
• systemd服务显示启动成功，但状态却一直是inactive (dead)。这种情况，十有八九是服务文件里虽然配置了User=git，但对应的目录权限却没有同步修改。

所以，正确的做法必须从创建隔离用户和严格限定路径所有权开始：

• 首先，运行命令创建系统用户：sudo adduser --system --shell /bin/bash --gecos 'Gitea' --disabled-password --home /home/git git。
• 紧接着，立即执行sudo chown -R git:git /home/git，别等到后续步骤再做，避免遗忘。
• 记住一个原则：所有Gitea相关的目录（custom、data、log），其所有权必须完全归属于git用户。仅仅靠chmod 755修改读写权限是远远不够的。

gitea web 启动失败的三个高频原因

即使用户和目录权限都设置正确了，手动执行gitea web命令时，它仍然可能静默退出或者监听失败。这时候，问题核心往往不在Gitea程序本身，而在于那些容易被忽略的环境变量和工作路径。

• GITEA_WORK_DIR必须显式设置。如果不设置，Gitea会默认使用当前shell的$HOME环境变量。如果你是通过sudo -u git bash切换用户后操作的，此时的$HOME很可能还是/root，这会导致配置和数据被写到错误的位置。
• -c参数指定的配置文件路径必须存在且可读。推荐将配置文件统一放在/home/git/custom/conf/app.ini。在首次启动前，记得手动创建这个空文件，并用chown git:git命令确保git用户有权读取。
• 端口被占用是个“隐形杀手”。执行netstat -tuln | grep :3000检查一下。在一些Ubuntu系统上，默认可能有snap版的lxd或其他服务占用了3000端口。解决方法是换个端口，在app.ini中修改HTTP_PORT = 3001即可。

如何验证Gitea是否真的成功启动了？别只看终端有没有报错。更可靠的方法是：先用sudo -u git ss -tuln | grep :3000确认3000端口是否处于监听状态；再用curl -I http://localhost:3000测试，如果返回200 OK或者重定向响应，那才算大功告成。

systemd 服务里 WorkingDirectory 和 Environment 怎么配才不踩坑

网上很多教程把systemd服务文件的内容抄来就用，但实际部署时，WorkingDirectory设错会导致gitea web找不到配置文件，而Environment缺失则可能让SQLite数据库初始化直接失败。

• WorkingDirectory=/home/git是底线。不能写成/home/git/custom，更不能留空。因为Gitea会从这个工作目录出发，向上寻找custom/conf/app.ini文件。
• Environment=HOME=/home/git USER=git必须写全。如果缺失，SQLite数据库的默认路径（HOME/data/gitea.db）就可能被解析成/root/data/gitea.db，导致权限错误。
• 别轻信“Type=simple就够了”。如果Gitea启动过程较慢（例如首次运行需要初始化数据库），务必在服务文件中加上TimeoutSec=300。否则，systemd可能会在Gitea还没准备好时就误判其启动失败，进而陷入反复重启的死循环。

修改完服务文件后，记得执行sudo systemctl daemon-reload && sudo systemctl restart gitea来重载配置并重启服务。之后，通过sudo journalctl -u gitea -f命令实时跟踪日志，这比盲目猜测问题所在要高效得多。

Docker 方式部署时 /data 挂载点权限容易被忽略

用Docker跑Gitea，最大的陷阱往往不是拉取镜像失败，而是容器内部以git用户身份运行的进程，无法写入宿主机上挂载的/var/lib/gitea目录。

• 在宿主机上，准备工作要做足。先执行sudo mkdir -p /var/lib/gitea/{custom,data,log}创建目录结构，紧接着执行sudo chown 1001:1001 /var/lib/gitea。这是因为Gitea官方Docker镜像内部固定使用UID/GID为1001的用户。
• 别以为docker run -v /var/lib/gitea:/data挂载上就万事大吉。必须确保容器内的/data目录对于git用户是可写的，否则初始化页面很可能卡在“Creating database…”这一步。
• 警惕静默故障。SQLite数据库的默认路径是/data/gitea.db。如果挂载目录权限不对，Gitea可能会静默降级，转而使用内存数据库。这样一来，所有数据在容器重启后都会丢失，而这种故障极其难以排查。

最保险的验证方法分两步：启动容器后，先用docker exec -u 0 -it gitea ls -l /data查看目录归属；再用docker exec -u 1001 -it gitea touch /data/test，测试UID 1001的用户是否拥有写入权限。

说到底，部署Gitea真正的难点，从来不是“怎么把软件装上去”，而是“弄清楚到底是谁、在哪个路径下、以什么身份、读写哪些文件”。Gitea本身确实轻量，但Linux那套严格的权限模型，可不会因为你是用Go写的程序就网开一面。