mirror of
https://github.com/wwiinnddyy/LanMountainDesktop.git
synced 2026-06-20 23:54:26 +08:00
264 lines
7.7 KiB
Markdown
264 lines
7.7 KiB
Markdown
# LanMontainDesktop CI/CD 评估与实现方案
|
||
|
||
## 📊 项目分析
|
||
|
||
### 项目特征
|
||
| 特性 | 详情 |
|
||
|------|------|
|
||
| **框架** | Avalonia 11 (.NET 10) |
|
||
| **主平台** | Windows (x64/x86) |
|
||
| **项目数量** | 2个主项目 + 1个测试项目 |
|
||
| **后端** | ASP.NET Core Web API (RecommendationBackend) |
|
||
| **特殊能力** | 视频壁纸支持 (LibVLC) |
|
||
| **发布方式** | PowerShell脚本 (scripts/package.ps1) |
|
||
|
||
### 与ClassIsland的对比
|
||
|
||
| 方面 | LanMontainDesktop | ClassIsland |
|
||
|------|-------------------|-------------|
|
||
| 平台覆盖 | 🔷 主要Windows | 🟢 多平台(Win/Linux/macOS) |
|
||
| 构建复杂度 | 🔷 中等 | 🔴 很高(专业级) |
|
||
| 发布周期 | 🔷 按需 | 🔴 频繁release |
|
||
| CI配置 | 🔴 无 | 🟢 完整 |
|
||
| 代码质量检查 | 🔴 无 | 🟢 Qodana集成 |
|
||
|
||
## 🎯 推荐方案（渐进式）
|
||
|
||
### **阶段1：基础CI（已完成 ✅）**
|
||
实现核心构建验证，支持每次commit自动检查
|
||
|
||
- ✅ **Build Workflow** - 每次push/PR自动构建
|
||
- Debug + Release 配置
|
||
- 两个项目同时构建
|
||
- 保存build artifacts
|
||
|
||
- ✅ **Code Quality** - 代码检查
|
||
- dotnet format检查
|
||
- 编译警告/错误检测
|
||
- Qodana集成（可选）
|
||
|
||
- ✅ **PR Template** - 统一pull request规范
|
||
- 变更类型分类
|
||
- 测试清单
|
||
- 截图/视频支持
|
||
|
||
- ✅ **Issue Templates** - GitHub问题规范
|
||
- 🐛 Bug Report
|
||
- ✨ Feature Request
|
||
- ⚙️ Configuration Issues
|
||
|
||
### **阶段2：多平台发布自动化（已完成 ✅）**
|
||
完整的跨平台构建与自动化发布
|
||
|
||
- ✅ **多平台Release Workflow** - Git tag触发全平台构建
|
||
- 🪟 **Windows**: x64 + x86 自包含可执行文件
|
||
- 🐧 **Linux**: x64 tar.gz包（支持自定义架构）
|
||
- 🍎 **macOS**: x64 + arm64 (Apple Silicon) tar.gz包
|
||
- 自动版本号更新
|
||
- 统一artifact命名
|
||
- GitHub Release自动创建详细说明
|
||
|
||
- ✅ **构建脚本支持**
|
||
- PowerShell脚本处理Windows特定依赖
|
||
- Bash脚本统一处理Linux/macOS
|
||
- .gitattributes确保行尾兼容
|
||
|
||
- ✅ **灵活的手动触发**
|
||
- 支持选择性构建（仅Windows/Linux/macOS）
|
||
- 预发布标记支持
|
||
- 版本号手动指定
|
||
|
||
- ✅ **Issue Management** - 自动化问题管理
|
||
- 自动标记过期问题
|
||
- 自动关闭无活动PR
|
||
- 可自定义时间阈值
|
||
|
||
### **阶段3：建议（未来优化）**
|
||
- 🔲 **安装程序生成** - MSI/EXE (Windows), .deb (Linux), DMG (macOS)
|
||
- 🔲 **代码签名** - macOS notarization, Windows签名
|
||
- 🔲 **AppImage/Snap** - Linux现代打包格式
|
||
- 🔲 **Docker镜像** - 后端容器化
|
||
- 🔲 **测试覆盖报告** - Codecov集成
|
||
- 🔲 **性能基准测试** - PR性能对比
|
||
- 🔲 **自动更新检查** - 依赖版本检查
|
||
|
||
## 🔧 创建的GitHub工作流与脚本
|
||
|
||
### 工作流文件（4个）
|
||
|
||
1. **[Build & Test](/.github/workflows/build.yml)** - 核心构建验证
|
||
- 在每个push和PR时自动运行
|
||
- Debug + Release 两种配置
|
||
- 支持两个项目同时构建
|
||
- 保存build artifacts用于检查
|
||
|
||
2. **[Code Quality](/.github/workflows/code-quality.yml)** - 代码质量检查
|
||
- 代码格式检查(`dotnet format`)
|
||
- 编译错误/警告检测
|
||
- 预留Qodana集成位置（可选）
|
||
|
||
3. **[Release & Publish (多平台)](/.github/workflows/release.yml)** ⭐ 升级版
|
||
- **Windows**: x64 + x86
|
||
- **Linux**: x64
|
||
- **macOS**: x64 + arm64 (Apple Silicon)
|
||
- 基于Git标签自动触发
|
||
- 支持手动选择构建平台
|
||
- 自动创建GitHub Release
|
||
|
||
4. **[Issue Management](/.github/workflows/issue-management.yml)** - 自动化问题管理
|
||
- 每日标记过期问题
|
||
- 自动关闭无活动PR
|
||
- 可自定义时间阈值
|
||
|
||
### 构建脚本
|
||
|
||
| 脚本 | 平台 | 功能 |
|
||
|------|------|------|
|
||
| `LanMontainDesktop\scripts\package.ps1` | Windows | 现有PowerShell打包脚本 |
|
||
| `scripts\build.sh` | Linux/macOS | 新增跨平台构建脚本 |
|
||
|
||
### 配置文件
|
||
|
||
| 文件 | 用途 |
|
||
|------|------|
|
||
| `.gitattributes` | 行尾处理，确保跨平台兼容 |
|
||
| `.github/CODEOWNERS` | 代码所有权定义 |
|
||
| `.github/pull_request_template.md` | PR提交规范 |
|
||
| `.github/ISSUE_TEMPLATE/*.md` | Issue模板 |
|
||
| `.github/WORKFLOWS_GUIDE.md` | 工作流使用指南 |
|
||
| `.github/MULTIPLATFORM_BUILD.md` | 多平台构建详细指南 ⭐ |
|
||
|
||
## 🚀 快速开始
|
||
|
||
### 1. 验证工作流正常运行
|
||
```bash
|
||
# Push到main分支
|
||
git add .github/
|
||
git commit -m "feat: Add GitHub CI/CD workflows"
|
||
git push origin main
|
||
|
||
# 检查GitHub Actions是否自动运行
|
||
# https://github.com/YOUR_ORG/LanMontainDesktop/actions
|
||
```
|
||
|
||
### 2. 创建第一个Release（可选）
|
||
```bash
|
||
# 本地修改版本号（如果需要）
|
||
# 然后创建tag
|
||
git tag v1.0.0
|
||
git push origin v1.0.0
|
||
|
||
# GitHub Actions会自动：
|
||
# 1. 更新版本号
|
||
# 2. 构建Release版本
|
||
# 3. 创建可执行文件
|
||
# 4. 生成GitHub Release
|
||
```
|
||
|
||
### 3. 配置分支保护规则（推荐）
|
||
在 GitHub > Settings > Branches > Branch Protection Rules：
|
||
- 要求CI检查通过再merge
|
||
- 要求PR审查
|
||
- 要求代码最新
|
||
|
||
## ⚙️ 配置选项
|
||
|
||
### 可选：启用Qodana代码分析
|
||
|
||
1. 访问 https://qodana.cloud
|
||
2. 注册并创建organization token
|
||
3. 在GitHub > Settings > Secrets > Actions 中添加：
|
||
- `QODANA_TOKEN`
|
||
- `QODANA_ENDPOINT=https://qodana.cloud`
|
||
4. 在 `.github/workflows/code-quality.yml` 中取消Qodana步骤注释
|
||
|
||
### 自定义构建参数
|
||
|
||
编辑 `.github/workflows/` 中的yml文件：
|
||
- `DOTNET_VERSION` - 改变.NET版本
|
||
- 分支列表 - 改变监控的分支
|
||
- 矩阵配置 - 添加更多构建配置
|
||
|
||
## 📊 工作流对比与选择
|
||
|
||
### Build日语言表
|
||
| 工作流 | 触发条件 | 运行时间 | 成本 |
|
||
|--------|---------|--------|------|
|
||
| Build | 每个push/PR | ~2-3分钟 | 低 |
|
||
| Code Quality | PR/push | ~2-3分钟 | 低 |
|
||
| Release | Tag push | ~5-10分钟 | 中 |
|
||
| Issue Mgmt | 每天1次 | ~1分钟 | 很低 |
|
||
|
||
### 预计月度GitHub Actions使用
|
||
- **小项目**(<5贡献者): 100-200 runner hours
|
||
- **中等项目**(5-20贡献者): 300-500 runner hours
|
||
- **大项目**（>20贡献者): 800+ runner hours
|
||
|
||
> 💡 **免费额度**: 2000 runner hours/月 (对大多数开源项目足够)
|
||
|
||
## 🔍 故障排查
|
||
|
||
### 工作流不运行？
|
||
- [ ] 检查 `.github/workflows/*.yml` 语法（YAML缩进）
|
||
- [ ] 确认分支名称配置正确
|
||
- [ ] 查看Actions标签查看错误日志
|
||
- [ ] 检查分支保护规则是否冲突
|
||
|
||
### 构建失败？
|
||
```bash
|
||
# 本地重现CI环境
|
||
dotnet clean
|
||
dotnet restore
|
||
dotnet build LanMontainDesktop/LanMontainDesktop.csproj -c Release
|
||
```
|
||
|
||
### PR检查无法通过？
|
||
1. 本地运行 `dotnet format`
|
||
2. 确保没有编译警告
|
||
3. 所有测试通过
|
||
|
||
## 📚 参考资源
|
||
|
||
- [.github/WORKFLOWS_GUIDE.md](.github/WORKFLOWS_GUIDE.md) - 详细使用指南
|
||
- [GitHub Actions文档](https://docs.github.com/actions)
|
||
- [ClassIsland CI/CD参考](https://github.com/ClassIsland/ClassIsland/.github/workflows)
|
||
- [Avalonia发布指南](https://docs.avaloniaui.net/docs/deployment)
|
||
|
||
## ✅ 完成清单
|
||
|
||
- [x] 构建工作流
|
||
- [x] 代码质量检查
|
||
- [x] 发布自动化
|
||
- [x] Issue管理
|
||
- [x] PR模板
|
||
- [x] Issue模板
|
||
- [x] CODEOWNERS定义
|
||
- [x] 完整文档
|
||
- [ ] 调试并测试所有工作流
|
||
- [ ] 配置Qodana（可选）
|
||
- [ ] 配置分支保护规则（推荐）
|
||
|
||
## 🎓 下一步建议
|
||
|
||
1. **立即做**
|
||
- 推送所有文件到GitHub
|
||
- 验证工作流运行成功
|
||
- 配置分支保护规则
|
||
|
||
2. **本周内**
|
||
- 在贡献指南中记录工作流
|
||
- 团队成员熟悉PR流程
|
||
- 测试第一个Release构建
|
||
|
||
3. **后续优化**
|
||
- 基于实际运行数据调整参数
|
||
- 添加额外的检查（危险代码扫描等）
|
||
- 集成代码覆盖率报告
|
||
- 准备多平台构建（需要）
|
||
|
||
---
|
||
|
||
**创建时间**: 2026-03-04
|
||
**参考项目**: ClassIsland
|
||
**目标**: 提高代码质量和发布效率 🚀
|