一、 分支管理策略

采用基于 GitLab Flow 的简化版分支模型：

二、 标准开发流程

1. 开启新任务

git checkout dev
git pull origin dev
git checkout -b feature/your-feature-name

2. 开发并本地验证

• 完成后端代码及插件 plugin/engine_group 修改。
• 运行单元测试：go test ./...
• 生成 Swagger 文档：go run github.com/swaggo/swag/cmd/swag@v1.16.6 init

3. 合并至 dev

开发完成后，发起 MR（Merge Request）或手动合并：

git checkout dev
git merge feature/your-feature-name
git push origin dev

• CI 行为：触发 dev 流水线，运行 verify 阶段，确保集成代码无误。

4. 发布至 main (预发布)

当 dev 稳定后，准备合入主分支。注意：合并前建议清理历史。

• 清理历史 (Squash)：如果 dev 有大量 fix: xxx 提交，建议使用 git reset --soft 压缩为一个整洁的提交。
• 合并操作：
  bash 复制代码

  git checkout main
  git merge dev
  git push origin main

• CI 行为：触发 main 流水线。此时会进行全平台构建，但部署任务（Deploy）为 Manual（手动触发）。

5. 正式发布

这是触发生产环境更新的关键一步：

git tag -a v1.1.0 -m "Release v1.1.0: 优化插件加载与CI流程"
git push origin v1.1.0

• CI 行为：触发 Tag 流水线。部署任务变为 on_success（自动）。

三、 CI/CD 流水线

流水线通过 .gitlab-ci.yml 驱动，分为四个阶段：

1. Prepare

• 任务：swagger:generate
• 逻辑：动态生成 API 文档，作为 Artifacts 传递给后续阶段。

2. Verify

• 任务：go:test
• 逻辑：执行所有包的单元测试。

3. Build

• 任务：web:build (Node.js) & build:backend (Go Matrix)
• 逻辑：
  • Web：编译前端 dist。
  • Go：通过矩阵编译 linux/amd64, linux/arm64, windows/amd64, darwin/arm64 四个版本。
  • 注入版本：编译时通过 -ldflags 将 Tag 或 Commit SHA 注入 main.Version。

4. Deploy

• 目标：服务器 (/opt/yuelai-engine)
• 安全：使用 GitLab 文件变量 SSH_PRIVATE_KEY 进行身份验证。
• 规则：
  • Tag 触发：全自动部署。
  • Main 推送：手动点击部署，用于临时紧急发布。

四、 常用维护指令

1. 强制清理主分支历史

如果你在 main 上留下了太多无效提交：

git reset --soft <target-commit-id>
git commit -m "feat: 重新整理 CI/CD 与部署配置"
git push origin main --force

如果是在 dev 分支操作的，那么可以 git checkout main 然后 git reset --hard dev 将 main 分支强制指向 dev 分支，最后再推送即可。

2. 同步删除本地与远端 Tag

git tag -d v1.1.0b
git push origin --delete v1.1.0b

也可以在 git push origin 时加上 --prune 参数，清除本地那些在远端已经不存在的分支引用。

3. 子模块更新

如果插件模块有更新：

git submodule update --remote --recursive
git add .
git commit -m "chore: 升级插件模块版本"

五、 GitLab CI/CD 环境变量配置

请确保 GitLab 项目后台已配置以下变量：

• SSH_HOST: 服务器的 IP 地址。
• SSH_USER: 服务运行用户。
• SSH_PRIVATE_KEY: 私钥的 GitLab 文件变量。
• DEPLOY_BACKEND_PATH: 后端存放路径。
• more...

注意事项

如果项目仓库中包含子模块（Git Submodule），则需要在子模块仓库中为主项目仓库配置 CI/CD 权限：

https://docs.gitlab.com/18.10/ci/jobs/ci_job_token/#gitlab-cicd-job-token-security

CI 过程中使用 CI_JOB_TOKEN 替换 SSH 地址，无需在 Runner 中额外配置子模块的访问权限。