跳到主要内容
版本：26.4.1

高可用部署（High Availability Deployment）

本指南介绍如何在高可用（HA）拓扑中部署 Gitea Enterprise。HA 通过在负载均衡器后运行多个应用实例，并将状态卸载到共享服务，使代码托管在某个节点发生故障时依然保持在线。

1. 前置要求​

  • 至少 两个应用节点（Linux 虚拟机、裸机或 Kubernetes 工作负载），并能够访问下面所列的共享服务。
  • 一个外部数据库集群（MySQL/MariaDB 或 PostgreSQL），自带复制或托管高可用能力。
  • 一个 Redis/Redis 集群部署，用于缓存、会话、任务队列和 globalLock。
  • 如果启用了代码搜索，需要一个 Elastic Search 部署。
  • 共享的非 Git 仓库存储：可以是 S3 兼容的存储桶，也可以是在每个节点上挂载于同一路径的 POSIX 卷（NFS/Gluster/NetApp）。
  • 共享的 Git 仓库存储：在每个节点上挂载于同一路径的 POSIX 卷（NFS/Gluster/NetApp）。
  • 一个负载均衡器，能够转发 HTTP/HTTPS（3000/443 端口）和 SSH（22/222 端口）流量并进行健康检查。

关于每个节点的准备工作，请参阅在 Linux 上安装、使用 Docker 安装或在 Kubernetes 上安装。下面的 HA 专属步骤建立在这些指南的基础之上。

2. 引导第一个应用节点​

  1. 按照您选择的单节点指南，安装 Enterprise 二进制文件或容器。
  2. 在配置过程中，将 APP_DATA_PATH 设置为共享存储挂载点（/data）。
  3. 更新 /data/gitea/conf/app.ini（或对应的环境变量），使用适合 HA 的配置：
APP_NAME = Gitea Enterprise
RUN_MODE = prod

[server]
DOMAIN               = git.example.com
ROOT_URL             = https://git.example.com/
PROTOCOL             = http
HTTP_PORT            = 3000
SSH_DOMAIN           = git.example.com
SSH_PORT             = 222
LANDING_PAGE         = explore
LFS_START_SERVER     = true
LFS_JWT_SECRET       = <shared secret>

[database]
DB_TYPE  = mysql
HOST     = db.internal:3306
NAME     = gitea
USER     = gitea
PASSWD   = <password>

[session]
PROVIDER         = redis
PROVIDER_CONFIG  = redis://:<password>@redis.internal:6379/0?pool_size=100&idle_timeout=120s

[cache]
ADAPTER = redis
HOST    = redis://:<password>@redis.internal:6379/1

[queue]
TYPE          = redis
CONN_STR      = redis://:<password>@redis.internal:6379/2

[storage]
STORAGE_TYPE = minio ; 一旦添加了该存储，其他位置的路径配置（如 attachment、
; lfs）应当移除。如果是迁移场景，请使用 gitea migrate-storage 将原有文件迁移到新的位置
MINIO_BUCKET = gitea-ee-data
MINIO_ENDPOINT = s3.internal:9000
MINIO_ACCESS_KEY_ID = <access>
MINIO_SECRET_ACCESS_KEY = <secret>

[indexer]
ISSUE_INDEXER_TYPE = db, elasticsearch or melllisearch ; HA 模式下 bleve 无法使用
ISSUE_INDEXER_CONN_STR = http://elastic:changeme@localhost:9200

REPO_INDEXER_ENABLED = true
REPO_INDEXER_TYPE = elasticsearch
REPO_INDEXER_CONN_STR = http://elastic:changeme@localhost:9200

[log]
; 请确保日志路径不会被不同的实例共享

[global_lock]
SERVICE_TYPE = redis
SERVICE_CONN_STR = redis://:<password>@redis.internal:6379/5

3. 添加额外节点​

对每个新增节点重复安装过程：

  1. 复用相同的 Enterprise 版本和配置文件。如果您使用模板生成 app.ini，建议使用 Ansible、Helm 或 Terraform，以避免配置漂移。
  2. 以读写方式挂载共享的 /data 卷。使用对象存储时，只需要将 /data/gitea/conf 保留在共享磁盘上，仓库数据则存放在存储桶中。
  3. 仔细检查文件权限（git:git），并确认该节点能够访问数据库、Redis 和存储端点。
  4. 启动服务，并验证 GET /api/healthz 返回 200 OK。

4. 配置负载均衡器​

  • 将所有健康的节点加入 HTTP/HTTPS 池。如果 TLS 在负载均衡器上终止，请转发 X-Forwarded-For、X-Forwarded-Proto 和 X-Forwarded-Host 请求头，以便 Gitea 生成正确的 URL。
  • 通过 TCP 转发 SSH 流量（可以是单独的 VIP，也可以在同一地址上使用 222 端口）。在 Kubernetes 中，可以使用 LoadBalancer service 或 NodePort 加外部负载均衡器来暴露 SSH。
  • 针对 /api/healthz 或 /api/v1/version 配置健康探测。如果检查连续失败三次，将节点标记为不健康，以避免向已降级的实例发送用户流量。
  • 启用连接排空（connection draining），使正在进行的 git push 能够在节点因维护而被移除之前完成。

5. 运维清单​

  • 备份：定期对数据库、Redis 和对象存储进行快照。请遵循上游的备份指南。
  • 升级：逐个节点滚动升级。先在负载均衡器上排空流量，停止服务，升级二进制文件或容器镜像标签，运行数据库迁移（仅第一个节点需要），然后重新加入负载均衡池。
  • 监控：使用 Prometheus 抓取 /metrics 端点，对队列深度、HTTP 错误率和复制延迟设置告警。
  • 灾难恢复：通过使用相同的配置和共享存储进行引导，测试恢复某个节点的流程。恢复后请验证许可证状态以及外发集成（SMTP、webhook）是否正常。

完成以上步骤后，您的 Gitea Enterprise 部署即可在单节点故障时保持可用，并随着组织的增长实现水平扩展。