dagu 项目说明书 - Doramagic.ai

Doramagic 项目包 · 项目说明书

dagu 项目

本地优先的工作流引擎，用于运维自动化与 AI 辅助运维场景；开源且支持自部署，单二进制、无需数据库，使用 YAML 声明式定义 DAG，内置 MCP 服务器供 AI 代理管理 DAG。

项目概览

Dagu 是一个面向开发者的自包含工作流引擎，目标是把"任务依赖、调度、执行、监控"四件事收敛到同一个二进制和同一份 YAML 声明里，避免在 cron、Airflow、CI 与脚本胶水之间来回拼接。

章节 相关页面

继续阅读本节完整说明和来源证据。

一、定位与核心能力

Dagu 用单一可执行文件承担调度器、API 服务器、Web UI、Worker 与 CLI 五种角色，运行时不强依赖外部数据库——状态、元数据、运行记录全部落盘到本地文件系统，部署形态可以是裸进程、systemd、Docker 容器或 Kubernetes Pod。

其能力边界围绕 DAG（有向无环图）展开：

以 YAML 描述步骤、依赖、条件、超时、重试、并行与环境变量；
内置 cron 风格的调度器，支持队列与并发控制；
通过生命周期钩子（handler_on.init / .exit / .success / .failure 等）扩展工作流；
提供 Web UI、REST API 与 CLI 三种入口，远程触发、查看日志、查看运行历史；
支持 http.request、docker、ssh、mail 等执行器，把外部系统纳入同一张图。

资料来源：README.md:1-80

二、系统组成与运行时角色

Dagu 在进程内把多个角色组合在一起，并通过 YAML 表达工作流拓扑。下图给出高层组件关系：

flowchart LR
  subgraph Scheduler["Scheduler / Queue"]
    S1[Cron 触发器]
    S2[运行队列]
  end
  subgraph Agent["Agent (单次运行)"]
    A1[DAG 解析与执行]
    A2[Step / Handler 执行器]
    A3[FileStore 写运行记录]
  end
  subgraph Server["HTTP Server"]
    H1[REST API]
    H2[Web UI]
  end
  S1 --> S2
  S2 --> A1
  A1 --> A2
  A2 --> A3
  H1 --> Agent
  H2 --> H1
  Agent --> FileStore[(本地文件存储)]

调度器把命中时间的任务入队并交给 internal/agent 启动一次 DAG 运行；运行过程通过文件存储持久化状态，UI 与 API 再从同一份存储里读取历史与日志，形成"调度—执行—可观测"的闭环。

资料来源：README.md:80-160, internal/runtime/builtin/docker/keepalive/README.md:1-40

三、部署形态

Dagu 提供三条主流部署路径，覆盖单机到集群场景：

容器镜像：Dockerfile 构建的镜像把二进制、dags/ 与数据目录打包，提供 dagu start-all、dagu scheduler 等入口命令；deploy/docker/README.md 给出 docker-compose 示例与挂载建议。资料来源：Dockerfile:1-60, deploy/docker/README.md:1-80
Helm Chart：charts/dagu/README.md 发布到 https://dagucloud.github.io/dagu 的 Helm 仓库，可直接 helm install dagu dagu/dagu，最近一次 chart 发布为 helm-dagu-1.0.11。资料来源：charts/dagu/README.md:1-60
Kubernetes 原生清单：deploy/k8s/README.md 提供 ConfigMap、Deployment 与 PVC 样例，便于在集群内独立调度与持久化运行记录。资料来源：deploy/k8s/README.md:1-80

三种形态共享同一份 YAML DAG 定义，因而本地调试与生产运行之间的迁移成本很低。

四、社区关注点与版本脉络

从近期 issue 与 release notes 可以归纳出用户最关心的几类问题：

可观测性补齐：onInit handler 的输出在 UI 中没有展示面（#2429），handler_on 步骤声明的 stdout.outputs 没有发布到 DAG run outputs（#2428），这两类缺口反映出"生命周期钩子 vs 用户可见性"仍是当前打磨重点。
可靠性：队列中启动前失败的 run 不会被移除，导致反复重派（#2436）；v2.10.5 修复了分布式执行下文件存储被破坏后的恢复能力，并补齐了启动期取消请求的丢失问题。
调度与体验：v2.10.0 引入按 profile 的调度，v2.10.4 明确 preconditions 的 eval 与值比较语义，v2.10.7 强化 Kanban 视图与日志搜索，路线整体朝向"配置更精细、可视化更直接"。
生态呼声：包括从 GPLv3 切换到更宽松许可（#1393）、远程存储下的 Worker 同步模式（#1260）、子目录 DAG 列表（#2400）以及 OAuth/OpenID 认证（#443）。

资料来源：README.md:160-240

把以上线索放到一起，可以看到 Dagu 当前的演进方向是：在保持"单二进制、自包含"核心定位的前提下，依次解决分布式协同、配置表达力与运维可见性三组问题。

资料来源：README.md:1-80

Lib 模块

ui/src/lib/ 是 Dagu 前端 UI 中独立于 React 组件树的基础工具库,集中提供横切关注点(cross-cutting concerns)的纯函数与轻量级服务,以便在页面、Hook、表单与 API 客户端中复用。资料来源：[ui/src/lib/ansi.tsx:1-1]()

章节 相关页面

继续阅读本节完整说明和来源证据。

章节 ANSI 序列与日志渲染

继续阅读本节完整说明和来源证据。

章节 认证与会话

继续阅读本节完整说明和来源证据。

章节 常量集中化

继续阅读本节完整说明和来源证据。

概述

ui/src/lib/ 是 Dagu 前端 UI 中独立于 React 组件树的基础工具库,集中提供横切关注点(cross-cutting concerns)的纯函数与轻量级服务,以便在页面、Hook、表单与 API 客户端中复用。资料来源：ui/src/lib/ansi.tsx:1-1

该模块遵循单一职责原则,每个文件通常对应一类问题域:

日志展示层 —— ANSI 转义序列解析与彩色渲染
认证与会话 —— HTTP 请求头注入、Token 生命周期管理
系统常量 —— UI 中复用的固定值与枚举
配置校验 —— DAG YAML 在前端的结构化校验
时间计算 —— DAG 运行的计时、相对时间与排期辅助

由于它们均为纯 TypeScript/JavaScript 模块,不依赖任何 React 上下文或全局状态,因此可以在 Web Worker、服务端预渲染(SSR)、单元测试等场景中安全复用。资料来源：ui/src/lib/authSession.ts:1-1

子模块结构

子模块	关注点	主要消费者
`ansi.tsx`	解析 shell ANSI 转义序列并以彩色/样式节点渲染	运行日志查看器、错误面板
`authHeaders.ts`	组装带 Bearer Token 或 Cookie 的请求头	API 客户端(`api/v2`)
`authSession.ts`	管理浏览器侧会话(登录、刷新、TTL)	顶层 `App`、登录页
`constants.ts`	枚举、UI 文案、路由前缀	整个前端
`dag-validation.ts`	YAML/JSON DAG 字段的前端预校验	DAG 编辑器、定义导入流程
`dagRunTiming.ts`	运行时长、相对时间、cron 描述	DAG 列表、运行详情页

资料来源：ui/src/lib/constants.ts:1-1、资料来源：ui/src/lib/dag-validation.ts:1-1、资料来源：ui/src/lib/dagRunTiming.ts:1-1

核心功能

ANSI 序列与日志渲染

Dagu 的执行节点会输出带 ANSI 颜色码的 stdout/stderr。ansi.tsx 将原始字节流解析为 React 节点数组,保留原始颜色但避免 dangerouslySetInnerHTML,从而兼容 v2.10.7 引入的"可搜索 ANSI 着色日志"特性。资料来源：ui/src/lib/ansi.tsx:1-1

认证与会话

authHeaders.ts 负责为每个出站请求附加 Authorization / Cookie 头,作为 API 客户端统一调用入口;authSession.ts 则封装 Token 的持久化、自动刷新与失效处理。在 v2.10.6 中,团队对长 TTL Token 进行了修复(浏览器定时器上限与登录后立即失效问题),相关逻辑会经由本模块的会话工具对外暴露。资料来源：ui/src/lib/authSession.ts:1-1

常量集中化

constants.ts 集中放置路由路径、状态枚举、默认分页大小、状态徽章颜色映射等;采用集中常量而非内联字符串有助于在重构(例如重构 Kanban 列顺序、相对时间格式)时保持一致。资料来源：ui/src/lib/constants.ts:1-1

DAG 校验

提交 DAG 定义到后端前,前端会通过 dag-validation.ts 对必填字段(name、schedule、步骤 id、command 等)进行结构与语义校验,从而在 UI 给出即时反馈,减少无效的 API 调用。资料来源：ui/src/lib/dag-validation.ts:1-1

时间计算

dagRunTiming.ts 提供:

运行开始/结束时刻的格式化(支持 v2.10.7 引入的"相对时间戳"展示)
各步骤累计耗时、间隔时长计算
下次预计触发时间的辅助生成(配合每个 profile 的 schedule 字段)

资料来源：ui/src/lib/dagRunTiming.ts:1-1

与上层组件的协作

Lib 模块不直接渲染界面,而是被 components/ 与 features/ 目录下的视图组合使用。下图展示从 UI 层到 Lib 的典型调用关系:

flowchart LR
  UI[React 组件] --> API[API 客户端]
  UI --> Logs[日志/运行视图]
  API --> AuthH[authHeaders.ts]
  Logs --> Ansi[ansi.tsx]
  UI --> Sess[authSession.ts]
  UI --> Cst[constants.ts]
  Edit[DAG 编辑器] --> Val[dag-validation.ts]
  Run[运行详情] --> Time[dagRunTiming.ts]

典型的数据流是:UI 组件在挂载或事件触发时调用 Lib 中的纯函数,得到格式化后的字符串、布尔校验结果或日期对象后再渲染。资料来源：ui/src/lib/authHeaders.ts:1-1、资料来源：ui/src/lib/dag-validation.ts:1-1

使用建议

保持纯函数:Lib 中的模块应避免直接访问 window/document,需要时通过参数注入,方便服务端测试
集中可复用枚举:任何新增的状态、徽章颜色、路由前缀都应优先放入 constants.ts
不要在 Lib 中发起网络请求:Lib 提供 headers/session 工具,实际 fetch 由上层 API 客户端负责,以保持职责清晰

已知边界

Lib 模块仅覆盖前端通用工具;后端对 handler_on.init 输出未发布到 DAG 运行输出的问题(参见 issue #2428、#2429)属于执行器与发布器范畴,不在前端 Lib 的职责内。
队列与子目录支持(issue #2436、#2400)等增强涉及后端加载器和调度器,Lib 仍只是消费层。

资料来源：ui/src/lib/ansi.tsx:1-1、资料来源：ui/src/lib/authSession.ts:1-1、资料来源：ui/src/lib/constants.ts:1-1

来源：https://github.com/dagucloud/dagu / 项目说明书

失败模式与踩坑日记

保留 Doramagic 在发现、验证和编译中沉淀的项目专属风险，不把社区讨论只当作装饰信息。

high 来源证据：feat: rerun a selected step and all downstream steps

可能增加新用户试用和生产接入成本。

medium 依赖 Docker 环境

非工程用户可能没有 Docker，启动成本明显增加。

medium 失败模式：installation: bug: `stdout.outputs` declared on a `handler_on` step is captured but never published to the...

Developers may fail before the first successful local run: bug: `stdout.outputs` declared on a `handler_on` step is captured but never published to the DAG run outputs

medium 失败模式：installation: bug: queued run that fails before startup is never dequeued and retries forever

Developers may fail before the first successful local run: bug: queued run that fails before startup is never dequeued and retries forever

Pitfall Log / 踩坑日志

项目：dagucloud/dagu

摘要：发现 26 个潜在踩坑项，其中 1 个为 high/blocking；最高优先级：安全/权限坑 - 来源证据：feat: rerun a selected step and all downstream steps。

1. 安全/权限坑 · 来源证据：feat: rerun a selected step and all downstream steps

严重度：high
证据强度：source_linked
发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：feat: rerun a selected step and all downstream steps
对用户的影响：可能增加新用户试用和生产接入成本。
证据：community_evidence:github | https://github.com/dagucloud/dagu/issues/2388 | 来源类型 github_issue 暴露的待验证使用条件。

2. 安装坑 · 依赖 Docker 环境

严重度：medium
证据强度：runtime_trace
发现：安装/运行入口包含 Docker 命令：docker run --rm -v ~/.dagu:/var/lib/dagu -p 8080:8080 ghcr.io/dagucloud/dagu:latest dagu start-all
对用户的影响：非工程用户可能没有 Docker，启动成本明显增加。
复现命令：docker run --rm -v ~/.dagu:/var/lib/dagu -p 8080:8080 ghcr.io/dagucloud/dagu:latest dagu start-all
证据：identity.distribution | https://github.com/dagucloud/dagu | docker run --rm -v ~/.dagu:/var/lib/dagu -p 8080:8080 ghcr.io/dagucloud/dagu:latest dagu start-all

3. 安装坑 · 失败模式：installation: bug: `stdout.outputs` declared on a `handler_on` step is captured but never published to the...

严重度：medium
证据强度：source_linked
发现：Developers should check this installation risk before relying on the project: bug: stdout.outputs declared on a handler_on step is captured but never published to the DAG run outputs
对用户的影响：Developers may fail before the first successful local run: bug: stdout.outputs declared on a handler_on step is captured but never published to the DAG run outputs
证据：failure_mode_cluster:github_issue | https://github.com/dagucloud/dagu/issues/2428 | bug: stdout.outputs declared on a handler_on step is captured but never published to the DAG run outputs

4. 安装坑 · 失败模式：installation: bug: queued run that fails before startup is never dequeued and retries forever

严重度：medium
证据强度：source_linked
发现：Developers should check this installation risk before relying on the project: bug: queued run that fails before startup is never dequeued and retries forever
对用户的影响：Developers may fail before the first successful local run: bug: queued run that fails before startup is never dequeued and retries forever
证据：failure_mode_cluster:github_issue | https://github.com/dagucloud/dagu/issues/2436 | bug: queued run that fails before startup is never dequeued and retries forever

5. 安装坑 · 失败模式：installation: helm-dagu-1.0.10

严重度：medium
证据强度：source_linked
发现：Developers should check this installation risk before relying on the project: helm-dagu-1.0.10
对用户的影响：Upgrade or migration may change expected behavior: helm-dagu-1.0.10
证据：failure_mode_cluster:github_release | https://github.com/dagucloud/dagu/releases/tag/helm-dagu-1.0.10 | helm-dagu-1.0.10

6. 安装坑 · 失败模式：installation: helm-dagu-1.0.11

严重度：medium
证据强度：source_linked
发现：Developers should check this installation risk before relying on the project: helm-dagu-1.0.11
对用户的影响：Upgrade or migration may change expected behavior: helm-dagu-1.0.11
证据：failure_mode_cluster:github_release | https://github.com/dagucloud/dagu/releases/tag/helm-dagu-1.0.11 | helm-dagu-1.0.11

7. 安装坑 · 失败模式：installation: question: `onInit` handler is recorded but never displayed — is that intended?

严重度：medium
证据强度：source_linked
发现：Developers should check this installation risk before relying on the project: question: onInit handler is recorded but never displayed — is that intended?
对用户的影响：Developers may fail before the first successful local run: question: onInit handler is recorded but never displayed — is that intended?
证据：failure_mode_cluster:github_issue | https://github.com/dagucloud/dagu/issues/2429 | question: onInit handler is recorded but never displayed — is that intended?

8. 安装坑 · 失败模式：installation: v2.10.0

严重度：medium
证据强度：source_linked
发现：Developers should check this installation risk before relying on the project: v2.10.0
对用户的影响：Upgrade or migration may change expected behavior: v2.10.0
证据：failure_mode_cluster:github_release | https://github.com/dagucloud/dagu/releases/tag/v2.10.0 | v2.10.0

9. 安装坑 · 来源证据：bug: queued run that fails before startup is never dequeued and retries forever

严重度：medium
证据强度：source_linked
发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：bug: queued run that fails before startup is never dequeued and retries forever
对用户的影响：可能增加新用户试用和生产接入成本。
证据：community_evidence:github | https://github.com/dagucloud/dagu/issues/2436 | 来源讨论提到 macos 相关条件，需在安装/试用前复核。

10. 安装坑 · 来源证据：question: `onInit` handler is recorded but never displayed — is that intended?

严重度：medium
证据强度：source_linked
发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：question: onInit handler is recorded but never displayed — is that intended?
对用户的影响：可能增加新用户试用和生产接入成本。
证据：community_evidence:github | https://github.com/dagucloud/dagu/issues/2429 | 来源讨论提到 linux 相关条件，需在安装/试用前复核。

11. 配置坑 · 失败模式：configuration: v2.10.4

严重度：medium
证据强度：source_linked
发现：Developers should check this configuration risk before relying on the project: v2.10.4
对用户的影响：Upgrade or migration may change expected behavior: v2.10.4
证据：failure_mode_cluster:github_release | https://github.com/dagucloud/dagu/releases/tag/v2.10.4 | v2.10.4

12. 配置坑 · 失败模式：configuration: v2.10.5

严重度：medium
证据强度：source_linked
发现：Developers should check this configuration risk before relying on the project: v2.10.5
对用户的影响：Upgrade or migration may change expected behavior: v2.10.5
证据：failure_mode_cluster:github_release | https://github.com/dagucloud/dagu/releases/tag/v2.10.5 | v2.10.5

13. 配置坑 · 失败模式：configuration: v2.10.6

严重度：medium
证据强度：source_linked
发现：Developers should check this configuration risk before relying on the project: v2.10.6
对用户的影响：Upgrade or migration may change expected behavior: v2.10.6
证据：failure_mode_cluster:github_release | https://github.com/dagucloud/dagu/releases/tag/v2.10.6 | v2.10.6

14. 能力坑 · 能力判断依赖假设

严重度：medium
证据强度：source_linked
发现：README/documentation is current enough for a first validation pass.
对用户的影响：假设不成立时，用户拿不到承诺的能力。
证据：capability.assumptions | https://github.com/dagucloud/dagu | README/documentation is current enough for a first validation pass.

15. 运行坑 · 运行可能依赖外部服务

严重度：medium
证据强度：source_linked
发现：项目说明出现 external service/cloud/webhook/database 等运行依赖关键词。
对用户的影响：本地安装成功不等于能力可用，外部服务不可用会阻断体验。
证据：packet_text.keyword_scan | https://github.com/dagucloud/dagu | matched external service / cloud / webhook / database keyword

16. 维护坑 · 失败模式：migration: v2.9.0

严重度：medium
证据强度：source_linked
发现：Developers should check this migration risk before relying on the project: v2.9.0
对用户的影响：Upgrade or migration may change expected behavior: v2.9.0
证据：failure_mode_cluster:github_release | https://github.com/dagucloud/dagu/releases/tag/v2.9.0 | v2.9.0

17. 维护坑 · 失败模式：migration: v2.9.1

严重度：medium
证据强度：source_linked
发现：Developers should check this migration risk before relying on the project: v2.9.1
对用户的影响：Upgrade or migration may change expected behavior: v2.9.1
证据：failure_mode_cluster:github_release | https://github.com/dagucloud/dagu/releases/tag/v2.9.1 | v2.9.1

18. 维护坑 · 维护活跃度未知

严重度：medium
证据强度：source_linked
发现：未记录 last_activity_observed。
对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
证据：evidence.maintainer_signals | https://github.com/dagucloud/dagu | last_activity_observed missing

严重度：medium
证据强度：source_linked
发现：no_demo
证据：downstream_validation.risk_items | https://github.com/dagucloud/dagu | no_demo; severity=medium

20. 安全/权限坑 · 存在评分风险

严重度：medium
证据强度：source_linked
发现：no_demo
对用户的影响：风险会影响是否适合普通用户安装。
证据：risks.scoring_risks | https://github.com/dagucloud/dagu | no_demo; severity=medium

21. 安全/权限坑 · 来源证据：bug: `stdout.outputs` declared on a `handler_on` step is captured but never published to the DAG run outputs

严重度：medium
证据强度：source_linked
发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：bug: stdout.outputs declared on a handler_on step is captured but never published to the DAG run outputs
对用户的影响：可能影响授权、密钥配置或安全边界。
证据：community_evidence:github | https://github.com/dagucloud/dagu/issues/2428 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

22. 能力坑 · 失败模式：capability: feat: rerun a selected step and all downstream steps

严重度：low
证据强度：source_linked
发现：Developers should check this capability risk before relying on the project: feat: rerun a selected step and all downstream steps
对用户的影响：Developers may hit a documented source-backed failure mode: feat: rerun a selected step and all downstream steps
证据：failure_mode_cluster:github_issue | https://github.com/dagucloud/dagu/issues/2388 | feat: rerun a selected step and all downstream steps

23. 运行坑 · 失败模式：performance: v2.10.1

严重度：low
证据强度：source_linked
发现：Developers should check this performance risk before relying on the project: v2.10.1
对用户的影响：Upgrade or migration may change expected behavior: v2.10.1
证据：failure_mode_cluster:github_release | https://github.com/dagucloud/dagu/releases/tag/v2.10.1 | v2.10.1

24. 维护坑 · issue/PR 响应质量未知

严重度：low
证据强度：source_linked
发现：issue_or_pr_quality=unknown。
对用户的影响：用户无法判断遇到问题后是否有人维护。
证据：evidence.maintainer_signals | https://github.com/dagucloud/dagu | issue_or_pr_quality=unknown

25. 维护坑 · 发布节奏不明确

严重度：low
证据强度：source_linked
发现：release_recency=unknown。
对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
证据：evidence.maintainer_signals | https://github.com/dagucloud/dagu | release_recency=unknown

26. 维护坑 · 失败模式：maintenance: v2.10.7

严重度：low
证据强度：source_linked
发现：Developers should check this maintenance risk before relying on the project: v2.10.7
对用户的影响：Upgrade or migration may change expected behavior: v2.10.7
证据：failure_mode_cluster:github_release | https://github.com/dagucloud/dagu/releases/tag/v2.10.7 | v2.10.7

来源：Doramagic 发现、验证与编译记录