bigscreen/QUICKSTART_DEVOPS.md

🚀 BigScreen DevOps 快速上手指南

5 分钟完成 Plane + Gitea + Registry 完整集成！

✅ 前置条件检查

确认以下服务已运行：

# 检查 Gitea
curl -I http://192.168.1.83:33000
# 预期: HTTP/1.1 200 OK

# 检查 Plane
curl -I http://192.168.1.83:8088
# 预期: HTTP/1.1 200 OK

# 检查 Registry
curl http://192.168.1.83:15000/v2/_catalog
# 预期: {"repositories":[...]}

📋 3 步完成集成

第 1 步: 获取 Plane API Key (1 分钟)

# 1. 打开 Plane
open http://192.168.1.83:8088/ljwx

# 2. 点击右上角头像 → Settings → API Tokens
# 3. 点击 "Generate New Token"
#    - Name: bigscreen-ci-cd
#    - Expires: Never (或选择过期时间)
# 4. 复制生成的 API Key (只显示一次!)

第 2 步: 设置 Plane 项目 (1 分钟)

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

# 设置 API Key
export PLANE_API_KEY="plane_api_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

# 运行一键设置脚本
./scripts/setup_plane_project.sh

脚本会自动:

• ✅ 检查项目是否存在
• ✅ 不存在则创建 "BigScreen 大屏系统" 项目
• ✅ 配置项目标识符为 "bigscreen"
• ✅ 显示下一步操作指引

第 3 步: 配置 Gitea Secret (2 分钟)

# 1. 打开 Gitea 仓库设置
open http://192.168.1.83:33000/gao/bigscreen/settings/secrets

# 2. 点击 "Add Secret"
#    Name: PLANE_API_KEY
#    Value: 粘贴你的 Plane API Key
#    点击 "Add Secret"

# 3. 验证 Secret 已添加 (应该看到 PLANE_API_KEY 在列表中)

🎉 测试集成 (1 分钟)

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

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

- 添加 Plane 集成 workflow
- 添加自动同步脚本
- 更新 Registry 地址为 192.168.1.83:15000"

git push origin main

观察自动化流程:

1. Gitea Actions 开始运行 (约 30 秒)

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

2. Plane 自动创建 Issue (约 1 分钟后)

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

📊 验证集成成功

检查点 1: Gitea Actions

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

预期看到:

• ✅ Plane Integration workflow 运行成功
• ✅ 状态显示绿色对勾
• ✅ 日志显示 "Plane 同步完成"

检查点 2: Plane Issue

访问: http://192.168.1.83:8088/ljwx/projects/bigscreen/issues

预期看到:

• ✅ 新的 Issue: "🏗️ 构建 main - xxx"
• ✅ 包含构建信息和相关链接
• ✅ 标签: ci-cd, build

检查点 3: Registry 镜像 (如果 build workflow 运行)

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

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

🎯 日常开发工作流

场景 1: 开发新功能

# 1. 在 Plane 创建功能 Issue (可选，也可以让 CI 自动创建)
# 2. 创建功能分支
git checkout -b feature/my-feature

# 3. 开发 + 提交
git add .
git commit -m "feat: 添加新功能"

# 4. 推送触发 CI
git push origin feature/my-feature

# 5. 在 Gitea 创建 PR
# 6. CI 自动运行测试
# 7. Plane 自动创建 PR 跟踪 Issue
# 8. Review 通过后合并
# 9. 自动构建 + 部署 + Plane 更新

场景 2: 修复 Bug

# 1. 快速修复
git checkout -b hotfix/bug-name
# ... 修复代码 ...
git commit -m "fix: 修复 XXX 问题"
git push origin hotfix/bug-name

# 2. 合并到 main
# 3. 自动构建新镜像
# 4. Plane 记录修复 Issue

📁 项目文件总览

新增的集成文件

bigscreen/
├── .gitea/workflows/
│   ├── build-and-push.yaml      # ✅ 已更新 Registry 地址
│   ├── ci.yaml                  # ✅ 已更新 Registry 地址
│   ├── deploy.yaml              # ✅ 已更新 Registry 地址
│   └── plane-integration.yaml   # ✨ 新增: Plane 集成
├── scripts/
│   ├── plane_sync.py            # ✨ 新增: Plane API 同步脚本
│   └── setup_plane_project.sh   # ✨ 新增: Plane 项目设置脚本
├── PLANE_INTEGRATION.md         # ✨ 新增: Plane 集成文档
├── DEVOPS_INTEGRATION.md        # ✨ 新增: DevOps 完整方案
└── QUICKSTART_DEVOPS.md         # ✨ 新增: 快速上手指南

Registry 配置更新

所有 workflow 文件中的 Registry 地址已更新为:

• REGISTRY_HOST: 192.168.1.83:15000
• REGISTRY_CACHE: 192.168.1.83:15001
• PROJECT_NAME: bigscreen

🔗 快速链接

服务	链接	说明
Plane 项目	http://192.168.1.83:8088/ljwx/projects/bigscreen	项目管理看板
Gitea 仓库	http://192.168.1.83:33000/gao/bigscreen	代码仓库
Gitea Actions	http://192.168.1.83:33000/gao/bigscreen/actions	CI/CD 执行历史
Gitea Secrets	http://192.168.1.83:33000/gao/bigscreen/settings/secrets	密钥配置
Registry	http://192.168.1.83:15000/v2/_catalog	镜像仓库
API 文档	http://192.168.1.83:8000/docs	FastAPI Swagger

📝 常用命令速查

# === Plane 相关 ===
# 手动测试 Plane 同步
export PLANE_API_KEY="your-key"
python scripts/plane_sync.py

# 重新设置 Plane 项目
./scripts/setup_plane_project.sh

# === Git 相关 ===
# 查看工作流文件
ls -la .gitea/workflows/

# 查看最近的 commit
git log --oneline -5

# === Docker 相关 ===
# 查看镜像列表
curl http://192.168.1.83:15000/v2/_catalog

# 查看 bigscreen 后端镜像标签
curl http://192.168.1.83:15000/v2/bigscreen-backend/tags/list

# === 本地开发 ===
# 启动开发环境
./start_app.sh

# 停止服务
./stop_app.sh

🆘 快速故障排查

❌ Plane Issue 没有自动创建

# 1. 检查 Gitea Actions 日志
#    访问: http://192.168.1.83:33000/gao/bigscreen/actions
#    查看 "Plane Integration" workflow 日志

# 2. 验证 Secret 配置
#    访问: http://192.168.1.83:33000/gao/bigscreen/settings/secrets
#    确认 PLANE_API_KEY 存在

# 3. 手动测试 API Key
curl -X GET http://192.168.1.83:8088/api/v1/workspaces/ljwx/projects/ \
  -H "x-api-key: YOUR_API_KEY"

❌ 镜像推送失败

# 1. 检查 Registry 服务
curl http://192.168.1.83:15000/v2/_catalog

# 2. 检查网络连接
ping 192.168.1.83

# 3. 查看 workflow 日志
#    访问 Actions 页面查看详细错误

❌ CI 测试失败

# 1. 本地运行测试
cd backend && pytest tests/ -v

cd frontend && npm run test

# 2. 检查代码格式
cd backend && black --check .

cd frontend && npm run lint

# 3. 修复后重新提交
git add .
git commit -m "fix: 修复测试问题"
git push

🎓 进阶主题

想要了解更多? 查看详细文档:

• 完整集成方案: DEVOPS_INTEGRATION.md
• Plane 集成详解: PLANE_INTEGRATION.md
• Kubernetes 部署: k8s/README.md
• 项目架构: CLAUDE.md

✨ 下一步

现在你已经完成了基础集成，可以考虑:

1. ⭐ 配置自动部署: 编辑 deploy.yaml 添加生产环境部署
2. 📊 添加监控: 集成 Prometheus + Grafana
3. 🔔 通知集成: 添加钉钉/企业微信通知
4. 🧪 增加测试覆盖: 提升自动化测试覆盖率
5. 📈 性能优化: 配置 CI 缓存加速构建

---

🎉 恭喜！你已经完成了 Plane + Gitea + Registry 的 DevOps 集成！

现在每次代码提交都会:

• ✅ 自动运行代码检查和测试
• ✅ 自动构建 Docker 镜像
• ✅ 自动推送到镜像仓库
• ✅ 自动同步到 Plane 项目管理
• ✅ 自动生成构建报告

Happy Coding! 🚀