彻底搞懂DataGrip报错：Connection refused to host 127.0.0.1排查指南-育师

1. 先说结论：这条报错到底在告诉你什么

我用DataGrip连本地数据库的时候，最常被问到的问题之一就是这个：Connection refused to host: 127.0.0.1。乍一看像是DataGrip本身出了问题，实际上它只是在传话——它把连接请求发到了127.0.0.1这个地址上，但那边根本没有程序在监听，或者说有程序在监听但拒绝了请求，于是DataGrip就把这个底层网络错误原样抛了出来。

拆开看就两件事：一是DataGrip作为客户端确实把请求发出去了，二是目标机器（也就是你自己的电脑）上没有对应的服务在指定端口上接活儿。这跟在浏览器里访问一个没人维护的网站，得到一个"无法访问此网站"的提示是一个道理，只是数据库客户端把这层错误翻译得更技术化了一些。

这个问题的排查价值不在于"怎么消掉这一行字"，而在于搞清楚你的数据库到底有没有在跑、跑在哪个地址上、监听的是哪个端口、允不允许外部连接进来。这四个问题全部对齐了，报错自然消失。反之，任何一个环节对不上，哪怕你把DataGrip删了重装十遍，问题照样还在。

这篇文章既适合刚接触DataGrip的新手，也适合那些被这个报错折磨过但一直没系统梳理过的老手。我会从报错本身的原理讲起，然后给出一套完整的排查路线，最后附上几个我实际踩过的坑和对应的解决办法，保证你能对着自己手头的场景一步步对齐条件。

2. 先理解这行报错的底层逻辑，再动手排查

2.1 从一次握手失败说起

任何数据库连接在建立之前，客户端都要先跟服务端完成一次TCP层面的握手。这个过程大体是：客户端主动向目标IP和端口发起连接请求，服务端回应"好的，我在这里"，双方确认之后才开始传数据。

Connection refused这个错误，对应的是在上图中的第二步就失败了——连接请求确实到达了目标机器，但目标机器上没有任何进程在监听那个端口，于是操作系统直接回答了一个RST包，把连接掐断了。这里的"refused"不是"你没权限访问"的意思，而是"这扇门后面没有人"。你敲了门，没人应，你得到的就是这句话。

在DataGrip的场景里，这个错误通常意味着你填的Host: 127.0.0.1是对的，但这一头的服务没在跑，或者端口填错了。举个例子，我见过不少人用DataGrip连MySQL，端口习惯性填3306，但自己在Docker里起MySQL时映射到了宿主机的33060，结果自然连不上。

2.2 为什么是127.0.0.1，而不是localhost

很多人在DataGrip的连接配置里写的是localhost，出错了之后看到报错信息里变成127.0.0.1，就以为是DataGrip自己改了什么。其实不是——localhost是一个主机名，需要经过解析才能变成IP地址。绝大多数系统里，localhost解析到127.0.0.1（也就是本机回环地址），但也有一小部分情况会解析到::1（IPv6的回环地址）。

这就会引出两个不同的坑：

如果你的数据库服务端只监听了IPv4的127.0.0.1，而DataGrip通过localhost解析到了IPv6的::1，连接照样会失败，而且报错信息里很可能还是Connection refused。
反过来，如果DataGrip里直接写死127.0.0.1，那就明确了"我就要连IPv4的回环地址"，除非服务端根本没监听在这个地址上，否则基本不会因为IP版本不匹配而翻车。

所以我个人的习惯是：在DataGrip连接本地数据库时，Host字段只写127.0.0.1，不写localhost，少一层解析就少一类问题。这不是什么高深技巧，纯粹是用踩坑换来的习惯。

2.3 DataGrip在这条链路里扮演的角色

搞清楚DataGrip的定位很重要。它只是一个客户端工具，本身不提供数据库服务能力，也不负责"唤醒"数据库。DataGrip通过JDBC驱动连接目标数据库——比如连MySQL时用的是MySQL Connector/J，连PostgreSQL时用的是PostgreSQL JDBC驱动。你填入的连接参数，其实是喂给JDBC驱动的，驱动再去发起TCP连接。

所以当DataGrip报Connection refused to host: 127.0.0.1的时候，你要明白这不是DataGrip的代码有bug，而是它如实反映了底层的网络状态。排查方向应该放在"数据库服务是否存活""端口监听是否正确""网络策略是否放行"这几个层面，而不是去重装DataGrip或者清缓存。

3. 从零开始的排查路线：四个层面逐一对齐

3.1 第一层：确认数据库进程真的在跑

最容易忽视也最常见的原因，就是数据库服务压根没启动。说句实话，我见过太多人打开DataGrip发现连不上，第一反应是改连接参数、改驱动版本、重启电脑，折腾半天最后发现MySQL服务根本就没开。

在Windows上，最简单的验证方法是按Win + R输入services.msc打开服务管理器，找到对应的数据库服务（比如MySQL80或者postgresql-x64-16），看它的状态是不是"正在运行"。如果没在运行，右键启动它，再回去连DataGrip。

在macOS或Linux上，可以用命令行确认：

# macOS上查看MySQL进程 ps aux | grep mysqld # Linux上查看服务状态（以systemd为例） systemctl status mysql # 或者 systemctl status postgresql

还有一种更直接的验证方式：直接用命令行客户端连一次试试。比如MySQL：

mysql -u root -p

PostgreSQL的话：

psql -U postgres -h 127.0.0.1

如果命令行能连上，但DataGrip连不上，那问题大概率出在DataGrip的配置上；如果命令行也连不上，那说明问题出在服务端，DataGrip只是背锅的那一个。

提示：有经验的工程师会先做这个五分之一的排查动作，因为它能在几秒钟内把问题范围缩小一半——"到底是我的客户端配置有问题，还是服务端根本没起来"。

3.2 第二层：检查端口监听状态，别被表象骗了

进程在跑，不代表它监听在你期望的地址和端口上。这里有一个非常关键的概念：一个数据库服务可以只监听在一部分网络接口上，而不是所有接口。

用netstat可以查看端口监听情况。在Windows上：

netstat -an | findstr 3306

在Linux或macOS上：

netstat -an | grep 3306 # 或者用更直观的方式 lsof -i :3306

重点看监听地址那一列。如果输出是类似下面这样的：

TCP 0.0.0.0:3306 0.0.0.0:0 LISTENING

说明MySQL监听在所有IPv4地址上，本机通过127.0.0.1去连肯定没问题。

但如果输出是这样：

TCP 127.0.0.1:3306 0.0.0.0:0 LISTENING

也OK，因为监听在127.0.0.1上，DataGrip通过127.0.0.1连是能通的。

真正的问题是下面这种：

TCP 0.0.0.0:3307 0.0.0.0:0 LISTENING

端口对不上。你DataGrip里填的3306，但服务实际跑在3307上，自然会refused。

还有一种很隐蔽的情况：进程明明在跑，端口监听也正常，但监听在IPv6地址上。比如：

TCP [::]:3306 0.0.0.0:0 LISTENING

这种通常意味着服务同时监听了IPv4和IPv6，不影响IPv4连接。但某些老版本或特殊配置下，服务只监听IPv6，那用127.0.0.1去连就不通了。

3.3 第三层：检查DataGrip连接配置，细节决定成败

服务端一切正常的情况下，问题就出在DataGrip这一侧。常见配置坑有这么几个：

主机名填错：比如填了localhost，但解析到IPv6，服务端只监听了IPv4。解决方案：改成127.0.0.1试试。
端口填错：MySQL默认3306，PostgreSQL默认5432，SQL Server默认1433。有些人本地装了多个数据库实例，端口被改过，或者云厂商的数据库端口是定制的，填错了一个也连不上。
数据库名称填错：DataGrip连接配置里会要求填一个要连接的数据库名称。如果填的这个库在服务端不存在，通常会报"Unknown database"而不是"Connection refused"，但有些驱动版本的行为可能不太一样，也值得留意。
认证方式不匹配：MySQL 8.0以上版本默认使用caching_sha2_password认证插件，旧版本的JDBC驱动不支持这种插件，就会报认证错误。这种情况一般不是"Connection refused"，但如果驱动过旧，有时候错误信息也会被包装得莫名其妙。
SSL配置冲突：某些数据库配置了强制SSL，而DataGrip里SSL没启用或者配置不对，也会导致连接建立不了，报错内容五花八门。

我的建议是：新建一个连接配置，把能选项尽量简化，先跑通最小配置再逐步增加选项。比如先不勾SSL、不填数据库名、用最简单的账号密码认证，如果能连上再一项项加回去，很快就能定位到是哪一项配置惹的祸。

3.4 第四层：防火墙和网络策略，本机也可能拦你

很多人以为本机连接不存在防火墙问题，但实际上Windows和macOS的防火墙默认会对入站连接做一些限制，尤其是当数据库服务是手动安装、没有弹出过防火墙授权弹窗的时候，很可能监听是正常的，但外部连接（包括本机的127.0.0.1连接，在某些安全策略下也会被影响）被防火墙拦了。

验证方法很粗暴：先临时关闭防火墙（这只建议在本地开发环境做），再试DataGrip连接。如果能连上，说明是防火墙规则的问题。不过不推荐关防火墙解决问题，正确做法是加一条入站规则，放行对应端口。

在Windows上，具体操作路径是：控制面板 -> Windows Defender防火墙 -> 高级设置 -> 入站规则 -> 新建规则 -> 选择端口 -> 填3306或5432 -> 允许连接。注意适用范围要勾选"这些配置文件"里的"专用"和"来宾或公用"，看你当前网络类型决定。

如果你用的是云服务器上的数据库，那还要检查安全组的入站规则。有些云厂商的安全组默认只放行某些端口，如果你把数据库端口改成非默认值，忘了在安全组里放行，手机上的DataGrip客户端连过去同样是"Connection refused"。

4. 分场景解法：本地库、Docker、远程库，逐一拆解

4.1 本地数据库连不上：从服务端配置文件入手

假设你的MySQL跑在本地，进程在跑，端口也监听了，但DataGrip还是refused，那就要去看MySQL的配置文件。在Linux上通常位于/etc/mysql/mysql.conf.d/mysqld.cnf或/etc/my.cnf，Windows上可能在安装目录的my.ini里。

重点关注配置项：

bind-address = 127.0.0.1

如果是这个值，说明MySQL只监听回环地址，也就是只允许本机连接。如果用DataGrip连接的是本机，这个配置不影响；但如果你想在另一台电脑上用DataGrip连这台机器的MySQL，就必须把它改成：

bind-address = 0.0.0.0

然后重启MySQL服务。改配置文件的逻辑是：0.0.0.0表示监听所有IPv4地址，你的服务才能真正被子网内的其他机器访问到。

PostgreSQL的对应配置在postgresql.conf里的listen_addresses项，默认是localhost，如果只想本机连，保持默认没问题；要支持远程连接，改成'*'。

另外PostgreSQL还有个独立于监听配置的访问控制文件pg_hba.conf，里面规定了哪些IP可以以何种方式认证。防火墙放行了、监听地址也对，但如果pg_hba.conf里没有添加对应IP网段的规则，连接一样会拒。报错信息会不太一样，通常是"no pg_hba.conf entry for host"，那就去编辑pg_hba.conf，加一行：

host all all 0.0.0.0/0 scram-sha-256

这里我的建议是：如果是本地开发，bind-address保持默认就好，没必要改成0.0.0.0，减少被局域网内其他设备扫描到的风险。

4.2 Docker容器里的数据库：请先搞明白端口映射

Docker现在几乎成了本地开发的标准装备，很多人会用Docker跑MySQL或PostgreSQL。这时"Connection refused"的原因又多了一个维度：容器内部的端口映射。

看下面这个命令：

docker run --name mysql-demo -e MYSQL_ROOT_PASSWORD=123456 -p 3306:3306 -d mysql:8.0

-p 3306:3306的意思是：把容器内的3306端口映射到宿主机的3306端口。这样你在DataGrip里连接127.0.0.1:3306，流量会被转发到容器内的3306端口。

但如果写的是：

docker run --name mysql-demo -e MYSQL_ROOT_PASSWORD=123456 -p 3307:3306 -d mysql:8.0

那宿主机上的3307端口对应容器内的3306端口。你在DataGrip里就应该填127.0.0.1:3307，填3306反而连不上。

还有一种更隐蔽的情况：Docker容器内部配置了bind-address = 127.0.0.1，但由于容器网络隔离的特性，这也可能影响宿主机的访问。不过MySQL官方镜像默认的bind-address是*，一般不会遇到这个问题，但如果你用的是自己构建的镜像或自定义配置文件，就要留意。

排查Docker场景的时候，我会先执行：

docker ps

看容器状态是否Up，再看端口映射：

docker port mysql-demo

输出类似3306/tcp -> 0.0.0.0:3306，对比一下映射是否正确，一分钟就能定位问题。

4.3 WSL2环境：IP地址跟你以为的不一样

如果你在Windows上通过WSL2跑数据库，然后拿Windows侧的DataGrip去连，可能会遇到一个WSL2特有的坑：WSL2的Linux子系统运行在虚拟机里，它的127.0.0.1和Windows的127.0.0.1不是同一个。

早期WSL2版本里，Linux子系统和Windows各自有独立的网络栈，你在WSL2里启动数据库，Windows侧通过127.0.0.1是连不过去的，要填WSL2的IP（用ip addr查看，通常是172.x.x.x）。这极其反直觉，很多人在这里卡了很久。

好消息是较新版本的Windows和WSL2已经改进了，默认开启了"镜像网络"或类似功能，使得Windows侧可以直接通过127.0.0.1访问WSL2里监听的端口。但如果你用的还是老版本，或者自定义了.wslconfig，那就可能遇到上述问题。

遇到这种情况，我的建议是：

先看WSL2的内网IP：在WSL2里执行hostname -I。
用那个IP在DataGrip里当作Host试试。
如果连不上，再看WSL2里的数据库监听地址是否包含0.0.0.0。
最后检查Windows防火墙对WSL2流量的拦截。

4.4 远程数据库：网络路径上的每一个节点都要查

远程连接数据库时，"Connection refused"的原因就更多了。从你的电脑到目标数据库之间，可能经过企业内网防火墙、云安全组、服务器自身防火墙，任何一环断了都会报类似的网络错误。

排查这类问题时，我通常会按这个顺序来：

先测网络通不通：用ping测目标主机是否可达，用telnet或nc测目标端口是否开放。
确认监听地址：远程数据库的bind-address必须是0.0.0.0或目标网卡IP，不能只监听127.0.0.1。
检查云安全组：登录云控制台，确认入站规则放行了目标端口。
检查服务器防火墙：firewalld或ufw或iptables是否放行了端口。
最后才看数据库本身的认证：这里有一个常见误区，很多人报错Connection refused就以为是网络问题，结果最后发现是数据库用户权限没配好。注意区分：网络不通是Operation timed out或Connection refused，而认证失败通常是Access denied for user或password authentication failed。

我见过有人把Access denied当成Connection refused去查防火墙，折腾了一晚上。正确姿势是，看到错误信息先分分类，别眉毛胡子一把抓。

5. 一次典型的排错现场：从报错到解决全程记录

5.1 问题现象

之前我在某个模拟项目X里，需要用DataGrip连接本机Docker里跑的PostgreSQL。启动完容器后，高高兴兴打开DataGrip新建连接，填了：

Host:127.0.0.1
Port:5432
Database:postgres
User:postgres
Password:postgres123

点Test Connection，一秒后弹窗：Connection refused to host: 127.0.0.1。

一开始我也没多想，先怀疑PostgreSQL没启动。于是执行：

docker ps

结果容器状态是Up，没毛病。第二个念头就是端口映射，于是执行：

docker port demo-pg

输出：

5432/tcp -> 0.0.0.0:5432

映射也没问题。这下就有点奇怪了，理论上应该能连上啊。

5.2 一步步深入

我在宿主机上直接测试端口：

nc -vz 127.0.0.1 5432

结果居然显示连接失败。这就说明问题不在DataGrip，而是宿主机层面根本连不进去。

不死心，我进到容器内部看：

docker exec -it demo-pg bash

然后在容器里面Localhost连接：

psql -U postgres -h localhost

能连通。这说明PostgreSQL进程没问题，监听也没问题，但宿主机连不进去，那答案只剩两个：要么端口映射没生效，要么防火墙拦截。

我用netstat -tlnp看了一眼监听地址：

tcp 0 0 0.0.0.0:5432 0.0.0.0:* LISTEN

还是没问题。最后发现问题出在Windows的Hyper-V防火墙规则上。Hyper-V的网络虚拟化组件有时候会在宿主机和WSL2/Docker之间加一层隐形的网络隔离，表现为端口映射正常、监听正常，但外部（包括宿主机自己）就是连不进去。

解决方法是给Docker Desktop的专用网络加一条放行规则，或者执行：

netsh advfirewall firewall add rule name="Allow PostgreSQL" dir=in action=allow protocol=TCP localport=5432

执行之后再试DataGrip连接，一次通过。

5.3 这次排错留给我的经验

排完这个故障，我有几个很深的感触：

不要跳过任何一层排查。我一开始看到容器Up，就觉得服务没问题；看到端口映射正确，就觉得网络没问题。但问题恰恰出在我没想到的Hyper-V防火墙层。
命令行永远是调试的第一选择。用DataGrip报错只能得到一行字，但用nc、telnet、docker port、netstat这些工具，每一步都能看到独立的证据，哪里断了哪里没断一目了然。
报错信息要看完整。连接报错时DataGrip下方还有一段完整的错误堆栈，里面包含了驱动版本、服务器版本等额外信息。有一次我就靠这个堆栈发现服务端和客户端的TLS版本不兼容，修正后问题解决。

6. 常见问题速查：照着这张表自查

场景	典型现象	排查方向	参考解法
本机服务未启动	命令行连接也失败，服务管理器中状态为已停止	服务是否运行	启动对应数据库服务
端口填写错误	服务正常，但DataGrip连不上	服务实际监听端口与配置端口对比	用`netstat`查看端口，修正DataGrip配置
监听地址限制	远程连不上，本机能连上	`bind-address`是否允许外部访问	改为`0.0.0.0`并重启服务
防火墙拦截	端口测试超时或拒连	系统防火墙入站规则、云安全组	放行对应端口或IP
容器端口映射错误	Docker容器在跑，但端口无法访问	`docker port`查看映射关系	修正`-p`参数或用正确端口连接
WSL2网络隔离	WSL2里服务正常，Windows侧连不上	WSL2 IP与Windows IP不同	使用WSL2分配的IP，或升级WSL版本
JDBC驱动版本过旧	能连但报认证错误	驱动版本与数据库版本兼容性	更新DataGrip内置驱动或手动添加最新驱动
数据库用户权限不足	报认证失败而非Connection refused	用户是否能从当前Host登录	修改用户Host为`%`或指定网段

这张表没法覆盖所有情况，但涵盖了九成以上的Connection refused场景。如果你是照着这篇文章一点点排查的，大概率在途中就已经找到答案了。

7. 聊几个操作细节，少走弯路

7.1 善用DataGrip的SSH隧道选项

如果你的数据库跑在远程服务器上，而服务器只对内网开放端口，我建议直接在DataGrip里用SSH隧道连接，而不是把远程数据库端口暴露到公网。配置方式也很简单：在连接配置的"SSH/SSL"选项卡里，勾选"Use SSH tunnel"，填上跳板机的地址、用户名和认证方式，DataGrip会先建立SSH连接，再通过这个隧道转发数据库流量。

这样做的好处是，你完全不需要修改数据库的bind-address，也无需在防火墙里放行数据库端口，只需要服务器开放22端口。从安全角度讲，少暴露一个数据库端口就少一分风险。我自己的开发服务器上，数据库永远是监听在127.0.0.1上的，外面的DataGrip全靠SSH隧道连进来，用了好多年没出过事。

7.2 把Datagrip驱动升级当作常规操作

DataGrip内置的JDBC驱动更新通常滞后于数据库官方发布的版本。当你遇到一些莫名其妙的连接报错时，不妨先试试更新驱动。路径是：连接配置界面下方有个"Download"或者驱动下拉列表里选择新版本。更新后重启测试，一种情况是问题消失（说明驱动旧了），另一种是报错变成更具体的信息（比如认证方式不支持）。

MySQL 8.0刚普及那阵子，很多人用DataGrip连不上，就是因为内置驱动不支持caching_sha2_password。更新驱动之后，问题立刻消失。这种案例不胜枚举，所以这不是一个可有可无的细节，而是连接类问题的标准处理动作之一。

7.3 把常用连接参数保存成模板

DataGrip允许你把连接配置保存为模板，也可以直接在连接配置的"General"选项卡里把连接参数项填完整后，用左上角的硬盘图标保存。这样下次新建连接时可以直接基于模板修改，省掉每次重新填写Host、Port这些基础信息的时间。

另外，DataGrip的"Database"面板里可以同时配置多个数据源，并且每个数据源都可以独立设置颜色标签、版本管理策略、SQL方言级别。建议你把线上环境和本地环境的连接分开命名，比如"local-mysql"和"prod-mysql"，再加上明确的主人字段避免误操作，能有效防止在本地调试时不小心连到生产库。

7.4 善用日志，别只盯着弹窗那一行

DataGrip的报错弹窗只显示精简信息，完整的错误堆栈在Help -> Show Log in Explorer（Windows）或Show Log in Finder（macOS）里。如果你遇到的是一个只在特殊场景下出现的连接问题，比如偶尔失败、时好时坏，建议开启DataGrip的日志，复现一遍操作，然后翻日志。日志里会有JDBC驱动级别的详细输出，包括连接URL、握手步骤、失败原因。

这个方法对排查名古屋那种"玄学"问题尤其管用。之前有人的DataGrip经常连不上，但过几分钟又能连上，纯粹看弹窗完全无法定位。翻日志后发现是数据库连接池的最大连接数耗尽，新的连接请求排队超时，跟网络本身没半毛钱关系。这个信息量，弹窗给不了你。

8. 我个人的体会

跟Connection refused搏斗了这么多次，我最大的体会是：这个报错是一个分水岭。没搞懂它之前，你会觉得它是玄学，动不动就想重装软件、重启电脑；搞懂它之后，你会发现它就是一面镜子，清清楚楚地反映出你那个数据库环境的配置状态。它不骗你，它只是没有直接用你能听懂的话告诉你到底哪里断了。

所以每当我看到有人在社区里发帖问这个报错，我通常不会直接给答案，而是先问一句：你命令行能连上吗？你查了端口监听吗？你填的端口对得上吗？这三个问题问完，多半他自己就解决了。这篇文章把这三个基础问题扩展成了完整的四条排查线，用过一次之后，你大概率再也不会被这条报错卡住了。

如果你现在正好被Connection refused to host: 127.0.0.1困扰着，先别急着卸载DataGrip。按上面第二部分的四条排查线走一遍——服务在跑吗？端口在听吗？配置对吗？防火墙放行了吗？——我敢打赌，你的问题就藏在这四个环节的某一个里面。找到它，解决它，然后你会发现DataGrip弹窗里的那行红色文字，其实也没那么吓人。