Quartz 4

🔍 搜索

Quartz v4制作自启动

13 min read

Quartz v4制作自启动

component Quartz

服务部署好了，本地使用的是linux系统，帮我制作一个自启动服务，启动知识库

在 Linux 系统中，最标准、最稳定的自启动方式是创建一个 Systemd 服务。

考虑到你使用了 nvm 管理 Node 版本，直接写 Systemd 配置文件通常会因为找不到 Node 环境变量而报错。

这里为你提供两种方案：方案一（Systemd 标准版） 和 方案二（PM2 懒人版，强烈推荐）。

方案一：使用 PM2 管理 (强烈推荐 ⭐)

对于 Node.js 项目（如 Quartz），使用 PM2 进程管理器是最简单的。它能自动处理环境变量、崩溃重启和日志管理，而且生成自启动脚本非常傻瓜化。

1. 安装 PM2

在终端执行（如果你之前通过 nvm 安装了 node，这一步会安装到当前 node 版本下）：

npm install -g pm2

2. 启动 Quartz

进入你的项目目录并启动：

cd /home/zbc/code_pangu/quartz

# 使用 PM2 启动 npm run dev，并命名为 "quartz-blog"
pm2 start npm --name "quartz-blog" -- run dev

此时，你的博客已经在后台运行了。你可以关闭终端验证一下网页是否还能访问。

3. 生成开机自启

这是最关键的一步。运行以下命令，PM2 会自动检测你的系统并生成 Systemd 脚本：

pm2 startup

注意： 终端会输出一行类似 sudo env PATH=$PATH:/home/zbc/... pm2 startup systemd -u zbc ... 的命令。 你需要复制那行输出的命令，并再次粘贴执行它。

4. 保存当前状态

执行完上一步后，运行保存命令，锁定当前运行列表：

pm2 save

搞定！ 下次开机它就会自动启动了。

  • 常用命令：
    • 查看状态：pm2 status
    • 看日志：pm2 logs quartz-blog
    • 重启：pm2 restart quartz-blog
    • 停止：pm2 stop quartz-blog

方案二：编写 Systemd 服务文件 (传统硬核)

如果你不想安装 PM2，想用纯原生的 Systemd，你需要手动指定 node 的绝对路径。

1. 获取 Node 和 npm 的绝对路径

因为你是用 nvm 安装的，路径比较深。请在终端执行：

which npm
# 输出示例：/home/zbc/.nvm/versions/node/v22.x.x/bin/npm

记下这个路径。

2. 创建服务文件

使用 sudo 编辑一个新的服务文件：

sudo nano /etc/systemd/system/quartz.service

粘贴以下内容（注意替换 ExecStart 里的路径为你刚才查到的路径）：

[Unit]
Description=Quartz Knowledge Base Service
After=network.target
 
[Service]
Type=simple
# 你的用户名
User=zbc
# 你的项目路径 (根据之前的日志推断)
WorkingDirectory=/home/zbc/code_pangu/quartz
 
# 关键：这里要用刚才 `which npm` 查到的绝对路径
# 格式：<npm绝对路径> run dev
ExecStart=/home/zbc/.nvm/versions/node/v22.12.0/bin/npm run dev
 
# 环境变量 (可选，如果遇到编码问题可加上)
Environment=NODE_ENV=production
 
# 崩溃后自动重启
Restart=on-failure
RestartSec=10
 
[Install]
WantedBy=multi-user.target

按 Ctrl+O 保存，Ctrl+X 退出。

3. 启用并启动服务

# 重载配置
sudo systemctl daemon-reload
 
# 设置开机自启
sudo systemctl enable quartz
 
# 立即启动
sudo systemctl start quartz

4. 检查状态

sudo systemctl status quartz

如果显示绿色的 active (running)，恭喜你，配置成功！

总结建议

  • 如果你希望简单、省心，特别是需要经常看日志调试，请选 方案一 (PM2)。
  • 如果你是服务器运维，希望保持系统极度纯净，请选 方案二 (Systemd)。

常见报错问题解决

1. 常见错误mpm环境环境环境变量适配错误

报错如下

sudo systemctl status quartz
● quartz.service - Quartz Knowledge Base Service
     Loaded: loaded (/etc/systemd/system/quartz.service; enabled; preset: enabl>
     Active: activating (auto-restart) (Result: exit-code) since Sun 2025-12-28>
    Process: 602393 ExecStart=/home/zbc/.nvm/versions/node/v22.12.0/bin/npm run>
   Main PID: 602393 (code=exited, status=203/EXEC)
        CPU: 1ms
lines 1-6/6 (END)

解决方案

这个错误代码 status=203/EXEC 的含义非常明确：系统找不到你指定的执行文件。

这通常是因为我之前给你的配置中，ExecStart 路径里的 Node 版本号 (v22.12.0) 是我预估的，而你本机实际安装的版本号可能不一样（比如是 v22.0.0 或其他），或者 NVM 环境下的 npm 需要特殊的 PATH 配置 才能被 Systemd 识别。

请按照以下 3 步修正：

第一步：获取本机真实的 Node 路径

请在终端执行下面这行命令，它会直接打印出你当前使用的 Node 安装目录：

echo $(dirname $(which npm))
  • 输出结果应该类似：/home/zbc/.nvm/versions/node/v22.x.x/bin
  • 请复制这个路径，我们待会要用到（下文称为 <你的Node路径>）。

第二步：修改 Systemd 配置文件

Systemd 启动时不会加载你的 .bashrc，所以它既不知道 npm 在哪，也不知道 npm 依赖的 node 在哪。我们需要显式告诉它。

编辑文件：

sudo nano /etc/systemd/system/quartz.service

将内容修改为如下（重点修改 Environment 和 ExecStart）：

[Unit]
Description=Quartz Knowledge Base Service
After=network.target

[Service]
Type=simple
User=zbc
WorkingDirectory=/home/zbc/code_pangu/quartz

# 【关键点1】显式设置 PATH，让 npm 能找到 node
# 请将 <你的Node路径> 替换为第一步里查到的真实路径！
# 例如：Environment=PATH=/home/zbc/.nvm/versions/node/v22.12.0/bin:/usr/local/bin:/usr/bin:/bin
Environment=PATH=<你的Node路径>:/usr/local/bin:/usr/bin:/bin

# 【关键点2】使用绝对路径启动
# 格式：<你的Node路径>/npm run dev
# 例如：ExecStart=/home/zbc/.nvm/versions/node/v22.12.0/bin/npm run dev
ExecStart=<你的Node路径>/npm run dev

Restart=on-failure
RestartSec=10

[Install]
WantedBy=multi-user.target

修改示范： 如果第一步输出是 /home/zbc/.nvm/versions/node/v22.3.0/bin，那么：

  • Environment=PATH=/home/zbc/.nvm/versions/node/v22.3.0/bin:/usr/local/bin:/usr/bin:/bin
  • ExecStart=/home/zbc/.nvm/versions/node/v22.3.0/bin/npm run dev

第三步：重载并重启

保存退出后（Ctrl+O → 回车 → Ctrl+X），执行：

# 1. 重载配置
sudo systemctl daemon-reload

# 2. 重启服务
sudo systemctl restart quartz

# 3. 再次检查状态
sudo systemctl status quartz

这次应该就能看到绿色的 Active: active (running) 了。

💡 为什么之前会报错？

npm 本质上是一个脚本，它的第一行是 #!/usr/bin/env node。 Systemd 默认的 PATH 只有 /usr/bin，里面没有 node（因为你的 node 在 NVM 目录下）。所以即使你把 npm 的路径写对了，npm 运行起来去找 node 时也会找不到，从而导致 203 错误。加上 Environment=PATH=... 是 NVM 环境下的必杀技。

2. status=1/FAILURE 缺少 HOME 环境变量。

报错如下

 sudo systemctl status quartz
● quartz.service - Quartz Knowledge Base Service
     Loaded: loaded (/etc/systemd/system/quartz.service; enabled; preset: enabl>
     Active: activating (auto-restart) (Result: exit-code) since Sun 2025-12-28>
    Process: 604037 ExecStart=/home/zbc/.nvm/versions/node/v22.21.1/bin/npm run>
   Main PID: 604037 (code=exited, status=1/FAILURE)
        CPU: 1.602s

解决方案

status=1/FAILURE 是一个运行时错误，这意味着 Systemd 成功找到了 npm 并开始执行，但程序自己报错退出了。这比之前的 203 错误（找不到文件）进步了一步！

根据经验，出现这种情况最可能的原因有两个：端口被占用（你之前的终端还没关）或者 缺少 HOME 环境变量。

请按以下步骤依次排查和修复：

第一步：查看报错日志（关键）

Systemd 的 status 输出被截断了，我们需要看详细日志才能确诊。请执行：

journalctl -u quartz.service -n 20 --no-pager

预测情况 A：端口被占用 如果日志里出现 EADDRINUSE: address already in use :::5000 (或 8080)，说明你之前在终端里手动运行 或者简单粗暴地杀掉所有 node 进程：pkill -f node

  1. 重启服务：sudo systemctl restart quartz

执行上面命令后得到

sudo systemctl status quartz
● quartz.service - Quartz Knowledge Base Service
     Loaded: loaded (/etc/systemd/system/quartz.service; enabled; preset: enabl>
     Active: activating (auto-restart) (Result: exit-code) since Sun 2025-12-28>
    Process: 604037 ExecStart=/home/zbc/.nvm/versions/node/v22.21.1/bin/npm run>
   Main PID: 604037 (code=exited, status=1/FAILURE)
        CPU: 1.602s
 
zbc@zbc-System-Product-Name:~$ journalctl -u quartz.service -n 20 --no-pager
12月 28 11:26:57 zbc-System-Product-Name npm[604572]: npm ERR! A complete log of this run can be found in:
12月 28 11:26:57 zbc-System-Product-Name npm[604572]: npm ERR!     /home/zbc/.npm/_logs/2025-12-28T03_26_57_060Z-debug-0.log
12月 28 11:26:57 zbc-System-Product-Name systemd[1]: quartz.service: Main process exited, code=exited, status=1/FAILURE
12月 28 11:26:57 zbc-System-Product-Name systemd[1]: quartz.service: Failed with result 'exit-code'.
12月 28 11:26:57 zbc-System-Product-Name systemd[1]: quartz.service: Consumed 1.607s CPU time.
12月 28 11:27:07 zbc-System-Product-Name systemd[1]: quartz.service: Scheduled restart job, restart counter is at 29.
12月 28 11:27:07 zbc-System-Product-Name systemd[1]: Started quartz.service - Quartz Knowledge Base Service.
12月 28 11:27:08 zbc-System-Product-Name npm[604622]: > @jackyzha0/quartz@4.5.2 dev
12月 28 11:27:08 zbc-System-Product-Name npm[604622]: > npx quartz build --serve --port 5000
12月 28 11:27:08 zbc-System-Product-Name npm[604639]: npm ERR! code EBADENGINE
12月 28 11:27:08 zbc-System-Product-Name npm[604639]: npm ERR! engine Unsupported engine
12月 28 11:27:08 zbc-System-Product-Name npm[604639]: npm ERR! engine Not compatible with your version of node/npm: @jackyzha0/quartz@4.5.2
12月 28 11:27:08 zbc-System-Product-Name npm[604639]: npm ERR! notsup Not compatible with your version of node/npm: @jackyzha0/quartz@4.5.2
12月 28 11:27:08 zbc-System-Product-Name npm[604639]: npm ERR! notsup Required: {"npm":">=10.9.2","node":">=22"}
12月 28 11:27:08 zbc-System-Product-Name npm[604639]: npm ERR! notsup Actual:   {"npm":"9.2.0"}
12月 28 11:27:08 zbc-System-Product-Name npm[604639]: npm ERR! A complete log of this run can be found in:
12月 28 11:27:08 zbc-System-Product-Name npm[604639]: npm ERR!     /home/zbc/.npm/_logs/2025-12-28T03_27_08_306Z-debug-0.log
12月 28 11:27:08 zbc-System-Product-Name systemd[1]: quartz.service: Main process exited, code=exited, status=1/FAILURE
12月 28 11:27:08 zbc-System-Product-Name systemd[1]: quartz.service: Failed with result 'exit-code'.
12月 28 11:27:08 zbc-System-Product-Name systemd[1]: quartz.service: Consumed 1.681s CPU time.

日志真相大白！问题出在 环境变量 PATH 上。

🔍 错误分析

日志显示：

  1. 报错原因：npm ERR! engine Not compatible ... Actual: {"npm":"9.2.0"}。 Quartz v4 需要 npm 10.9.2 以上，但 Systemd 实际运行的 npm 版本是 9.2.0。
  2. 为什么会这样：虽然你在 ExecStart 里指定了 Node v22 的 npm 路径，但 npm run dev 在执行内部命令（如 npx）时，会去 PATH 环境变量里找 node/npm。 由于 Systemd 默认不加载你的 .bashrc，它找不到 NVM 设置的路径，于是回退到了你 Linux 系统自带的一个老版本 npm (v9.2.0)，导致报错。

✅ 终极修复方案

你需要修改 /etc/systemd/system/quartz.service 文件，显式添加 Environment 变量，把 Node v22 的路径加到 PATH 的最前面。

1. 编辑服务文件

sudo nano /etc/systemd/system/quartz.service

2. 全文替换 (复制下面的内容)

请直接清空原有内容（或仔细比对），确保 Environment 这一行存在且正确。 (根据你的日志，你的 Node 路径是 /home/zbc/.nvm/versions/node/v22.21.1/bin)

[Unit]
Description=Quartz Knowledge Base Service
After=network.target

[Service]
Type=simple
User=zbc
WorkingDirectory=/home/zbc/code_pangu/quartz

# 核心修复点：强制设置 PATH，让 Systemd 优先使用 NVM 的 Node v22
Environment=PATH=/home/zbc/.nvm/versions/node/v22.21.1/bin:/usr/local/bin:/usr/bin:/bin
# 补充 HOME 变量，防止 npm 找不到缓存目录报错
Environment=HOME=/home/zbc

# 启动命令
ExecStart=/home/zbc/.nvm/versions/node/v22.21.1/bin/npm run dev

# 崩溃重启
Restart=on-failure
RestartSec=10

[Install]
WantedBy=multi-user.target

3. 重载并重启

保存文件 (Ctrl+O → 回车 → Ctrl+X)，然后执行：

# 1. 重载 systemd 配置
sudo systemctl daemon-reload

# 2. 重启服务
sudo systemctl restart quartz

# 3. 再次查看状态
sudo systemctl status quartz

这次应该能看到绿色的 active (running) 了！因为 PATH 设置正确后，脚本就会使用 Node v22 的环境来运行，满足版本要求。****

还有一个需要注意的点

修改 .scss 样式文件后，有时候 Quartz 的热更新（Hot Reload）可能不会立即捕捉到变化。如果保存后网页没有变样，请在终端里按 Ctrl + C 停止，然后重新运行：

npx quartz build --serve

到此问题解决

Graph View

Backlinks