前言

各位技术折腾家们，大家好！作为开发者，我们日常离不开代码管理。虽然 GitHub、GitLab、Gitee 等公共代码托管平台非常方便，但有时候，我们可能需要一个完全私有、可控、轻量级的代码仓库，比如：

用于存放一些不方便公开的代码。

在本地网络环境中搭建，提高访问速度。

学习和掌握 Git 服务端的部署与管理。

为小型团队提供一个私有协作平台。

今天，我就给大家介绍一个完美的解决方案——Gitea。它是一个用 Go 语言编写的自托管 Git 服务，资源占用极小，安装部署极其简单，功能却非常完备，几乎涵盖了 GitHub/GitLab 的所有核心特性：代码仓库、Issue 跟踪、Pull Request、Wiki 等。

我们将继续使用 Docker Compose，以最快速、最简洁的方式，将 Gitea 和它所需的数据库部署到你的 Linux 服务器上。

部署环境准备

在开始之前，请确保你的服务器已经安装了 Docker 和 Docker Compose。如果还没有，可以参考我之前文章中提供的方法进行安装。

简单回顾（以 Ubuntu 为例）：

# 安装 Docker
sudo apt update
sudo apt install docker.io -y
sudo systemctl enable docker --now

# 安装 Docker Compose (如果版本低于 2.x, 建议升级到新版)
# 可以通过 `docker compose version` 或 `docker-compose --version` 检查
sudo curl -L "https://github.com/docker/compose/releases/download/v2.24.5/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
sudo chmod +x /usr/local/bin/docker-compose

(注：Docker Compose 的最新版本号可能可能有所不同，请根据实际情况访问 Docker Compose GitHub Release 查看最新版本并替换 v2.24.5。)

Gitea 部署步骤

我们将使用 Docker Compose 同时启动 Gitea 应用容器和 PostgreSQL 数据库容器。Gitea 也支持 MySQL、SQLite3，这里我们选择 PostgreSQL。

1. 创建项目目录

首先，在你的服务器上创建一个用于存放 Gitea 相关文件和数据的目录：

mkdir gitea_data
cd gitea_data

2. 编写 Docker Compose 文件

在这个 gitea_data 目录下，创建一个名为 docker-compose.yml 的文件：

vi docker-compose.yml

然后将以下内容粘贴进去：

version: "3"

services:
  gitea:
    image: gitea/gitea:latest # Gitea 官方最新镜像
    container_name: gitea
    restart: always
    ports:
      - "3000:3000" # Gitea Web 界面端口，可以修改为其他未占用端口
      - "2222:22"   # Gitea SSH 端口，如果需要通过 SSH 克隆/推送代码，必须映射
    volumes:
      - ./data:/data # Gitea 数据持久化目录
      - /etc/timezone:/etc/timezone:ro # 确保时区正确
      - /etc/localtime:/etc/localtime:ro # 确保本地时间正确
    environment:
      - DB_TYPE=postgres            # 数据库类型
      - DB_HOST=db:5432             # 数据库主机名和端口，`db` 是 Docker Compose 中数据库服务的名称
      - DB_NAME=gitea               # 数据库名称
      - DB_USER=giteauser           # 数据库用户
      - DB_PASSWD=your_db_password  # 数据库密码，请务必修改为强密码！
      - GITEA__database__DB_TYPE=postgres
      - GITEA__database__HOST=db:5432
      - GITEA__database__NAME=gitea
      - GITEA__database__USER=giteauser
      - GITEA__database__PASSWD=your_db_password
      - GITEA__server__ROOT_URL=http://your_server_ip:3000/ # Gitea 访问 URL，请替换
      # 如果你计划使用域名和 HTTPS，可以在这里先用 IP+端口，后面再在 Gitea 界面修改
    depends_on:
      - db # 依赖 db 服务，确保数据库先启动

  db:
    image: postgres:15 # PostgreSQL 数据库镜像
    container_name: gitea_db
    restart: always
    volumes:
      - ./postgres_data:/var/lib/postgresql/data # 数据库数据持久化
    environment:
      - POSTGRES_USER=giteauser      # 数据库用户
      - POSTGRES_PASSWORD=your_db_password # 数据库密码，与 Gitea 服务保持一致
      - POSTGRES_DB=gitea            # 数据库名称

重要提示：

your_db_password: 请务必修改为复杂且安全的数据库密码！ 这是你的 Gitea 数据安全的关键。

GITEA__server__ROOT_URL: 请替换为你的服务器 IP 地址或域名以及 Gitea 监听的端口。 例如 http://192.168.1.100:3000/ 或 http://gitea.yourdomain.com:3000/。如果后面计划使用域名和 HTTPS，这里可以先用 IP，部署成功后再通过 Gitea 后台界面修改。

ports:

3000:3000 是 Gitea 的 Web 界面端口。你可以修改宿主机端口（冒号左边），例如 80:3000 或 8080:3000。

2222:22 是 Gitea 的 SSH 服务端口。22 是容器内部 SSH 的默认端口，2222 是映射到宿主机的端口。如果你需要通过 SSH 克隆/推送代码，这个端口必须映射并确保防火墙放行。

3. 启动 Gitea 服务

在 gitea_data 目录下，执行以下命令启动 Gitea 和 PostgreSQL：

docker compose up -d

up: 创建并启动 docker-compose.yml 中定义的服务。

-d: 后台运行（detached mode）。

第一次运行，Docker 会下载 Gitea 和 PostgreSQL 镜像，这可能需要一些时间，取决于你的网络速度。

你可以使用以下命令查看容器状态：

docker compose ps

当 State 显示为 Up 时，表示容器已经成功运行。

4. 配置防火墙

如果你的服务器开启了防火墙（如 UFW 或 firewalld），需要放行 Gitea 的 Web 端口（默认 TCP 3000）和 SSH 端口（默认 TCP 2222）。

使用 UFW (Ubuntu 默认)：

sudo ufw allow 3000/tcp
sudo ufw allow 2222/tcp # 如果你需要SSH服务
sudo ufw reload # 如果UFW已启用，需要重新加载规则
sudo ufw status

使用 firewalld (CentOS/RHEL 8+ 默认)：

sudo firewall-cmd --add-port=3000/tcp --permanent
sudo firewall-cmd --add-port=2222/tcp --permanent # 如果你需要SSH服务
sudo firewall-cmd --reload
sudo firewall-cmd --list-all

5. 访问 Gitea 并完成初始化设置

打开你的浏览器，访问 http://你的服务器IP地址:3000 (如果你修改了端口，请使用你修改后的端口)。

首次访问，你会看到 Gitea 的初始配置页面。大部分设置 Docker Compose 文件中已经指定，你只需要：

数据库设置：

数据库类型： 保持 PostgreSQL。

主机： 保持 db:5432。

用户、密码、数据库名： 保持与 docker-compose.yml 中设置的一致。

应用基本设置：

仓库存放路径： 保持 /data/git/repositories。

Gitea 基本 URL： 确认这里显示的是你正确的访问地址（例如 http://你的服务器IP:3000/）。如果后面你打算用域名和 HTTPS 访问，可以在这里先用 IP 地址，后续再在 Gitea 后台管理界面修改。

可选设置： 根据你的需求选择是否启用注册、是否需要管理员审批等。

管理员账户设置： 创建你的第一个 Gitea 管理员账户，设置用户名、密码和邮箱。

点击 “立即安装 Gitea”。安装过程很快，完成后你就会被重定向到登录页面。使用你刚刚创建的管理员账户登录，就可以开始创建你的第一个代码仓库了！

常用 Docker Compose 管理命令

停止 Gitea 服务：docker compose stop

启动已停止的 Gitea 服务：docker compose start

重启 Gitea 服务：docker compose restart

查看服务日志：
docker compose logs -f gitea # 查看 Gitea 服务日志
docker compose logs -f db # 查看数据库服务日志

停止并删除所有容器、网络和卷： (慎用，会删除容器，但 ./data 和 ./postgres_data 目录下的数据会保留)
docker compose down

如果你要完全删除数据，需要手动删除 gitea_data/data 和 gitea_data/postgres_data 目录。

后续优化与思考

域名与 HTTPS： 强烈建议为你的 Gitea 实例配置一个域名，并通过 Nginx/Caddy 等反向代理工具加上 SSL 证书，实现 HTTPS 访问，保障代码传输安全。这通常会将 3000 端口隐藏在反向代理后面。

SSH 端口： 如果你的服务器 SSH 端口（默认 22）是暴露在公网的，那么 Gitea 的 SSH 端口 (2222) 可以不用映射到 22，以避免冲突。客户端克隆代码时，需要明确指定端口，例如 git clone ssh://git@your_server_ip:2222/your_username/your_repo.git。

备份： 定期备份 gitea_data/data 目录（包含所有代码仓库、配置等）和 gitea_data/postgres_data 目录（数据库）至关重要。

邮箱配置： 在 Gitea 后台配置 SMTP 服务器，以便发送注册邮件、评论通知、密码重置等邮件。

Actions/CI/CD： Gitea 也支持集成 CI/CD 工具（如 Gitea Actions），实现代码提交后的自动化构建和部署。

总结与展望

通过本篇教程，你已经成功在自己的服务器上搭建了一个功能完备的 Gitea 私有 Git 代码托管服务。这意味着你拥有了一个完全掌控、安全可靠的代码管理平台，无论是个人项目、学习实践，还是团队内部协作，都将得心应手。

自建 Gitea 不仅让你摆脱了对第三方平台的依赖，也为你提供了一个深入理解 Git 服务和 Web 应用部署的绝佳机会。快去创建你的第一个私有仓库，享受代码的自由吧！