# 自建 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 环境的服务器

```yaml
# 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
```

**启动命令**：
```bash
# 创建目录
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 环境的裸机

```bash
# 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：一键安装脚本（最简单）

```bash
# 下载官方安装脚本
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 配置

```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）

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

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

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

---

## 四、从 Gitee 迁移到 Gitea

### 4.1 迁移单个仓库

```bash
# 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 批量迁移（所有仓库）

```bash
#!/bin/bash
# migrate.sh

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

REPOS=("rui-framework" "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` 中配置：

```ini
[actions]
ENABLED = true
DEFAULT_ACTIONS_URL = github
```

### 5.2 注册 Runner

```bash
# 获取注册令牌（在 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 工作流

```yaml
# 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 工作流

```yaml
# rui-framework/.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 禁用公开注册（私有化）

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

---

## 七、备份策略

### 7.1 自动备份脚本

```bash
#!/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：
```bash
# 每天凌晨 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 官方文档](https://docs.gitea.com/)
- [Gitea Actions 文档](https://docs.gitea.com/usage/actions/overview)
- [OpenCode 多仓库操作指南](../docs/opencode-workflow.md)

---

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