big-bro-watches-everything/devstar

Fork 0

Files

vecmatex 31d4e8b438 添加debug界面

2025-11-19 09:08:04 +08:00

11 KiB

Raw Permalink Blame History

在线调试工作流功能 - 实现总结

📌 功能概述

这是一个为 Gitea DevStar 项目添加的新功能，允许开发者在 Web 界面上在线调试和测试 GitHub Actions 工作流，而无需每次都推送代码到仓库。

🎯 主要特性

✅ 在线工作流编辑器 - 直接在 Web UI 中输入或粘贴工作流 YAML
✅ 实时验证 - 检查工作流 YAML 语法是否正确
✅ 一键执行 - 快速运行工作流获取反馈
✅ 完整日志 - 查看工作流执行的所有输出和错误信息
✅ 脚本保存 - 保留执行过的工作流脚本用于对比
✅ 权限控制 - 只有具有写权限的用户才能访问
✅ 分支选择 - 支持在不同分支上测试工作流

📁 实现文件结构

devstar/
├── services/actions/
│   └── debug_workflow.go                 # 核心业务逻辑
├── routers/api/v1/repo/
│   └── actions_debug.go                  # API 端点实现
├── routers/api/v1/
│   └── api.go                            # 路由注册 (已修改)
├── templates/repo/actions/
│   └── debug_workflow.tmpl               # Web UI 模板
├── tests/integration/
│   └── debug_workflow_test.go            # 测试用例
└── docs/
    ├── DEBUG_WORKFLOW_GUIDE.md           # 完整实现指南
    └── DEBUG_WORKFLOW_EXAMPLES.md        # 使用示例

🔧 技术实现

1. 业务逻辑层 (`services/actions/debug_workflow.go`)

主要函数：

DebugActionWorkflow() - 执行调试工作流的核心函数
validateWorkflowContent() - YAML 验证
saveDebugWorkflowContent() - 保存工作流内容
GetDebugWorkflowRun() - 获取调试运行详情

核心流程：

验证输入参数和工作流内容
获取目标 Git 提交信息
创建特殊的 ActionRun 记录（标记为调试模式）
解析工作流创建 Jobs
保存工作流脚本内容
触发工作流执行

2. API 端点 (`routers/api/v1/repo/actions_debug.go`)

端点：

POST /api/v1/repos/{owner}/{repo}/actions/debug-workflow
GET /api/v1/repos/{owner}/{repo}/actions/debug-workflow/{run_id}

请求格式：

{
  "workflow_content": "name: Test\non: workflow_dispatch\njobs:...",
  "ref": "main",
  "inputs": {}
}

响应格式：

{
  "run": { "id": 123, "status": "waiting", ... },
  "workflow_content": "..."
}

3. 路由注册 (`routers/api/v1/api.go`)

在 actions 路由组中添加了新的调试工作流路由：

m.Group("/actions/debug-workflow", func() {
    m.Post("", reqRepoWriter(unit.TypeActions), bind(actions.DebugWorkflowOptions{}), repo.DebugWorkflow)
    m.Get("/{run_id}", reqRepoWriter(unit.TypeActions), repo.GetDebugWorkflowOutput)
}, context.ReferencesGitRepo(), reqToken())

4. Web UI 模板 (`templates/repo/actions/debug_workflow.tmpl`)

主要功能：

YAML 编辑器（monospace 字体，语法突出）
分支选择下拉菜单
输入参数编辑区
验证和运行按钮
实时日志显示
日志复制和下载功能
最近运行历史

交互流程：

User Input → Validate (API check) → Run (POST) → Poll Status → Show Logs

🔐 安全设计

权限检查
- 需要仓库写权限 (reqRepoWriter(unit.TypeActions))
- 需要有效的 token
- 验证用户身份
YAML 验证
- 使用 jobparser.Parse() 验证语法
- 必须包含 jobs 定义
- 拒绝无效的工作流
隔离
- 调试工作流使用特殊的 WorkflowID (debug-workflow.yml)
- 所有日志和输出单独标记
- 不能访问仓库的真实密钥
日志
- 所有调试运行都被记录
- 可以追踪谁运行了什么工作流

🧪 测试覆盖

创建了 5 个测试用例 (tests/integration/debug_workflow_test.go)：

✅ TestDebugWorkflow - 基本工作流执行
✅ TestDebugWorkflowWithInputs - 带输入参数的工作流
✅ TestDebugWorkflowInvalidContent - 无效的 YAML 拒绝
✅ TestDebugWorkflowEmptyContent - 空内容拒绝
✅ TestDebugWorkflowDefaultRef - 默认分支处理

📊 数据模型

ActionRun 特殊字段

WorkflowID: "debug-workflow.yml" (标记为调试模式)
Title: "[DEBUG] {workflow_name}" (带 DEBUG 前缀)
Event: "workflow_dispatch" (固定)
TriggerEvent: "workflow_dispatch" (固定)

ActionRunJob

保存完整的工作流 YAML 内容在 WorkflowPayload 字段
便于后续查看和对比

🚀 使用流程

最小示例

1. 创建工作流

name: Hello World
on: workflow_dispatch
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - run: echo "Hello"

2. 调用 API

curl -X POST http://localhost:3000/api/v1/repos/user/repo/actions/debug-workflow \
  -H "Authorization: token YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "workflow_content": "name: Hello World\non: workflow_dispatch\njobs:\n  test:\n    runs-on: ubuntu-latest\n    steps:\n      - run: echo \"Hello\"",
    "ref": "main"
  }'

3. 查询结果

curl -H "Authorization: token YOUR_TOKEN" \
  http://localhost:3000/api/v1/repos/user/repo/actions/debug-workflow/123

🔄 集成流程

┌─────────────────────────────────────────────────────────────┐
│ 1. Web UI 界面 (debug_workflow.tmpl)                        │
│    - 用户输入工作流 YAML                                     │
│    - 选择分支                                                │
│    - 验证和运行                                              │
└──────────────────┬──────────────────────────────────────────┘
                   │
                   ▼
┌─────────────────────────────────────────────────────────────┐
│ 2. API 端点 (actions_debug.go)                              │
│    - 权限检查                                                │
│    - 参数验证                                                │
│    - 请求分发                                                │
└──────────────────┬──────────────────────────────────────────┘
                   │
                   ▼
┌─────────────────────────────────────────────────────────────┐
│ 3. 业务逻辑 (debug_workflow.go)                             │
│    - YAML 验证                                               │
│    - 创建 ActionRun                                          │
│    - 创建 ActionRunJob                                       │
│    - 保存工作流脚本                                          │
│    - 触发执行                                                │
└──────────────────┬──────────────────────────────────────────┘
                   │
                   ▼
┌─────────────────────────────────────────────────────────────┐
│ 4. 现有的工作流执行引擎                                      │
│    - Actions Runner                                          │
│    - Job 执行                                                │
│    - 日志收集                                                │
└──────────────────┬──────────────────────────────────────────┘
                   │
                   ▼
┌─────────────────────────────────────────────────────────────┐
│ 5. 结果显示                                                  │
│    - 返回日志                                                │
│    - 显示执行状态                                            │
│    - 保存原始脚本                                            │
└─────────────────────────────────────────────────────────────┘

📝 文档

1. 实现指南 (`DEBUG_WORKFLOW_GUIDE.md`)

功能概述
API 使用方法
前端集成建议
Web UI 模板代码
数据流图表
安全考虑

2. 使用示例 (`DEBUG_WORKFLOW_EXAMPLES.md`)

7 个实际使用场景
从 Hello World 到复杂工作流
最佳实践
常见问题解答

🔍 特性亮点

1. 无缝集成

使用现有的 ActionRun 和 ActionRunJob 模型
利用现有的工作流执行引擎
不需要修改底层逻辑

2. 易于识别

所有调试运行都标记为 [DEBUG]
使用特殊的 WorkflowID
可以轻松区分测试和正式运行

3. 完整功能

支持所有工作流功能（Jobs、Steps、Actions 等）
支持输入参数
支持环境变量
支持分支选择

4. 用户友好

简单的 Web 界面
实时验证反馈
完整的执行日志
日志下载功能

🚦 下一步建议

短期改进

✨ 添加语法高亮编辑器（Monaco）
✨ 工作流模板库
✨ 历史记录快速重新运行

中期改进

🎯 实时日志流（WebSocket）
🎯 变量自动完成
🎯 工作流预验证报告

长期改进

🚀 工作流调试器（断点、步进）
🚀 集成式环境变量管理
🚀 工作流性能分析

📦 依赖

github.com/nektos/act/pkg/jobparser - 工作流解析
code.gitea.io/gitea/models/actions - 数据模型
code.gitea.io/gitea/services/actions - 业务逻辑
现有的 Gitea Actions 执行引擎

✅ 验收标准

能够提交自定义工作流 YAML
能够验证工作流语法
能够执行调试工作流
能够查看完整的执行日志
能够查看执行的原始脚本
所有调试运行都被正确标记
权限检查正常工作
测试覆盖主要场景

📞 支持

有任何问题或建议，请：

查看 DEBUG_WORKFLOW_GUIDE.md 和 DEBUG_WORKFLOW_EXAMPLES.md
运行测试：go test -v ./tests/integration -run TestDebugWorkflow
检查 API 文档：/api/v1/docs

实现日期: 2025-11-14
作者: Gitea 开发团队
版本: 1.0

11 KiB Raw Permalink Blame History Unescape Escape