Gitea：用 Docker 搭私有代码托管

本文属于「自托管 Docker 部署实战」系列（共 35 篇），第 9 篇。示例中的 IP（192.0.2.10）、域名（example.com）、密码均为占位符，请按实际环境替换。

它是什么

轻量自托管 Git 服务，替代 GitHub 的私有仓库。本文用的 commitgo/gitea-ee 是企业版镜像，社区版镜像为 gitea/gitea。

前置条件

一台 Linux 服务器（1C1G 起步；Java 类应用建议 2C4G 以上）；
已安装 Docker 与 Compose v2，执行 docker compose version 有版本号输出；
所有示例里的 IP / 域名 / 密码都是占位符，实际部署请替换成自己的。

# 安装 Docker（已安装可跳过）
curl -fsSL https://get.docker.com | sh

# 目录约定：一个服务一个目录，后文的 ./data 均指栈目录内
mkdir -p /srv/docker/active/<stack> && cd /srv/docker/active/<stack>

镜像地址

commitgo/gitea-ee:27.3.8
gitea/gitea:<版本号>    # 社区版备选
mysql:8.4.7

目录结构

/srv/docker/active/gitea/
├── docker-compose.yml
├── .env
├── data/                 # 仓库、附件、配置、SSH 密钥
└── mysql-data/

部署步骤

# docker-compose.yml
services:
  gitea:
    image: commitgo/gitea-ee:27.3.8
    container_name: gitea
    restart: always
    depends_on:
      mysql:
        condition: service_healthy
    environment:
      - USER_UID=1000
      - USER_GID=1000
      - GITEA__database__DB_TYPE=mysql
      - GITEA__database__HOST=mysql:3306
      - GITEA__database__NAME=gitea
      - GITEA__database__USER=gitea
      - GITEA__database__PASSWD=${GITEA_DB_PASSWORD}
      - GITEA__server__ROOT_URL=https://git.example.com/
      - GITEA__server__SSH_PORT=222
    ports:
      - "3000:3000"       # HTTP
      - "222:22"          # SSH，宿主机 22 被占用时换端口
    volumes:
      - ./data:/data
      - /etc/timezone:/etc/timezone:ro
      - /etc/localtime:/etc/localtime:ro

  mysql:
    image: mysql:8.4.7
    restart: always
    environment:
      - MYSQL_ROOT_PASSWORD=${MYSQL_ROOT_PASSWORD}
      - MYSQL_DATABASE=gitea
      - MYSQL_USER=gitea
      - MYSQL_PASSWORD=${GITEA_DB_PASSWORD}
    volumes:
      - ./mysql-data:/var/lib/mysql

docker compose up -d
# 首次访问 http://<SERVER_IP>:3000 完成安装向导

关键配置

GITEA__server__ROOT_URL 必须是对外 URL，否则 clone 地址、Webhook、OAuth 全部指向错误主机；
GITEA__server__SSH_PORT 要写成对外暴露的 SSH 端口（上面是 222），不是容器内的 22；
用 MySQL 时 USER_UID/GID 和宿主机目录属主要一致，否则 push 会报权限错误；
备份只备 data/ 和数据库即可，data/git/repositories 是仓库本体。

注意事项

SSH 端口不要和宿主机 sshd 冲突；
大仓库多时，MySQL 的 innodb_buffer_pool_size 要调，默认值会拖慢；
升级前看 CHANGELOG，Gitea 版本号跨度大时可能要求逐版本升级；
暴露公网务必关掉「允许注册」，并开启 2FA。

备份与升级

# 1) 数据库
docker exec gitea-mysql sh -c 'exec mysqldump -uroot -p"$MYSQL_ROOT_PASSWORD" --single-transaction --all-databases' | gzip > "gitea-db-$(date +%F).sql.gz"

# 2) 仓库、附件与配置
tar czf "gitea-data-$(date +%F).tar.gz" ./data

# 3) 升级
docker compose pull
docker compose up -d

data/git/repositories 是仓库本体，别只备数据库；
跨大版本按官方文档逐版本升级，不要跳版。