Node.js 服务部署入门:进程管理、反向代理与优雅退出

安排服务启动、请求转发与停止流程,并区分应用和部署平台的职责

🎯 引言

学完这篇文章,你能安排服务启动、请求转发与停止流程,并区分应用和部署平台的职责。

⚙️ 为应用提供健康检查

沿用工程化篇的 config.mjs 和统一异常篇的 error-handler.mjs。新建 service.mjs:

service.mjs
import express from 'express';
import { setTimeout as delay } from 'node:timers/promises';
import { config } from './config.mjs';
import { errorHandler } from './error-handler.mjs';

const app = express();
let stopping = false;

停止过程中不再执行新的业务操作:

service.mjs
app.use((req, res, next) => {
    if (stopping) return res.status(503).json({ error: '服务正在停止' });
    next();
});

添加健康检查:

service.mjs
app.get('/health', (req, res) => {
    res.json({ status: 'ok' });
});

/health 证明 HTTP 服务能够响应。平台若需要判断能否接收业务流量,还要检查数据库等必要依赖是否就绪,并限制检查耗时。


⏳ 用慢接口观察停止过程

添加一个等待 1.5 秒的接口:

service.mjs
app.get('/slow', async (req, res) => {
    await delay(1500);
    res.json({ message: '处理完成' });
});
app.use(errorHandler);

它用于观察已经接收的请求能否在服务停止前完成。Express 5 会把异步失败交给错误中间件。


🔌 监听并设置接收期限

service.mjs
const server = app.listen(config.port, '127.0.0.1', () => {
    console.log('服务已启动', process.pid);
});
server.headersTimeout = 10_000;
server.requestTimeout = 30_000;

app.listen 返回 HTTP 服务器对象。headersTimeout 限制接收完整请求头的时间,requestTimeout 限制接收完整请求的时间;它们不限制业务函数执行时间,数据库和外部调用仍需各自配置超时。

监听本机适合同机反向代理访问。容器需要通过端口映射访问时,可监听 0.0.0.0,再通过容器和网络规则限制外部入口。


🛑 优雅退出先等待,再兜底

优雅退出是先停止接收新工作,给已接受的请求完成机会,再释放资源。先添加超时后的兜底函数:

service.mjs
function forceStop() {
    console.error('超过退出等待期限');
    server.closeAllConnections();
    process.exit(1);
}

再添加正常退出流程:

service.mjs
function shutdown() {
    if (stopping) return;
    stopping = true;
    const deadline = setTimeout(forceStop, 5000);
    server.close(() => {
        clearTimeout(deadline);
        console.log('HTTP 请求已结束');
    });
}

server.close 停止接收新连接并等待当前 HTTP 请求结束。正常结束就清除兜底计时器;超过 5 秒才强制中断。实际业务的等待期限应与允许请求时长协调。


📣 接收停止通知并验证

继续添加信号处理:

service.mjs
process.on('SIGTERM', shutdown);
process.on('SIGINT', shutdown);

SIGTERM 常由部署平台发送,Ctrl+C 通常触发 SIGINT。启动服务后,在另一个终端请求 /slow,1.5 秒结束前按 Ctrl+C;客户端应仍得到 200 和“处理完成”,然后服务退出。

node --env-file=.env service.mjs
curl -i http://127.0.0.1:3000/slow

有数据库时,在 HTTP 请求结束后关闭连接池;有 SSE 或 WebSocket 时主动通知并结束长连接,不能期待所有连接都自动结束。未捕获的严重异常也不能只打印后继续正常营业,应记录并由外部管理重新启动。


🧰 让进程管理工具负责恢复

Linux 的 systemd 可以在开机时启动服务,并在异常退出后重启。下面是一个服务单元示例,应放到已准备好的 Linux 服务器上;不是 macOS 本地命令。

backend-demo.service
[Unit]
Description=Backend demo
After=network.target

[Service]
Type=exec
User=nodeapp
WorkingDirectory=/srv/backend-demo
ExecStart=/opt/node/bin/node --env-file=/srv/backend-demo/.env service.mjs
Restart=on-failure
RestartSec=3
TimeoutStopSec=10

[Install]
WantedBy=multi-user.target

使用前需要创建低权限账号 nodeapp、部署文件并授予所需读写权限,将 Node 路径替换为服务器上的实际绝对路径。应用自己的 5 秒期限短于平台的 10 秒,才能先完成清理。不要用管理员账号长期运行普通接口。

将单元安装到 /etc/systemd/system/ 后,重新加载并启用:

sudo systemctl daemon-reload
sudo systemctl enable --now backend-demo

查看状态与日志:

systemctl status backend-demo
journalctl -u backend-demo -f

看到进程运行后仍要请求 /health 验证响应。失败时查看路径、账号权限与配置,不能只反复重启。


🌐 由反向代理提供外部入口

Nginx 接收外部请求,再转发到本机 Node.js。下面是已安装 Nginx 环境中的 HTTP 转发配置,应放在 http 上下文内加载的配置文件中:

server {
    listen 80;
    server_name api.example.com;
    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_set_header Host $host;
    }
}

这里不带额外路径的 proxy_pass 保留原请求路径。示例只展示转发,正式登录服务还必须为域名配置有效证书与 HTTPS,并将 HTTP 入口重定向到 HTTPS;不要直接通过公网明文传输密码。

修改配置后先检查再重新加载:

sudo nginx -t
sudo systemctl reload nginx

如果本机 /health 成功,域名访问却 502,检查代理目标与监听地址;若页面报 CORS,检查浏览器来源许可,不要把所有问题都归为“Node.js 没启动”。


❓ 知识问答

Q1:Node.js 崩溃后能靠自己的代码重启自己吗?

应由外部进程管理工具负责,应用进程已结束时内部定时器也不再运行。

Q2:为什么不收到信号就直接退出?

可能截断正在发送的响应或数据写入。等待已有请求完成能减少这类中断,但必须有上限。

Q3:反向代理能替代身份认证吗?

普通转发不能。它负责网络入口,业务接口仍需要自己的身份和权限检查。


🧪 小练习

先验证慢请求能在停止时完成,再将演示延迟改为 8 秒,验证 5 秒兜底会中断请求。完成后恢复原值,不把测试配置用于正式业务。

// 请在这里编写代码或记录验证结果