Node-Postgres 中 SCRAM-SERVER-FIRST-MESSAGE 密码类型错误的解决方案

问题背景

在使用 Node-Postgres 连接 PostgreSQL 数据库时，开发者可能会遇到一个常见的认证错误："SASL: SCRAM-SERVER-FIRST-MESSAGE: client password must be a string"。这个错误通常发生在使用 SCRAM-SHA-256 认证机制时，表明客户端提供的密码不符合预期类型。

错误原因分析

该错误的根本原因是 PostgreSQL 客户端库期望接收一个字符串类型的密码，但实际接收到的可能是 undefined、null 或其他非字符串类型的值。这种情况通常发生在以下几种场景：

1. 环境变量未正确设置或拼写错误
2. 数据库连接配置中密码字段被意外忽略
3. 多个数据库连接实例之间配置不一致
4. ORM 或认证库与直接连接混合使用时配置冲突

典型解决方案

1. 检查环境变量配置

确保数据库连接密码的环境变量名称正确且已设置。例如，在项目中检查是否使用了正确的变量名：

// 错误示例：变量名拼写错误
const password = process.env.VITE_PWS; // 应该是 VITE_PWD

// 正确示例
const password = process.env.VITE_PWD;

2. 验证密码字段类型

在创建连接池或客户端时，显式验证密码类型：

const pool = new Pool({
  user: 'dbuser',
  host: 'localhost',
  database: 'mydb',
  password: typeof process.env.DB_PASSWORD === 'string' ? process.env.DB_PASSWORD : '',
  port: 5432,
});

3. 统一数据库连接实例

当使用 ORM（如 Drizzle）和认证库（如 Lucia Auth）时，确保它们使用相同的数据库连接实例：

// db.ts - 创建共享的连接池
import { Pool } from 'pg';
export const pool = new Pool({ /* 配置 */ });

// auth.ts - 使用相同的连接实例
import { pool } from './db';
import { pg } from '@lucia-auth/adapter-postgresql';

const auth = lucia({
  adapter: pg(pool),
  // 其他配置
});

4. 硬编码测试

为排除环境变量问题，可以暂时硬编码密码进行测试：

const pool = new Pool({
  // 其他配置
  password: 'your_actual_password_here', // 临时测试用
});

深入理解 SCRAM 认证

SCRAM (Salted Challenge Response Authentication Mechanism) 是 PostgreSQL 默认的安全认证机制。其工作流程包括：

1. 客户端发起连接请求
2. 服务器发送第一个挑战消息 (SERVER-FIRST-MESSAGE)
3. 客户端需要使用字符串类型的密码计算响应
4. 如果密码非字符串，就会触发本文讨论的错误

最佳实践建议

1. 统一配置管理：集中管理数据库配置，避免多处定义
2. 类型检查：在关键位置添加类型验证
3. 连接池复用：特别是在复杂应用中复用连接池
4. 错误处理：添加详细的连接错误日志记录
5. 开发/生产环境检查：确保环境变量在不同环境中一致

总结

"SASL: SCRAM-SERVER-FIRST-MESSAGE: client password must be a string" 错误虽然表象简单，但反映了数据库连接配置中的深层次问题。通过系统性地检查配置来源、统一连接管理和加强类型验证，可以有效预防和解决此类问题。在复杂应用中，特别注意 ORM 和认证库之间的配置一致性是避免这类错误的关键。