必须用专用用户运行gitea，因其可避免权限混乱与安全风险：确保日志写入、ssh密钥加载、文件上传等功能正常，并要求所有数据目录由该用户完全拥有，配置文件需赋予对应读取权限。
直接用二进制方式部署 Gitea 是最可控、最省心的选择，尤其适合 Linux 服务器环境。它不依赖系统包管理器，避免版本冲突，也比 Docker 更少抽象层，出问题时排查路径更短。
为什么必须用专用用户运行 gitea 服务
以 root 或普通用户直接运行 gitea web 会带来权限混乱和安全风险：日志写入失败、仓库目录被其他进程误改、SSH 密钥无法加载、Web 界面上传文件报错等，几乎都源于用户与目录所有权不匹配。
- 创建用户时务必指定独立 home 目录，例如
sudo adduser --system --home /home/git git - 所有数据目录（
data、log、custom）必须由该用户完全拥有：sudo chown -R git:git /home/git -
app.ini配置文件若放在/etc/gitea/，也要确保git用户有读取权限（sudo chmod 640 /etc/gitea/app.ini+sudo chgrp git /etc/gitea/app.ini）
gitea web 启动失败的三个高频原因
常见现象是执行 sudo -u git gitea web -c /path/to/app.ini 后立即退出，或日志里反复出现 failed to open database、listen tcp :3000: bind: permission denied、Git version too old。
- 端口被占用：默认 3000 端口可能已被其他服务（如 Jenkins、Node.js 应用）占用，改用
HTTP_PORT = 3001并在app.ini中显式设置 - Git 版本过低：Gitea 要求 Git ≥ 2.20；统信 UOS、CentOS 7 等旧系统常自带 1.8.x，需手动升级，验证命令为
git --version - SQLite 数据库路径不可写：如果
APP_DATA_PATH指向/var/lib/gitea/data，但该路径属 root 且无写权限，gitea会静默失败，务必检查ls -ld /var/lib/gitea/data
systemd 服务配置里最容易漏掉的关键项
很多教程复制的 gitea.service 文件缺少环境隔离，导致服务启动后无法读取用户级配置或时区，表现为 Web 界面时间错乱、邮件发送失败、SSH 克隆超时。
- 必须显式设置
Environment=HOME=/home/git USER=git，否则 Go 运行时无法定位~/.ssh -
WorkingDirectory必须与ExecStart中二进制所在路径一致，否则gitea会从错误位置加载custom/下的模板或钩子 - 若使用 SQLite，建议加一行
ProtectHome=read-only防止意外覆盖用户家目录，但不要开ProtectSystem=full，否则无法写数据库文件
真正麻烦的不是第一次跑起来，而是后续改域名、换数据库、开 HTTPS 或集成 LDAP 时，app.ini 里几十个参数互相牵扯——比如改了 ROOT_URL 却忘了同步 SSH_DOMAIN，会导致 SSH 克隆地址生成错误；又比如启用了 ENABLE_REVERSE_PROXY_AUTHENTICATION 却没配好 Nginx 的 X-Forwarded-User 头，登录就无限重定向。这些细节不写死在配置里，只靠 Web 向导点一点是不够的。
