在香港服务器部署Gitea,如何配置HTTPS与仓库访问?
在香港服务器上部署 Gitea,可以采用“Gitea 监听本机端口、Nginx 对外提供 HTTPS、系统 OpenSSH 处理 Git SSH 连接”的结构。关键是让 Gitea 的外部地址、反向代理请求头、证书域名和仓库克隆地址保持一致,同时把仓库数据、数据库与密钥纳入备份。

下面以 Ubuntu Server 24.04 LTS、x86_64 架构、单台服务器部署为例,使用 SQLite、systemd 和 Nginx,完成安装、HTTPS 配置、HTTPS/SSH 仓库访问及恢复检查。适用于小团队起步部署;若已有较高的并发写入需求,应先评估独立数据库和存储方案。命令中的域名、邮箱和版本号需要替换为实际值,示例结果仅用于判断状态,不代表实际执行记录。
A5数据提供中国香港物理服务器租用,覆盖入门建站、Xeon Gold及AMD EPYC等配置,并配备SSD或NVMe存储与不同内存规格,可承载Gitea代码仓库、数据库及持续集成等多任务运行。针对团队成员分布和仓库访问需求,香港产品提供CN2与国际带宽选择,为HTTPS网页访问及SSH代码交互提供相应的网络资源基础。
一、准备条件:确定域名、端口和数据边界
1. 明确服务结构
本文采用以下端口分工:
| 用途 | 监听位置 | 对外开放要求 |
|---|---|---|
| Gitea Web | 127.0.0.1:3000 | 不对公网开放 |
| HTTP 与证书验证 | Nginx,TCP 80 | 使用 HTTP-01 验证时开放 |
| HTTPS Web 与 Git | Nginx,TCP 443 | 向使用者开放 |
| Git SSH | 系统 OpenSSH,示例 TCP 22 | 按协作者来源地址开放 |
HTTPS 与 SSH 是两条独立的仓库访问通道。 HTTPS 经过 Nginx,使用账号及访问令牌认证;SSH 直接连接系统 OpenSSH,使用上传到 Gitea 的公钥认证。HTTPS 正常,并不能证明 SSH 克隆地址也配置正确。

开始前应具备:
- 一台可通过 SSH 管理的 Ubuntu 24.04 服务器,以及可用的控制台或救援入口。
- 一个域名,例如
git.example.com,其 A 记录指向服务器公网 IPv4。 - 如配置了 AAAA 记录,服务器 IPv6、监听和防火墙也必须可用;否则先移除无效记录。
- 已确认云平台安全组和系统防火墙的现有规则。
- 可保存异机备份的位置,而不是只在服务器本地保留副本。
香港服务器的地域本身不改变 Gitea 配置方式。实际使用体验取决于开发者所在地、线路、带宽及仓库大小,验收时应从团队常用网络测试克隆和推送,不能只检查服务器本机页面。
2. 检查基础环境并安装依赖
以下服务端命令在同一个 root Bash 会话中执行。已有业务的服务器应先检查 Nginx 配置与端口占用,不要直接替换其他站点。
uname -m
timedatectl status
ss -lntp
df -h
free -h
apt update
apt install -y git nginx certbot ca-certificates curl sqlite3
read -rp "Gitea 域名,例如 git.example.com: " DOMAIN
read -rp "证书联系邮箱: " CERT_EMAIL
预期架构为 x86_64,系统时间同步正常,磁盘有充足余量。这里的二进制安装步骤不适用于 ARM 架构。
防火墙调整可能切断管理连接。操作前记录现有规则并保留 SSH 会话;管理端口不一定是 22,必须以实际配置为准:
ufw status verbose
sshd -T | grep '^port '
如果 UFW 已启用,可在确认管理端口已放行后追加 Web 规则:
ufw allow 80/tcp
ufw allow 443/tcp
不要为本文额外开放 3000,也不要直接执行防火墙重置。若 UFW 原本未启用,先完成管理入口放行和控制台验证,再决定是否启用;云平台安全组仍需单独配置。
二、安装 Gitea,并用 systemd 守护进程
1. 创建独立运行用户并安装二进制
本例使用专用 git 用户。若服务器已有同名用户,先确认其用途,不要直接复用其他系统的服务账号。
adduser --system --group --home /home/git --shell /bin/bash git
install -d -o git -g git -m 0750 \
/var/lib/gitea \
/var/lib/gitea/data \
/var/lib/gitea/custom
install -d -o git -g git -m 0700 /home/git/.ssh
install -d -o root -g git -m 0750 /etc/gitea
从 Gitea 发布渠道核对所选版本的维护状态和升级说明,再输入明确版本号,不使用含义不固定的“latest”。
read -rp "准备安装的 Gitea 完整版本号: " GITEA_VERSION
GITEA_FILE="gitea-${GITEA_VERSION}-linux-amd64"
curl --fail --location \
"https://dl.gitea.com/gitea/${GITEA_VERSION}/${GITEA_FILE}" \
-o /tmp/gitea
curl --fail --location \
"https://dl.gitea.com/gitea/${GITEA_VERSION}/${GITEA_FILE}.sha256" \
-o /tmp/gitea.sha256
EXPECTED_HASH=$(awk '{print $1}' /tmp/gitea.sha256)
ACTUAL_HASH=$(sha256sum /tmp/gitea | awk '{print $1}')
if [[ "$EXPECTED_HASH" =~ ^[0-9a-fA-F]{64}$ ]] &&
[ "${EXPECTED_HASH,,}" = "$ACTUAL_HASH" ]; then
install -o root -g root -m 0755 /tmp/gitea /usr/local/bin/gitea
else
echo "校验失败,停止安装"
fi
/usr/local/bin/gitea --version
下载或校验失败时不要继续。摘要校验用于检查下载完整性,并不能替代发布来源核验;如使用签名验证,应按所选版本提供的说明执行。
2. 写入配置并初始化数据库
下面采用命令行初始化,避免把未完成安装的页面暴露到公网。配置包含密钥,不能放进代码仓库或公开日志。
本步骤面向新部署。若 /etc/gitea/app.ini 已存在,应先备份并比较差异,不要覆盖既有配置。
SECRET_KEY=$(/usr/local/bin/gitea generate secret SECRET_KEY)
INTERNAL_TOKEN=$(/usr/local/bin/gitea generate secret INTERNAL_TOKEN)
cat > /etc/gitea/app.ini <<EOF
APP_NAME = Team Git
RUN_USER = git
RUN_MODE = prod
[server]
PROTOCOL = http
HTTP_ADDR = 127.0.0.1
HTTP_PORT = 3000
DOMAIN = ${DOMAIN}
ROOT_URL = https://${DOMAIN}/
APP_DATA_PATH = /var/lib/gitea/data
DISABLE_SSH = false
SSH_DOMAIN = ${DOMAIN}
SSH_PORT = 22
START_SSH_SERVER = false
SSH_ROOT_PATH = /home/git/.ssh
SSH_CREATE_AUTHORIZED_KEYS_FILE = true
LFS_START_SERVER = false
[database]
DB_TYPE = sqlite3
PATH = /var/lib/gitea/data/gitea.db
[repository]
ROOT = /var/lib/gitea/data/gitea-repositories
[security]
INSTALL_LOCK = true
SECRET_KEY = ${SECRET_KEY}
INTERNAL_TOKEN = ${INTERNAL_TOKEN}
[service]
DISABLE_REGISTRATION = true
REQUIRE_SIGNIN_VIEW = true
DEFAULT_KEEP_EMAIL_PRIVATE = true
[session]
PROVIDER = file
[log]
MODE = console
LEVEL = Info
EOF
chown root:git /etc/gitea/app.ini
chmod 0640 /etc/gitea/app.ini
unset SECRET_KEY INTERNAL_TOKEN
runuser -u git -- env GITEA_WORK_DIR=/var/lib/gitea \
/usr/local/bin/gitea migrate --config /etc/gitea/app.ini
ROOT_URL 决定页面链接、跳转及 HTTPS 克隆地址,因此必须填写最终访问地址。不能因为后端使用 HTTP,就把它写成 http://127.0.0.1:3000/。
这里明确关闭了 Git LFS 服务。如果团队需要 LFS,应单独启用、配置相应密钥,并重新核算上传限制、对象存储与备份容量。
接着创建首个管理员:
read -rp "管理员邮箱: " ADMIN_EMAIL
read -rsp "管理员初始密码: " ADMIN_PASSWORD
echo
runuser -u git -- env GITEA_WORK_DIR=/var/lib/gitea \
/usr/local/bin/gitea admin user create \
--config /etc/gitea/app.ini \
--username siteadmin \
--password "$ADMIN_PASSWORD" \
--email "$ADMIN_EMAIL" \
--admin \
--must-change-password
unset ADMIN_PASSWORD
密码通过变量输入可避免直接写入 shell 历史,但执行瞬间仍可能出现在进程参数中,应在可信管理环境操作。首次登录后更换密码,并为管理员启用双因素认证。
3. 创建 systemd 服务并验证
cat > /etc/systemd/system/gitea.service <<'EOF'
[Unit]
Description=Gitea
After=network.target
[Service]
Type=simple
User=git
Group=git
WorkingDirectory=/var/lib/gitea
Environment=USER=git
Environment=HOME=/home/git
Environment=GITEA_WORK_DIR=/var/lib/gitea
ExecStart=/usr/local/bin/gitea web --config /etc/gitea/app.ini
Restart=on-failure
RestartSec=5s
UMask=0027
NoNewPrivileges=true
PrivateTmp=true
ProtectSystem=full
[Install]
WantedBy=multi-user.target
EOF
systemctl daemon-reload
systemctl enable --now gitea
systemctl status gitea --no-pager
curl -I http://127.0.0.1:3000/
ss -lntp | grep ':3000'
预期服务为 active (running),本机 HTTP 请求返回正常页面或登录跳转,3000 端口只监听 127.0.0.1。若未启动,先检查:
journalctl -u gitea -n 100 --no-pager
不要用扩大目录权限的方式掩盖错误。配置文件由 root 管理、git 用户只读;数据库和仓库目录则必须允许 git 用户写入。
三、配置 Nginx、HTTPS 证书与自动续期
1. 先建立证书验证入口
使用 HTTP-01 验证时,域名必须正确解析,公网 TCP 80 必须可访问。以下配置只开放证书验证路径,不提供 Gitea 安装页面。
install -d -o root -g root -m 0755 \
/var/www/acme/.well-known/acme-challenge
cat > /etc/nginx/sites-available/gitea <<EOF
server {
listen 80;
server_name ${DOMAIN};
location ^~ /.well-known/acme-challenge/ {
root /var/www/acme;
default_type text/plain;
}
location / {
return 404;
}
}
EOF
ln -s /etc/nginx/sites-available/gitea \
/etc/nginx/sites-enabled/gitea
nginx -t && systemctl reload nginx
如站点文件或软链接已存在,先备份,不要强制覆盖。Nginx 输出 test is successful 后才能重载;同一域名也不应出现在多个冲突的 server 块中。
申请证书:
certbot certonly --webroot \
-w /var/www/acme \
-d "$DOMAIN" \
--email "$CERT_EMAIL" \
--agree-tos \
--no-eff-email
成功后用 certbot certificates 核对证书名称和路径。下方使用常见路径 /etc/letsencrypt/live/域名/;若实际证书名称带有后缀,应按显示结果修改。
2. 切换到 HTTPS 反向代理
这是覆盖站点配置的操作,先保存刚才的 HTTP 配置,失败时可恢复。
cp -a /etc/nginx/sites-available/gitea \
/etc/nginx/sites-available/gitea.before-https
cat > /etc/nginx/sites-available/gitea <<EOF
server {
listen 80;
server_name ${DOMAIN};
location ^~ /.well-known/acme-challenge/ {
root /var/www/acme;
default_type text/plain;
}
location / {
return 301 https://${DOMAIN}\$request_uri;
}
}
server {
listen 443 ssl;
server_name ${DOMAIN};
ssl_certificate /etc/letsencrypt/live/${DOMAIN}/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/${DOMAIN}/privkey.pem;
ssl_protocols TLSv1.2 TLSv1.3;
client_max_body_size 100m;
access_log /var/log/nginx/gitea.access.log;
error_log /var/log/nginx/gitea.error.log;
location / {
proxy_pass http://127.0.0.1:3000;
proxy_http_version 1.1;
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_read_timeout 300s;
proxy_send_timeout 300s;
}
}
EOF
nginx -t && systemctl reload nginx
这里的 100m 是示例请求体上限,不是仓库总容量。较大的 HTTPS 推送可能受该值限制,但盲目取消限制也会增加资源占用风险。应结合实际推送体积、Gitea 附件限制及可用磁盘设置。
如果后续启用依赖 WebSocket 的功能,还需要按该功能要求传递升级请求头;本文配置先覆盖普通 Web 页面和 Git HTTPS 访问。
3. 验证证书与续期
从服务器外部执行:
curl -I "http://git.example.com/"
curl -I "https://git.example.com/"
HTTP 应跳转至 HTTPS;HTTPS 应通过证书验证并返回页面或登录跳转。不要使用 curl -k 作为验收依据,因为它会跳过证书校验。
为续期后加载新证书创建部署钩子:
install -d -m 0755 /etc/letsencrypt/renewal-hooks/deploy
cat > /etc/letsencrypt/renewal-hooks/deploy/reload-nginx.sh <<'EOF'
#!/bin/sh
/usr/sbin/nginx -t && /usr/bin/systemctl reload nginx
EOF
chmod 0755 /etc/letsencrypt/renewal-hooks/deploy/reload-nginx.sh
systemctl list-timers --all | grep certbot
certbot renew --dry-run
应看到 Certbot 定时任务,并且续期演练成功。部署钩子还应单独执行一次验证;若采用其他 Certbot 安装方式,则需确认对应的调度机制,不能只凭首次签发成功就认为续期可用。
四、配置仓库访问,并分别验证 HTTPS 与 SSH
1. 使用 HTTPS 克隆和推送
登录管理账号后,通过后台创建普通成员账号,再创建一个用于测试的私有仓库,例如 team/demo。为成员分配写入权限,而不是让日常开发都使用管理员。
客户端建议使用访问令牌,令牌只授予需要的仓库权限,不要把令牌放进克隆 URL、脚本输出或远程地址。
以下命令在开发者电脑执行:
git clone https://git.example.com/team/demo.git
cd demo
git config user.name "Deployment Check"
git config user.email "check@example.com"
printf 'Gitea access check\n' > access-check.txt
git add access-check.txt
git commit -m "Verify repository access"
git push
认证提示中输入 Gitea 用户名,并将具有相应写入权限的访问令牌作为密码。建议通过系统凭据管理器保存,不使用明文存储方式。
验证结果应包括:能够克隆、提交成功推送、网页中出现对应提交。测试完成后可撤销临时令牌,避免长期保留过大的权限。
2. 使用 SSH 密钥访问
客户端生成专用密钥;如果文件已存在,不要覆盖原密钥:
ssh-keygen -t ed25519 \
-f ~/.ssh/id_ed25519_gitea \
-C "gitea-access"
只把 .pub 公钥内容添加到 Gitea 的用户设置中,私钥留在客户端。可配置客户端别名:
Host gitea-hk
HostName git.example.com
User git
Port 22
IdentityFile ~/.ssh/id_ed25519_gitea
IdentitiesOnly yes
首次连接前,通过服务器控制台等可信渠道核对 SSH 主机指纹:
ssh-keygen -lf /etc/ssh/ssh_host_ed25519_key.pub
客户端验证:
ssh -T gitea-hk
git ls-remote git@gitea-hk:team/demo.git
Gitea 通常会提示认证成功、但不提供交互式 shell。ssh -T 可能以非零状态退出,应结合消息判断;仓库访问还要通过 git ls-remote 或实际克隆验证。
服务器上可核对:
namei -l /home/git/.ssh/authorized_keys
sshd -T | grep -E '^(pubkeyauthentication|authorizedkeysfile|allowusers|allowgroups)'
私钥认证失败时,不要直接手工重写 Gitea 管理的 authorized_keys。先确认 .ssh 目录、文件权限、系统 SSH 用户限制及公钥是否正确上传。
如果系统 OpenSSH 实际使用 2222,则客户端端口、云安全组和 Gitea 的 SSH_PORT 都应改为 2222。这里仍使用系统 OpenSSH,因此不启用 Gitea 内置 SSH 服务,也不需要配置它的监听端口。

五、处理常见异常,并建立日志与一致性备份
1. 按低风险顺序检查失败
| 现象 | 检查顺序 | 对应处理 |
|---|---|---|
| 域名无法访问 | DNS、A/AAAA、云安全组、系统防火墙、Nginx 监听 | 修正解析或放行必要端口,不开放 3000 |
| 证书申请失败 | 外部能否访问验证路径、80 端口、AAAA 是否有效 | 修正网络条件后重试;不能开放 80 时改用适合的 DNS 验证 |
| HTTPS 返回 502 | Nginx 错误日志、本机 3000 请求、Gitea 状态 | 后端未启动则查 Gitea 日志;后端正常则查代理地址 |
| 页面跳回 HTTP 或链接错误 | ROOT_URL、X-Forwarded-Proto | 修正后重启 Gitea,并重新检查跳转 |
| HTTPS 推送返回 413 | Nginx 请求体限制、实际推送大小 | 在容量允许范围内调整上限,不直接设为无限 |
| SSH 提示公钥拒绝 | 主机及端口、客户端所选密钥、账号限制、文件权限 | 逐项修正;TLS 证书与 SSH 公钥认证无关 |
| 能读取但无法推送 | 仓库角色、令牌权限、分支保护 | 调整授权或按合并流程操作,不关闭全部保护 |
常用只读检查命令:
journalctl -u gitea --since "30 minutes ago" --no-pager
tail -n 100 /var/log/nginx/gitea.error.log
journalctl -u ssh --since "30 minutes ago" --no-pager
systemctl show gitea -p NRestarts -p MemoryCurrent
df -h /var/lib/gitea
df -i /var/lib/gitea
本配置将 Gitea 日志写入 journald,Nginx 日志单独写入文件。应确认 journald 的保留策略及持久化状态,并检查系统 logrotate 是否覆盖这两个 Nginx 日志。访问日志可能包含私有仓库路径,不宜无限保留或公开上传。
2. 不只按“能启动”判断资源是否够用
小团队可将 2 vCPU、2~4 GiB 内存作为起步评估参考,但这不是容量承诺。仓库数量、并发克隆、代码搜索、Git 垃圾回收和后台任务都会影响峰值。
磁盘需要同时容纳 Git 对象、数据库、附件、临时文件和本地备份,还应留出维护余量。带宽则要关注多个成员同时克隆时的持续吞吐,而非只看端口标称速率。
SQLite 适合单机、较低并发写入的起步环境。若持续出现锁等待、写入延迟,或需要高可用,应评估迁移到 PostgreSQL 等外部数据库;升级 CPU 不能解决所有数据库竞争问题。
3. 停机制作一致性备份
Gitea 的有效备份不只是仓库目录。 至少需要数据库、仓库与应用数据、app.ini 中的密钥,以及 SSH 公钥配置。升级前还应保留原二进制与服务配置。

下面的备份会短暂停止 Web 和 HTTPS 推送,安排在维护窗口执行。系统 SSH 服务不会停止,因此还需要确认没有正在进行的 Git SSH 写入;严格的维护窗口应在边界侧暂时阻止新的 Git SSH 连接,并等待现有传输结束。
install -d -o root -g root -m 0700 /srv/gitea-backup
STAMP=$(date +%Y%m%d-%H%M%S)
BACKUP="/srv/gitea-backup/gitea-${STAMP}.tar.gz"
systemctl stop gitea
if tar -czf "$BACKUP" -C / \
etc/gitea \
var/lib/gitea \
home/git \
usr/local/bin/gitea \
etc/systemd/system/gitea.service \
etc/nginx/sites-available/gitea; then
chmod 0600 "$BACKUP"
systemctl start gitea
sha256sum "$BACKUP" > "${BACKUP}.sha256"
tar -tzf "$BACKUP" | head -n 20
else
systemctl start gitea
echo "备份失败,不能将此文件作为恢复依据"
fi
这份备份包含私钥或应用密钥,应加密后传到异机,并设置访问权限和保留周期。TLS 证书及续期配置另行备份;若 Nginx 承载其他站点,不要在恢复时整体覆盖其证书目录。
SQLite 在线直接复制主数据库文件可能遗漏尚未合并的事务状态,因此这里选择停机备份。改用外部数据库后,还必须加入该数据库的一致性导出。真正的备份验收是隔离环境恢复成功,而不是压缩包能够列出文件。
六、上线验收与回滚检查项
1. 上线验收
- Gitea 仅监听
127.0.0.1:3000,公网无法直接访问后端端口。 - HTTP 跳转到 HTTPS,证书域名正确,客户端无需跳过证书校验。
- Certbot 续期演练成功,续期后可以重载 Nginx。
- 仓库页面生成的 HTTPS 地址、SSH 域名和端口均正确。
- 普通成员分别完成 HTTPS、SSH 的读取测试,并至少完成一次实际推送。
- 私有仓库对未授权用户不可读,分支保护符合团队规则。
- systemd 能自动启动服务;日志能查询,磁盘与内存有监控。
- 从团队常用网络完成访问测试,并记录大型克隆和推送的表现。
- 已有异机备份,且完成隔离恢复演练。
2. 配置与版本回滚
如果只是 Nginx 配置变更失败,恢复保存的站点文件,执行 nginx -t,通过后再重载。若调整防火墙造成访问中断,应通过保留的管理会话或控制台恢复原规则,而不是继续叠加规则。
如果 Gitea 升级已修改数据库结构,不能只把二进制换回旧版本。应恢复升级前同一时间点的数据库、数据目录、配置和二进制,否则可能出现版本与数据不兼容。
回滚前先核对:
- 明确回滚点,告知成员该时间点之后的新提交、议题和附件可能需要另行补回。
- 停止服务并阻止新的 Git 写入,保存当前故障状态,避免丢失后续排查依据。
- 用
tar -tzf检查目标归档,在隔离目录试解压,确认文件完整。 - 将现有相关目录移到保留位置后,再恢复匹配的一组文件,避免旧文件与新数据混合。
- 恢复正确的属主和权限,执行
systemctl daemon-reload、nginx -t,再启动服务。 - 重新核验 HTTPS 登录、SSH 认证、仓库读取、推送与最新保留提交。
完成这些检查后,才算同时打通了香港服务器上的 HTTPS 服务入口和仓库访问链路,并具备可维护、可恢复的运行基础。
本文由A5数据原创发布,转载请注明出处:https://www.a5idc.com/helpcontent/3416.html



