devstar/DEBUG_FIXES_SUMMARY.md

Gitea 工作流在线调试功能 - 故障修复总结

🔧 已修复的问题

1. 路由 404 错误 ✅

问题：前端 fetch 请求返回 404 Not Found

• 原因：fetch URL 构造错误，导致路由不匹配

修复方案：

• 后端添加 DebugAPIURL 变量传递给前端
• 前端使用 {{.DebugAPIURL}} 而非手动构造路径
• 确保 URL 正确指向 /repo/actions/debug-api/{sessionID}/run

2. CSRF 令牌验证失败 ✅

问题：HTTP 400 - Invalid CSRF token

• 原因：POST 请求没有包含 CSRF 令牌

修复方案：

• 后端自动在 ctx.Data["CsrfToken"] 设置 CSRF 令牌
• 前端从页面上下文读取 {{.CsrfToken}}
• 在所有 POST 请求头中添加 X-Csrf-Token: {token}

关键代码：

const headers = {
    'Content-Type': 'application/json',
    'X-Csrf-Token': csrfToken,
};

fetch(url, {
    method: 'POST',
    headers: headers,
    body: JSON.stringify(payload),
})

3. 日志显示错误 ✅

问题：日志容器显示错误或空内容

• 原因：refreshLogs 函数尝试从 HTML 页面解析日志，而不是调用 API

修复方案：

• 改为调用 ViewPost 接口（POST 到 /runs/{runIndex}）
• 发送正确的 LogCursors JSON 格式
• 从 JSON 响应的 logs.stepsLog 提取日志内容
• 支持两种日志格式：
  • rawOutput：原始输出
  • lines：逐行输出数组

关键代码：

fetch(`${actionsURL}/runs/${currentRunIndex}`, {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
        'X-Csrf-Token': csrfToken,
    },
    body: JSON.stringify({ LogCursors: [] }),
})
.then(response => response.json())
.then(data => {
    // 从 data.logs.stepsLog 提取日志
    if (data.logs && data.logs.stepsLog) {
        let logContent = '';
        data.logs.stepsLog.forEach(stepLog => {
            if (stepLog.rawOutput) {
                logContent += stepLog.rawOutput + '\n';
            }
        });
    }
})

📋 文件修改清单

后端文件

• routers/web/repo/actions/debug.go
  • 添加 DebugAPIURL 数据变量
  • 移除错误的 ctx.CSRFToken() 调用（CSRF 令牌自动设置）
  • 添加调试日志便于故障排查

前端文件

• templates/repo/actions/debug.tmpl
  • 添加 csrfToken 变量初始化
  • 修改 fetch 请求包含 CSRF header
  • 修复 refreshLogs() 函数调用正确的 API
  • 改进日志解析逻辑

🚀 使用流程

1. 访问调试页面

   • 进入 Actions 页面 → 选择工作流 → 点击 Debug 按钮

2. 编辑工作流

   • 在左侧编辑器修改 YAML 内容
   • 选择分支/标签和事件类型
   • 配置输入参数和环境变量（可选）

3. 运行工作流

   • 点击"Run"按钮
   • 后端创建 ActionRun 并触发 Runner 执行
   • 前端自动刷新日志

4. 查看日志

   • 右侧实时显示工作流执行日志
   • 支持日志复制功能
   • 点击运行 ID 可查看详细页面

✨ 核心特性

• ✅ 在线编辑：直接编辑工作流 YAML
• ✅ 灵活配置：选择分支、事件类型、输入参数、环境变量
• ✅ 实时反馈：自动刷新日志显示执行进度
• ✅ 错误处理：详细的控制台日志便于调试
• ✅ CSRF 保护：完整的安全验证机制
• ✅ 权限管理：基于 Gitea 的权限系统

🔍 调试提示

如果遇到问题，查看浏览器控制台日志：

• debugAPIURL 变量值
• csrfToken 是否正确
• 网络请求状态
• 后端返回的错误信息

📌 已知限制

• 日志刷新间隔 2 秒（可配置）
• 仅显示最新日志（不支持历史日志查询）
• 工作流会话 24 小时自动过期

---

版本：v1.0 - Production Ready ✅ 最后更新：2025-11-20