Linux如何详细安装与配置Gitea私有Git仓库？

本文共计1258个文字，预计阅读时间需要6分钟。

默认使用`docker run`启动Gitea容器，所有数据（用户、仓库、配置）都保存在容器内部的文件系统中。一旦容器被删除或重装，`/data`目录将不存在，整个实例相当于重装。

正确做法是强制绑定宿主机目录：

• sudo mkdir -p /var/lib/gitea/{custom,data,log}（注意权限：后续要让容器内 git 用户能写）
• sudo chown -R 1001:1001 /var/lib/gitea（Gitea 官方镜像默认以 UID 1001 运行，不是 root）
• 启动时必须带 -v /var/lib/gitea:/data，且不能只挂 /data/gitea 这种子路径
• 如果还要自定义配置（比如改 SMTP 或 SSH 端口），得额外挂 -v /var/lib/gitea/custom:/data/gitea/custom

完整命令示例：
docker run -d --name=gitea -p 3000:3000 -p 2222:22 -v /var/lib/gitea:/data -v /etc/localtime:/etc/localtime:ro -u 1001:1001 --restart=always gitea/gitea:latest

app.ini 配置必须在首次启动前准备好，否则网页向导会写死默认值

Gitea 第一次访问 http://IP:3000 会进入安装向导，它会把填的数据库地址、管理员密码等直接写进 /data/gitea/conf/app.ini。但这个文件一旦生成，后续再挂载自定义 custom/conf/app.ini 就不会生效——Gitea 优先读 /data/gitea/conf/app.ini，而不是你挂的 custom 目录。

解决办法只有两个：

• 首次启动前，先手动创建 /var/lib/gitea/custom/conf/app.ini，并确保其中包含 [database] 和 [server] 基础段（哪怕只是占位），这样向导就不会自动生成 /data/gitea/conf/app.ini
• 或者干脆不走网页向导：启动容器后 docker exec -it gitea bash，手动运行 gitea migrate 和 gitea admin create-user 初始化，再停掉容器，把 /data/gitea/conf/app.ini 拷出来改好，重新挂载启动

关键配置项举例：
DOMAIN = git.example.com
ROOT_URL = https://git.example.com/
SSH_PORT = 2222
HTTP_PORT = 3000
这些必须和反向代理或端口映射对得上，否则 clone 地址会错

用 systemd 管理二进制部署时，WorkingDirectory 和 User 权限必须严格匹配

二进制方式看似简单，但 systemd 服务文件里一个字段写错，gitea web 就起不来，日志里只报 failed to open log file 或空错误。

核心检查点：

• User= 必须是运行 Gitea 的系统用户（如 git），不能是 root；该用户主目录（HOME）要设对，因为 Gitea 会去读 $HOME/.ssh 和写日志
• WorkingDirectory= 必须是该用户的主目录（如 /home/git），否则 gitea web 启动时找不到 custom/conf/app.ini（它默认从工作目录往下找）
• ExecStart= 推荐显式指定配置路径：/home/git/gitea web -c /home/git/custom/conf/app.ini，避免依赖当前路径
• 目录权限：确保 /home/git/{custom,data,log} 全部属于 git:git，且 custom 至少是 750，否则 Gitea 拒绝加载配置

常见报错：Failed to load configuration '/home/git/custom/conf/app.ini': open /home/git/custom/conf/app.ini: permission denied——八成是 custom 目录权限不对，或父目录（如 /home/git）没开其他用户执行位（x）

反向代理必须透传 X-Forwarded-Proto 和 X-Forwarded-Host

如果你用 Nginx 把 https://git.example.com 代理到本地 http://127.0.0.1:3000，但没透传关键头，Gitea 生成的 clone URL 会变成 http://git.example.com/xxx.git（混用 http/https），或者 Webhook 回调地址写成 http://localhost:3000，根本不可达。

Nginx 配置里这几行不能少：

location / { proxy_pass http://127.0.0.1:3000; 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_set_header X-Forwarded-Host $host; proxy_set_header X-Forwarded-Ssl on; }

同时，app.ini 中的 ROOT_URL 必须写成最终对外的地址（https://git.example.com/），不能写 http://localhost:3000；DISABLE_SSH 设为 true 可避免 SSH 配置干扰，除非你真要用内置 SSH

真正麻烦的不是安装步骤，而是目录权限、UID 匹配、配置加载顺序这三处细节——它们不出错时一切正常，一出错就只能看 journalctl -u gitea 或 docker logs gitea，而且错误信息往往不指向真实原因。