bigscreen/DEVOPS_INTEGRATION.md

🚀 BigScreen DevOps 完整集成方案

📊 架构总览

┌─────────────────────────────────────────────────────────────────────┐
│                         开发工作流                                    │
└─────────────────────────────────────────────────────────────────────┘
                                 │
                    ┌────────────┼────────────┐
                    │                         │
            ┌───────▼────────┐       ┌───────▼────────┐
            │   代码开发      │       │   任务管理      │
            │   (VS Code)    │◄─────►│   (Plane)      │
            └───────┬────────┘       └───────┬────────┘
                    │                        │
                    │ git push               │ 自动同步
                    │                        │
            ┌───────▼────────┐               │
            │   版本控制      │               │
            │   Gitea        │               │
            │  192.168.1.83  │               │
            │     :33000     │               │
            └───────┬────────┘               │
                    │                        │
                    │ webhook                │
                    │                        │
            ┌───────▼────────────────────────▼─────┐
            │          Gitea Actions               │
            │          CI/CD 工作流                 │
            ├──────────────────────────────────────┤
            │  • 代码检查 (Black, Ruff, ESLint)     │
            │  • 单元测试 (Pytest, Vitest)          │
            │  • 构建镜像 (Docker Build)            │
            │  • 推送镜像 (Registry Push)           │
            │  • 部署应用 (Kubernetes)              │
            │  • 同步状态 (Plane API)               │
            └───────┬──────────────────┬───────────┘
                    │                  │
        ┌───────────▼──────┐  ┌───────▼────────┐
        │  镜像仓库         │  │  项目管理       │
        │  Registry        │  │  Plane         │
        │  192.168.1.83    │  │  192.168.1.83  │
        │    :15000        │  │    :8088       │
        └───────┬──────────┘  └────────────────┘
                │
                │ pull images
                │
        ┌───────▼──────────┐
        │  生产部署         │
        │  Kubernetes      │
        └──────────────────┘

🎯 服务端口总览

服务	地址	用途
Gitea	http://192.168.1.83:33000	Git 代码托管 + CI/CD
Plane	http://192.168.1.83:8088	项目管理 + 任务跟踪
Registry	http://192.168.1.83:15000	Docker 镜像仓库
Registry Cache	http://192.168.1.83:15001	镜像缓存加速
Backend API	http://192.168.1.83:8000	FastAPI 后端服务
Frontend	http://192.168.1.83:5173	Vue3 前端界面

🔧 快速开始

步骤 1: 获取 Plane API Key

# 1. 访问 Plane
open http://192.168.1.83:8088/ljwx

# 2. 登录后进入设置 → API Tokens
# 3. 创建新的 API Token 并复制

步骤 2: 设置 Plane 项目

# 导出 API Key
export PLANE_API_KEY="plane_api_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

# 运行设置脚本
cd /Users/brunogao/work/codes/templates/bigscreen
./scripts/setup_plane_project.sh

步骤 3: 配置 Gitea Secret

# 访问 Gitea 仓库设置
open http://192.168.1.83:33000/gao/bigscreen/settings/secrets

# 添加 Secret:
# Name: PLANE_API_KEY
# Value: 粘贴你的 Plane API Key

步骤 4: 测试集成

cd /Users/brunogao/work/codes/templates/bigscreen

# 提交新的集成配置
git add .
git commit -m "feat: 集成 Plane 项目管理系统"
git push origin main

# 查看 Actions 执行
open http://192.168.1.83:33000/gao/bigscreen/actions

# 等待几秒后查看 Plane Issue
open http://192.168.1.83:8088/ljwx/projects/bigscreen/issues

📋 CI/CD 工作流

1. 代码检查和测试 (ci.yaml)

触发条件: Push 到 main/develop 分支，或 PR 创建

执行步骤:

• ✅ Python 代码格式检查 (Black)
• ✅ Python 代码质量检查 (Ruff)
• ✅ Python 类型检查 (Mypy)
• ✅ Python 单元测试 (Pytest)
• ✅ JavaScript 代码检查 (ESLint)
• ✅ TypeScript 类型检查
• ✅ 前端单元测试 (Vitest)

2. 构建并推送镜像 (build-and-push.yaml)

触发条件: Push 到 main 分支，或创建版本标签

执行步骤:

• 🏗️ 构建后端 Docker 镜像
• 🏗️ 构建前端 Docker 镜像
• 📦 推送到 Registry (192.168.1.83:15000)
• 🏷️ 标签策略:
  • latest - 最新版本
  • main-{commit} - 主分支提交
  • v* - 版本标签

3. 自动部署 (deploy.yaml)

触发条件: Push 到 main 分支，或手动触发

执行步骤:

• 🚀 部署到开发环境
• 🔄 滚动更新 Kubernetes
• ✅ 健康检查
• 📊 部署验证

4. Plane 集成 (plane-integration.yaml)

触发条件: 任何代码变更或工作流完成

执行步骤:

• 📝 创建构建记录 Issue
• 📊 更新构建状态
• 🔗 添加相关链接
• 📈 生成构建报告

🎨 Plane 项目管理实践

Issue 类型

类型	前缀	优先级	标签
构建记录	🏗️	Low	ci-cd, build
Pull Request	🔀	Medium	pull-request, review
Bug 修复	🐛	High	bug, hotfix
新功能	✨	Medium	feature
部署任务	🚀	High	deploy

工作流状态

Backlog → In Progress → Testing → Done
  ↓           ↓           ↓         ↓
待办       开发中      测试中    已完成

标签体系

技术栈:

• backend - 后端相关
• frontend - 前端相关
• database - 数据库相关
• devops - DevOps 相关

类型:

• bug - Bug 修复
• feature - 新功能
• enhancement - 功能增强
• documentation - 文档更新

优先级:

• critical - 紧急
• high - 高优先级
• medium - 中优先级
• low - 低优先级

🔄 开发工作流示例

场景 1: 开发新功能

# 1. 在 Plane 创建功能 Issue
#    标题: ✨ 添加用户导出功能
#    优先级: Medium
#    标签: feature, backend

# 2. 创建功能分支
git checkout -b feature/user-export

# 3. 开发功能
# ... 编码 ...

# 4. 提交代码
git add .
git commit -m "feat: 添加用户数据导出接口"
git push origin feature/user-export

# 5. 创建 PR (Gitea)
#    CI 自动运行测试
#    Plane 自动创建 PR 跟踪 Issue

# 6. Code Review 后合并
#    自动构建镜像
#    自动部署到开发环境
#    Plane Issue 自动更新状态

# 7. 验证后关闭 Issue

场景 2: 修复 Bug

# 1. 在 Plane 创建 Bug Issue
#    标题: 🐛 用户登录超时问题
#    优先级: High
#    标签: bug, backend

# 2. 创建修复分支
git checkout -b hotfix/login-timeout

# 3. 修复 Bug
# ... 编码和测试 ...

# 4. 提交并推送
git add .
git commit -m "fix: 修复用户登录超时问题"
git push origin hotfix/login-timeout

# 5. 创建 PR 并合并
#    CI 运行完整测试
#    构建并推送修复版本镜像

# 6. 紧急部署
./scripts/deploy_hotfix.sh

# 7. Plane Issue 标记为 Done

📊 监控和报告

CI/CD 仪表板

访问 Gitea Actions 查看构建历史:

http://192.168.1.83:33000/gao/bigscreen/actions

Plane 项目看板

查看任务进度和团队协作:

http://192.168.1.83:8088/ljwx/projects/bigscreen

镜像仓库

查看 Docker 镜像版本:

# 列出后端镜像
curl http://192.168.1.83:15000/v2/bigscreen-backend/tags/list

# 列出前端镜像
curl http://192.168.1.83:15000/v2/bigscreen-frontend/tags/list

🛠️ 常用命令

Git 操作

# 查看状态
git status

# 创建分支
git checkout -b feature/new-feature

# 提交代码
git add .
git commit -m "feat: 添加新功能"
git push origin feature/new-feature

Docker 操作

# 拉取镜像
docker pull 192.168.1.83:15000/bigscreen-backend:latest

# 查看本地镜像
docker images | grep bigscreen

# 运行容器
docker run -d -p 8000:8000 192.168.1.83:15000/bigscreen-backend:latest

Plane API 测试

# 获取项目信息
curl -X GET http://192.168.1.83:8088/api/v1/workspaces/ljwx/projects/bigscreen/ \
  -H "x-api-key: YOUR_API_KEY"

# 创建 Issue
curl -X POST http://192.168.1.83:8088/api/v1/workspaces/ljwx/projects/PROJECT_ID/issues/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "测试 Issue",
    "description_html": "<p>这是一个测试</p>",
    "priority": "medium"
  }'

🆘 故障排查

CI/CD 失败

1. 检查 Actions 日志
2. 验证环境变量配置
3. 确认 Registry 可访问性
4. 检查磁盘空间

Plane 同步失败

1. 验证 API Key 有效性
2. 检查网络连接
3. 查看 plane_sync.py 日志
4. 确认项目 ID 正确

镜像推送失败

1. 检查 Registry 服务状态
2. 验证认证信息
3. 确认网络可达性
4. 检查磁盘空间

📚 参考文档

• Gitea Actions 文档
• Plane API 文档
• Docker Registry API
• Kubernetes 部署

🎯 下一步计划

• 添加自动化测试覆盖率报告
• 集成 SonarQube 代码质量分析
• 实现蓝绿部署策略
• 添加性能测试流程
• 集成 Prometheus + Grafana 监控
• 实现自动回滚机制