错误：Authentication failed 排查指南

当使用 MCP postgres 工具连接数据库时，如果遇到 "Authentication failed" 错误，说明身份验证失败。本文提供完整的排查和解决方案。

错误现象

Error: Authentication failed for user 'username'
Error: password authentication failed for user 'username'

错误原因

1. 用户名或密码错误
2. pg_hba.conf 配置问题
3. 用户不存在或无权限
4. 认证方法不匹配

排查步骤

第一步：检查用户名和密码

验证连接字符串

{
  "mcpServers": {
    "postgres": {
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres",
        "postgresql://username:password@localhost/dbname"
      ]
    }
  }
}

常见错误

• 用户名拼写错误
• 密码包含特殊字符未转义
• 使用了错误的数据库名

使用环境变量（推荐）

{
  "mcpServers": {
    "postgres": {
      "args": ["-y", "@modelcontextprotocol/server-postgres", "postgresql://localhost/dbname"],
      "env": {
        "PGUSER": "username",
        "PGPASSWORD": "password"
      }
    }
  }
}

第二步：检查 pg_hba.conf 配置

找到配置文件

# 查看配置文件位置
ps aux | grep config_file

# 通常是
# /usr/local/var/postgres/pg_hba.conf (macOS)
# /etc/postgresql/15/main/pg_hba.conf (Linux)

检查认证方法

# 查看 pg_hba.conf
cat /path/to/pg_hba.conf | grep -v "^#" | grep -v "^$"

常见配置

# TYPE  DATABASE        USER            ADDRESS                 METHOD
host    all             all             127.0.0.1/32            trust
host    all             all             ::1/128                 trust
host    all             all             0.0.0.0/0               md5

认证方法说明

方法	说明	安全性
trust	无需密码	低
md5	MD5 密码验证	中
scram-sha-256	SCRAM 验证	高
password	明文密码	低
peer	本地用户匹配	中

第三步：检查用户是否存在

使用 psql 检查用户

# 以 postgres 用户登录
psql -U postgres

# 查看所有用户\du

# 查看特定用户\du username

创建用户

-- 创建新用户
CREATE USER username WITH PASSWORD 'password';

-- 授予数据库权限
GRANT CONNECT ON DATABASE dbname TO username;
GRANT USAGE ON SCHEMA public TO username;
GRANT SELECT ON ALL TABLES IN SCHEMA public TO username;

第四步：检查用户权限

查看用户权限

-- 查看用户权限\dp

-- 查看数据库权限\l

-- 查看特定表权限\z tablename

授予权限

-- 授予查询权限
GRANT SELECT ON tablename TO username;

-- 授予所有权限
GRANT ALL PRIVILEGES ON DATABASE dbname TO username;

第五步：重启 PostgreSQL

修改 pg_hba.conf 后必须重启：

# macOS
brew services restart postgresql

# Linux
sudo systemctl restart postgresql

常见问题

Q: 密码正确但还是认证失败？

可能原因：

1. pg_hba.conf 中没有允许该 IP 的连接
2. 认证方法不匹配
3. 用户没有该数据库的权限

解决：

# 检查 pg_hba.conf
grep "host" /path/to/pg_hba.conf

# 确保有允许本地连接的配置
host    all             all             127.0.0.1/32            md5

Q: 如何重置用户密码？

-- 以 postgres 用户登录
psql -U postgres

-- 修改密码\password username
-- 或
ALTER USER username WITH PASSWORD 'newpassword';

Q: 如何查看当前认证配置？

# 查看 pg_hba.conf
cat /path/to/pg_hba.conf

# 查看当前连接使用的认证方式\show password_encryption;

验证修复

1. 确认用户名密码正确
2. 确认 pg_hba.conf 允许连接
3. 确认用户有数据库权限
4. 重启 PostgreSQL
5. 使用 psql 测试连接
6. 重启 Claude Code

下一步

• PostgreSQL 工具配置
• Connection refused 错误排查
• 文件系统工具配置