2657 字
13 分钟
Gitea:自建 Git 代码托管与仓库备份
2026-11-15

先说问题:代码放在别人家,心里总有一块不踏实#

把代码全托管在公共平台上当然方便,但有几件事始终捏在别人手里:私有仓库的可见性规则说改就改,平台故障或账号异常时你连拉都拉不下来,内网项目、脚本仓库、配置仓库这类「不想出门」的东西根本没地方放。更现实的一点:给 GitHub 上的重要仓库做一份自己能掌控的镜像备份,是很多人在吃过一次亏之后才想起来的事。

Gitea 就是为这个场景准备的:一个用 Go 写的轻量 Git 托管服务,功能对标 GitHub 的核心部分——仓库、议题、拉取请求、组织与团队、软件包、Wiki 一应俱全,但资源占用只有 GitLab 的零头,一台小 VPS 就能流畅跑全家桶。自建 Gitea 的定位通常不是取代 GitHub,而是给私有代码安个家、给公开仓库留一份自己的备份。

本篇主线:

  1. Docker Compose 部署,先讲内置数据库、再讲外接数据库
  2. 初始化管理员,关掉公开注册
  3. 把 SSH 端口和域名配对,让克隆地址一次正确
  4. 组织与团队权限怎么分
  5. 从 GitHub 批量迁移与镜像同步
  6. 备份策略:官方 dump、数据卷与 Git 镜像三层

两种数据库方案,先选再装#

Gitea 支持 SQLite、PostgreSQL、MySQL 三种数据库。个人自建就两条路线:

方案适合人群代价
内置 SQLite个人使用、仓库不多、图省事数据库就是一个文件,备份最简单;并发写入能力弱
外接 PostgreSQL多人协作、仓库多、想长期经营多一个数据库容器要维护,性能和可靠性上限更高

判断标准很简单:只有你自己用,SQLite 足够;要拉家人或小团队进来,直接上 PostgreSQL,别等迁移的那天。两种方案的 Compose 只差数据库部分,下面先给 SQLite 版全量,外接版只列差异。

部署一:内置 SQLite 版#

Terminal window
mkdir -p ~/gitea && cd ~/gitea

docker-compose.yml:

services:
gitea:
image: gitea/gitea:latest
container_name: gitea
restart: unless-stopped
environment:
- USER_UID=1000
- USER_GID=1000
- GITEA__server__DOMAIN=git.example.com
- GITEA__server__ROOT_URL=https://git.example.com/
- GITEA__server__SSH_DOMAIN=git.example.com
- GITEA__server__SSH_PORT=2222
- GITEA__service__DISABLE_REGISTRATION=true
- GITEA__security__INSTALL_LOCK=true
- GITEA__security__SECRET_KEY=改成一长串随机字符串
volumes:
- ./data:/data
- /etc/timezone:/etc/timezone:ro
- /etc/localtime:/etc/localtime:ro
ports:
- "3000:3000"
- "2222:22"
Terminal window
docker compose up -d

说明几个容易埋雷的配置:

  • 容器内的 Git SSH 服务监听 22 端口,映射到宿主机的 2222;GITEA__server__SSH_PORT 必须写映射后的 2222,Gitea 生成克隆地址时用的就是这个值,写错会导致页面上复制的 SSH 克隆地址永远连不上。
  • INSTALL_LOCK=true 表示跳过网页安装向导、直接以配置为准;代价是没有网页初始化流程,管理员账号要靠命令行创建(下一节)。
  • SECRET_KEY 参与加密数据库里的敏感字段,上线后不要再更换,换了之后已存的令牌、两步验证等数据会解不开。它要和数据一起备份。
  • DISABLE_REGISTRATION=true 关掉公开注册,自建服务的基本动作,开放注册的 Gitea 很快会变成垃圾仓库集散地。

正式对外时 3000 端口同样只作调试,网页访问走 Nginx Proxy Manager 反代加 HTTPS;SSH 的 2222 端口需要直连暴露(或按安全篇的思路改到非标准端口并做限源)。

WARNING

Gitea 里躺着的是全部代码、部署密钥和访问令牌,是被扫描器盯得最紧的服务类型之一。上线第一件事就是确认公开注册已经关闭、管理员开了两步验证;历史上大量自建 Git 服务被入侵,都是从「忘了关注册」开始的。

部署二:外接 PostgreSQL 版#

在上面基础上加一个数据库服务,并给 Gitea 补数据库环境变量:

db:
image: docker.io/library/postgres:16-alpine
restart: unless-stopped
environment:
- POSTGRES_USER=gitea
- POSTGRES_PASSWORD=改成强密码
- POSTGRES_DB=gitea
volumes:
- ./db-data:/var/lib/postgresql/data

Gitea 服务里追加:

- GITEA__database__DB_TYPE=postgres
- GITEA__database__HOST=db:5432
- GITEA__database__NAME=gitea
- GITEA__database__USER=gitea
- GITEA__database__PASSWD=与上面一致的密码

并在 Gitea 服务下加 depends_on: [db]。已经用 SQLite 跑了一段想迁过去的,可以用 Gitea 的数据库转换工具,但更稳妥的做法是新实例装好后逐个仓库用镜像推过去,账号和权限重新建——个人量级这条路反而省事。

创建管理员与第一次登录#

INSTALL_LOCK 模式下执行:

Terminal window
docker exec -u git gitea gitea admin user create \
--admin \
--username admin \
--email admin@example.com \
--password '你的强密码'

注意必须带 -u git,用 root 身份执行会在数据目录里留下属主错误的文件,后续服务读写会出莫名其妙的问题。创建成功后打开站点,用这个账号登录,第一件事是去个人设置里打开两步验证,并到站点管理面板里再确认一遍注册确实关闭、默认仓库可见性符合预期(建议设为私有优先)。

SSH 克隆测试一把:

Terminal window
git clone ssh://git@git.example.com:2222/admin/test.git

先在网页上建个测试仓库、把本机 SSH 公钥加到个人设置里再克隆。地址里端口是 2222、用户是 git,对得上就说明 SSH 链路和前面配置都正确。

组织与团队:多人协作时的权限骨架#

单人使用可以跳过这一节,但只要有第二个人进来,就该用组织来管仓库,而不是把仓库堆在个人名下再逐个加协作者。

  • 组织(Organization):仓库的归属主体,类似 GitHub 上的 org,所有者、管理员、普通成员三档组织级角色。
  • 团队(Team):组织内的权限分组,每个团队单独设置能访问哪些仓库、以及对代码、议题、拉取请求、发布、Wiki、软件包这些单元的权限级别(无 / 读取 / 写入 / 管理员)。
场景推荐分法
家人共享脚本与配置一个组织,成员全部进「家庭」团队,写入权限
小团队项目按项目建团队,只给对应仓库的写入,其余只读
只读访客(如部署机拉代码)单独建机器人账号或只读团队,配合部署密钥使用

原则和本系列 安全加固篇 一致:权限按最小够用给,部署拉代码用只读的部署密钥,不要图省事到处用管理员账号的令牌。

从 GitHub 迁移仓库与镜像同步#

这是自建 Gitea 最大的实用价值之一。网页右上角「+」→「新建迁移」,选择 GitHub,填仓库地址和访问令牌,可以勾选要一并搬过来的内容:议题、标签、里程碑、拉取请求、发布、Wiki;仓库用了 Git LFS 的记得勾上 LFS 选项,否则大文件只会剩指针。

更关键的是「将此仓库设为镜像」:勾上之后 Gitea 会定时从 GitHub 拉取同步(拉取镜像),默认同步间隔可以在仓库设置里调。这样 GitHub 仍是主力,Gitea 是一份自动更新的完整备份,某天平台出问题或者账号出状况,你手里始终有一份能直接切换的副本。

批量迁移没有官方一键全账号搬运,仓库多的做法是拿 GitHub API 拉出仓库清单,写个小脚本循环调 Gitea 的迁移 API 建仓。几十个仓库的量级,脚本跑一晚上也就完了。

备份:三层都要有#

Gitea 的数据分三块:/data 里的仓库与附件、数据库里的账号议题等元数据、配置文件里的密钥。三层备份对应着做:

第一层:官方 dump。

Terminal window
docker exec -u git gitea gitea dump -c /data/gitea/conf/app.ini

在数据目录生成一个包含仓库、数据库和配置的 zip,是官方推荐的整体备份方式,恢复时解压回对应位置即可。

第二层:数据卷整目录备份。

停服或低峰期把 ./data(外接版再加 ./db-data)整目录打包,和本系列其他服务一起进 备份与迁移篇 的统一备份节奏。只备份仓库目录、不备份数据库是最常见的自欺欺人——仓库文件还在,但用户、权限、议题全没了,等于只剩一堆裸仓库要手工认领。

第三层:Git 镜像异地冗余。

Git 本身就是分布式的:对最重要的几个仓库,在另一台机器或另一个平台留一份镜像,git push --mirror 定期推一次。这层备份不依赖 Gitea 能否恢复,任何 Git 工具都能直接读,是最后的兜底。

常见问题与排障#

SSH 克隆提示 Permission denied 或连接超时。 按顺序查:公钥是否加到了当前登录账号而不是管理员账号;克隆地址里的端口是不是 2222;服务器防火墙有没有放行 2222;SSH_DOMAIN 与实际访问域名是否一致。

反向代理后页面样式错乱、链接跳回内网地址。 ROOT_URL 没配对的典型表现。改成最终对外访问的完整地址(含 https),重启容器。

推送大仓库被中断。 多半是反向代理的请求体大小限制:在 NPM 对应站点的 Advanced 里放开 client_max_body_size,或改走 SSH 推送绕开 HTTP 层限制。

网页迁移 GitHub 仓库失败。 令牌权限不够是最常见原因:迁移议题和拉取请求需要令牌能读对应仓库的这些内容;私有仓库要确认令牌覆盖该仓库。网络层面确认服务器能正常访问 GitHub,拉取大仓库超时可以在仓库设置的镜像同步里改重试。

管理员密码忘了。 宿主机执行 docker exec -u git gitea gitea admin user change-password --username admin --password '新密码' 即可重置,这也是自建服务的好处——最高权限始终在自己手里。

小结#

Gitea 的部署难度在自建服务里属于最低的一档,一个 Compose 文件、一个数据目录就全齐了;真正的价值在部署之外的三件事:SSH 与域名一次配对、GitHub 仓库开镜像同步、备份三层都做满。做到这三点,它既是私有代码的家,也是公开仓库的一份保险,平台风云再变,你的代码始终有一份握在自己手里。

同属本系列扩充篇的还有文档归档的 Paperless-ngx、本地 AI 界面 Open WebUI 与照片备份 Immich,可以按需取用。

Gitea:自建 Git 代码托管与仓库备份
https://www.anexns.cloudns.org/posts/selfhost-gitea/
作者
Anexns
发布于
2026-11-15
许可协议
CC BY-NC-SA 4.0