Docker部署Gitea教程：轻量级私有代码托管平台搭建与维护

最近给团队内部搭了一套代码托管平台，用的就是 Docker 部署 Gitea。这事其实立项挺快，因为大家早就被 GitHub 私有仓库的成员数限制和 GitLab 的资源占用搞得有点烦。用 Docker 装 Gitea，一套下来顺手得就像装个普通 Web 应用，资源占用低、管理方便，后来陆陆续续帮几个朋友也部署过，踩过的坑基本都摸清了。这篇就把从环境准备到日常维护的完整过程拆开讲清楚，顺带把新手最容易卡住的几个问题一次说透。

Gitea 是一个开源的轻量级代码托管方案，GitHub、GitLab 能做的核心事情它基本都能做：代码仓库托管、Issue 跟踪、Pull Request、Webhook、CI/CD 对接，这些通通都有。Docker 又是现在部署服务最普遍的方式，把它俩结合，一台 1 核 2G 的机器就能带起一个小团队的日常开发。这篇文章适合谁看？想在公司内网搭私有代码仓库的运维/后端同学，想搞个人代码备份库的独立开发者，还有那些被 GitLab 内存占用逼疯、正在找替代方案的朋友。不管你是第一次碰 Docker 还是已经玩了很久，这篇都值得你花几分钟过一遍。

1. 为什么选 Gitea + Docker，而不是其他方案

1.1 相比于 GitLab 和 Gitee，Gitea 的差异在哪

先聊选型。市面上自建代码仓库无外乎 GitLab、Gitea、Gogs 这几个，再加上直接用 Gitee/GitHub 托管。我的结论很明确：中小型团队自建选 Gitea，要极致的轻量选 Gogs，公司合规性要求高或者需要重度 CI/CD 集成选 GitLab，至于 Gitee/GitHub，私有仓库不是不好用，而是仓库数量、成员数、大小限制多了以后非常难受，代码资产也不在自己手里。

Gitea 是用 Go 写的，单二进制文件就能跑，内存占用在 Docker 容器里通常在 200MB 到 500MB 之间。对比一下，GitLab 官方推荐的机器配置是 4 核 4G 起步，实际跑起来 8G 都不算宽裕。同样是自建，Gitea 的资源需求只有 GitLab 的十分之一。

功能上，我之前专门列过一张对比表：

所以如果你的团队规模在几十人以内，对 CI/CD 的需求可以接受外挂 Jenkins、Drone 这类工具，Gitea 几乎就是最优解。我就是看重这一点才最终敲定用它。

1.2 Docker 部署带来的实际收益

为什么偏要用 Docker 装，而不是直接下载二进制包跑？我也干过裸机部署。两种方式各有利弊，但 Docker 的优势在实际维护中很快体现出来。

先说隔离性。Gitea 需要 SQLite 或 MySQL/PostgreSQL 做存储，如果你直接装在宿主机上，就得自己维护一套数据库环境。装了 Redis 可能还会想给 Gitea 的缓存用，这些东西一旦在宿主机上铺开，以后每次系统升级、依赖冲突都够你喝一壶。用 Docker 以后，Gitea 和数据库各自跑在容器里，宿主机只需要装一个 Docker，其他东西一概不用管。哪天不想要了，docker compose down 然后删掉数据目录，系统恢复洁净，这点非常香。

再说可迁移性。Docker 容器可以把配置、数据卷直接打包迁到另一台机器，只要把 Gitea 数据目录和 docker-compose.yml 拷过去，新机器直接 docker compose up -d 就能恢复服务。我后来帮朋友把服务从一台腾讯云迁移到阿里云，整个流程半小时搞定，换作裸机安装，数据库导来导去，SSH 端口、systemd 脚本全部要重配，一小时打底。

还有版本升级。Gitea 大概一个月发一个小版本，Docker 部署升级就是两条命令：docker compose pull + docker compose up -d，容器自动重建。裸机升级得下载新二进制、备份旧文件、改 systemd 脚本，一不留神还会把数据目录搞乱。用久了你会觉得，Docker 这东西不是可选项，是必选项。

2. 环境准备：Docker 装好且能跑起来，后面才不踩坑

2.1 Linux 下安装 Docker，Ubuntu 和 CentOS 都给你过一遍

Gitea 部署在 Linux 服务器上是绝对主流。Ubuntu/Debian 系，我一般建议用官方脚本，命令是：

curl -fsSL https://get.docker.com | sh

装完以后启动服务并设置开机自启：

systemctl enable --now docker

CentOS 7 和 CentOS 8 有些旧版本的内核和 Docker 存在兼容问题，CentOS 7 尤其要注意。如果遇到 docker 服务启动失败，先检查内核版本是不是 3.10。很多教程直接让用官方脚本，但 CentOS 7 官方脚本装出来的 Docker 版本可能和系统旧内核不匹配，建议先更新内核或者用 docker-ce.repo 安装：

yum install -y yum-utils yum-config-manager --add-repo https://download.docker.com/linux/centos/docker-ce.repo yum install -y docker-ce docker-ce-cli containerd.io systemctl start docker systemctl enable docker

内核太旧的问题在 CentOS 7 上特别典型，装完 docker 以后运行 docker info 如果提示 kernel version 或者 iptables 相关的错误，多半就是内核版本导致的。如果公司服务器不允许随便升内核，我建议直接上 Docker 20.10 版本，配合 CentOS 7 的 3.10 内核勉强能跑，但稳定性打折扣，能升还是升。

2.2 Windows/Mac 上的 Docker Desktop 注意事项

本地开发调试用 Windows 或 Mac 的同学，一般会装 Docker Desktop。这个工具本身做得不错，但启动失败是最常见的问题，错误提示经常是：Docker Desktop failed to start because virtualisation support wasn't detected。

这问题说白了就是虚拟化没打开。Windows 上你需要：

• 开机进 BIOS 开启 Intel VT-x 或 AMD-V
• 启用 Windows 的 Hyper-V 和“适用于 Linux 的 Windows 子系统”功能
• 确保没有把 Hyper-V 和第三方虚拟机软件弄冲突

我自己实测过，VMware 和 Docker Desktop 一起用的时候，Hyper-V 冲突的概率非常高，两个都想要就得用 WSL2 模式跑 Docker。在 Docker Desktop 设置里勾选 Use the WSL 2 based engine，然后装一个 WSL2 内核更新包，这个方法在 Win10 和 Win11 上都稳定。

Mac 上问题少一些，主要是 Intel 芯片的老机器开启虚拟化后 Docker Desktop 会吃不少内存，建议在 Settings -> Resources 里把内存配额调到 4GB 以上，不然跑 Gitea + MySQL 容易卡。

2.3 装完 Docker 必做的三件小事

Docker 装好只是开始，有三件事我强烈建议你立刻做掉，不然后面大概率要返工。

第一件事，配置 Docker 镜像加速。原因很简单，默认拉取 Docker Hub 镜像的速度在国内环境下经常慢到让人怀疑人生，Gitea 的镜像倒不算大，但 MySQL 镜像、后续想装的 Runner 镜像都挺大的，不配加速就是给自己找罪受。各云厂商的控制台里一般都能找到专属加速地址，Docker 配置文件 /etc/docker/daemon.json 里加上 registry-mirrors 一项，重启 docker 服务即可。这一步对部署体验的提升非常明显，几乎是必做项。

第二件事，把当前用户加入 docker 组，从而避免每次执行 docker 命令都要 sudo：

sudo usermod -aG docker $USER newgrp docker

我自己遇到过很多次 permission denied while trying to connect to the docker api 这个报错，用户不在 docker 组里是最常见原因，加了组以后问题立刻消失，比去改 socket 权限省心得多。

第三件事，规划好端口占用。Gitea 默认要用 3000 端口做 HTTP，22 端口做 SSH。但服务器上 22 一般已经给系统 SSH 占用了，Gitea 的 SSH 端口肯定要改。我建议提前想好端口规划，比如 HTTP 用 3000，SSH 用 2222，避免装到一半发现冲突再做迁移。顺便说一句，docker 装 mysql 失败、装其他容器端口映射报错这些，八成都是端口占用和防火墙没放行的问题，跟 docker 本身关系不大。

3. Gitea 容器化安装全流程，从拉镜像到仓库可用

3.1 目录规划：数据、配置、日志分离是首要原则

在动手 docker run 之前，先想好目录布局。Gitea 的官方镜像把数据放在 /data 目录下，里面又分了 git 仓库存储、数据库文件、配置目录和日志。我建议把整个 /data 挂载到宿主机的一个独立目录。也就是说，容器内部的数据目录和宿主机目录一一对应。

我常用的目录规划长这样：

mkdir -p /srv/gitea cd /srv/gitea

然后整个 Gitea 的数据都存放在 /srv/gitea 下，后续备份只需要打包这一个目录，极其清爽。有些教程喜欢把 config、data、logs 分开挂多个卷，原则上没问题，但备份时要挂多个目录打包，还要处理文件权限差异，反而更麻烦。对于 Gitea 这个体量的应用，单一数据目录是最顺手的选择。

3.2 使用 docker-compose.yml 定义服务，而不是一串 docker run

我强烈建议使用 docker-compose，而不是敲一长串 docker run 参数。原因很简单——可读性强、易于版本管理、服务依赖关系明确。

下面给出一个我实际在用的 docker-compose.yml，数据库选的 PostgreSQL，Web 端口映射的 3000，SSH 端口映射的 2222：

version: "3" services: gitea: image: gitea/gitea:latest container_name: gitea environment: - USER_UID=1000 - USER_GID=1000 - GITEA__database__DB_TYPE=postgres - GITEA__database__HOST=db:5432 - GITEA__database__NAME=gitea - GITEA__database__USER=gitea - GITEA__database__PASSWD=gitea123 restart: always volumes: - /srv/gitea:/data - /etc/timezone:/etc/timezone:ro - /etc/localtime:/etc/localtime:ro ports: - "3000:3000" - "2222:22" depends_on: - db db: image: postgres:16 container_name: gitea-db environment: - POSTGRES_USER=gitea - POSTGRES_PASSWORD=gitea123 - POSTGRES_DB=gitea restart: always volumes: - /srv/gitea-db:/var/lib/postgresql/data

看到这里你可能会发现一个关键点：Gitea 容器映射的是容器内部的 22 端口到宿主机的 2222 端口，而不是直接映射宿主机的 22。这样做的好处非常明显——你系统的 sshd 继续占用 22，Gitea 的 SSH 功能走 2222，两边互不干扰。

关于数据库选择，官方支持 SQLite、MySQL、PostgreSQL。SQLite 适合个人使用或仓库数量很少的场景，零维护；团队多人并发写或者仓库数量上来了，建议直接用 PostgreSQL。MySQL 也能用，但我个人遇到过一次 Gitea + MySQL 的字符集配置问题，折腾了半小时，换成 PostgreSQL 后世界清净了。小团队选 PostgreSQL 是稳妥路线。

3.3 启动容器并完成初始化配置

配置文件写好后，启动服务：

docker compose up -d

首次启动会自动拉取 gitea/gitea 和 postgres 镜像。然后访问 http://服务器IP:3000 就能看到 Gitea 的安装引导页面。

安装页面有几个字段需要仔细填：

数据库设置：数据库类型选 PostgreSQL，主机地址填 db:5432，这里 db 是 docker-compose 里定义的服务名，在容器网络内部可以直接用服务名互相访问。如果你填 localhost 或者 127.0.0.1，容器内部解析到的是 gitea 容器自己，而不是数据库容器，会连接失败。这是新手最容易踩的坑。

站点名称和基础 URL：站点名称随意，基础 URL 建议直接填将来对外访问的域名，比如 http://git.example.com，如果暂时没有域名先填 http://IP:3000，后面也可以在配置文件里改。

SSH 服务器端口：这里要填 2222，因为 Gitea 容器内 SSH 监听的是 22，映射到宿主机是 2222，所以给用户展示的克隆地址里 SSH 端口应该是 2222。

服务器域名的配置同理。页面填完，点击安装，几秒钟后就会跳到登录页。用第一个管理员账号登录后台，就能正常使用了。

3.4 给 Gitea 配置域名和反向代理（HTTPS 可选但推荐）

如果只是内网 IP 访问，到 3.3 步已经够用。但如果想用域名访问、想上 HTTPS，就需要在前面加一层 Nginx 反向代理。

我一般是在宿主机装一个 Nginx，或者再用一个 Docker 起 nginx-proxy，然后配置 server 块代理到 3000 端口。一个实际可用的 Nginx 配置片段：

server { listen 80; server_name git.example.com; client_max_body_size 512m; location / { proxy_pass http://127.0.0.1:3000; 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; } }

关键点有两个。一是 client_max_body_size 一定要调大，不然推送大文件或者 LFS 时会直接 413，默认 1m 肯定不够用。二是要配置 X-Forwarded-Proto 等头，Gitea 会用这个判断请求协议，否则即使 HTTPS 反代了，Gitea 页面里生成的克隆地址仍然会是 http，导致克隆报错。

HTTPS 证书我一般直接用 ACME 自动申请，配上自动续期后基本可以做到一劳永逸。这个环节属于锦上添花，但对体验提升是质变级的。

4. 安装完成后的配置与日常维护

4.1 管理员账号、组织和权限模型

Gitea 第一次启动时创建的第一个账号会变成管理员。但我建议你在安装页面先创建一个普通管理员账号，后面再按需创建普通成员，而不是所有人都混在一个大账号里。

具体规划时我通常这样做：

• 创建一个组织，命名为 team-name（团队名）
• 组织下建项目仓库，按项目维度建私有仓库
• 给成员分角色：Owner、Collaborator、Read 等

Gitea 的权限模型没有 GitLab 那么细，但在中小团队里足够用了。有一点要说清楚：Gitea 的仓库阅读权限是私有仓库默认只有显式添加的成员能看，这一点比 GitHub 的免费版要友好得多——GitHub 免费版私有仓库其实也可以邀请协作者，但 Gitea 完全无限制，这一点对自建场景来说太关键了。

我实际使用中都会在设置里开启“注册邀请制”，让普通用户不能自己注册，只能由管理员添加。毕竟自建仓库面向的是团队内部，放开注册等于向全网开放了一个可能存在敏感代码的入口，这一条务必注意。

4.2 备份与恢复策略：把整个数据目录打包

Docker 部署最大的优势之一是备份非常简单。Gitea 的全部数据，包含配置、仓库、数据库、SSH 密钥、LFS 文件，都存放在挂载的 /data 目录下。结合 PostgreSQL 的数据卷 /srv/gitea-db，我把备份策略定为：

• 每天凌晨用 cron 执行备份脚本
• 用 tar 压缩 /srv/gitea 和 /srv/gitea-db 两个目录
• 压缩包保留最近 7 天
• 有条件的话异地备份或对象存储同步

一个简单的备份脚本长这样：

#!/bin/bash BACKUP_DIR="/backup/gitea" DATE=$(date +%Y%m%d%H%M) mkdir -p $BACKUP_DIR tar czf "$BACKUP_DIR/gitea-$DATE.tar.gz" /srv/gitea tar czf "$BACKUP_DIR/gitea-db-$DATE.tar.gz" /srv/gitea-db find $BACKUP_DIR -name "*.tar.gz" -mtime +7 -delete

有人可能会问，直接用 docker compose down 再打包会不会更好？理论上数据库文件在服务运行中打包可能出现不一致，但 PostgreSQL 的 WAL 机制会让文件即使在运行中也处于相对安全的状态。保守起见，备份前先执行 docker compose exec db pg_dump 导出一份 SQL，双保险。恢复流程就是把压缩包解压回原目录，然后 docker compose up -d，数据直接回来，非常省事。这套方案我实测恢复过两次，一次是误删仓库，一次是机房迁移，都是半小时内搞定。

4.3 给 Gitea 加 CI/CD 能力（Drone 或 Gitea Actions）

Gitea 本身不附带 CI 功能，但可以非常优雅地集成外部 CI。两个主流路线：

一是 Drone CI，用 docker-compose 一把梭，Drone 服务 + Runner 一个容器搞定，跟 Gitea 的集成非常顺滑。二是 Gitea Actions，这个和 GitHub Actions 的语法几乎一致，1.19 版本之后内置支持，配置 .gitea/workflows/*.yml 就能跑。对于熟悉 GitHub Actions 的人来说上手几乎零成本。

我用的是 Gitea Actions，原因很简单：少一个外部服务，跟 GitHub 生态无缝衔接。在仓库里建一个 .gitea/workflows/build.yml，用 Go 项目举个例子：

name: build on: [push] jobs: build: runs-on: ubuntu-latest steps: - uses: actions/checkout@v3 - uses: actions/setup-go@v4 with: go-version: '1.21' - run: go build

Runner 在宿主机上起一个 Docker 容器就能用，配置也简单。这个能力加上以后，整个代码仓库才真正变成完整的 DevOps 基础设施。这里不是必须，但值得一试。

4.4 升级 Gitea 到新版，注意数据备份放第一

Gitea 的小版本更新很频繁。Docker 部署升级就是两行命令：

docker compose pull docker compose up -d

但升级前务必先备份，尤其是跨大版本升级，比如从 1.x 升到 2.x，数据库结构可能有变更，回滚起来没那么简单。我的习惯是：先备份，再升级，然后检查首页、仓库列表、Issue、PR 这些核心功能是否正常。如果发现异常，立刻 docker compose down，恢复备份，再排查原因，避免在坏数据上继续操作。Gitea 官方文档也建议升级前先查看 release notes，这个习惯值得养成。

另外注意一点：gitea/gitea:latest 标签虽然方便，但升级的确定性就差一些。生产环境我更推荐固定版本号，比如用的 gitea/gitea:1.21.5，每次升级都是显式改标签，可控性高很多。这个思路和 docker 部署其他服务也一致，固定版本号永远是更稳的选择。

5. 常见问题排查实录，踩过的坑全在这里

5.1 permission denied while trying to connect to the docker api

这个报错基本可以判定是权限问题，最常见的就是用户不在 docker 组里。我排查顺序如下：

groups $USER

如果输出里没有 docker，那就执行 usermod 加入组。如果已经在组里还报错，大概率是 shell 会话没有刷新组信息，登出重进或者用 newgrp docker 就能解决。

另一种情况是 Docker 服务本身没起来。用 systemctl status docker 查看，如果服务是 dead 状态，journalctl -u docker 看日志。我遇到过好几次 Docker 服务启动失败，都是因为防火墙规则或者 iptables 配置被改过，导致 docker 无法初始化网络。解决办法是先停掉 firewalld 再启动 docker，成功后再把 firewalld 拉起来，观察 docker network 是否正常创建。如果你用 Ubuntu，ufw status 也需要确认没挡掉 docker 的网段。

5.2 镜像下载慢或直接超时

这个放在 docker 部署的任何服务上都是第一痛点。Gitea 镜像本身七十多兆，PostgreSQL 镜像两百多兆，在网速不给力的环境里光拉镜像就能耗掉你二十分钟。除了配镜像加速，我还有一个经验是——不要在高峰期拉镜像，尽量在低峰期或首次部署前就把镜像 pull 好。比如：

docker pull gitea/gitea:latest docker pull postgres:16

提前拉好，后面 docker compose up -d 就会非常快。如果已经配了加速还是慢，试试用 docker pull 指定 tag，比如具体的小版本号，有些时候 latest 标签体积反而比指定版本大。再有一个骚操作是给 registry 配置 HTTP/HTTPS 代理，但大多数场景下镜像加速就够用了。

5.3 容器网络不通，连不上数据库

这个问题我在 3.3 节已经提过，主机地址写 localhost 导致连不上数据库。在 docker-compose 网络里，容器之间互相访问必须用服务名，而不是 localhost。检查方法很简单：

docker exec -it gitea bash ping db

如果 ping 不通，说明 gitea 容器和 db 容器不在同一个网络里。docker compose 默认会创建一个项目名命名的网络，只要两个服务都定义在同一个 compose 文件里，默认就在一个网络下。如果你手贱加了 network_mode: host 或者其他自定义网络配置，这个错误就会冒出来，写完 compose 文件后记得 docker compose config 检查一下。

访问宿主机上的数据库是另一种场景。比如你想让 Gitea 连接宿主机上已经跑着的 MySQL，而不用起容器数据库，那 Gitea 容器里访问宿主机就不能用 127.0.0.1，而要用 host.docker.internal（Mac/Windows）或者宿主机的内网 IP（Linux）。有次我图省事直接在 compose 里写了 127.0.0.1:3306，结果 Gitea 一直报连接拒绝，排查了十几分钟才反应过来。把 host 改成宿主机内网 IP 后立刻恢复。

5.4 端口冲突，尤其是 3000 和 ssh

Gitea 的 Web 端口 3000 和系统的 sshd 端口 22 都是高占用端口。如果 3000 被别的服务占了，docker compose up 会直接报 bind: address already in use。处理方式：要么改 Gitea 的宿主机映射端口，比如 3000 改成 13000，要么找出占用进程干掉它。但我一般不会去杀进程，因为那个进程可能也是个重要服务。我的建议是：Gitea 的映射端口调整到不冲突的端口，比如 3000 和 2222，这两个端口在大多数服务器上不太容易被占用。如果你想要严谨一点，改完端口后记得改防火墙放行规则。

5.5 容器重启后数据丢失

这个坑可以说是新手最容易犯的。比如 docker run 的时候忘了挂数据卷，或者 compose 文件里写错了 volumes，容器一删数据全没了。我在第一台测试机上就吃过这个亏，当时图方便直接 docker run 没挂卷，后来想升级版本容器一删，仓库数据全没了。万幸是测试机没有正式数据，从那以后凡是涉及有状态服务，我第一件事就是把 volumes 写好，先想清楚数据放哪，再考虑怎么跑起来。

还有一点：Gitea 容器里的 /data 目录是整个应用的根数据目录，如果你把 /data 挂载到了宿主机目录，那么配置文件、仓库存储、LFS 文件全都在里面。恢复时只用恢复这个目录即可。另外，如果遇到容器启动了但 Gitea 无法打开网页，大概率是挂载目录权限不对，容器内进程以 uid 1000 运行，宿主机目录的所有者也要对应调整为 1000 权限。

5.6 Docker Desktop 的 Windows 特有问题

Windows 上启动 Docker Desktop 失败，十有八九就是虚拟化没开。排查路径：

• 任务管理器 -> 性能 -> CPU，看虚拟化是否显示“已启用”
• 如果没启用，进 BIOS 把 Intel VT-x / AMD-V 打开
• 如果 BIOS 已经打开仍然检测不到，多半是 Hyper-V 功能没启用

Enable-WindowsOptionalFeature -Online -FeatureName Microsoft-Hyper-V-All

装完 Hyper-V 后重启，再试 Docker Desktop。再加上 WSL2 内核更新，这套组合拳基本能解决 90% 的 Windows Docker 启动问题。如果还不行，去事件查看器看 Docker 服务相关的错误日志，会比到处搜教程高效得多。

6. 实战后的几点体会

整套部署流程讲完，最后分享一些我的个人体会。

Gitea + Docker 这套组合，对我来说是那种“没有惊艳，但用起来非常踏实”的东西。它不像 GitLab 那样功能多到让人焦虑，也不像 Gitee 那样时不时冒出条款限制。它就像你办公室角落里的饮水机，平时不怎么注意，但每个人都离不开。对于个人开发者，一个 Docker 容器就把代码仓库放在自己的服务器上，配合自动备份脚本，整个代码资产的管理效率比散落在网盘里高出不止一个数量级。

我在实际部署中发现，最有价值的一件事不是安装本身，而是把 Gitea 的备份和升级流程跑顺，这决定了这个系统能不能长期稳定用下去。很多人装完就丢在一边，出了事故才想起来根本没备份。建议你把备份脚本写进 cron 的第一天就做掉，别等丢了再说。

最后分享一个小技巧：Gitea 的配置文件在 /data/gitea/conf/app.ini。装完以后如果不小心把端口、域名填错了，不用重新跑安装流程，直接改这个文件然后 docker compose restart gitea 就能生效。Linux 环境下用起来非常顺手。

这套东西的扩展空间也很大。前文提到的 Gitea Actions、Drone CI、镜像仓库集成，甚至配合一些自动化脚本做依赖管理、版本发布，都可以逐步加进来。先把 Gitea 跑起来，让代码进仓库，后续的 DevOps 能力都建立在“有个稳定可控的代码仓库”这个基础之上。如果你正在为代码管理的事犯愁，照着这篇装一套，大概率能帮你省下不少事。