Ubuntu 22.04 安装 Dagu 2.21.0 指南

在 Ubuntu 22.04 上安装 Dagu 2.21.0 并用 systemd 服务化常驻：官方脚本安装（system 级服务 + admin 引导）与手动二进制两条路线实测，含 dry-run 预览、远程访问 DAGU_HOST 配置、升级降级、八条 FAQ 与卸载清理，全部回显实测照抄。

Dagu自动化监控2026/10/19

Ubuntu 22.04 安装 Dagu 2.21.0 指南

目标：在 Ubuntu 22.04 服务器上从零部署 Dagu 2.21.0 工作流引擎，覆盖官方脚本安装（主线，含 systemd 服务托管与管理员账号引导）、手动二进制 + 手动 systemd 备用方案、远程访问配置、升级与降级、常见故障排障与卸载清理。全文命令与回显均在 Ubuntu 22.04 x86_64 环境逐条实测通过，安装完成后 Admin UI 以 systemd 常驻运行并实测返回 HTTP 200。

一、环境信息

本章记录实测环境与版本基准，读者可据此判断自己环境与本文的差异。

  • 操作系统：Ubuntu 22.04.5 LTS（x86_64），内核 6.8.0-138-generic。
  • 安装对象：Dagu 2.21.0（GitHub Releases 2026-10-19 查询的最新稳定版，2026-10-18 发布，非 Pre-release；helm-dagu-2.0.5 为 Helm Chart 发行物，不作为本文对象）。
  • 程序目录：/usr/local/bin/dagu（单二进制，实测约 173MB）。
  • 数据目录（DAGU_HOME）：/var/lib/dagu/（dags 工作流定义、logs 执行日志、data 内置状态）。
  • 配置目录：/etc/dagu/（dagu.env 服务端环境变量、bootstrap.env 引导变量）。
  • systemd 服务：/etc/systemd/system/dagu.service（服务名 dagu）。
  • 服务端口：Admin UI 默认 8080；本例服务器 8080 已被其他服务占用（ss -ltn 实查 0.0.0.0:8080 已有监听），故本文统一改用 8114（DAGU_PORT=8114），读者端口空闲时可保持默认。
  • 网络说明：GitHub 下载在本环境部分时段不稳定，实测经代理 http://192.168.1.62:7897 下载成功，读者无此需求可直连。

二、前置条件

安装前逐项确认，避免中途失败。

2.1 系统与工具

Dagu 为静态编译的 Go 单二进制，无运行时依赖，只需基础下载工具：

apt-get update && apt-get install -y curl ca-certificates

实测回显（已装时提示）：

Reading package lists... Done
curl is already the newest version (7.81.0-1ubuntu1.20).
0 upgraded, 0 newly installed, 0 to remove and 2 not upgraded.

⚠️ 注意：最小化安装的系统（如云镜像、部分服务器模板）可能缺少 sudo，而官方安装脚本会调用 sudo，缺失时报 sudo: command not found（见第九章 FAQ）。先确认：

sudo --version | head -1

实测回显（缺失时安装后）：

apt-get install -y sudo

Sudo version 1.9.9

2.2 端口复核

确认目标端口未被占用（本文以 8114 为例）：

ss -ltn | grep -E ':(8080|8114)\b' || echo "ports free"

实测结果：8080 已有监听（被其他服务占用，见前文），8114 无匹配输出（空闲）。端口被占用时，ss -ltn 的 LISTEN 行末尾带 users 字段，形如：

users:(("<进程名>",pid=<PID>,fd=<FD>))

按进程名与 PID 即可定位占用者，再决定释放该端口或改用其他端口。

结论：8114 可用，本文按 8114 部署；若读者 8114 也被占用，替换为任意空闲端口即可。

2.3 内存与磁盘

Dagu 资源占用很轻：单进程常驻内存实测约 130MB（RSS 132792KB），二进制约 173MB，加上日志与历史增长，预留 1GB 磁盘、512MB 内存即可稳定运行小规模工作流。

三、版本选型与发行物形态

Dagu 发布节奏很快（2026-09-09 v2.16.3 → 2026-10-18 v2.21.0，约 40 天 14 个版本），安装前先确认「最新稳定版」：Pre-release 不作为生产对象。查询命令：

curl -s https://api.github.com/repos/dagucloud/dagu/releases?per_page=5 | grep -E '"tag_name"|"prerelease"'

实测回显（2026-10-19）：

  "tag_name": "v2.21.0",
  "prerelease": false,
  "tag_name": "helm-dagu-2.0.5",
  "prerelease": false,
  "tag_name": "v2.20.1",
  "prerelease": false,

v2.21.0 的发行资产（Release Assets 实测清单）：

资产平台大小
dagu_2.21.0_linux_amd64.tar.gzLinux x86_6455.0 MB
dagu_2.21.0_linux_arm64.tar.gzLinux ARM6450.1 MB
dagu_2.21.0_linux_{armv6,armv7,386,ppc64le,s390x}.tar.gz其他 Linux 架构49.9~53.1 MB
dagu_2.21.0_darwin_{amd64,arm64}.tar.gzmacOS52.2~55.8 MB
dagu_2.21.0_windows_{amd64,arm64,386}.tar.gz / -setup.exeWindows40.3~56.0 MB
checksums.txt校验和—

⚠️ 注意：仓库经历过组织迁移（yohamta/dagu → dagu-dev/dagu → dagucloud/dagu），旧地址自动重定向，脚本与文档均以 dagucloud/dagu 为准；Releases 列表中 helm-dagu-x.y.z 是 Kubernetes Helm Chart 版本线，Linux 服务器安装看 v2.x.y 系列即可。

四、方案 A：官方脚本安装（主线，systemd 系统服务）

4.1 方案说明

官方推荐路径：引导式脚本安装器（installer.sh）。它一次性完成：下载平台对应二进制 → 安装到指定目录 → 注册 systemd 服务（user 或 system 级）→ 引导创建第一个管理员账号。本文以 root 执行 system 级安装（生产服务器标准形态：开机自启、不依赖具体登录用户）。

4.2 dry-run 预览

先以 --dry-run 预览安装计划，确认目录/服务形态符合预期：

curl -fsSL https://raw.githubusercontent.com/dagucloud/dagu/main/scripts/installer.sh | \
  bash -s -- --dry-run --no-prompt --service yes --service-scope system \
  --install-dir /usr/local/bin --admin-username admin --admin-password 'q1w2e3r4'

实测回显：

Dagu Installer
Install Dagu, set it up as a background app, and get you to the UI quickly.


Install plan
Version: latest
OS: linux
Architecture: amd64
Install directory: /usr/local/bin
Run as background app: yes
Service scope: system
Dagu home: /var/lib/dagu
URL: http://127.0.0.1:8080
Admin bootstrap: admin
Skill install: skip
Dry run: yes
✓ Dry run complete. No changes were made.

4.3 正式安装

去掉 --dry-run 正式执行：

curl -fsSL https://raw.githubusercontent.com/dagucloud/dagu/main/scripts/installer.sh | \
  bash -s -- --service yes --service-scope system \
  --install-dir /usr/local/bin --admin-username admin --admin-password 'q1w2e3r4'

实测回显（关键段）：

Install plan
Version: v2.21.0
OS: linux
Architecture: amd64
Install directory: /usr/local/bin
Run as background app: yes
Service scope: system
Dagu home: /var/lib/dagu
URL: http://127.0.0.1:8080
Admin bootstrap: admin
Skill install: skip
· Downloading Dagu v2.21.0

Success
Installed: /usr/local/bin/dagu
Service URL: http://127.0.0.1:8080
Status command: sudo systemctl status dagu
Admin username: admin
Workflows: /var/lib/dagu/dags
Free monitoring: http://127.0.0.1:8080/license#monitoring
Skill install: skipped

⚠️ 注意（实测排障）：非交互 shell（自动化/CI）执行时脚本会反复打印 main: line 522: /dev/tty: No such device or address，这是向导尝试读终端的提示；命令行参数齐全时最终仍会正常装完，可忽略。另：最小化系统缺 sudo 时脚本中途报 main: line 1909: sudo: command not found 退出，apt-get install -y sudo 后重跑即可（见第九章 FAQ）。

4.4 验证安装

dagu version

实测回显：

2.21.0

systemctl is-active dagu && systemctl is-enabled dagu

实测回显：

active
enabled

安装器生成的服务单元内容（实测 systemctl cat dagu）：

# /etc/systemd/system/dagu.service
[Unit]
Description=Dagu Workflow Engine
After=network.target
Wants=network-online.target

[Service]
Type=simple
ExecStart=/usr/local/bin/dagu start-all
WorkingDirectory=/var/lib/dagu
EnvironmentFile=/etc/dagu/dagu.env
EnvironmentFile=-/etc/dagu/bootstrap.env
Restart=always
RestartSec=10
User=root
Group=root

[Install]
WantedBy=multi-user.target

要点解读：EnvironmentFile=/etc/dagu/dagu.env 是服务端配置入口（下一节改端口/监听地址就在这里）；Restart=always 保证进程崩溃后 10 秒自动拉起；bootstrap.env 带负号前缀表示文件可缺省。

4.5 服务端口与远程访问配置

安装器默认写死 DAGU_HOST='127.0.0.1'（仅本机可访问），远程访问必须改为 0.0.0.0；本例同时把端口从默认 8080 改为 8114（8080 已被占用）。编辑 /etc/dagu/dagu.env：

cat /etc/dagu/dagu.env

实测回显（安装器初始内容）：

DAGU_HOME='/var/lib/dagu'
DAGU_HOST='127.0.0.1'
DAGU_PORT='8080'
PATH='/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/root/.local/bin:/root/bin:/root/.npm-global/bin:/root/.local/share/pnpm:/root/.bun/bin:/opt/homebrew/bin'

修改并重启：

sed -i "s/DAGU_HOST='127.0.0.1'/DAGU_HOST='0.0.0.0'/" /etc/dagu/dagu.env
sed -i "s/DAGU_PORT='8080'/DAGU_PORT='8114'/" /etc/dagu/dagu.env
systemctl restart dagu

逐项说明：DAGU_HOME 数据根目录；DAGU_HOST 监听地址（0.0.0.0 才允许远程访问，仅本机用默认 127.0.0.1 更安全）；DAGU_PORT 服务端口；PATH 是安装器从安装时 shell 快照的环境路径，DAG 步骤里能直接调用的 CLI 工具由它决定，后续新装工具需追加或重跑安装器。

验证监听与远程可达：

ss -ltn | grep 8114
curl -s -o /dev/null -w "%{http_code}\n" http://127.0.0.1:8114/

实测回显：

LISTEN 0    4096   0.0.0.0:8114   0.0.0.0:*
200

浏览器访问 http://<服务器IP>:8114/ 打开 Admin UI，用引导创建的 admin / q1w2e3r4 登录。API 认证为 Bearer JWT（登录取 token，供巡检脚本调用）：

curl -s -X POST -H 'Content-Type: application/json' \
  -d '{"username":"admin","password":"q1w2e3r4"}' \
  http://127.0.0.1:8114/api/v1/auth/login

实测回显（节选）：

{"expiresAt":"2026-10-20T05:04:15.227706783Z","token":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiI2YzViYzZjNi05NDU1LTRmNmEtOTEzNS1lMDkzYTRlM2E1OWUiLCJleHAiOjE3OTI0NzI2NTUsImlhdCI6MTc5MjM4NjI1NSwidWlkIjoiNmM1YmM2YzYtOTQ1NS00ZjZhLTkxMzUtZTA5M2E0ZTNhNTllIiwidXNlcm5hbWUiOiJhZG1pbiIsInJvbGUiOiJhZG1pbiJ9.rbrkPbIrG3-guvb9t0M_B_2c1gUqEPcKIY_-nXi-Bf8","user":{"authProvider":"builtin","createdAt":"2026

五、方案 B：手动二进制 + 手动 systemd（离线/受控环境）

5.1 方案说明

安装器本质就是「下载 tar.gz + 写服务文件」的封装。网络受限、无法直连 GitHub 的服务器，或希望对每一步可控的场景，用手动方式：下载 Release 二进制 → 放入 PATH → 手写 dagu.env 与 systemd 单元 → 启动。全部步骤实测通过。

5.2 下载与安装二进制

cd /tmp
curl -fsSL -o dagu.tar.gz \
  https://github.com/dagucloud/dagu/releases/download/v2.21.0/dagu_2.21.0_linux_amd64.tar.gz
ls -la dagu.tar.gz
tar -tzf dagu.tar.gz

实测回显：

-rw-r--r-- 1 root root 57666476 Oct 19 05:04 dagu.tar.gz
LICENSE
README.md
README_SCHEMA.md
dagu

tar -xzf dagu.tar.gz
install dagu /usr/local/bin/dagu
dagu version
rm -f /tmp/dagu /tmp/dagu.tar.gz /tmp/LICENSE /tmp/README.md /tmp/README_SCHEMA.md

实测回显：

2.21.0

⚠️ 注意：GitHub 直连失败（Connection reset by peer / Connection refused）时改走代理：export http_proxy=http://192.168.1.62:7897 https_proxy=http://192.168.1.62:7897 后重试；也可在能联网的机器下载后经内网传到目标服务器（配合 sha256sum -c checksums.txt 校验）。

5.3 数据目录与环境文件

mkdir -p /var/lib/dagu/dags /var/lib/dagu/logs /var/lib/dagu/data /etc/dagu
cat > /etc/dagu/dagu.env << 'EOF'
DAGU_HOME=/var/lib/dagu
DAGU_HOST=0.0.0.0
DAGU_PORT=8114
EOF
cat /etc/dagu/dagu.env

实测回显：

DAGU_HOME=/var/lib/dagu
DAGU_HOST=0.0.0.0
DAGU_PORT=8114

5.4 systemd 单元与启动

cat > /etc/systemd/system/dagu.service << 'EOF'
[Unit]
Description=Dagu Workflow Engine
After=network.target
Wants=network-online.target

[Service]
Type=simple
ExecStart=/usr/local/bin/dagu start-all
WorkingDirectory=/var/lib/dagu
EnvironmentFile=/etc/dagu/dagu.env
Restart=always
RestartSec=10
User=root
Group=root

[Install]
WantedBy=multi-user.target
EOF
systemctl daemon-reload
systemctl enable --now dagu
sleep 3
systemctl is-active dagu

实测回显：

Created symlink /etc/systemd/system/multi-user.target.wants/dagu.service → /etc/systemd/system/dagu.service.
active

5.5 首次初始化管理员

手动安装没有安装器的「引导建号」环节，首次访问 UI 会进入 /setup 初始化页；也可直接调 API 创建管理员（实测）：

curl -s -X POST -H 'Content-Type: application/json' \
  -d '{"username":"admin","password":"q1w2e3r4"}' \
  http://127.0.0.1:8114/api/v1/auth/setup | head -c 200

实测回显（节选，成功返回 JWT）：

{"expiresAt":"2026-10-20T05:13:47.359119229Z","token":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJmNjEwZjlkMS02OTQxLTRlZjEtOGRlOC02OWMxMmU0NTViMDMiLCJleHAiOjE3OTI0NzMyMjcsImlhdCI6MTc5MjM4NjgyNywi

创建后即可用 admin / q1w2e3r4 登录 UI。CLI 直接执行时若未带 DAGU_HOME，默认落在 ~/.config/dagu/，与服务端目录不一致，建议在 /etc/profile.d/dagu.sh 中固化：

echo 'export DAGU_HOME=/var/lib/dagu' > /etc/profile.d/dagu.sh

六、方案对比与选择建议

维度方案 A：官方脚本方案 B：手动二进制
版本自动取最新稳定版，可 --version 指定下载时指定 URL 即指定版本
联网要求需访问 raw.githubusercontent.com + github.com仅需下载 Release 一个文件（可离线转移）
systemd 注册自动（user/system 两档）手写单元文件
管理员账号自动引导创建需 /setup 或 API 创建
服务参数（PATH 快照）自动抓取当前 shell PATH在 dagu.env 手工维护
适用可联网的常规服务器（推荐）离线/受控、需要审计每一步的环境

选择建议：可联网选方案 A（一条命令含服务化与建号）；离线内网、安全基线要求高、或安装器反复失败时选方案 B，两者产物等价。

七、升级、降级与多版本管理

7.1 安装器升级/降级

安装器重复执行即原地升级，--version 可指定任意版本（含降级）：

curl -fsSL https://raw.githubusercontent.com/dagucloud/dagu/main/scripts/installer.sh | \
  bash -s -- --version v2.20.1 --service yes --service-scope system \
  --install-dir /usr/local/bin --admin-username admin --admin-password 'q1w2e3r4'
dagu version
systemctl is-active dagu

实测回显（降级到 2.20.1）：

· Downloading Dagu v2.20.1

Success
Installed: /usr/local/bin/dagu
...
2.20.1
active

再升回最新版（--version v2.21.0 或省略取 latest），实测 2.21.0 + active。

⚠️ 注意（实测踩坑）：安装器重跑会重写 /etc/dagu/dagu.env，此前手工修改的 DAGU_HOST='0.0.0.0' 与 DAGU_PORT 会被还原为默认 127.0.0.1/8080。每次升级后必须复核：

grep -E 'DAGU_HOST|DAGU_PORT' /etc/dagu/dagu.env

实测回显（升级后未复核时，远程访问会莫名 404/拒绝）：

DAGU_HOST='127.0.0.1'
DAGU_PORT='8080'

修复：按 4.5 重新 sed 修改并 systemctl restart dagu，实测恢复 200。

⚠️ 另：重跑安装器时不带 --admin-username/--admin-password 会报 ✗ The admin password must be at least 8 characters. 并中止（向导无法在无终端环境询问），务必带齐参数。执行期间报错 Error: failed to connect to github.com port 443 时按 5.2 走代理重试。

7.2 手动升级

方案 B 的升级就是替换二进制：

systemctl stop dagu
install 新版dagu /usr/local/bin/dagu
systemctl start dagu
dagu version

Dagu 自带 dagu upgrade 子命令可在线升级到最新版（实测 dagu upgrade --help 可查看参数），其内部同样是下载-替换流程，受限网络下仍建议手动下载。

7.3 回滚

回滚 = 用 7.1/7.2 方式装回旧版本二进制；执行历史与 DAG 定义在数据目录中向后兼容（官方按小版本保持数据格式兼容，跨大版本升级前建议先备份 /var/lib/dagu，见 D2 运维篇）。

八、安装验证清单

逐项确认安装完整可用：

dagu version && systemctl is-active dagu && systemctl is-enabled dagu

实测回显：

2.21.0
active
enabled

ss -ltn | grep 8114
curl -s -o /dev/null -w "%{http_code}\n" http://127.0.0.1:8114/
ls /var/lib/dagu/

实测回显：

LISTEN 0    4096   0.0.0.0:8114   0.0.0.0:*
200
dags  data  logs

首次启动安装器会预置 6 个官方示例 DAG（example-01 ~ example-06），登录 UI 即可触发体验；首次启动日志中 Scheduler started、Server is starting 两条确认调度器与 Web 服务均已就绪：

journalctl -u dagu --no-pager | grep -E 'Scheduler started|Server is starting' | tail -2

实测回显：

Oct 19 05:05:36 ubuntu dagu[3564]: time=2026-10-19T05:05:36.309Z level=INFO msg="Scheduler started"
Oct 19 05:05:36 ubuntu dagu[3564]: time=2026-10-19T05:05:36.459Z level=INFO msg="Server is starting" addr=127.0.0.1:8080 url=http://127.0.0.1:8080

九、常见问题（FAQ）

Q1：安装脚本报 sudo: command not found 怎么办？ 最小化系统未预装 sudo，而脚本以 sudo 执行落盘操作。apt-get install -y sudo 后重跑安装命令。实测报错原文：main: line 1909: sudo: command not found。

Q2：脚本刷屏 /dev/tty: No such device or address？ 在无终端的自动化环境（CI、远程管道）执行交互式向导的提示。所有参数已通过命令行给出时直接忽略，最终输出 Success 即成功；无参数裸跑 | bash 则向导无法继续，退出码非 0。

Q3：重跑安装器报 The admin password must be at least 8 characters.？ 向导在重复安装时仍要求管理员参数，无终端环境无法询问。补上 --admin-username admin --admin-password 'q1w2e3r4' 重跑。

Q4：升级后远程突然访问不了？ 安装器重写 dagu.env，DAGU_HOST 还原为 127.0.0.1。按第七章 7.1 复核并改回 0.0.0.0，systemctl restart dagu。

Q5：服务 active 但 UI 502/拒绝连接？ 依次排查：ss -ltn | grep <端口> 确认监听地址与端口；grep DAGU_HOST /etc/dagu/dagu.env 是否 127.0.0.1（远程必为 0.0.0.0）；journalctl -u dagu -n 50 看启动日志中 Server is starting addr= 实际绑定值；防火墙 ufw status 放行端口。

Q6：GitHub 下载失败/超时？ 实测报错：curl: (56) OpenSSL SSL_read: Connection reset by peer、curl: (7) Failed to connect to github.com port 443。走代理 export http_proxy=http://192.168.1.62:7897 https_proxy=http://192.168.1.62:7897 后重试，或改方案 B 手动转移二进制。

Q7：CLI 能跑但看不到服务端创建的 DAG？ CLI 未带 DAGU_HOME 时默认 ~/.config/dagu/，与服务端 /var/lib/dagu/ 是两套目录。export DAGU_HOME=/var/lib/dagu（建议写入 /etc/profile.d/dagu.sh）后再执行 dagu ls。实测未设置时 CLI 启动提示：msg="Creating example DAGs for first-time users" dir=/root/.config/dagu/dags。

Q8：API 带 Basic Auth 返回 401？ 2.x 内置用户体系走 JWT 而非 Basic Auth：先 POST /api/v1/auth/login 取 token，再以 Authorization: Bearer <token> 调用；响应头 Www-Authenticate: Bearer realm="restricted" 即提示令牌方式。

十、卸载与清理

停止并移除服务、二进制、配置与数据（执行前确认 /var/lib/dagu/dags 里没有还需要的工作流定义）：

systemctl stop dagu
systemctl disable dagu

实测回显：

Removed /etc/systemd/system/multi-user.target.wants/dagu.service.

rm -f /etc/systemd/system/dagu.service
systemctl daemon-reload
rm -f /usr/local/bin/dagu
rm -rf /etc/dagu /var/lib/dagu

验证卸载干净：

systemctl is-active dagu; which dagu; ls /var/lib/dagu; ls /etc/dagu

实测回显：

inactive
ls: cannot access '/var/lib/dagu': No such file or directory
ls: cannot access '/etc/dagu': No such file or directory

which dagu 无输出即二进制已移除。如仅重装而保留数据，跳过最后一条 rm -rf /var/lib/dagu 即可。

十一、参考链接