2026-03-13 Fri 00:00:00 CST

Gitea 完整实践指南：从部署到自动化

一、Gitea 概述

1.1 什么是 Gitea

Gitea 是一个轻量级的自托管 Git 服务，采用 Go 语言编写，是 GitHub 和 GitLab 的轻量替代方案。它提供了完整的代码托管功能，包括 Issues、Pull Requests、Wiki、CI/CD 等，同时保持了极低的资源占用。

为什么选择 Gitea？

特性	Gitea	GitLab	GitHub
资源占用	极低（100MB RAM）	高（2GB+ RAM）	SaaS
部署复杂度	简单	复杂	无需部署
数据控制	完全自控	完全自控	依赖第三方
国内访问	可部署内网	可部署内网	需代理

1.2 核心特性

轻量级：单个二进制文件，内存占用极低
易部署：支持二进制、Docker、包管理器多种方式
完整功能：Issues、PR、Wiki、CI/CD、LFS、包管理
插件系统：支持通过 Markdown 插件扩展功能
兼容性强：支持 GitHub/GitLab 导入，API 兼容

1.3 适用场景

个人/小团队代码托管 - 轻量快速启动
企业内网 Git 服务 - 数据完全自控
CI/CD 平台基础 - 结合 Actions 构建自动化流水线
镜像仓库中转站 - 在国内网络环境下加速访问

二、Gitea 部署与配置

2.1 系统要求

资源	最低配置	推荐配置
CPU	1核	2核+
内存	512MB	1GB+
磁盘	10GB	50GB+
操作系统	Linux/macOS/Windows	Linux 64位

2.2 二进制安装（推荐）

下载与安装

# 下载最新版本（国内用户建议使用镜像站点）
wget https://dl.gitea.io/gitea/1.22/gitea-1.22.0-linux-amd64

# 或使用 GitHub 镜像加速
wget https://mirror.ghproxy.com/https://github.com/go-gitea/gitea/releases/download/v1.22.0/gitea-1.22.0-linux-amd64

# 添加执行权限
chmod +x gitea-1.22.0-linux-amd64

# 移动到系统路径
sudo mv gitea-1.22.0-linux-amd64 /usr/local/bin/gitea

# 创建 gitea 用户
sudo useradd -r -m -d /var/lib/gitea -s /bin/bash gitea

配置 Systemd 服务

# 创建服务文件
sudo nano /etc/systemd/system/gitea.service

gitea.service 配置：

[Unit]
Description=Gitea
After=syslog.target
After=network.target
After=mariadb.service postgresql.service mysql.service

[Service]
Type=simple
User=gitea
Group=gitea
WorkingDirectory=/var/lib/gitea
ExecStart=/usr/local/bin/gitea web --config /etc/gitea/app.ini
Restart=always
Environment=USER=gitea
HOME=/var/lib/gitea

[Install]
WantedBy=multi-user.target

# 重载并启动服务
sudo systemctl daemon-reload
sudo systemctl enable gitea
sudo systemctl start gitea

# 查看状态
sudo systemctl status gitea

2.3 初始化配置

首次访问 http://your-server:3000 会进入初始化向导：

数据库配置（SQLite）

数据库类型：SQLite3
路径：/var/lib/gitea/data/gitea.db

SQLite 适合小规模部署，无需额外数据库服务，配置最简单。

基本设置

服务器域名：your-server.example.com
Gitea 基础 URL：https://your-server.example.com/
SSH 服务端口：22 或自定义
监听 HTTP 端口：3000

管理员账号

用户名：admin
密码：[设置强密码]
邮箱：admin@example.com

2.4 app.ini 配置文件详解

配置文件位置：/etc/gitea/app.ini

[server]
PROTOCOL          = http
DOMAIN            = your-server.example.com
ROOT_URL          = https://your-server.example.com/
HTTP_PORT         = 3000
DISABLE_SSH       = false
SSH_PORT          = 22
START_SSH_SERVER  = true
LFS_START_SERVER  = true

[database]
TYPE     = sqlite3
PATH     = /var/lib/gitea/data/gitea.db

[repository]
ROOT            = /var/lib/gitea/repositories
SCRIPT_TYPE     = bash
DEFAULT_PUSH_CREATE_PRIVATE = true

[lfs]
PATH = /var/lib/gitea/data/lfs

[service]
DISABLE_REGISTRATION              = true
REQUIRE_SIGNIN_VIEW               = true
REGISTER_EMAIL_CONFIRM            = true

[session]
PROVIDER = file

2.5 国内网络环境适配

SSL 证书配置（Let’s Encrypt）

# 安装 certbot
sudo apt install certbot

# 申请证书
sudo certbot certonly --standalone -d your-server.example.com

# 证书路径
证书：/etc/letsencrypt/live/your-server.example.com/fullchain.pem
私钥：/etc/letsencrypt/live/your-server.example.com/privkey.pem

修改 app.ini：

[server]
PROTOCOL = https
CERT_FILE = /etc/letsencrypt/live/your-server.example.com/fullchain.pem
KEY_FILE = /etc/letsencrypt/live/your-server.example.com/privkey.pem

# 重启服务
sudo systemctl restart gitea

自签名证书（内网使用）

# 生成自签名证书
sudo openssl req -x509 -nodes -days 365 -newkey rsa:2048 \
  -keyout /etc/ssl/private/gitea.key \
  -out /etc/ssl/certs/gitea.crt

# 设置权限
sudo chmod 600 /etc/ssl/private/gitea.key
sudo chmod 644 /etc/ssl/certs/gitea.crt

修改 app.ini 指向自签名证书路径。

三、Gitea Actions（CI/CD）

3.1 Actions 简介

Gitea Actions 是 Gitea 1.19+ 引入的 CI/CD 功能，兼容 GitHub Actions 语法。它由以下组件构成：

Gitea 实例：存储 Workflow 文件，触发构建任务
Act Runner：执行 Workflow 的 Runner 程序
Job：实际运行的工作单元

3.2 Act Runner 部署

下载与安装

# 下载 act runner
wget https://dl.gitea.com/act-runner/act-runner-0.2.10-linux-amd64

# 添加执行权限
chmod +x act-runner-0.2.10-linux-amd64
sudo mv act-runner-0.2.10-linux-amd64 /usr/local/bin/act-runner

# 创建 runner 用户
sudo useradd -r -m -d /var/lib/act-runner -s /bin/bash act-runner

注册 Runner

# 获取注册令牌（在 Gitea 管理页面获取）
# Gitea 设置 -> Actions -> Runners -> New Runner

# 注册 Runner
sudo -u act-runner act-runner register \
  --instance https://your-server.example.com \
  --token <your-token> \
  --name "linux-runner" \
  --labels "docker:docker"

# 创建 systemd 服务
sudo nano /etc/systemd/system/act-runner.service

act-runner.service 配置：

[Unit]
Description=Gitea Actions Runner
After=network.target

[Service]
Type=simple
User=act-runner
Group=act-runner
WorkingDirectory=/var/lib/act-runner
ExecStart=/usr/local/bin/act-runner daemon --config /var/lib/act-runner/config.yaml
Restart=always

[Install]
WantedBy=multi-user.target

# 启动服务
sudo systemctl daemon-reload
sudo systemctl enable act-runner
sudo systemctl start act-runner
sudo systemctl status act-runner

3.3 Workflow 编写

Workflow 文件位于仓库的 .gitea/workflows/ 目录下，使用 YAML 格式。

基本结构

name: CI Workflow

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

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Run tests
        run: |
          echo "Running tests..."
          make test

自动构建 Docker 镜像

name: Build and Push Docker Image

on:
  push:
    branches: [ main ]
    tags: [ 'v*' ]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v3

      - name: Login to Registry
        uses: docker/login-action@v3
        with:
          registry: registry.example.com
          username: ${{ secrets.REGISTRY_USERNAME }}
          password: ${{ secrets.REGISTRY_PASSWORD }}

      - name: Build and push
        uses: docker/build-push-action@v5
        with:
          context: .
          push: true
          tags: registry.example.com/myapp:latest,registry.example.com/myapp:${{ github.ref_name }}
          cache-from: type=registry,ref=registry.example.com/myapp:buildcache
          cache-to: type=registry,ref=registry.example.com/myapp:buildcache,mode=max

自动化部署

name: Deploy to Server

on:
  push:
    branches: [ main ]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Deploy via SSH
        uses: appleboy/ssh-action@v1.0.0
        with:
          host: ${{ secrets.DEPLOY_HOST }}
          username: ${{ secrets.DEPLOY_USER }}
          key: ${{ secrets.DEPLOY_SSH_KEY }}
          script: |
            cd /opt/myapp
            git pull origin main
            docker-compose down
            docker-compose pull
            docker-compose up -d

3.4 国内网络优化

Runner 镜像源配置

在 Runner 服务器上配置 Docker 镜像加速：

# 修改 Docker daemon 配置
sudo nano /etc/docker/daemon.json

{
  "registry-mirrors": [
    "https://docker.m.daocloud.io",
    "https://docker.1panel.live"
  ]
}

# 重启 Docker
sudo systemctl restart docker

Workflow 中使用镜像加速

name: Build with Mirror

on: [push]

jobs:
  build:
    runs-on: ubuntu-latest
    container:
      image: ghcr.m.daocloud.io/catthehacker/ubuntu:act-latest
    steps:
      - uses: actions/checkout@v4

      - name: Configure npm mirror
        run: |
          npm config set registry https://registry.npmmirror.com          

      - name: Configure pip mirror
        run: |
          pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple          

      - name: Configure Go proxy
        run: |
          go env -w GOPROXY=https://goproxy.cn,direct          

      - name: Build
        run: make build

超时配置（giteatimeout）

Actions Runner 在国内网络环境下容易遇到超时问题。需要在多个层面配置：

1. Runner 服务配置

修改 /var/lib/act-runner/config.yaml：

runner:
  # 连接超时（秒）
  fetch_timeout: 180
  # 运行超时（秒），0 表示不限制
  timeout: 10800  # 3 小时

2. Workflow 级别超时

jobs:
  build:
    timeout-minutes: 60  # 单个 Job 超时
    steps:
      - name: Download with retry
        run: |
          # 使用重试脚本
          for i in {1..3}; do
            curl -L -o package.tar.gz ${{ env.DOWNLOAD_URL }} && break
            echo "Retrying... ($i/3)"
            sleep 10
          done

3. 网络层面优化

# 增加系统网络超时
sudo sysctl -w net.ipv4.tcp_keepalive_time=600
sudo sysctl -w net.ipv4.tcp_keepalive_intvl=60
sudo sysctl -w net.ipv4.tcp_keepalive_probes=20

3.5 Secrets 管理

在仓库中配置敏感信息：

仓库设置 -> Secrets and variables -> Actions -> New Repository Secret

常用 Secrets：

REGISTRY_USERNAME - 镜像仓库用户名
REGISTRY_PASSWORD - 镜像仓库密码
DEPLOY_SSH_KEY - 部署服务器 SSH 私钥
DEPLOY_HOST - 部署服务器地址
DEPLOY_USER - 部署用户名

四、仓库镜像（Repository Mirror）

4.1 镜像功能概述

Gitea 支持两种镜像模式：

类型	方向	说明
Pull 镜像	远程 → Gitea	从 GitHub/GitLab 拉取更新到 Gitea
Push 镜像	Gitea → 远程	将 Gitea 的更改推送到远程

4.2 从 GitHub 同步（Pull 镜像）

配置步骤

在 GitHub 生成 Personal Access Token
GitHub 设置 -> Developer settings -> Personal access tokens -> Tokens (classic)
- 勾选 repo 权限

在 Gitea 创建 Pull 镜像

仓库设置 -> Mirroring -> Add New Pull Mirror

仓库地址：https://github.com/username/repo.git
用户名：your-github-username
密码：your-github-pat-token
同步间隔：8h（推荐）

手动触发同步
仓库设置 -> Mirroring -> Sync Now

配置文件方式

修改 app.ini：

[mirror]
ENABLED         = true
DEFAULT_INTERVAL = 8h

4.3 推送到远程仓库（Push 镜像）

配置步骤

获取目标仓库认证信息
- GitHub：使用 Personal Access Token
- Gitee：使用 Personal Access Token（私有令牌）

在 Gitea 创建 Push 镜像

仓库设置 -> Mirroring -> Add New Push Mirror

仓库地址：https://gitee.com/username/repo.git
用户名：your-gitee-username
密码：your-gitee-token

触发时机
- 每次推送到 Gitea 仓库后自动推送
- 可配置推送特定分支

4.4 国内网络场景应用

Gitee 镜像中转架构

┌─────────┐         ┌─────────┐         ┌─────────┐
│ GitHub  │  Pull   │  Gitea  │  Push   │  Gitee  │
│ (国外)  │ ──────> │ (内网)  │ ──────> │ (国内)  │
└─────────┘         └─────────┘         └─────────┘
     ↑                                       ↓
     │                                       │
     └────────────── 团队克隆 ───────────────┘

实施步骤：

设置 GitHub → Gitea Pull 镜像
```
# GitHub 同步配置
[mirror]
INTERVAL = 4h
```
- 每 4 小时自动拉取 GitHub 更新
- 团队成员直接从 Gitea 克隆（内网快速）
设置 Gitea → Gitee Push 镜像
- 将 Gitea 仓库推送到 Gitee
- 外部合作伙伴从 Gitee 克隆
多地域镜像
在多个 Gitee 实例之间建立镜像链，实现就近访问。

私有仓库镜像

使用 SSH 密钥认证：

# 生成 SSH 密钥对
ssh-keygen -t ed25519 -C "gitea-mirror" -f ~/.ssh/gitea_mirror

# 公钥添加到 GitHub/Gitee
cat ~/.ssh/gitea_mirror.pub

在 Gitea 镜像配置中使用 SSH URL：

git@github.com:username/repo.git

4.5 镜像故障排查

常见问题

问题	原因	解决方案
认证失败	Token 过期	更新 PAT
同步超时	网络慢	增加超时时间、使用代理
LFS 文件未同步	LFS 未配置	配置 Git LFS
大仓库同步慢	历史记录大	浅克隆（–depth 1）

调试同步

# 查看 Gitea 日志
sudo journalctl -u gitea -f

# 手动测试镜像
cd /var/lib/gitea/repositories/username/repo.git
sudo -u gitea git fetch --all -v

LFS 同步配置

修改 app.ini：

[lfs]
STORAGE_TYPE = local
PATH = /var/lib/gitea/data/lfs

[server]
LFS_START_SERVER = true
LFS_JWT_SECRET = your-secret-key

五、高级话题

5.1 第三方认证集成

LDAP 集成

修改 app.ini：

[service]
ENABLE_CAPTCHA = false

[security]
ENABLE_LOGIN_SOURCE_COOKIE = true

[ldap]
ENABLED = true
SOURCE_NAME = Company LDAP
HOST = ldap-server.example.com:389
BIND_DN = cn=admin,dc=example,dc=com
BIND_PASSWORD = password
SEARCH_BASE = ou=users,dc=example,dc=com
USERNAME_ATTRIBUTE = uid
USER_FILTER = (&(objectClass=person)(|(uid=%[1]s)(mail=%[1]s)))
EMAIL_ATTRIBUTE = mail
NAME_ATTRIBUTE = givenName
SURNAME_ATTRIBUTE = sn

5.2 Webhook 集成

配置 Webhook 实现自动化通知：

仓库设置 -> Webhooks -> Add Webhook

常见集成：

企业微信机器人
钉钉机器人
Slack
自定义 HTTP 服务

5.3 安全加固

启用 2FA（双因素认证）
```
设置 -> 安全 -> 启用 2FA
```

API 限流

[api]
ENABLE_SWAGGER = false
MAX_RESPONSE_ITEMS = 50

审计日志

[log]
MODE = file
LEVEL = info

查看日志：

设置 -> 审计日志

Gitea 完整实践指南：从部署到自动化

一、Gitea 概述

1.1 什么是 Gitea

为什么选择 Gitea？

1.2 核心特性

1.3 适用场景

二、Gitea 部署与配置

2.1 系统要求

2.2 二进制安装（推荐）

下载与安装

配置 Systemd 服务

2.3 初始化配置

数据库配置（SQLite）

基本设置

管理员账号

2.4 app.ini 配置文件详解

2.5 国内网络环境适配

SSL 证书配置（Let’s Encrypt）

自签名证书（内网使用）

三、Gitea Actions（CI/CD）

3.1 Actions 简介

3.2 Act Runner 部署

下载与安装

注册 Runner

3.3 Workflow 编写

基本结构

自动构建 Docker 镜像

自动化部署

3.4 国内网络优化

Runner 镜像源配置

Workflow 中使用镜像加速

超时配置（giteatimeout）

3.5 Secrets 管理

四、仓库镜像（Repository Mirror）

4.1 镜像功能概述

4.2 从 GitHub 同步（Pull 镜像）

配置步骤

配置文件方式

4.3 推送到远程仓库（Push 镜像）

配置步骤

4.4 国内网络场景应用

Gitee 镜像中转架构

私有仓库镜像

4.5 镜像故障排查

常见问题

调试同步

LFS 同步配置

五、高级话题

5.1 第三方认证集成

LDAP 集成

5.2 Webhook 集成

5.3 安全加固

六、参考资源