在香港服务器部署Gitea,如何配置HTTPS与仓库访问?

发布人:A5数据发布时间:2026-10-13 09:13阅读量:131

在香港服务器上部署 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 Web127.0.0.1:3000不对公网开放
HTTP 与证书验证Nginx,TCP 80使用 HTTP-01 验证时开放
HTTPS Web 与 GitNginx,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 返回 502Nginx 错误日志、本机 3000 请求、Gitea 状态后端未启动则查 Gitea 日志;后端正常则查代理地址
页面跳回 HTTP 或链接错误ROOT_URL、X-Forwarded-Proto修正后重启 Gitea,并重新检查跳转
HTTPS 推送返回 413Nginx 请求体限制、实际推送大小在容量允许范围内调整上限,不直接设为无限
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 公钥配置。升级前还应保留原二进制与服务配置。

五、处理常见异常,并建立日志与一致性备份 / 3. 停机制作一致性备份配图

下面的备份会短暂停止 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

相关推荐