nginx配合express部署的核心是充当入口网关，安全高效转发请求；需确保express监听0.0.0.0、nginx正确配置proxy_pass与x-real-ip等头信息，并按场景区分全量代理、前缀代理或静态资源直服。
Nginx 配合 Express 部署时，核心是让 Nginx 充当入口网关，把用户请求安全、高效地转给运行在本地或容器中的 Express 实例。关键不在 Express 怎么写，而在于 Nginx 怎么“认得清”后端地址、“传得准”客户端信息、“转得稳”各类请求（包括 API、WebSocket、静态资源等）。
ZenHeart zenlink 与 zenlink-mcp 为 OpenClaw，涵盖安装、MCP 注册、钩子接线、入站轮询及升级维护。
确认 Express 服务监听方式
Express 必须绑定到可被 Nginx 访问的地址，不能只监听 localhost 或 127.0.0.1（尤其在 Docker 或跨主机场景下会失效）：
- 开发时可用 app.listen(3000, '0.0.0.0')，确保监听所有接口
- 生产环境推荐用环境变量控制： const PORT = process.env.PORT || 3000
- 启动后验证：在服务器本机执行 curl http://127.0.0.1:3000/ 能返回响应，说明服务就绪
Nginx 基础反向代理配置要点
在 /etc/nginx/conf.d/myapp.conf 中添加 server 块，重点不是套模板，而是理解每行作用：
- listen 80 或 listen 443 ssl：定义 Nginx 接收请求的端口
- proxy_pass http://127.0.0.1:3000：必须以 http:// 开头，末尾不加 /（否则路径拼接会出错）
- proxy_set_header Host $host：把原始域名传给 Express，避免 req.hostname 变成 127.0.0.1
- proxy_set_header X-Real-IP $remote_addr 和 X-Forwarded-For：让 Express 能拿到真实用户 IP
- proxy_http_version 1.1 + Upgrade/Connection 头：必要时支持 WebSocket 升级
常见转发场景与配置差异
根据实际访问路径灵活调整 location 规则：
- 全量代理（整个域名指向 Express）：
→ location / { proxy_pass http://127.0.0.1:3000; }
- 前缀代理（如所有 /api/ 请求）：
→ location /api/ { proxy_pass http://127.0.0.1:3000/; }（注意 proxy_pass 末尾的 /，会剥离 /api）
- 多服务共存（如 /admin 转另一端口）：
→ 新增独立 location /admin/ { proxy_pass http://127.0.0.1:4000/; }
- 静态资源由 Nginx 直接服务（提升性能）：
→ location ~* \.(js|css|png|jpg|gif)$ { root /var/www/myapp/public; expires 1y; }
验证与排错关键步骤
配置完成后别急着 reload，分步确认：
- 运行 nginx -t 检查语法是否合法
- 用 curl -H "Host: yourdomain.com" http://127.0.0.1/ 模拟 Nginx 转发效果
- 查看 Nginx 错误日志：tail -f /var/log/nginx/error.log（超时、连接拒绝等错误基本都在这）
- 在 Express 中打印 req.headers['x-forwarded-for'] 和 req.ip，确认 IP 透传是否生效
- 若页面空白或 502，优先检查 Express 是否真在运行、端口是否被防火墙拦截、proxy_pass 地址能否从 Nginx 所在机器 ping 通或 telnet 通
