NAS 自建 Git 服务：Gitea 部署与备份

为什么选 Gitea

自建 Git 服务的主要选项对比：

对家用 NAS，Gitea 是明显合适的选择。 GitLab 那套完整 DevOps 平台需要 4GB 以上内存和多容器协作，在 2C2G 或 4C8G 的家用机器上跑不动，也没必要。

Gitea 提供的功能对个人和小团队来说已经足够：仓库管理、分支保护、Pull Request、Issue、Wiki、Actions（兼容 GitHub Actions 语法的 CI）、包管理（npm/maven/docker）、Webhook、SSH 和 HTTP 两种协议。

部署

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/
    volumes:
      - ./data:/data
      - /etc/timezone:/etc/timezone:ro
      - /etc/localtime:/etc/localtime:ro
    ports:
      - 3000:3000
      - 2222:22

SSH 端口冲突：必须处理的第一个问题

这是自建 Git 服务在 NAS 上最容易卡住的地方。

Git 支持 HTTP 和 SSH 两种协议。HTTP 走 3000 端口没冲突，但 SSH 默认用 22，而 NAS 自己的 SSH 服务已经占用了 22。

解决方式是把容器的 22 映射到宿主机的其他端口（上面示例用了 2222）。这样 clone 地址变成：

git clone ssh://git@192.168.1.10:2222/username/repo.git

注意 URL 格式变了。 默认 SSH 的 git@host:user/repo 这种简写形式默认连 22 端口，用非标准端口必须写成完整的 ssh:// 形式。

如果嫌麻烦，可以只用 HTTP(S)。 Gitea 的 HTTP 协议完全可用，配合个人访问令牌（Token）也能认证。对局域网或反代后的 HTTPS 访问，HTTP 方案更简单。

数据库选择

Gitea 支持 SQLite、MySQL/MariaDB、PostgreSQL：

个人用途直接用 SQLite。 它随 Gitea 一起安装在 /data 目录里，不用额外维护数据库容器。只有当你有几十个仓库、多人频繁访问时，才需要考虑换 PostgreSQL。

首次配置

容器启动后访问 3000 端口，会进入安装向导。几个要注意的选项：

• 站点名称和管理员账号：向导里创建的第一个账号自动成为管理员
• 服务器域名和 Root URL：填实际访问地址。如果填错，Web 界面里的 clone 地址会是错的
• 禁止自助注册：默认设置下任何人都能注册账号。如果是自用，务必在站点设置里关闭注册（DISABLE_REGISTRATION），或在安装后到管理后台关掉

备份：两种层次

正规备份方式 是 Gitea 自带的 dump 命令，它会生成一个包含数据库、仓库、附件、配置的完整归档：

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

生成的文件在容器内的 /data/gitea-dump-*.zip，拷出来存到别处。

简单方式 是备份整个 /data 目录。它包含：

• gitea/repositories/ — 所有 Git 仓库（裸仓库）
• gitea/gitea.db — SQLite 数据库（用户、Issue、PR、权限）
• gitea/conf/app.ini — 配置文件
• gitea/attachments/、gitea/avatars/ — 附件与头像

恢复时版本要匹配。 Gitea 跨大版本升级时数据库结构会变，用旧版本备份恢复到新版本实例上通常需要执行迁移。建议备份时记录一下 Gitea 的版本号。

备份频率：代码仓库是最高价值的数据之一，且改动频繁。建议每天一次，并保留多份历史版本（至少 7 天）。

异地备份：仓库数据体积小（除非有大量二进制或 LFS 文件），很适合用 rclone 同步到云端，成本极低。

进阶功能

Gitea Actions：兼容 GitHub Actions 语法的 CI 系统。需要额外部署 act_runner（一个独立的 runner 程序并注册到实例）。对个人项目来说，用它做自动构建、测试、部署是够用的。

镜像仓库（Package Registry）：支持 npm、Maven、Docker、PyPI 等包格式。可以在家里搭一个私有 npm 源，这对前端开发很实用。

仓库镜像：可以配置 Gitea 自动从 GitHub 镜像仓库（定时拉取），相当于给重要的开源项目做一份本地快照。

LFS（大文件存储）：如果仓库里有大文件，需要启用 LFS。注意 LFS 文件会显著增加存储占用和备份体积。

资源占用实测预期

对 NAS 来说这点开销几乎可以忽略。 即便是 2GB 内存的入门机型，与系统和其他服务并存也没问题。

存储的 IO 特征：Git 操作产生大量小文件读写，这是机械盘最不擅长的负载类型。如果仓库多且操作频繁，把 Gitea 的 data 目录放在 SSD 上会有明显改善。

一个务实的判断

自建 Git 服务适合这些情况：

• 有不便托管到公共平台的代码（公司内部、客户项目）
• 想给所有仓库做本地统一备份
• 需要私有包管理源
• 纯粹想折腾、想把数据握在自己手里

如果只是个人开源项目，GitHub / Gitee 更省心——不用维护、不用备份、协作方便、还自带 Pages 和 CI 额度。自建服务的持续维护成本（升级、备份、故障排查）是真实存在的，只有在确实有理由时才值得承担。