Gitea：轻量级Git服务完全指南：自建GitHub替代方案的完整教程

Gitea：轻量级Git服务完全指南：自建GitHub替代方案的完整教程

背景

在软件开发中，Git 仓库托管是团队协作的核心基础设施。GitHub、GitLab 等公共服务为开源项目提供了优秀的平台，但在企业场景下，存在数据隐私顾虑、仓库数量限制、企业版定价高等问题。

Gitea 正是为解决这一需求而生的轻量级 Git 服务。作为 GitHub/GitLab 的开源替代方案，Gitea 以其轻量、低资源占用、易于部署的特点，成为了个人开发者和中小团队搭建私有 Git 服务的首选。

本文将提供一份保姆级教程，详细讲解 Gitea 的部署与配置，帮助读者快速搭建完全自主掌控的私有 Git 仓库平台。

一、项目概述

1.1 Gitea 简介

Gitea 是一款由 Gogs 项目分支而来的轻量级 Git 服务，GitHub Star 数超过 30K。它采用 Go 语言开发，设计理念是"简单、高效、低资源占用"。

Gitea 的核心特点：

• 轻量高效：资源占用极低，最低只需 256MB 内存
• 快速部署：一键部署，几分钟内完成安装
• 功能完整：支持 Git 仓库、Issue、Pull Request、Wiki 等
• 易于扩展：支持多种数据库和存储后端
• 主题定制：提供多主题支持
• 开源自由：基于 MIT 协议，完全开源

1.2 核心功能

1.2.1 仓库管理

Gitea 提供了完整的仓库管理功能：

• 创建仓库：创建公开、私有、内部仓库
• 仓库操作：推送、拉取、分支管理
• 代码浏览：在线查看代码、提交历史
• 文件管理：上传、下载、在线编辑
• 版本标签：创建和管理 Git 标签

1.2.2 协作功能

• Issue 追踪：创建、管理 Issue
• Pull Request：代码审查和合并
• 代码审查：行级评论和讨论
• Wiki：项目文档编写
• 里程碑：Issue 里程碑管理

1.2.3 组织管理

• 组织创建：创建和管理组织
• 团队管理：创建团队，分配权限
• 成员管理：邀请和管理成员
• 权限控制：细粒度的仓库访问权限

1.3 Gitea vs GitLab vs Gogs

特性	Gitea	GitLab	Gogs
资源占用	低	高	极低
功能丰富度	中等	非常丰富	基础
安装难度	简单	复杂	极简
数据库	MySQL/PostgreSQL/SQLite	PostgreSQL/MySQL	SQLite/MySQL/PostgreSQL
CI/CD	基础	完整	无（需外部）
适合场景	中小团队	大型企业	个人/极简需求

二、Docker Compose 部署

2.1 环境准备

确保服务器已安装：

• Docker 20.10+
• Docker Compose 2.0+
• 内存：最低 256MB，推荐 1GB+
• 磁盘：根据仓库大小而定

2.2 创建部署目录

mkdir -p /opt/gitea
cd /opt/gitea

# 创建数据目录
mkdir -p {data,config}

2.3 创建 docker-compose.yml

cat > docker-compose.yml << 'EOF'
version: "3.8"

services:
  server:
    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=your_db_password
    restart: unless-stopped
    ports:
      - "3000:3000"
      - "2222:22"
    volumes:
      - ./data:/data
      - ./config:/config
      - /etc/timezone:/etc/timezone:ro
      - /etc/localtime:/etc/localtime:ro
    depends_on:
      - db

  db:
    image: postgres:15-alpine
    container_name: gitea-db
    environment:
      - POSTGRES_USER=gitea
      - POSTGRES_PASSWORD=your_db_password
      - POSTGRES_DB=gitea
    volumes:
      - postgres_data:/var/lib/postgresql/data
    restart: unless-stopped

volumes:
  postgres_data:
EOF

2.4 配置 Gitea

创建 Gitea 配置文件：

cat > config/app.ini << 'EOF'
[server]
PROTOCOL         = http
DOMAIN           = git.your-domain.com
ROOT_URL         = %(PROTOCOL)s://%(DOMAIN)s/
HTTP_PORT        = 3000
SSH_PORT         = 22
DISABLE_SSH      = false
SSH_DOMAIN       = %(DOMAIN)s
LFS_START_SERVER = true

[database]
DB_TYPE  = postgres
HOST     = db:5432
NAME     = gitea
USER     = gitea
PASSWD   = your_db_password

[security]
INSTALL_LOCK                 = true
SECRET_KEY                   = your-secret-key-change-this
INTERNAL_TOKEN               = your-internal-token

[service]
DISABLE_REGISTRATION         = false
ALLOW_ONLY_EXTERNAL_REGISTRATION = false
ENABLE_CAPTCHA               = true

[mailer]
ENABLED = false

[session]
PROVIDER = database

[log]
MODE      = console
LEVEL     = info
ROOT_PATH = /data/gitea/log
EOF

2.5 启动服务

# 启动服务
docker compose up -d

# 查看服务状态
docker compose ps

# 查看日志
docker compose logs -f

2.6 初始化配置

首次访问 http://your-server-ip:3000，完成初始化：

1. 数据库配置：确认数据库连接信息
2. 管理员账户：创建第一个管理员账户
3. 应用基础配置：设置站点名称、域名等

2.7 Nginx 反向代理

cat > /etc/nginx/sites-available/gitea << 'EOF'
server {
    listen 80;
    server_name git.your-domain.com;

    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;
    }

    location ~ ^/(git|ws) {
        proxy_pass http://127.0.0.1:3000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
    }
}
EOF

ln -s /etc/nginx/sites-available/gitea /etc/nginx/sites-enabled/
nginx -t
systemctl reload nginx

# 启用 HTTPS
apt-get install -y certbot python3-certbot-nginx
certbot --nginx -d git.your-domain.com

三、快速入门

3.1 用户注册与登录

首次使用需要注册账户：

1. 点击"注册"按钮
2. 输入用户名、邮箱、密码
3. 完成注册（如果开启了邮件验证，需要验证邮箱）

3.2 创建仓库

3.2.1 新建仓库

1. 点击右上角"+" → “新建仓库”
2. 填写仓库信息：
   • 仓库名称：英文名称
   • 描述：仓库说明
   • 可见性：公开/私有
   • 初始化仓库：是否添加 README
3. 点击"创建仓库"

3.2.2 推送现有代码

# 在本地仓库中设置远程
git remote add origin http://your-server/user/repo.git

# 推送代码
git push -u origin master

3.3 仓库操作

3.3.1 克隆仓库

git clone http://your-server/user/repo.git

3.3.2 创建分支

git checkout -b feature/new-feature

3.3.3 提交和推送

git add .
git commit -m "feat: add new feature"
git push origin feature/new-feature

四、协作功能

4.1 Issue 管理

4.1.1 创建 Issue

1. 进入仓库页面
2. 点击"Issue" → “新建 Issue”
3. 填写标题和描述
4. 添加标签、里程碑、指派人
5. 点击"提交 Issue"

4.1.2 Issue 标签

系统默认标签：

• bug
• duplicate
• enhancement
• help wanted
• invalid
• question

可以自定义标签：

1. 进入仓库设置 → “标签”
2. 点击"新建标签"
3. 设置名称和颜色

4.2 Pull Request

4.2.1 创建 Pull Request

1. 在分支页面点击"Compare & pull request"
2. 填写 PR 标题和描述
3. 选择目标分支
4. 点击"创建 Pull Request"

4.2.2 代码审查

在 PR 详情页面：

• 查看文件更改：查看具体的代码改动
• 行级评论：点击代码行号添加评论
• 审批 PR：审核通过后合并

4.2.3 合并 PR

1. 检查所有评论已解决
2. 点击"合并 Pull Request"
3. 选择合并方式（merge/squash/rebase）
4. 确认合并

4.3 Wiki

Wiki 用于项目文档：

1. 点击仓库的"Wiki"标签
2. 创建首页和子页面
3. 使用 Markdown 编辑内容

五、组织和团队

5.1 创建组织

1. 点击右上角"+" → “新建组织”
2. 输入组织名称和描述
3. 设置组织可见性
4. 完成创建

5.2 创建团队

在组织中创建团队：

1. 进入组织设置 → “团队”
2. 点击"新建团队"
3. 填写团队名称和描述
4. 配置团队权限

5.3 权限配置

权限级别	说明
无权限	无法访问仓库
读取	可以查看和克隆
分支	可以推送分支
写入	可以推送和合并
管理员	完全控制

六、配置管理

6.1 邮件配置

启用邮件通知：

[mailer]
ENABLED      = true
HOST         = smtp.example.com:587
USER         = noreply@example.com
PASSWD       = your_password
FROM         = noreply@example.com

6.2 SSH 配置

6.2.1 添加 SSH 密钥

1. 进入个人设置 → “SSH 密钥”
2. 点击"添加密钥"
3. 粘贴公钥内容
4. 设置密钥名称

6.2.2 生成 SSH 密钥

ssh-keygen -t ed25519 -C "your_email@example.com"
cat ~/.ssh/id_ed25519.pub

6.3 Webhook 配置

配置 Webhook 实现外部集成：

1. 进入仓库设置 → “Webhooks”
2. 点击"添加 Webhook"
3. 选择类型（Gitea/JSON）
4. 输入目标 URL
5. 设置触发事件

七、备份恢复

7.1 数据备份

# 备份数据目录
tar -czf gitea_data_$(date +%Y%m%d).tar.gz /opt/gitea/data

# 备份数据库
docker compose exec -T db pg_dump -U gitea > gitea_db_$(date +%Y%m%d).sql

7.2 数据恢复

# 恢复数据库
docker compose exec -T db psql -U gitea < gitea_db_20260325.sql

# 恢复数据目录
tar -xzf gitea_data_20260325.tar.gz -C /

八、常见问题

8.1 部署问题

Q：服务启动后显示 502

A：检查 Gitea 和数据库启动状态：

docker compose logs server
docker compose logs db

Q：无法发送邮件

A：检查邮件配置是否正确，确保 SMTP 服务可用。

8.2 使用问题

Q：SSH 推送失败

A：检查 SSH 配置：

1. 确认已添加 SSH 公钥
2. 检查 SSH 端口是否正确（默认 22）
3. 测试 SSH 连接：

ssh -T git@your-server

Q：无法克隆仓库

A：检查仓库路径和权限配置。

九、总结

Gitea 作为轻量级 Git 服务的优秀代表，以其低资源占用、快速部署和完整功能的特点，为个人开发者和中小团队提供了理想的私有 Git 解决方案。

通过本文的保姆级教程，读者应该已经掌握了：

1. Docker 部署：使用 Docker Compose 快速部署 Gitea
2. 仓库管理：创建、克隆、推送仓库
3. 协作功能：Issue、Pull Request、Wiki
4. 权限管理：组织和团队权限配置
5. 配置管理：邮件、SSH、Webhook
6. 备份恢复：数据备份和恢复方法

对于需要搭建私有 Git 服务的团队，Gitea 是一个值得信赖的开源选择。

---

© 版权归无边界科技所有，版权所有。