Node.js 服务部署入门:进程管理、反向代理与优雅退出
🎯 引言
学完这篇文章,你能安排服务启动、请求转发与停止流程,并区分应用和部署平台的职责。
⚙️ 为应用提供健康检查
沿用工程化篇的 config.mjs 和统一异常篇的 error-handler.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;
停止过程中不再执行新的业务操作:
app.use((req, res, next) => {
if (stopping) return res.status(503).json({ error: '服务正在停止' });
next();
});
添加健康检查:
app.get('/health', (req, res) => {
res.json({ status: 'ok' });
});
/health 证明 HTTP 服务能够响应。平台若需要判断能否接收业务流量,还要检查数据库等必要依赖是否就绪,并限制检查耗时。
⏳ 用慢接口观察停止过程
添加一个等待 1.5 秒的接口:
app.get('/slow', async (req, res) => {
await delay(1500);
res.json({ message: '处理完成' });
});
app.use(errorHandler);
它用于观察已经接收的请求能否在服务停止前完成。Express 5 会把异步失败交给错误中间件。
🔌 监听并设置接收期限
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,再通过容器和网络规则限制外部入口。
🛑 优雅退出先等待,再兜底
优雅退出是先停止接收新工作,给已接受的请求完成机会,再释放资源。先添加超时后的兜底函数:
function forceStop() {
console.error('超过退出等待期限');
server.closeAllConnections();
process.exit(1);
}
再添加正常退出流程:
function shutdown() {
if (stopping) return;
stopping = true;
const deadline = setTimeout(forceStop, 5000);
server.close(() => {
clearTimeout(deadline);
console.log('HTTP 请求已结束');
});
}
server.close 停止接收新连接并等待当前 HTTP 请求结束。正常结束就清除兜底计时器;超过 5 秒才强制中断。实际业务的等待期限应与允许请求时长协调。
📣 接收停止通知并验证
继续添加信号处理:
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 本地命令。
[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 秒兜底会中断请求。完成后恢复原值,不把测试配置用于正式业务。
// 请在这里编写代码或记录验证结果
