vifo
a7f3ee3565
同步仓库名称变更，涉及 16 个文件 66 处引用： - ai-skills: 菜单配置 - backend/guides: AI操作手册、环境配置、部署、gitnexus、opencode 工作流 - backend: 模块创建规则、通信规范、协作工作流、实施规范 - frontend: 收银设计、管理后台实施计划 - standards: 数据库设计规范
481 lines
11 KiB
Markdown
481 lines
11 KiB
Markdown
# 自建 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）。
|