先说问题:代码放在别人家,心里总有一块不踏实
把代码全托管在公共平台上当然方便,但有几件事始终捏在别人手里:私有仓库的可见性规则说改就改,平台故障或账号异常时你连拉都拉不下来,内网项目、脚本仓库、配置仓库这类「不想出门」的东西根本没地方放。更现实的一点:给 GitHub 上的重要仓库做一份自己能掌控的镜像备份,是很多人在吃过一次亏之后才想起来的事。
Gitea 就是为这个场景准备的:一个用 Go 写的轻量 Git 托管服务,功能对标 GitHub 的核心部分——仓库、议题、拉取请求、组织与团队、软件包、Wiki 一应俱全,但资源占用只有 GitLab 的零头,一台小 VPS 就能流畅跑全家桶。自建 Gitea 的定位通常不是取代 GitHub,而是给私有代码安个家、给公开仓库留一份自己的备份。
本篇主线:
- Docker Compose 部署,先讲内置数据库、再讲外接数据库
- 初始化管理员,关掉公开注册
- 把 SSH 端口和域名配对,让克隆地址一次正确
- 组织与团队权限怎么分
- 从 GitHub 批量迁移与镜像同步
- 备份策略:官方 dump、数据卷与 Git 镜像三层
两种数据库方案,先选再装
Gitea 支持 SQLite、PostgreSQL、MySQL 三种数据库。个人自建就两条路线:
| 方案 | 适合人群 | 代价 |
|---|---|---|
| 内置 SQLite | 个人使用、仓库不多、图省事 | 数据库就是一个文件,备份最简单;并发写入能力弱 |
| 外接 PostgreSQL | 多人协作、仓库多、想长期经营 | 多一个数据库容器要维护,性能和可靠性上限更高 |
判断标准很简单:只有你自己用,SQLite 足够;要拉家人或小团队进来,直接上 PostgreSQL,别等迁移的那天。两种方案的 Compose 只差数据库部分,下面先给 SQLite 版全量,外接版只列差异。
部署一:内置 SQLite 版
mkdir -p ~/gitea && cd ~/giteadocker-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"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 端口需要直连暴露(或按安全篇的思路改到非标准端口并做限源)。
WARNINGGitea 里躺着的是全部代码、部署密钥和访问令牌,是被扫描器盯得最紧的服务类型之一。上线第一件事就是确认公开注册已经关闭、管理员开了两步验证;历史上大量自建 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/dataGitea 服务里追加:
- 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 模式下执行:
docker exec -u git gitea gitea admin user create \ --admin \ --username admin \ --email admin@example.com \ --password '你的强密码'注意必须带 -u git,用 root 身份执行会在数据目录里留下属主错误的文件,后续服务读写会出莫名其妙的问题。创建成功后打开站点,用这个账号登录,第一件事是去个人设置里打开两步验证,并到站点管理面板里再确认一遍注册确实关闭、默认仓库可见性符合预期(建议设为私有优先)。
SSH 克隆测试一把:
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。
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,可以按需取用。