第 4 章 - Gitea 轻量平台

Gitea 是一个轻量级的自托管 Git 服务，使用 Go 语言编写，单二进制部署，资源占用低（约 150-300MB 内存），功能覆盖代码托管、Issue、PR、CI/CD 等核心需求。

4.1 功能概览

功能模块	说明
代码托管	Git 仓库、分支管理、LFS 支持
协作功能	Pull Request、Code Review、Issue、Wiki
组织管理	组织（Organization）、团队（Team）、权限
CI/CD	Gitea Actions（兼容 GitHub Actions 语法）
包管理	npm、Maven、PyPI、NuGet、Container 镜像
镜像	仓库镜像推送/拉取
认证	LDAP、OAuth2、SAML、SMTP
API	REST API 和 GraphQL

4.2 安装部署

4.2.1 二进制安装（推荐）

# 下载最新版本（以 1.22 为例）
GITEA_VERSION="1.22.0"
wget -O /usr/local/bin/gitea \
  "https://dl.gitea.com/gitea/${GITEA_VERSION}/gitea-${GITEA_VERSION}-linux-amd64"

chmod +x /usr/local/bin/gitea

# 验证
gitea --version
# Gitea version 1.22.0 built with ...

4.2.2 创建系统用户和目录

# 创建系统用户
sudo adduser \
  --system \
  --shell /bin/bash \
  --group \
  --home /home/git \
  --disabled-password \
  git

# 创建必要的目录
sudo mkdir -p /var/lib/gitea/{custom,data,log}
sudo mkdir -p /etc/gitea

# 设置权限
sudo chown -R git:git /var/lib/gitea/
sudo chown root:git /etc/gitea
sudo chmod 750 /etc/gitea

4.2.3 Systemd 服务配置

sudo tee /etc/systemd/system/gitea.service << 'EOF'
[Unit]
Description=Gitea (Git with a cup of tea)
After=syslog.target
After=network.target
After=postgresql.service mysql.service mariadb.service

[Service]
Type=simple
User=git
Group=git
WorkingDirectory=/var/lib/gitea/
RuntimeDirectory=gitea
ExecStart=/usr/local/bin/gitea web --config /etc/gitea/app.ini
Environment=GITEA_WORK_DIR=/var/lib/gitea
Environment=USER=git
Restart=always
RestartSec=2s
LimitNOFILE=65535

[Install]
WantedBy=multi-user.target
EOF

sudo systemctl daemon-reload
sudo systemctl enable gitea
sudo systemctl start gitea

4.2.4 安装数据库

选项一：SQLite（最简单，适合小团队）

无需额外安装，Gitea 内置 SQLite 支持。

选项二：PostgreSQL（推荐生产环境）

# 安装 PostgreSQL
sudo apt install postgresql -y

# 创建数据库和用户
sudo -u postgres psql << SQL
CREATE USER gitea WITH PASSWORD 'gitea_password_change_me';
CREATE DATABASE giteadb OWNER gitea;
GRANT ALL PRIVILEGES ON DATABASE giteadb TO gitea;
SQL

# 验证连接
psql -h 127.0.0.1 -U gitea -d giteadb

选项三：MySQL/MariaDB

sudo apt install mariadb-server -y
sudo mysql_secure_installation

sudo mysql << SQL
CREATE DATABASE giteadb CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'gitea'@'localhost' IDENTIFIED BY 'gitea_password_change_me';
GRANT ALL PRIVILEGES ON giteadb.* TO 'gitea'@'localhost';
FLUSH PRIVILEGES;
SQL

4.2.5 Web 安装向导

启动 Gitea 后访问 http://server:3000，进入安装向导。

关键配置项：

配置项	推荐值
Database Type	PostgreSQL / MySQL / SQLite
Database Host	127.0.0.1:5432 (PostgreSQL)
Database Name	giteadb
Database User	gitea
Database Password	（设置强密码）
Repository Root Path	/var/lib/gitea/data/gitea-repositories
Git LFS Root Path	/var/lib/gitea/data/lfs
HTTP Port	3000
SSH Port	22
SSH Server Domain	git.example.com
Gitea Base URL	https://git.example.com
Admin Username	admin
Admin Password	（设置强密码）

4.2.6 手动配置文件

sudo tee /etc/gitea/app.ini << 'INI'
[server]
DOMAIN           = git.example.com
HTTP_PORT        = 3000
ROOT_URL         = https://git.example.com/
SSH_DOMAIN       = git.example.com
SSH_PORT         = 22
START_SSH_SERVER = false
LFS_START_SERVER = true
LFS_CONTENT_PATH = /var/lib/gitea/data/lfs
OFFLINE_MODE     = false

[database]
DB_TYPE  = postgres
HOST     = 127.0.0.1:5432
NAME     = giteadb
USER     = gitea
PASSWD   = gitea_password_change_me
SSL_MODE = disable
CHARSET  = utf8

[repository]
ROOT                     = /var/lib/gitea/data/gitea-repositories
ENABLE_PUSH_CREATE_USER  = true
ENABLE_PUSH_CREATE_ORG   = true
DEFAULT_BRANCH           = main

[service]
DISABLE_REGISTRATION              = false
REQUIRE_SIGNIN_VIEW               = false
ENABLE_NOTIFY_MAIL                = false
ALLOW_ONLY_EXTERNAL_REGISTRATION  = false

[mailer]
ENABLED = false

[log]
MODE      = file
LEVEL     = Info
ROOT_PATH = /var/lib/gitea/log

[security]
INSTALL_LOCK   = true
SECRET_KEY     = auto_generated_change_me
INTERNAL_TOKEN = auto_generated_change_me
INI

sudo chown git:git /etc/gitea/app.ini
sudo systemctl restart gitea

4.3 Docker 部署

4.3.1 使用 Docker Compose

# docker-compose.yml
version: "3"

services:
  gitea:
    image: gitea/gitea:1.22
    container_name: gitea
    restart: always
    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=gitea_password
    volumes:
      - ./gitea/data:/data
      - /etc/timezone:/etc/timezone:ro
      - /etc/localtime:/etc/localtime:ro
    ports:
      - "3000:3000"
      - "2222:22"
    networks:
      - gitea-network
    depends_on:
      - db

  db:
    image: postgres:16-alpine
    container_name: gitea-db
    restart: always
    environment:
      - POSTGRES_USER=gitea
      - POSTGRES_PASSWORD=gitea_password
      - POSTGRES_DB=gitea
    volumes:
      - ./postgres/data:/var/lib/postgresql/data
    networks:
      - gitea-network

networks:
  gitea-network:
    driver: bridge

# 启动
docker compose up -d

# 查看日志
docker compose logs -f gitea

# 访问 http://localhost:3000 进行安装配置

4.4 基本功能使用

4.4.1 创建组织和团队

通过 Web 界面操作：

点击右上角 + → New Organization
填写组织名称、描述
创建后进入组织设置 → Teams
创建团队并设置权限级别

权限级别说明：

权限级别	读取	写入	管理 Issues	管理仓库
Guest	✅	❌	评论	❌
Reader	✅	❌	✅	❌
Writer	✅	✅	✅	❌
Admin	✅	✅	✅	✅
Owner	✅	✅	✅	✅

4.4.2 Pull Request 工作流

1. Fork 或创建分支
   git checkout -b feature/new-login

2. 开发并推送
   git push origin feature/new-login

3. 在 Web 界面创建 Pull Request
   - 源分支: feature/new-login
   - 目标分支: main
   - 描述变更内容

4. Code Review
   - 团队成员审查代码
   - 提交 Review 意见
   - Approve 或 Request Changes

5. 合并
   - Merge Commit（保留完整历史）
   - Squash and Merge（压缩为单个提交）
   - Rebase and Merge（线性历史）

4.4.3 Issue 和看板

<!-- Issue 模板示例: .gitea/ISSUE_TEMPLATE/bug.md -->
---
name: Bug 报告
about: 报告一个 bug
labels: bug
---

## 描述
<!-- 简要描述 bug -->

## 复现步骤
1. 步骤一
2. 步骤二
3. 步骤三

## 预期行为
<!-- 描述预期的行为 -->

## 实际行为
<!-- 描述实际的行为 -->

## 环境信息
- OS:
- 浏览器:
- 版本:

4.5 迁移功能

4.5.1 从 GitHub 迁移

Gitea 内置迁移功能，支持从 GitHub、GitLab、Bitbucket 等平台迁移。

通过 Web 界面：

点击 + → New Migration
选择源平台（GitHub）
输入仓库 URL 和 Access Token
选择迁移内容（代码、Issues、PR、标签、里程碑）

通过 API：

# 使用 Gitea API 迁移
curl -X POST "https://git.example.com/api/v1/repos/migrate" \
  -H "Authorization: token YOUR_GITEA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "clone_addr": "https://github.com/owner/repo.git",
    "repo_name": "repo",
    "repo_owner": "your-organization",
    "service": "github",
    "auth_token": "ghp_xxxxxxxxxxxx",
    "issues": true,
    "pull_requests": true,
    "labels": true,
    "milestones": true,
    "mirror": false,
    "private": true
  }'

4.5.2 批量迁移脚本

#!/bin/bash
# batch-migrate.sh - 从 GitHub 批量迁移仓库

GITEA_URL="https://git.example.com"
GITEA_TOKEN="your_gitea_token"
GITHUB_TOKEN="ghp_xxxxxxxxxxxx"
GITHUB_ORG="github-org-name"
GITEA_ORG="gitea-org-name"

# 获取 GitHub 仓库列表
repos=$(curl -s -H "Authorization: token $GITHUB_TOKEN" \
  "https://api.github.com/orgs/${GITHUB_ORG}/repos?per_page=100" | \
  jq -r '.[].name')

for repo in $repos; do
    echo "Migrating: $repo"
    
    curl -s -X POST "${GITEA_URL}/api/v1/repos/migrate" \
      -H "Authorization: token ${GITEA_TOKEN}" \
      -H "Content-Type: application/json" \
      -d "{
        \"clone_addr\": \"https://github.com/${GITHUB_ORG}/${repo}.git\",
        \"repo_name\": \"${repo}\",
        \"repo_owner\": \"${GITEA_ORG}\",
        \"service\": \"github\",
        \"auth_token\": \"${GITHUB_TOKEN}\",
        \"issues\": true,
        \"pull_requests\": true,
        \"labels\": true,
        \"milestones\": true,
        \"private\": true
      }" | jq '.full_name'
    
    sleep 2  # 避免触发速率限制
done

4.6 CI/CD 集成

4.6.1 Gitea Actions

Gitea Actions 兼容 GitHub Actions 语法，在仓库 .gitea/workflows/ 目录下定义流水线。

# .gitea/workflows/build.yml
name: Build and Test

on:
  push:
    branches: [main, dev]
  pull_request:
    branches: [main]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'
      
      - name: Install dependencies
        run: npm ci
      
      - name: Run tests
        run: npm test
      
      - name: Build
        run: npm run build
      
      - name: Upload artifact
        uses: actions/upload-artifact@v4
        with:
          name: build-output
          path: dist/

4.6.2 配置 Runner

Gitea Actions 需要 Runner 来执行任务。

# 安装 act_runner
wget https://dl.gitea.com/act_runner/0.2.11/act_runner-0.2.11-linux-amd64
chmod +x act_runner-0.2.11-linux-amd64
sudo mv act_runner-0.2.11-linux-amd64 /usr/local/bin/act_runner

# 注册 Runner
act_runner register \
  --instance https://git.example.com \
  --token YOUR_REGISTRATION_TOKEN

# 启动 Runner
act_runner daemon --config config.yaml

创建 Systemd 服务：

sudo tee /etc/systemd/system/act_runner.service << 'EOF'
[Unit]
Description=Gitea Actions Runner
After=network.target

[Service]
Type=simple
User=git
ExecStart=/usr/local/bin/act_runner daemon --config /home/git/act_runner/config.yaml
Restart=always
RestartSec=5s

[Install]
WantedBy=multi-user.target
EOF

sudo systemctl daemon-reload
sudo systemctl enable act_runner
sudo systemctl start act_runner

4.7 API 使用

4.7.1 创建 API Token

在 Web 界面：Settings → Applications → Generate Token

4.7.2 常用 API 调用

GITEA_URL="https://git.example.com"
TOKEN="your_api_token"

# 获取当前用户信息
curl -s -H "Authorization: token $TOKEN" \
  "$GITEA_URL/api/v1/user" | jq

# 列出仓库
curl -s -H "Authorization: token $TOKEN" \
  "$GITEA_URL/api/v1/repos/search?limit=50" | jq '.data[].full_name'

# 创建仓库
curl -s -X POST -H "Authorization: token $TOKEN" \
  -H "Content-Type: application/json" \
  "$GITEA_URL/api/v1/user/repos" \
  -d '{"name": "new-repo", "description": "New repository", "private": true}' | jq

# 创建 Issue
curl -s -X POST -H "Authorization: token $TOKEN" \
  -H "Content-Type: application/json" \
  "$GITEA_URL/api/v1/repos/owner/repo/issues" \
  -d '{"title": "Bug: login failed", "body": "Description...", "labels": [1]}' | jq

4.8 镜像配置

4.8.1 推送镜像到 GitHub

在 Web 界面操作：

进入仓库 Settings → Repository → Mirror Settings
选择 Push Mirror
填写 GitHub 仓库 URL：https://github.com/your-org/repo.git
添加 GitHub Personal Access Token
设置同步间隔

4.8.2 拉取镜像（从 GitHub 同步）

# Pull Mirror - 从远程仓库自动同步
# 在 Web 界面创建仓库时选择 "Migrate Repository"
# 或在已有仓库的 Settings → Mirror Settings 中配置

4.9 性能优化

4.9.1 大仓库优化

# /etc/gitea/app.ini

[git]
; 启用 Git GC
ENABLE_AUTO_GIT_WIRE_PROTOCOL = true

[repository]
; 限制仓库大小
MAX_CREATION_LIMIT = -1
; 启用 Large File Storage
ENABLE_PUSH_CREATE_USER = true

[server]
; 启用 Gzip 压缩
ENABLE_GZIP = true

[cache]
; 启用缓存
ADAPTER = redis
HOST = redis://127.0.0.1:6379/0

[queue]
; 任务队列配置
TYPE = redis
CONN_STR = redis://127.0.0.1:6379/1

4.9.2 监控指标

# 启用 Prometheus 指标
[metrics]
ENABLED = true

# 访问指标端点
curl http://localhost:3000/metrics

4.10 扩展阅读

本章小结

学到了什么	关键要点
安装部署	二进制安装 + Systemd，或 Docker Compose 一键部署
数据库	SQLite（小团队）/ PostgreSQL（生产）/ MySQL
功能使用	组织、团队、PR、Issue、Wiki
迁移	内置迁移支持 GitHub/GitLab，支持批量脚本
CI/CD	Gitea Actions 兼容 GitHub Actions 语法
API	RESTful API，支持自动化管理

下一章：第 5 章 - Forgejo 社区分支 — 了解 Forgejo 与 Gitea 的差异，以及 Forgejo Actions 的独特优势。

强曰为道

第 4 章 - Gitea 轻量平台

第 4 章 - Gitea 轻量平台

4.1 功能概览

4.2 安装部署

4.2.1 二进制安装（推荐）

4.2.2 创建系统用户和目录

4.2.3 Systemd 服务配置

4.2.4 安装数据库

4.2.5 Web 安装向导

4.2.6 手动配置文件

4.3 Docker 部署

4.3.1 使用 Docker Compose

4.4 基本功能使用

4.4.1 创建组织和团队

4.4.2 Pull Request 工作流

4.4.3 Issue 和看板

4.5 迁移功能

4.5.1 从 GitHub 迁移

4.5.2 批量迁移脚本

4.6 CI/CD 集成

4.6.1 Gitea Actions

4.6.2 配置 Runner

4.7 API 使用

4.7.1 创建 API Token

4.7.2 常用 API 调用

4.8 镜像配置

4.8.1 推送镜像到 GitHub

4.8.2 拉取镜像（从 GitHub 同步）

4.9 性能优化

4.9.1 大仓库优化

4.9.2 监控指标

4.10 扩展阅读

本章小结