如何在Linux服务器上首次部署Gitea并验证仓库可以正常访问?
首次部署 Gitea,可以先采用 Linux 二进制、systemd 和 SQLite:不需要单独搭建数据库,适合个人使用、测试环境或小规模团队的初始验证。下面以 Ubuntu 22.04/24.04、Debian 12、x86_64 架构为例,完成安装、首次网页配置,并通过浏览器和 Git 命令确认仓库能够访问。
示例使用 Gitea 1.22.6。正式部署时,可根据目标版本和服务器架构调整下载地址;如果系统不是 Debian/Ubuntu 系,包管理和防火墙命令也需要相应替换。
准备条件
开始前,确认具备以下条件:
- 一台可通过 SSH 管理的 Linux 服务器,并有
sudo权限。 - 系统为 64 位 Debian/Ubuntu,服务器可以访问 Gitea 下载站点。
- 已确定访问方式:示例使用服务器 IP 和 HTTP 端口
3000。若使用域名,需先将域名解析到服务器,并确保后续配置中的访问地址一致。 - 服务器的安全组或防火墙允许管理端访问 TCP
3000。如果只做本机测试,可暂不开放公网端口。
先确认系统和处理器架构:
cat /etc/os-release
uname -m
本文命令中的二进制文件适用于 x86_64。如果 uname -m 输出为 aarch64、armv7l 等结果,应选择对应架构的 Gitea 文件,不能直接使用 amd64 二进制。
安装 Gitea
安装 Git 并创建运行账号
Gitea 需要调用 Git 执行仓库操作。SQLite 由 Gitea 使用,不需要额外安装独立数据库服务。
sudo apt update
sudo apt install -y git ca-certificates curl
创建专用系统账号和数据目录:
sudo adduser \
--system \
--group \
--disabled-password \
--home /var/lib/gitea \
git
sudo install -d -o git -g git -m 750 \
/var/lib/gitea/custom \
/var/lib/gitea/data \
/var/lib/gitea/log
sudo install -d -o root -g git -m 770 /etc/gitea
git 账号用于运行服务,不应以 root 身份启动 Gitea。/var/lib/gitea 保存应用数据和仓库;/etc/gitea 用于保存配置。初次网页安装时,服务需要能够写入配置目录,因此这里将其设置为 root:git 所有、组权限可写。
检查账号和目录:
getent passwd git
stat -c '%U:%G %a %n' /var/lib/gitea /var/lib/gitea/data /etc/gitea
预期能查到 git 账号;数据目录应归 git:git 所有,配置目录应显示为 root:git 且权限为 770。
下载并安装二进制文件
先设定版本和架构。以下示例适用于 x86_64:
GITEA_VERSION=1.22.6
GITEA_ARCH=amd64
curl -fL \
"https://dl.gitea.com/gitea/${GITEA_VERSION}/gitea-${GITEA_VERSION}-linux-${GITEA_ARCH}" \
-o /tmp/gitea
file /tmp/gitea
file 输出应表明这是 Linux 可执行文件。确认下载成功后安装到 /usr/local/bin:
sudo install -o root -g root -m 755 /tmp/gitea /usr/local/bin/gitea
/usr/local/bin/gitea --version
版本命令应返回 Gitea 版本信息。如果下载失败,先检查版本号、处理器架构和服务器的 HTTPS 出站连接,不要将 HTML 错误页面安装为可执行文件。
配置并启动服务
创建 systemd 服务单元:
sudo tee /etc/systemd/system/gitea.service >/dev/null <<'EOF'
[Unit]
Description=Gitea
After=network.target
[Service]
Type=simple
User=git
Group=git
WorkingDirectory=/var/lib/gitea
Environment=USER=git
Environment=HOME=/var/lib/gitea
Environment=GITEA_WORK_DIR=/var/lib/gitea
ExecStart=/usr/local/bin/gitea web --config /etc/gitea/app.ini
Restart=always
RestartSec=2
[Install]
WantedBy=multi-user.target
EOF
重新加载 systemd 并启动服务:
sudo systemctl daemon-reload
sudo systemctl enable --now gitea
查看服务状态:
sudo systemctl status gitea --no-pager
如果服务处于 active (running),继续检查监听端口和 HTTP 响应:

sudo ss -lntp | grep ':3000'
curl -sS -o /dev/null -w '%{http_code}\n' http://127.0.0.1:3000/
端口检查应能找到 Gitea 进程;HTTP 状态码通常为 200 或安装流程产生的重定向状态。若本机请求失败,先查看服务日志:
sudo journalctl -u gitea -n 50 --no-pager
确认没有启动错误后,从管理电脑的浏览器访问:
http://服务器IP:3000/
如果本机 curl 可访问、浏览器却无法连接,问题通常在服务器外部的安全组、防火墙或路由,不一定是 Gitea 服务本身。
完成首次网页配置
首次访问会进入安装页面。使用 SQLite 完成最小配置:

- 数据库类型选择 SQLite3。
- 数据库路径填写
/var/lib/gitea/data/gitea.db。 - 仓库根目录使用
/var/lib/gitea/data/gitea-repositories或页面提供的默认路径;确认其位于 Gitea 可写的数据目录中。 - 域名填写服务器 IP,或已解析到服务器的域名。
- Gitea 基础 URL 填写实际访问地址,例如
http://服务器IP:3000/。 - HTTP 监听端口保持
3000。 - 创建首个管理员账号,并妥善保存账号凭据。
首次部署只通过 HTTP 在内网或受控环境验证时,可以使用示例地址。若计划通过公网域名长期提供服务,应先规划 HTTPS 和实际对外 URL;不要让配置中的基础 URL 与用户实际访问地址长期不一致。
提交安装页面后,Gitea 会生成配置并初始化数据库。安装完成后检查服务是否仍在运行:
sudo systemctl is-active gitea
sudo ls -l /etc/gitea/app.ini /var/lib/gitea/data/gitea.db
配置文件和数据库文件应已生成,服务状态应返回 active。再次访问基础 URL,页面应进入登录页或 Gitea 首页,而不是仍停留在安装页面。
验证仓库可以正常访问
只看到登录页,还不能说明仓库读写链路可用。需要创建一个仓库,再用 Git 客户端读取它。
创建测试仓库
登录 Gitea,创建名为 deploy-check 的仓库。为便于首次验证,可将仓库设为公开,并勾选初始化 README。公开仓库适合验证匿名读取;私有仓库则需要在 Git 客户端配置有效凭据,不能用匿名访问结果判断其权限是否正常。
创建后,页面应显示仓库文件列表和克隆地址。先确认网页能够打开仓库页面,再执行命令行验证。
使用 Git 读取仓库
在管理电脑或服务器上执行,替换地址中的服务器 IP 和仓库所有者名称:
git ls-remote http://服务器IP:3000/所有者/deploy-check.git
如果仓库已初始化 README,命令通常会输出一条或多条引用记录,例如:
a1b2c3d4... HEAD
a1b2c3d4... refs/heads/main
以上仅为输出格式示例,不代表实际仓库的提交 ID。git ls-remote 成功返回引用,说明 HTTP 仓库地址可达,Gitea 能读取仓库数据。
再执行一次克隆,验证实际下载:

git clone http://服务器IP:3000/所有者/deploy-check.git
cd deploy-check
git status
克隆成功后,目录中应包含 README 等初始化文件,git status 应显示当前分支且工作区干净。若还要验证写入,可在本地新增一个文件并推送;这会修改测试仓库,建议仅对专用测试仓库操作:
printf 'Gitea deployment check\n' > deployment-check.txt
git add deployment-check.txt
git commit -m "Add deployment check file"
git push
公开仓库通常也要求登录后才能推送。若提示身份信息缺失,按 Gitea 页面支持的认证方式配置凭据,不要把密码直接写进仓库 URL 或脚本。推送成功后刷新仓库页面,应能看到新提交和文件。
防火墙与访问范围
先确认服务器是否启用了 UFW:
sudo ufw status
如果 UFW 显示为 active,且确实需要从管理电脑访问 3000 端口,可按来源地址限制开放范围,例如:
sudo ufw allow from 管理电脑公网IP to any port 3000 proto tcp
sudo ufw status numbered
不要在远程维护时随意启用 UFW 或重置现有规则,这可能导致 SSH 连接中断。使用云服务器时,还需在云平台安全组中放行相同端口;安全组规则与系统防火墙是两层独立控制。

常见失败处理
- 服务无法启动:查看
sudo journalctl -u gitea -n 100 --no-pager。若提示找不到配置文件,确认服务命令中的路径为/etc/gitea/app.ini,并重新执行sudo systemctl daemon-reload后启动。 - 安装页面无法保存:检查数据目录和配置目录权限。数据应由
git用户写入;安装阶段的/etc/gitea应允许git组写入。不要用chmod -R 777解决权限问题。 - 本机能访问,远程不能访问:依次检查 Gitea 是否监听可远程访问的地址、系统防火墙和云平台安全组。仅本机访问成功不能证明公网端口已开放。
- Git 返回 404:检查仓库所有者、仓库名称和克隆地址是否一致,并确认仓库已创建。仓库名和所有者名称拼写错误也会导致访问失败。
- Git 返回 401 或要求认证:确认仓库是否为私有仓库,以及当前使用的账号是否有读取权限。不要通过关闭认证来绕过权限问题。
- 页面跳转到错误地址:检查 Gitea 的基础 URL 是否与浏览器实际访问地址一致。若修改过地址,修改后重启服务,并重新测试仓库页面和克隆地址。
验收与回滚检查项
首次部署验收时,逐项确认:
gitea --version能返回版本信息,systemctl is-active gitea返回active。- 服务器本机和管理电脑均能按预期访问 Gitea 页面。
- 管理员账号可以登录,配置文件和 SQLite 数据库已生成。
- 测试仓库页面可打开,
git ls-remote和git clone均能成功。 - 如果需要写入,登录用户能够向测试仓库推送提交。
- 防火墙和云安全组只开放实际需要的访问范围。
如果首次部署需要撤销,先停止服务,再备份数据和配置;不要直接删除目录。下面的归档命令会在 /root 下创建备份文件,需确认磁盘空间足够:
sudo systemctl disable --now gitea
sudo tar -czf "/root/gitea-backup-$(date +%Y%m%d-%H%M%S).tar.gz" \
/etc/gitea /var/lib/gitea
确认归档文件存在且可读取后,可移除服务单元和二进制文件:
sudo rm -f /etc/systemd/system/gitea.service
sudo systemctl daemon-reload
sudo rm -f /usr/local/bin/gitea
这一步不会自动删除 Gitea 配置、仓库和数据库。保留数据便于后续恢复;只有确认不再需要且备份可用时,才考虑清理 /etc/gitea 和 /var/lib/gitea。
Gitea这类代码托管服务可作为团队协作与项目仓库管理的组成部分。A5数据提供香港、美国、日本、韩国、中国台湾、新加坡和马来西亚等地区的物理服务器,配置覆盖Xeon Gold、AMD EPYC平台及SSD、NVMe存储,可为代码仓库、业务后台和相关数据服务提供部署资源。不同地区的网络线路与硬件方案各有侧重,适合承载面向不同访问区域的开发协作和业务服务。
本文由A5数据原创发布,转载请注明出处:https://www.a5idc.com/helpcontent/5495.html



