Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
94 changes: 94 additions & 0 deletions .cursor/rules/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,94 @@
# Cursor Rules 索引

本目录包含了为 Dockerfiles 项目创建的所有 Cursor Rules,帮助开发者更好地理解和使用项目。

## 规则文件列表

### 1. [project-overview.mdc](mdc:project-overview.mdc) - 项目概览

- **适用范围**: 始终应用
- **内容**: 项目整体结构、技术栈、构建系统等概览信息
- **用途**: 帮助开发者快速了解项目全貌

### 2. [dockerfile-patterns.mdc](mdc:dockerfile-patterns.mdc) - Dockerfile 模式

- **适用范围**: 所有 Dockerfile 相关文件
- **内容**: 命名规范、结构模式、最佳实践
- **用途**: 指导 Dockerfile 的编写和维护

### 3. [ci-cd-workflow.mdc](mdc:ci-cd-workflow.mdc) - CI/CD 工作流

- **适用范围**: GitHub Actions 和构建脚本
- **内容**: 构建流程、环境配置、脚本说明
- **用途**: 理解自动化构建和部署流程

### 4. [nginx-patterns.mdc](mdc:nginx-patterns.mdc) - Nginx 镜像模式

- **适用范围**: Nginx 相关镜像
- **内容**: 特殊功能、环境变量、脚本说明
- **用途**: 了解 Nginx 镜像的高级功能

### 5. [powershell-combinations.mdc](mdc:powershell-combinations.mdc) - PowerShell 镜像组合

- **适用范围**: PowerShell 相关镜像
- **内容**: 组合模式、版本策略、使用场景、pnpm 支持
- **用途**: 选择合适的 PowerShell 镜像组合,包括现代前端开发环境

### 6. [database-patterns.mdc](mdc:database-patterns.mdc) - 数据库镜像模式

- **适用范围**: 数据库和中间件镜像
- **内容**: 版本支持、配置特点、最佳实践
- **用途**: 了解各种数据库镜像的特性

### 7. [development-tools.mdc](mdc:development-tools.mdc) - 开发工具镜像

- **适用范围**: 开发环境相关镜像
- **内容**: .NET、Node.js、Python、Android 等开发工具
- **用途**: 选择合适的开发环境镜像

### 8. [operations-tools.mdc](mdc:operations-tools.mdc) - 运维工具镜像

- **适用范围**: 运维和部署相关镜像
- **内容**: 容器管理、代码管理、网络服务等工具
- **用途**: 了解运维工具镜像的功能

### 9. [architecture-principles.mdc](mdc:architecture-principles.mdc) - 架构设计原则

- **适用范围**: 始终应用
- **内容**: 设计理念、架构模式、技术选型原则
- **用途**: 理解项目的整体设计思路

## 使用建议

### 新用户

1. 首先阅读 [project-overview.mdc](mdc:project-overview.mdc) 了解项目概览
2. 查看 [architecture-principles.mdc](mdc:architecture-principles.mdc) 理解设计理念
3. 根据具体需求查看相应的专项规则

### 开发者

1. 遵循 [dockerfile-patterns.mdc](mdc:dockerfile-patterns.mdc) 的编写规范
2. 参考 [ci-cd-workflow.mdc](mdc:ci-cd-workflow.mdc) 的构建流程
3. 使用相应的专项规则指导具体工作

### 运维人员

1. 重点关注 [operations-tools.mdc](mdc:operations-tools.mdc) 的运维工具
2. 了解 [database-patterns.mdc](mdc:database-patterns.mdc) 的数据库配置
3. 参考 [nginx-patterns.mdc](mdc:nginx-patterns.mdc) 的 Web 服务配置

## 规则维护

- 规则文件使用 Markdown 格式编写
- 文件名使用 kebab-case 命名规范
- 每个规则文件都包含清晰的适用范围和用途说明
- 定期更新规则内容,保持与项目发展同步

## 反馈和建议

如果您对规则内容有任何建议或发现需要更新的地方,请:

1. 在项目仓库中提出 Issue
2. 提交 Pull Request 进行改进
3. 通过其他方式联系项目维护者
125 changes: 125 additions & 0 deletions .cursor/rules/architecture-principles.mdc
Original file line number Diff line number Diff line change
@@ -0,0 +1,125 @@
# Dockerfiles 项目架构设计原则

## 项目愿景

构建一个全面、稳定、易用的 Docker 基础镜像集合,为开发、测试、生产环境提供标准化的容器化解决方案。

## 核心设计原则

### 1. 多平台支持

- **优先支持** Linux ARM64 和 AMD64 平台
- **扩展支持** Windows AMD64 平台
- **统一体验** 跨平台一致的镜像功能

### 2. 版本管理策略

- **LTS 优先** - 优先选择长期支持版本
- **向下兼容** - 保持版本间的兼容性
- **渐进升级** - 提供平滑的升级路径

### 3. 功能组合模式

- **基础镜像** - 提供核心功能的最小集合
- **功能扩展** - 通过标签组合添加特定功能
- **按需选择** - 用户可根据需求选择合适的镜像

### 4. 安全性和稳定性

- **安全更新** - 定期更新基础镜像和依赖
- **漏洞修复** - 及时修复已知安全问题
- **稳定发布** - 经过充分测试的稳定版本

## 架构模式

### 分层架构

```
应用层 (Application)
服务层 (Service) - Nginx, .NET, Node.js 等
运行时层 (Runtime) - .NET, Node.js, Python 等
操作系统层 (OS) - Ubuntu, Debian, Alpine 等
```

### 组合模式

- **单一职责** - 每个镜像专注于特定功能
- **功能组合** - 通过标签组合实现复杂需求
- **依赖注入** - 通过环境变量配置运行时行为

### 扩展机制

- **脚本注入** - 支持运行时脚本执行
- **配置注入** - 支持环境变量配置
- **插件架构** - 支持功能模块扩展

## 技术选型原则

### 基础镜像选择

- **Ubuntu** - 功能完整,适用于开发环境
- **Debian** - 稳定可靠,适用于生产环境
- **Alpine** - 轻量级,适用于工具类服务

### 版本策略

- **主版本** - 保持与上游项目同步
- **次版本** - 功能增强和安全更新
- **补丁版本** - 问题修复和性能优化

### 平台支持

- **ARM64** - 支持 ARM 架构,适应云原生趋势
- **AMD64** - 支持 x86_64 架构,保持广泛兼容性
- **Windows** - 支持 Windows 容器,扩展使用场景

## 质量保证

### 构建流程

- **自动化构建** - GitHub Actions 持续集成
- **多平台测试** - 跨平台功能验证
- **镜像验证** - 构建后功能测试

### 发布策略

- **版本标签** - 语义化版本管理
- **多仓库同步** - Docker Hub + 阿里云镜像
- **回滚机制** - 支持快速版本回退

### 监控和维护

- **使用统计** - 镜像下载和使用情况
- **问题反馈** - 用户问题收集和解决
- **定期更新** - 安全补丁和功能更新

## 最佳实践指导

### 镜像使用

1. **选择合适版本** - 根据项目需求选择镜像版本
2. **配置管理** - 使用环境变量进行配置
3. **资源优化** - 合理设置资源限制
4. **安全加固** - 启用必要的安全特性

### 镜像构建

1. **遵循标准** - 使用项目定义的命名和结构规范
2. **功能验证** - 构建后验证镜像功能
3. **文档维护** - 及时更新 README 说明
4. **测试覆盖** - 编写必要的测试用例

### 贡献指南

1. **代码规范** - 遵循项目的编码规范
2. **测试要求** - 新功能需要包含测试
3. **文档更新** - 同步更新相关文档
4. **版本管理** - 遵循语义化版本规范
description:
globs:
alwaysApply: false

---
78 changes: 78 additions & 0 deletions .cursor/rules/ci-cd-workflow.mdc
Original file line number Diff line number Diff line change
@@ -0,0 +1,78 @@
# CI/CD 工作流规则

## GitHub Actions 工作流

### 主要工作流文件

- `buildx.yml` - 主要的构建和推送工作流

### 触发条件

- **Push** - 推送到 master 分支时触发
- **PR** - 创建 Pull Request 时触发
- **路径过滤** - 仅当 `src/**` 或 `build/**` 目录有变更时触发

## 构建流程

### 1. Windows 构建阶段

- 运行在 `windows-latest` 环境
- 登录 Docker Hub
- 执行 `build-push.ps1` 脚本

### 2. Linux 构建阶段

- 运行在 `ubuntu-22.04` 环境
- 依赖 Windows 构建完成
- 登录 Docker Hub
- 执行 `build-push.ps1` 脚本

### 3. 阿里云同步阶段

- Windows 和 Linux 环境分别执行
- 登录阿里云容器镜像服务
- 执行 `build-sync-manifest.ps1` 脚本

## 环境变量配置

### Docker Hub 配置

```yaml
DOCKERHUB_USERNAME: ${{ vars.DOCKERHUB_USERNAME }}
DOCKERHUB_TOKEN: ${{ secrets.DOCKERHUB_TOKEN }}
```

### 阿里云配置

```yaml
ALIYUN_DOCKERHUB: ${{ vars.ALIYUN_DOCKERHUB }}
ALIYUN_DOCKERHUB_USERNAME: ${{ vars.ALIYUN_DOCKERHUB_USERNAME }}
ALIYUN_DOCKERHUB_TOKEN: ${{ secrets.ALIYUN_DOCKERHUB_TOKEN }}
```

## 构建脚本

### 主要脚本文件

- `build-push.ps1` - 构建并推送到 Docker Hub
- `build-sync-manifest.ps1` - 同步镜像到其他仓库
- `build-images-define.ps1` - 定义要构建的镜像列表

### 构建配置

- 支持多平台构建 (linux/arm64, linux/amd64, windows/amd64)
- 自动标签管理
- 镜像推送和同步

## 最佳实践

1. **依赖管理** - 使用 `needs` 确保构建顺序
2. **错误处理** - 构建失败时及时通知
3. **资源优化** - 合理分配构建资源
4. **安全考虑** - 使用 GitHub Secrets 存储敏感信息
5. **监控告警** - 构建状态监控和通知
description:
globs:
alwaysApply: false

---
Loading