docs: 迁移 spring-ai 通用文档到 rui-docs

从 docs-local 迁移以下文档： - backend/guides/: AI开发环境配置、Nacos配置、GitNexus指南、OpenCode工作流等 - backend/templates/: Superpowers设计模板、计划模板、审查清单 - backend/config-templates/: 应用配置模板、Nacos配置 - backend/design/: 数据库表结构规划 - backend/specs/: 项目文档治理、MQ统一推送设计 - backend/: 代码分析报告、Feign分析报告、文档治理报告 - frontend/design/: Admin-UI分模块打包设计
2026-06-04 09:31:24 +08:00
parent 2e38c53434
commit 19de7e24ec
36 changed files with 5872 additions and 0 deletions
@@ -0,0 +1,480 @@
+# 自建 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=("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` 中配置：
+
+```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
+# 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 禁用公开注册（私有化）
+
+```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）。