Docker-compose 自部署个人代码托管服务：Gitea 极简搭建指南

前言#

前段时间我分享过 Gogs安装教程，体验还不错。但说实话，Gitea 这个从 Gogs 分支而来的轻量级 DevOps 平台真的更香——Go 语言编写、极易安装、运行飞快,支持 Git 托管和 CI/CD，更新频繁维护活跃，更适合长期使用。

为什么我选择 Gitea 而不是 GitHub?#

说实话，刚开始我也和很多人一样，直接用 GitHub 多方便啊。但是慢慢地我发现了一些问题:

代码隐私没保障 - 尤其是在内网环境或者一些私密项目中
依赖第三方平台 - 稳定性和政策风险都不在自己掌控中
有各种限制 - 私有仓库数量、协作人数都有门槛

你有没有遇到过这样的情况？公司内部项目想自托管，又不想折腾 GitLab 那么重的东西。这时候 Gitea 真的太适合了。

开始搭建: Docker Compose 部署#

个人比较习惯使用 Docker Compose 来进行自部署，原因只有一个：它更易于维护。

下面是我的 docker-compose.yml 配置，使用的是 PostgreSQL 数据库（高性能） :

1
version: "3"
2

3
networks:
4
  gitea:
5
    external: false
6

7
services:
8
  server:
9
    image: docker.gitea.com/gitea:1.25.4
10
    container_name: gitea
11
    environment:
12
      - USER_UID=1000
13
      - USER_GID=1000
14
      - GITEA__database__DB_TYPE=postgres
15
      - GITEA__database__HOST=db:5432
16
      - GITEA__database__NAME=gitea
17
      - GITEA__database__USER=gitea
18
      - GITEA__database__PASSWD=gitea
19
    restart: always
20
    networks:
21
      - gitea
22
    volumes:
23
      - ./gitea:/data
24
      - /etc/timezone:/etc/timezone:ro
25
      - /etc/localtime:/etc/localtime:ro
26
    ports:
27
      - "3000:3000"
28
      - "222:22"
29
    depends_on:
30
      - db
31

32
  db:
33
    image: docker.io/library/postgres:14
34
    restart: always
35
    environment:
36
      - POSTGRES_USER=gitea
37
      - POSTGRES_PASSWORD=gitea
38
      - POSTGRES_DB=gitea
39
    networks:
40
      - gitea
41
    volumes:
42
      - ./postgres:/var/lib/postgresql/data

更多关于Docker Compose 容器化部署的配置可以参考官方文档 ->通过Docker安装 & 环境变量

运行启动：

1
docker-compose up -d

等个几秒，访问 http://localhost:3000 就能看到安装界面了。

SSH 配置踩坑#

第一次部署完，页面上显示的 SSH 地址不对。我把容器里的 22 端口映射到了宿主机的 222，但页面显示的还是默认端口。

结果就是 clone 的时候报 connection refused，折腾了半天。

解决办法：

改 /data/gitea/conf/app.ini：

1
[server]
2
SSH_DOMAIN = your-git-domain.com
3
DISABLE_SSH = false
4
SSH_PORT = 222
5
SSH_LISTEN_PORT = 22  # 这个必须是 22，改了没用

注意 SSH_LISTEN_PORT 是容器内部监听的，固定是 22。我一开始改了这个，重启好几次都没生效，后来看文档才明白。

改完重启：

1
docker restart gitea

这时候页面上显示的 clone 地址就是 ssh://git@your-git-domain.com:222/user/repo.git 了。

客户端配置：

不想每次敲端口，可以在 ~/.ssh/config 里加：

1
Host gitea
2
    HostName your-git-domain.com
3
    Port 222
4
    User git

之后就能直接用 git clone gitea:user/repo.git。

Nginx 反向代理#

有域名的话建议配个反向代理。注意 client_max_body_size 要设大一点，不然传大文件会报错。

1
location / {
2
    client_max_body_size 512M;
3
    proxy_pass http://localhost:3000;
4
    proxy_set_header Connection $http_connection;
5
    proxy_set_header Upgrade $http_upgrade;
6
    proxy_set_header Host $host;
7
    proxy_set_header X-Real-IP $remote_addr;
8
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
9
    proxy_set_header X-Forwarded-Proto $scheme;
10
}

注意这些配置项:

client_max_body_size 512M - 支持上传 512MB 的文件
proxy_set_header Upgrade 和 Connection - 支持 WebSocket(Gitea 的实时功能需要)
X-Forwarded-Proto - 让 Gitea 知道是 HTTPS 还是 HTTP

总结回顾#

回顾一下核心要点:

✅ Docker Compose 一键部署,超级简单
✅ PostgreSQL 数据库性能更好
✅ SSH 端口配置要正确,否则 clone 不通
✅ Nginx 反向代理记得设置 client_max_body_size

现在就可以开始:

创建目录，复制上面的 docker-compose.yml
运行 docker-compose up -d 启动
访问 http://localhost:3000 完成初始配置
修改 app.ini 配置 SSH 端口
(可选)配置 Nginx 反向代理

Gitea 真的比 GitLab 轻量太多，使用下来整体挺稳的。个人或者小团队用很合适。也可以考虑把 Astro 静态博客托管到你的 Gitea 私人仓库进行版本管理及自动化拉取变更、构建静态页面。