Ubuntu 22.04 安装 Cronmaster 2.4.1 指南

目标：在一台 Ubuntu 22.04 服务器上，用官方预构建包把 Cronmaster 2.4.1 装成 systemd 常驻服务，并验证「登录 → 建任务 → cron 按时执行」全链路。本篇所有命令与回显都来自真实执行的记录，不是推演；文中出现的端口、路径、任务 ID 均与测试机一致。

适用读者：已有 Linux 基础、希望在不引入额外编排系统的前提下管理宿主机 crontab 的运维工程师。

一、方案说明与前置条件

Cronmaster 不替换 cron，也不自己跑任务。它只负责把 /var/spool/cron/crontabs/<user> 这份文本「搬」到浏览器里做增删改查，真正的触发仍由系统 cron 守护进程完成。因此部署形态天然是「单机常驻 Web 服务 + 系统 cron」，本篇采用官方 Release 提供的预构建包（cronmaster_2.4.1_prebuild.tar.gz，约 23 MB），配合 Node.js 24 运行时和 systemd 托管。

1.1 测试环境

1.2 依赖链

预构建包是 Next.js standalone 产物，运行期只依赖三样东西：

1. Node.js 运行时（实测 v24.22.1）。包里自带 node_modules，不需要 npm install。
2. tar 与 xz-utils。官方包是 .tar.gz，但安装 Node 时常见做法是下载 .tar.xz，若缺少 xz 会在解压阶段直接失败——这是本次踩到的第一个坑，见第五节。
3. 系统 cron。任务最终落在 crontab 里，由 cron.service 执行；若 cron 未安装或未启动，面板能建任务但永远不会跑。

ss、netstat 之类工具不是必需，但在排查端口占用时很有用；测试机上恰好没有 ss。

二、安装 Node.js 24

先确认系统自带的 Node 版本。Ubuntu 22.04 仓库里的 Node 通常是 12/16，不满足 Next.js 16 的要求，因此手工装官方二进制包。

apt-get update
apt-get install -y curl xz-utils

注意：xz-utils 必须在解压前安装。本次未装时执行解压报 tar (child): xz: Cannot exec: No such file or directory。

下载并解压 Node 24：

cd /usr/local/src
curl -fsSLO https://nodejs.org/dist/v24.22.1/node-v24.22.1-linux-x64.tar.xz
tar -xf node-v24.22.1-linux-x64.tar.xz
mv node-v24.22.1-linux-x64 /usr/local/node24
ln -sfn /usr/local/node24/bin/node /usr/local/bin/node
ln -sfn /usr/local/node24/bin/npm /usr/local/bin/npm

验证：

node -v
npm -v

回显：

v24.22.1
11.19.1

三、部署预构建包

3.1 获取并解压

mkdir -p /opt/cronmaster
cd /opt/cronmaster
curl -fsSLO https://github.com/fccview/cronmaster/releases/download/2.4.1/cronmaster_2.4.1_prebuild.tar.gz
tar -xzf cronmaster_2.4.1_prebuild.tar.gz -C /opt/cronmaster --strip-components=1

解压后的目录结构关键点：

ls -1 /opt/cronmaster

app
howto
node_modules
package.json
server.js
.next

需要说明的是：预构建包里没有 .next/standalone 目录，但根目录有 server.js 和完整的 node_modules。server.js 是 Next.js standalone 启动入口，直接 node server.js 即可，无需 next start，也无需构建。

3.2 准备数据目录

面板会在运行期生成日志、包装脚本和自定义翻译，默认落在应用目录下的 data/ 与 scripts/：

mkdir -p /opt/cronmaster/data /opt/cronmaster/scripts /opt/cronmaster/snippets

四、systemd 托管

4.1 编写单元文件

创建 /etc/systemd/system/cronmaster.service：

[Unit]
Description=Cronmaster 2.4.1 cron management panel
Documentation=https://github.com/fccview/cronmaster
After=network-online.target cron.service
Wants=network-online.target

[Service]
Type=simple
WorkingDirectory=/opt/cronmaster
Environment=NODE_ENV=production
Environment=PORT=3000
Environment=HOSTNAME=0.0.0.0
Environment=AUTH_PASSWORD=q1w2e3r4
Environment=HOST_CRONTAB_USER=root
Environment=LOCALE=zh
ExecStart=/usr/local/bin/node /opt/cronmaster/server.js
Restart=always
RestartSec=5
User=root

[Install]
WantedBy=multi-user.target

几个关键点：

• After=... cron.service：确保 cron 先起来，避免面板启动后读到空 crontab。
• User=root：Cronmaster 需要读写 /var/spool/cron/crontabs/root，非 root 身份会因权限不足而无法保存。
• LOCALE=zh：中文界面。注意不要写 zh-cn，原因见第五节排障。
• HOSTNAME=0.0.0.0：让 Next.js 监听所有网卡，否则只能本机访问。
• Restart=always：进程异常退出后自动拉起，实测 RestartSec=5 足够。

4.2 启动与自检

systemctl daemon-reload
systemctl enable --now cronmaster
systemctl is-enabled cronmaster
systemctl is-active cronmaster

回显：

enabled
active

查看进程资源占用：

systemctl show cronmaster -p MainPID -p MemoryCurrent -p TasksCurrent

回显：

MainPID=2818
MemoryCurrent=95727616
TasksCurrent=11

即主进程 PID 2818，常驻内存约 91 MiB（95727616 字节），线程 11 个。这个量级对一台 4 GB 内存的服务器可以忽略不计。

健康检查：

curl -s http://127.0.0.1:3000/api/health

回显：

{"status":"healthy"}

五、登录与建任务

浏览器访问 http://<服务器IP>:3000，进入登录页，输入 AUTH_PASSWORD 设置的密码（本次为 q1w2e3r4），登录后进入任务列表。

5.1 通过 API 验证登录

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

回显：

{"success":true,"message":"Login successful"}

5.2 新建任务

在界面点「新建任务」，填写：

保存后任务出现在列表中，ID 为 mi57-o0t1。对应的 crontab 内容：

crontab -l

# B1 test job | id: mi57-o0t1
* * * * * echo cronmaster-b1-test >> /tmp/b1-test.log

面板会把备注和任务 ID 写成注释行，放在任务上方。这一点很实用：即使以后面板下线，这份 crontab 仍然可读、可维护。

六、验证任务真实执行

等待一到两分钟，检查任务写入的目标文件：

cat /tmp/b1-test.log

回显（已累计 3 次执行）：

cronmaster-b1-test
cronmaster-b1-test
cronmaster-b1-test

说明系统 cron 按 * * * * * 每分钟触发了一次，cronmaster-b1-test 字符串被真实追加。至此「面板建任务 → 文本落入 crontab → 系统 cron 执行」的闭环验证通过。

七、排障实录

7.1 解压 Node 包报 xz: Cannot exec

现象：

tar (child): xz: Cannot exec: No such file or directory

原因：Node 官方 Linux 包使用 .tar.xz 压缩，Ubuntu 22.04 最小安装未带 xz。

解决：apt-get install -y xz-utils 后重新解压，node -v 输出 v24.22.1。

7.2 LOCALE=zh-cn 启动告警并回退英文

现象：单元文件里写 LOCALE=zh-cn 后，journalctl -u cronmaster 出现：

Cannot find module '../../../_translations/zh-cn.json'

界面仍是英文。

原因：2.4.1 内置的简体中文翻译文件名是 zh.json，不是 zh-cn.json。应用在找不到指定 locale 时会静默回退 en.json，只留一条启动日志。

解决：改为 LOCALE=zh 后界面正常显示中文。这是实测确认的产品缺陷：zh-cn 这个常见写法在 2.4.1 上不可用。

7.3 端口被占用

现象：systemctl start cronmaster 失败，journalctl 显示监听 3000 端口失败。测试机上 3000 端口已被其他服务占用。

解决：一是改单元里的 Environment=PORT=3000 为其他未占用端口；二是先 ss -lntp（或 netstat -lntp）确认占用者再决定。本次测试机上没有 ss，退而使用 netstat 和 /proc/net/tcp 判断，非阻塞性问题。

7.4 面板能建任务但任务不执行

排查顺序：

1. systemctl is-active cron —— 若为 inactive，systemctl enable --now cron。
2. crontab -l —— 确认任务确实写入了当前用户的 crontab。
3. grep CRON /var/log/syslog —— 看 cron 是否尝试执行、是否报命令不存在。
4. 检查命令里的可执行文件是否在 cron 的 PATH 内；cron 默认 PATH 很短，建议写绝对路径（/usr/bin/echo 之类）。

八、日常运维要点

• 升级：停服务 → 备份 data/ 与 scripts/ → 解压新版本包覆盖 → 保留旧 data/ → systemctl start cronmaster。data/ 里是历史日志和包装脚本，务必保留；包装脚本的宿主机绝对路径已经写进 crontab，覆盖升级不影响已有任务。
• 备份：真正需要备份的是 /var/spool/cron/crontabs/<user>（任务本体）和 /opt/cronmaster/data（日志与包装脚本）。
• 降级：Cronmaster 不维护数据库，降级只要换回旧版本目录并重启即可，没有 schema 迁移风险。
• 安全：默认只有密码一道门，生产环境建议同时设置高强度 AUTH_PASSWORD 与 API_KEY，并在前置反向代理上启用 HTTPS。面板具备写 crontab 的能力，等同于宿主机命令执行权限，务必只对可信网络开放。
• 卸载：systemctl disable --now cronmaster，删除 /etc/systemd/system/cronmaster.service、/opt/cronmaster。卸载前先确认 crontab 里的任务是否还需要保留——面板删掉后任务仍会继续跑，需要手工 crontab -e 清理。

九、结论

在 Ubuntu 22.04 上用预构建包 + systemd 部署 Cronmaster 2.4.1 是一条干净路径：不需要编译、不需要数据库、常驻内存约 91 MiB。唯一需要提前准备的是 Node.js 24 与 xz-utils；唯一需要记住的配置陷阱是 LOCALE 必须写 zh 而不是 zh-cn。完成部署后，任务的增删改查与执行日志都在一个 Web 界面里完成，而任务本身仍是标准的 crontab 文本，退出成本很低。

下一步可继续阅读本专栏《Cronmaster 2.4.1 配置参数详解》了解全部环境变量，或《Cronmaster 2.4.1 API 详解》把任务管理接入自有运维平台。