rui-docs/backend/guides/self-hosted-git-server.md

自建 Git 服务器方案：Gitea

版本: v1.0
创建日期: 2026-06-04
适用场景: 替代 Gitee，实现完整的 Git + CI/CD 私有化部署

---

一、为什么选择 Gitea？

1.1 对比分析

特性	Gitee	GitLab CE	Gitea	Gogs
开源免费	部分功能收费	✅ 社区版免费	✅ 完全开源	✅ 完全开源
资源占用	云端，无需部署	4GB+ 内存	128MB 内存	64MB 内存
CI/CD	收费	✅ 内置	✅ Gitea Actions	❌ 需搭配 Drone
中文支持	✅ 原生	✅ 支持	✅ 支持	✅ 支持
Issue 模板	✅ 支持	✅ 支持	✅ 支持	✅ 支持
代码审查	✅ 支持	✅ 支持	✅ 支持	✅ 支持
部署难度	无需部署	复杂	简单	简单
GitHub Actions 兼容	❌	❌	✅ 兼容	❌

1.2 Gitea 优势

• ✅ 轻量级：单二进制文件，内置 SQLite，无需额外数据库
• ✅ 低资源：128MB 内存即可运行，适合低配服务器
• ✅ CI/CD 内置：Gitea Actions 完全兼容 GitHub Actions 语法
• ✅ 易迁移：支持从 Gitee/GitHub 导入仓库
• ✅ Webhook 丰富：支持钉钉、企业微信、Slack 等通知
• ✅ 权限管理：组织、团队、仓库级权限控制

---

二、部署方案

方案 A：Docker 部署（推荐）

适合：有 Docker 环境的服务器

# docker-compose.yml
version: "3"

services:
  gitea:
    image: gitea/gitea:latest
    container_name: gitea
    environment:
      - USER_UID=1000
      - USER_GID=1000
      - GITEA__database__DB_TYPE=sqlite3
      - GITEA__server__DOMAIN=git.vifo.cc
      - GITEA__server__ROOT_URL=https://git.vifo.cc
      - GITEA__server__SSH_DOMAIN=git.vifo.cc
      - GITEA__actions__ENABLED=true
    restart: always
    networks:
      - gitea
    volumes:
      - ./gitea:/data
      - /etc/timezone:/etc/timezone:ro
      - /etc/localtime:/etc/localtime:ro
    ports:
      - "3000:3000"
      - "222:22"

  # 可选：Gitea Actions Runner（执行 CI/CD 任务）
  runner:
    image: gitea/act_runner:latest
    container_name: gitea-runner
    environment:
      - GITEA_INSTANCE_URL=https://git.vifo.cc
      - GITEA_RUNNER_REGISTRATION_TOKEN=your-token
      - GITEA_RUNNER_NAME=default-runner
    restart: always
    networks:
      - gitea
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - ./runner:/data
    depends_on:
      - gitea

networks:
  gitea:
    external: false

启动命令：

# 创建目录
mkdir -p ~/gitea && cd ~/gitea

# 创建 docker-compose.yml（粘贴上方内容）
nano docker-compose.yml

# 启动
docker-compose up -d

# 查看日志
docker-compose logs -f gitea

初始化配置：

1. 访问 http://服务器IP:3000
2. 填写管理员账号（首次访问会自动跳转到安装页面）
3. 基础 URL 设置为你的域名（如 https://git.vifo.cc）
4. 数据库选择 SQLite（轻量级）或 MySQL（生产环境）

---

方案 B：二进制部署

适合：没有 Docker 环境的裸机

# 1. 下载二进制（Linux AMD64）
wget -O gitea https://dl.gitea.com/gitea/latest/gitea-latest-linux-amd64
chmod +x gitea

# 2. 创建用户（不要使用 root 运行）
sudo useradd -r -m -s /bin/bash git

# 3. 创建工作目录
sudo mkdir -p /var/lib/gitea/{custom,data,log}
sudo chown -R git:git /var/lib/gitea/
sudo chmod -R 750 /var/lib/gitea/

# 4. 移动到系统目录
sudo mv gitea /usr/local/bin/

# 5. 创建 Systemd 服务
sudo tee /etc/systemd/system/gitea.service > /dev/null <<EOF
[Unit]
Description=Gitea
After=network.target

[Service]
User=git
Group=git
WorkingDirectory=/var/lib/gitea
ExecStart=/usr/local/bin/gitea web --config /var/lib/gitea/custom/conf/app.ini
Restart=always
Environment=USER=git HOME=/home/git GITEA_WORK_DIR=/var/lib/gitea

[Install]
WantedBy=multi-user.target
EOF

# 6. 启动服务
sudo systemctl daemon-reload
sudo systemctl enable gitea
sudo systemctl start gitea

# 7. 查看状态
sudo systemctl status gitea

---

方案 C：一键安装脚本（最简单）

# 下载官方安装脚本
curl -s https://raw.githubusercontent.com/go-gitea/gitea/main/contrib/install.sh | bash

# 或者使用 snap（Ubuntu/Debian）
sudo snap install gitea

---

三、Nginx 反向代理 + HTTPS

3.1 Nginx 配置

# /etc/nginx/conf.d/gitea.conf
server {
    listen 80;
    server_name git.vifo.cc;
    return 301 https://$server_name$request_uri;
}

server {
    listen 443 ssl http2;
    server_name git.vifo.cc;

    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    location / {
        proxy_pass http://localhost: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;
    }
}

3.2 申请免费 SSL 证书（Let's Encrypt）

# 安装 certbot
sudo apt install certbot python3-certbot-nginx

# 申请证书
sudo certbot --nginx -d git.vifo.cc

# 自动续期测试
sudo certbot renew --dry-run

---

四、从 Gitee 迁移到 Gitea

4.1 迁移单个仓库

# 1. 在 Gitea 创建空仓库（如 rui-frontend）

# 2. 本地克隆 Gitee 仓库
git clone --mirror https://gitee.com/rui/rui-frontend.git

# 3. 推送到 Gitea
cd rui-frontend.git
git remote add gitea https://git.vifo.cc/rui/rui-frontend.git
git push gitea --mirror

4.2 批量迁移（所有仓库）

#!/bin/bash
# migrate.sh

GITEA_URL="https://git.vifo.cc"
GITEA_TOKEN="your-token"
GITEA_ORG="rui"

REPOS=("spring-ai" "rui-frontend" "rui-payment")

for repo in "${REPOS[@]}"; do
    echo "迁移: $repo"
    
    # 在 Gitea 创建仓库
    curl -X POST "$GITEA_URL/api/v1/orgs/$GITEA_ORG/repos" \
        -H "Authorization: token $GITEA_TOKEN" \
        -H "Content-Type: application/json" \
        -d "{\"name\": \"$repo\", \"private\": true}"
    
    # 克隆并推送
    git clone --mirror "https://gitee.com/rui/$repo.git" "/tmp/$repo"
    cd "/tmp/$repo"
    git remote add gitea "$GITEA_URL/$GITEA_ORG/$repo.git"
    git push gitea --mirror
    cd ..
done

---

五、配置 CI/CD（Gitea Actions）

5.1 启用 Actions

在 app.ini 中配置：

[actions]
ENABLED = true
DEFAULT_ACTIONS_URL = github

5.2 注册 Runner

# 获取注册令牌（在 Gitea 管理后台 → Actions → Runners → 创建新 Runner）
# 然后执行：
docker exec -it gitea-runner act_runner register \
  --instance https://git.vifo.cc \
  --token YOUR_TOKEN \
  --name default-runner \
  --labels ubuntu-latest:docker://node:18

5.3 创建前端 CI/CD 工作流

# rui-frontend/.gitea/workflows/build.yml
name: Build and Deploy

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

jobs:
  build:
    runs-on: ubuntu-latest
    
    steps:
      - name: Checkout
        uses: actions/checkout@v4
      
      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '18'
          cache: 'pnpm'
      
      - name: Install pnpm
        uses: pnpm/action-setup@v2
        with:
          version: 8
      
      - name: Install dependencies
        run: pnpm install
      
      - name: Build admin-ui
        run: pnpm build:admin
      
      - name: Deploy to server
        if: github.ref == 'refs/heads/main'
        run: |
          # 部署脚本
          echo "部署到生产环境"

5.4 创建后端 CI/CD 工作流

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

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

jobs:
  build:
    runs-on: ubuntu-latest
    
    steps:
      - name: Checkout
        uses: actions/checkout@v4
      
      - name: Setup JDK 21
        uses: actions/setup-java@v4
        with:
          java-version: '21'
          distribution: 'temurin'
          cache: maven
      
      - name: Build with Maven
        run: cd backend && mvn clean install -DskipTests
      
      - name: Run tests
        run: cd backend && mvn test

---

六、Gitea 常用配置

6.1 配置 Issue 模板

与 Gitee 类似，创建 .gitea/issue_templates/ 目录：

.gitea/issue_templates/
├── api_request.md
├── framework_bug.md
└── cross_team_task.md

注意：Gitea 的 Issue 模板语法与 Gitee 兼容。

6.2 配置 Webhook（通知钉钉/企业微信）

在仓库设置 → Webhooks 中添加：

URL: https://oapi.dingtalk.com/robot/send?access_token=xxx
触发事件: Push, Pull Request, Issue

6.3 禁用公开注册（私有化）

# app.ini
[service]
DISABLE_REGISTRATION = true
REQUIRE_SIGNIN_VIEW = true

---

七、备份策略

7.1 自动备份脚本

#!/bin/bash
# backup.sh

BACKUP_DIR="/backup/gitea"
DATE=$(date +%Y%m%d)

# 备份 Gitea 数据
tar czf "$BACKUP_DIR/gitea-$DATE.tar.gz" /var/lib/gitea

# 保留最近 7 天的备份
find "$BACKUP_DIR" -name "gitea-*.tar.gz" -mtime +7 -delete

添加到 crontab：

# 每天凌晨 2 点备份
0 2 * * * /path/to/backup.sh

---

八、常见问题

Q1: Gitea 和 GitLab 怎么选？

• Gitea：轻量、简单、资源占用低，适合小团队（< 50 人）
• GitLab：功能强大、生态丰富，适合大团队、需要复杂 CI/CD 流水线

Q2: 需要多少服务器资源？

规模	CPU	内存	磁盘	推荐
小团队 (< 10人)	1 核	1GB	20GB	阿里云/腾讯云 入门配置
中等团队 (10-50人)	2 核	2GB	50GB	阿里云 2C2G
大团队 (50+人)	4 核	4GB	100GB	阿里云 4C4G

Q3: 可以从 Gitea 迁移回 Gitee/GitHub 吗？

可以。Gitea 支持导出仓库，也可以直接推送回其他 Git 平台。

Q4: Gitea Actions 和 GitHub Actions 完全兼容吗？

大部分常用 action 兼容。如果某个 action 不兼容，可以自己写 shell 脚本替代。

---

九、部署检查清单

• 准备一台 Linux 服务器（1C1G 起步）
• 安装 Docker（推荐）或下载 Gitea 二进制
• 配置域名和 DNS 解析
• 配置 Nginx 反向代理 + HTTPS
• 初始化 Gitea 并创建管理员账号
• 创建组织（如 rui）
• 从 Gitee 迁移仓库
• 配置 Gitea Actions Runner
• 创建 CI/CD 工作流文件
• 配置 Webhook 通知
• 设置备份策略

---

十、相关文档

• Gitea 官方文档
• Gitea Actions 文档
• OpenCode 多仓库操作指南

---

提示：如果不方便自己部署服务器，也可以考虑 Gitea Cloud（官方托管版）或继续使用 Gitee 免费版（仅代码托管，CI/CD 用其他方案如 Jenkins）。