Node MariaDB应用部署Namecheap后注册接口超时500错误排查

静态页面访问正常、POST接口挂5分钟返回500、无明确错误栈、请求被重复分发，是Namecheap共享主机部署Node.js应用的典型问题，核心原因基本集中在以下几点：

• 数据库连接配置错误：Namecheap共享主机的MariaDB地址不是本地调试用的localhost，必须使用cPanel数据库面板提供的专属内网主机地址，部分实例还会分配非3306的服务端口；如果配置错地址/端口，连接请求会被主机防火墙静默丢弃，不会直接抛出连接拒绝错误，会一直挂起到服务器5分钟硬超时阈值才终止。你看到的请求重复分发，是主机默认的Phusion Passenger进程管理器在请求挂起后的自动重试行为。
• 数据库驱动未配置超时：MariaDB Node.js驱动默认无连接、查询超时限制，连接挂起时不会触发错误回调，Express路由层只会记录请求匹配、分发的日志，捕获不到挂起的异步连接，所以DEBUG日志里看不到错误栈。
• 环境变量未生效：很多用户只在项目本地的.env文件里写配置，没有在cPanel的Node.js应用设置面板同步配置环境变量，导致生产环境读不到正确的数据库连接参数，默认回退到localhost配置触发连接挂起。
• 静态资源走Express内置的static模块直接读取文件返回，不涉及数据库连接，所以不受影响可以正常访问。

1. 先独立验证数据库连接 #

不要在业务路由里测连接，在项目根目录新建db-test.js写入以下代码，先排除数据库配置问题：

const mariadb = require('mariadb');
// 所有参数从cPanel数据库面板复制，不要沿用本地配置
const pool = mariadb.createPool({
  host: process.env.DB_HOST,
  port: Number(process.env.DB_PORT),
  user: process.env.DB_USER,
  password: process.env.DB_PASSWORD,
  database: process.env.DB_NAME,
  connectionLimit: 3, // 共享主机限制连接数，不要设超过5
  connectTimeout: 5000 // 强制5秒连接超时，禁止无限等待
});

async function testConnection() {
  try {
    const conn = await pool.getConnection();
    console.log('数据库连接成功，连接ID：', conn.threadId);
    const testResult = await conn.query('SELECT 1 AS pass');
    console.log('查询测试通过：', testResult);
    conn.release();
    process.exit(0);
  } catch (err) {
    console.error('数据库连接失败，错误详情：', err);
    process.exit(1);
  }
}
testConnection();

通过SSH进入Namecheap主机的项目目录，执行node db-test.js：

• 如果5秒内返回连接失败错误，根据错误提示核对参数：注意创建数据库用户后，必须在cPanel面板操作「将用户添加到数据库」，给用户分配对应库的全部权限，否则账号密码正确也无法连接。
• 如果一直卡着无输出，直接回cPanel核对DB_HOST、DB_PORT参数，不要用localhost/127.0.0.1。

2. 给数据库连接池加全链路超时配置 #

验证数据库连接正常后，修改业务里的数据库连接池配置，加全链路超时参数，从根源避免连接挂起无响应：

const pool = mariadb.createPool({
  // 基础连接参数
  connectTimeout: 3000, // 建立连接超时3秒
  socketTimeout: 10000, // 单条SQL执行超时10秒
  acquireTimeout: 5000 // 从连接池获取连接超时5秒
});

配置完成后，任何数据库层面的阻塞都会直接抛出明确错误，不会再挂到5分钟服务器超时。

3. 补全全局错误捕获逻辑 #

在所有路由注册的最末尾，添加Express错误处理中间件和全局Promise异常捕获，保证所有错误都能打日志：

// 放在所有app.use()、app.get/post()等路由注册代码之后
app.use((err, req, res, next) => {
  console.error('请求处理错误：', {
    path: req.path,
    method: req.method,
    errorStack: err.stack,
    time: new Date().toISOString()
  });
  res.status(500).send('服务内部错误');
});

// 捕获未处理的Promise异常
process.on('unhandledRejection', (err) => {
  console.error('未捕获的异步异常：', err?.stack || err);
});

配置后所有未被业务代码捕获的错误都会输出到stderr.log，不会再出现无错误栈的情况。

4. 核对Node.js应用启动配置 #

• 进入cPanel的Node.js应用设置页，确认所有环境变量（数据库参数、PORT等）都已经在面板里配置完成，不要依赖本地.env文件（共享主机默认不会自动加载.env，除非你自己用dotenv配置且确认.env文件已经上传到服务器）。
• 应用监听端口不要硬编码，必须监听process.env.PORT，Passenger会自动做请求转发，不需要自己配置端口。
• 确认已经在项目目录执行过npm install --production，所有依赖都安装完成，Node.js版本和本地开发版本保持一致。

如果以上步骤完成后仍有问题，在storeUserController的关键节点加日志打点：

const storeUser = async (req, res, next) => {
  console.log('步骤1：进入注册控制器，请求参数：', req.body);
  try {
    console.log('步骤2：准备执行数据库操作');
    // 原有注册业务逻辑
    console.log('步骤3：数据库操作完成，准备返回响应');
    res.status(200).json({code: 0, msg: '注册成功'});
  } catch (err) {
    console.log('步骤4：捕获业务错误：', err);
    next(err);
  }
}

触发注册请求后看日志停在哪个步骤：停在步骤2就是数据库连接/查询阻塞，停在其他步骤对应排查对应节点的逻辑即可。

注意：Namecheap共享主机对单个Node.js进程有资源限制，单请求内存占用不能超过128MB，不要在注册逻辑里执行大文件读写、外站API请求等耗时操作，否则也会触发超时终止。

内容的提问来源于stack exchange，提问作者Daniel Torres