如何在美国服务器上部署Gitea,搭建可用的私有代码仓库?
在美国服务器上部署 Gitea,可以用一台 Ubuntu LTS 主机、SQLite、Gitea 内置 SSH 服务和 Nginx 完成首次运行。Gitea 负责仓库与网页界面,Nginx 提供 HTTPS 入口,仓库通过单独的 SSH 端口进行 Git 操作;初次建管理员账号时,可用 SSH 隧道访问本机网页端口,避免在初始化期间公开注册入口。

以下以 Ubuntu 22.04/24.04、amd64 架构和 git.example.com 为例。美国机房本身不改变安装步骤,但需要确认域名解析、主机防火墙和云平台安全组均允许所需流量。SQLite 适合单机、规模较小的团队;如果团队规模或并发写入量增长,应另行评估数据库与备份方案。
针对美国节点上的私有代码仓库与配套业务服务,A5idc数据提供美国物理服务器资源,常规Xeon系列有CN2 GIA线路方案,AMD EPYC系列覆盖不同计算配置,部分机型配备DDR5内存和NVMe存储,可为Gitea运行、仓库数据保存及相关服务提供硬件基础。多档资源组合也适用于不同规模的团队仓库部署。
准备条件
部署前准备一台有管理员权限的 Ubuntu 服务器、已解析到服务器公网 IP 的域名,以及一台用于管理服务器的电脑。还需要准备管理员邮箱,并决定团队成员如何访问 Git 仓库。
先确认系统版本、架构和磁盘空间:
lsb_release -a
dpkg --print-architecture
df -h /
本文的二进制下载示例针对 amd64。如果输出为 arm64,应下载与该架构匹配的 Gitea 文件,不要直接使用 amd64 文件。建议预留足够空间存放仓库、日志和备份;具体需要量取决于仓库体积与增长情况。
检查服务器已有防火墙规则和 SSH 管理通道:
sudo ufw status verbose
sudo systemctl status ssh
如果使用云平台安全组,也要检查其入站规则。更改防火墙前确认当前 SSH 管理连接不会被中断;不要直接清空已有规则或关闭服务器当前使用的远程管理端口。
将 git.example.com 的 DNS A 记录指向服务器公网 IP。可以在服务器上初步检查解析结果:
getent ahosts git.example.com
输出中应能看到预期的服务器地址。域名解析尚未生效时,仍可先完成 Gitea 安装,但配置 Nginx 和申请证书前应确认解析已正确。
安装 Gitea 与运行账户
安装 Git、SQLite、下载工具和证书组件:
sudo apt update
sudo apt install -y git sqlite3 curl ca-certificates
git --version
sqlite3 --version
命令正常返回版本信息即表示基础依赖可用。接下来创建专用的系统账户和数据目录,使 Gitea 不以 root 身份运行:
sudo adduser --system --shell /bin/bash --gecos 'Git Version Control' \
--group --disabled-password --home /home/git git
sudo mkdir -p /var/lib/gitea/{custom,data,log}
sudo mkdir -p /etc/gitea
sudo chown -R git:git /var/lib/gitea
sudo chmod 750 /var/lib/gitea /var/lib/gitea/{custom,data,log}
sudo chown root:git /etc/gitea
sudo chmod 750 /etc/gitea
确认账户和目录权限:
getent passwd git
stat -c '%U:%G %a %n' /var/lib/gitea /var/lib/gitea/data /etc/gitea
数据目录应由 git 账户管理;配置目录由 root 管理,同时允许 git 组读取。这样可以让服务写入仓库与数据库,同时减少普通服务进程修改配置文件的权限。

下载前,先从 Gitea 发布页面确认所需版本和对应的 Linux amd64 文件名。下面以变量表示版本号;将示例值替换为已确认的版本,不要把它当作当前最新版本:
GITEA_VERSION='1.23.8'
curl -fL \
"https://dl.gitea.com/gitea/${GITEA_VERSION}/gitea-${GITEA_VERSION}-linux-amd64" \
-o /tmp/gitea
安装前应按发布页面提供的校验值核对下载文件。先计算本地摘要,再与所选版本的发布校验值逐字符比对:
sha256sum /tmp/gitea
摘要不匹配时不要安装该文件,应重新下载并核对版本、架构和来源。确认无误后安装到系统路径:
sudo install -o root -g root -m 0755 /tmp/gitea /usr/local/bin/gitea
/usr/local/bin/gitea --version
如果最后一条命令输出版本信息,说明二进制可以运行。若出现 Exec format error,首先检查下载文件是否与服务器架构匹配。
配置服务与首次启动
生成供 Gitea 使用的密钥。每条命令会输出一段值;把输出分别保存到稍后的 app.ini 配置项中,不要把密钥发布到网页、工单或代码仓库:
sudo -u git /usr/local/bin/gitea generate secret SECRET_KEY
sudo -u git /usr/local/bin/gitea generate secret INTERNAL_TOKEN
创建配置文件:
sudo nano /etc/gitea/app.ini
填写以下配置,并将域名、密钥值替换为自己的内容:
APP_NAME = Team Git
RUN_USER = git
RUN_MODE = prod
[repository]
ROOT = /var/lib/gitea/data/gitea-repositories
[database]
DB_TYPE = sqlite3
PATH = /var/lib/gitea/data/gitea.db
[server]
DOMAIN = git.example.com
SSH_DOMAIN = git.example.com
HTTP_ADDR = 127.0.0.1
HTTP_PORT = 3000
ROOT_URL = https://git.example.com/
DISABLE_SSH = false
SSH_PORT = 2222
START_SSH_SERVER = true
SSH_LISTEN_HOST = 0.0.0.0
SSH_LISTEN_PORT = 2222
[security]
INSTALL_LOCK = true
SECRET_KEY = 替换为生成的SECRET_KEY
INTERNAL_TOKEN = 替换为生成的INTERNAL_TOKEN
[service]
DISABLE_REGISTRATION = false
REQUIRE_SIGNIN_VIEW = true
此配置让网页服务只监听服务器本机的 127.0.0.1:3000,外部无法直接访问该端口;内置 SSH 服务监听 2222 端口。首次创建管理员账号期间,HTTP 注册入口也只通过本机隧道访问。管理员账号创建完成后,应关闭公开注册。
保存后限制配置文件权限:
sudo chown root:git /etc/gitea/app.ini
sudo chmod 640 /etc/gitea/app.ini
sudo stat -c '%U:%G %a %n' /etc/gitea/app.ini
建立 systemd 服务:
sudo nano /etc/systemd/system/gitea.service
写入:
[Unit]
Description=Gitea
After=network.target
[Service]
Type=simple
User=git
Group=git
WorkingDirectory=/var/lib/gitea
Environment=USER=git HOME=/home/git GITEA_WORK_DIR=/var/lib/gitea
ExecStart=/usr/local/bin/gitea web --config /etc/gitea/app.ini
Restart=always
RestartSec=2s
LimitNOFILE=65535
[Install]
WantedBy=multi-user.target
加载服务并启动:
sudo systemctl daemon-reload
sudo systemctl enable --now gitea
sudo systemctl status gitea --no-pager
状态显示 active (running) 表示进程已启动。再检查服务日志和本机 HTTP 响应:
sudo journalctl -u gitea -n 50 --no-pager
curl -I http://127.0.0.1:3000
curl 返回 200、302 或 303 等 HTTP 响应通常表示网页服务已接通;具体状态可能随版本和页面路径不同而变化。若没有响应,先查服务日志,不要先开放 3000 端口。

创建管理员并启用 HTTPS
在自己的管理电脑上通过 SSH 隧道打开 Gitea 页面。将 SERVER_ADMIN 替换为实际的服务器管理用户名:
ssh -L 3000:127.0.0.1:3000 SERVER_ADMIN@服务器公网IP
保持该 SSH 会话运行,然后在本地浏览器访问 http://127.0.0.1:3000。按照页面提示创建第一个管理员账户,并确认页面中的数据库与域名设置和 /etc/gitea/app.ini 一致。隧道访问失败时,先检查服务器 SSH 是否可用,以及本机 3000 端口是否已被其他程序占用。
管理员创建完成后,关闭注册入口:
sudo nano /etc/gitea/app.ini
将配置改为:
[service]
DISABLE_REGISTRATION = true
REQUIRE_SIGNIN_VIEW = true
保存后重启并验证:
sudo systemctl restart gitea
sudo systemctl is-active gitea
应返回 active。接下来安装 Nginx 与证书工具:
sudo apt install -y nginx certbot python3-certbot-nginx
创建站点配置:
sudo nano /etc/nginx/sites-available/gitea
写入 HTTP 反向代理配置:
server {
listen 80;
server_name git.example.com;
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;
}
}
启用站点并检查配置:
sudo ln -s /etc/nginx/sites-available/gitea /etc/nginx/sites-enabled/gitea
sudo nginx -t
sudo systemctl reload nginx
nginx -t 应显示配置语法检查成功。确认域名已指向本机、外部能通过 80 端口访问后,申请并配置 HTTPS 证书:
sudo certbot --nginx -d git.example.com
按提示完成邮箱与证书申请。随后用浏览器访问 https://git.example.com,检查登录页是否正常、浏览器是否能验证证书。Gitea 配置里的 ROOT_URL 应保持为实际对外访问地址;若更换域名或协议,应同步修改并重启服务。
开放访问端口并验证仓库操作
外部访问通常需要 HTTPS 的 443/tcp 和 Git SSH 的 2222/tcp;证书申请阶段还需要 80/tcp。Gitea 网页端口 3000/tcp 不应直接对公网开放。确认已有管理 SSH 规则后,再按本机防火墙实际情况调整。例如使用 UFW 时:
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw allow 2222/tcp
sudo ufw status numbered
如果 UFW 尚未启用,启用前先确认管理 SSH 规则已放行,并检查云平台安全组中的对应规则。若仅允许特定办公网络访问,应将来源地址限制在可信范围,而不是照搬对所有来源开放的示例。
在 Gitea 网页端创建一个私有测试仓库,并在用户设置中添加客户端的 SSH 公钥。测试 SSH 认证时指定 Gitea 的端口:
ssh -T -p 2222 git@git.example.com
首次连接可能会询问是否信任服务器主机密钥;确认连接目标无误后再接受。认证成功后再测试仓库克隆:
git clone ssh://git@git.example.com:2222/用户名/测试仓库.git
仓库地址应替换为页面提供的实际路径。若提示权限不足,先检查添加的公钥是否与本机私钥对应、账号是否有该私有仓库的访问权限,以及 SSH 端口是否被服务器防火墙和云平台安全组放行。
常见失败与处理
- 服务启动后很快退出:运行
sudo journalctl -u gitea -n 100 --no-pager。如果提示无法读取配置,检查/etc/gitea/app.ini是否为root:git、权限是否为640;如果提示无法写入数据库或仓库目录,检查/var/lib/gitea的属主及可写权限。 - Nginx 返回 502:确认 Gitea 仍在运行,并执行
curl -I http://127.0.0.1:3000。本机请求失败时应先修复 Gitea;本机请求成功时检查 Nginx 的proxy_pass、站点配置和错误日志:sudo tail -n 50 /var/log/nginx/error.log。 - 域名能打开但页面生成的链接错误:核对
ROOT_URL是否为https://git.example.com/,检查 Nginx 是否传递X-Forwarded-Proto,修改后重启 Gitea。 - 网页可用但克隆失败:区分网页 HTTPS 与 Git SSH 两条链路。SSH 克隆使用
2222,不是网页端口3000,也不一定是服务器管理 SSH 端口22。检查 Gitea 的SSH_PORT、SSH_LISTEN_PORT、客户端公钥和防火墙规则是否一致。 - 证书申请失败:检查 DNS 是否解析到当前服务器,以及外部是否能够访问
80/tcp。如服务器前还有云平台防火墙,也要核对其规则;排除问题后再重试申请。
验收与回滚
正式交付前逐项确认:
systemctl is-active gitea返回active,服务器重启后服务仍会自动启动。https://git.example.com可正常访问,登录后能查看和创建仓库。- 匿名访问受登录要求限制,注册入口已关闭。
- 测试账号能够通过
2222端口完成 SSH 认证,并克隆有权限访问的私有仓库。 - 公网未开放
3000/tcp;云平台安全组与主机防火墙的放行范围符合团队访问要求。 - 已保存
/etc/gitea/app.ini、数据库和仓库目录的备份,并确认备份文件可读取。SQLite 备份前建议停止 Gitea,避免复制过程中数据库仍有写入。
备份示例:
sudo systemctl stop gitea
sudo tar -czf "/root/gitea-backup-$(date +%F-%H%M%S).tar.gz" \
/etc/gitea /var/lib/gitea
sudo systemctl start gitea
sudo systemctl is-active gitea
该备份包含密钥、数据库与仓库,应限制访问并存放在服务器之外。若备份失败,先不要移除原数据目录;修复备份问题后再恢复服务。
首次部署出现问题且尚无需要保留的数据时,可先停止服务并保留现场,再处理配置或重新部署:
sudo systemctl disable --now gitea
sudo mv /var/lib/gitea "/var/lib/gitea.rollback-$(date +%F-%H%M%S)"
sudo mv /etc/gitea "/etc/gitea.rollback-$(date +%F-%H%M%S)"
这些操作会让 Gitea 无法使用原数据启动,但不会删除旧目录。若仓库已经投入使用,不要直接移动或覆盖数据目录;应先确认有完整备份,再按备份方案恢复。确认不再回滚后,才考虑清理保留的目录和调整此前新增的防火墙规则。
本文由A5数据原创发布,转载请注明出处:https://www.a5idc.com/helpcontent/9400.html



