Skip to content

项目结构与版本管理.md

Latest commit

 

History

History
138 lines (113 loc) · 4.14 KB

项目结构与版本管理.md

File metadata and controls

138 lines (113 loc) · 4.14 KB
Raw

项目结构与版本管理

📁 项目目录结构

baidu-autosave/
├── backend/                    # 后端 Python 应用
│   ├── web_app.py             # Flask Web 应用主文件
│   ├── storage.py             # 百度网盘存储操作
│   ├── scheduler.py           # 任务调度器
│   ├── notify.py              # 通知服务
│   └── utils.py               # 工具函数
├── frontend/                   # Vue 3 前端源码
│   ├── src/                   # 源代码目录
│   │   ├── components/        # Vue 组件
│   │   ├── views/             # 页面组件
│   │   ├── stores/            # Pinia 状态管理
│   │   ├── services/          # API 服务层
│   │   ├── types/             # TypeScript 类型定义
│   │   └── utils/             # 前端工具函数
│   ├── package.json           # 前端依赖和版本配置
│   └── vite.config.ts         # Vite 构建配置
├── static/                     # 前端构建产物（生产环境）
│   ├── index.html
│   ├── assets/                # JS/CSS 资源文件
│   └── favicon/               # 网站图标
├── config/                     # 应用配置文件
│   ├── config.json
│   └── config.template.json
├── .github/workflows/          # CI/CD 配置
│   └── docker-build-auto.yml  # 自动构建和发布
├── docs/                       # 项目文档
├── Dockerfile                  # Docker 构建配置
└── docker-compose.yml         # Docker Compose 配置

🔧 版本管理机制

版本号来源

  • 主版本号：存储在 frontend/package.json 中
  • 格式：采用语义化版本规范 (MAJOR.MINOR.PATCH)
  • 当前版本：1.1.3

版本更新命令

开发环境（手动更新）

# 进入前端目录
cd frontend

# 补丁版本 (1.1.3 -> 1.1.4)
npm run version:patch

# 次版本 (1.1.3 -> 1.2.0)  
npm run version:minor

# 主版本 (1.1.3 -> 2.0.0)
npm run version:major

这些命令会自动：

  1. 更新 package.json 中的版本号
  2. 创建 Git 提交和标签
  3. 推送到远程仓库
  4. 触发自动构建流程

自动构建与发布

触发条件

当以下文件发生变化时，会自动触发 CI/CD：

  • frontend/package.json - 版本号变更
  • frontend/src/** - 前端源码变更
  • web_app.py - 后端主文件变更
  • storage.py - 存储模块变更
  • scheduler.py - 调度器变更
  • notify.py - 通知模块变更
  • utils.py - 工具函数变更

构建流程

  1. 版本检测：比较当前和上一次提交的版本号
  2. Docker 构建：多阶段构建（前端 + 后端）
  3. 镜像推送：推送到 Docker Hub
  4. 创建 Release：在 GitHub 创建版本发布

输出产物

  • Docker 镜像标签：
    • v1.1.3 - 具体版本号
    • latest - 最新版本
  • GitHub Release：Release v1.1.3

🚀 部署方式

开发环境

# 后端开发
python web_app.py

# 前端开发  
cd frontend && npm run dev

生产环境

# Docker 构建
docker build -t baidu-autosave .

# Docker 运行
docker run -p 5000:5000 baidu-autosave

# 或使用 Docker Compose
docker-compose up

📋 最佳实践

版本发布流程

  1. 开发完成：在 feature 分支完成开发
  2. 合并到主分支：创建 PR 并合并到 main
  3. 更新版本号：运行版本更新命令
  4. 自动构建：CI/CD 自动构建和发布
  5. 验证部署：检查 Docker 镜像和 GitHub Release

版本号规范

  • 主版本（Major）：破坏性变更，API 不兼容
  • 次版本（Minor）：新功能添加，向后兼容
  • 补丁版本（Patch）：bug 修复，向后兼容

目录规范

  • 前端代码：统一放在 frontend/ 目录
  • 后端代码：根目录下的 Python 文件
  • 构建产物：自动生成到 static/ 目录
  • 配置文件：统一放在 config/ 目录

这种结构确保了：

  • ✅ 前后端分离开发
  • ✅ 自动化版本管理
  • ✅ 一键部署发布
  • ✅ 清晰的项目组织