在 N8N大学 的自动化实战中，MariaDB 是最常用的数据库之一。但新手在配置 n8n 的 MariaDB 节点时，经常会遇到各种报错，导致数据流直接中断。
作为你的引路人，笔者必须告诉你：90% 的连接问题，其实都出在配置细节上。别急着怀疑人生，也别急着重装数据库。今天这篇硬核指南，我们就来拆解导致连接失败的 3 个核心配置项。
问题复现：你遇到的报错长什么样？
在 n8n 中配置 MariaDB 节点时，最典型的报错通常出现在点击 "Test Credentials" 或运行工作流时：
Connection refused
Error: getaddrinfo ENOTFOUND
Access denied for user 'root'@'172.17.0.1'
Unknown database 'your_db_name'这些报错虽然看起来吓人，但其实都在指向同一个本质：配置信息不匹配。无论是 Docker 部署的 n8n，还是本地安装，只要检查好下面这 3 个配置项，问题基本能解决。
解决方案一：主机地址 (Host) 的“内外之别”
这是新手最容易踩的第一个坑。如果你的 MariaDB 和 n8n 不在同一台机器上，或者都在 Docker 容器里，Host 的写法至关重要。
1. Docker 环境下的特殊处理
如果你的 n8n 和 MariaDB 都跑在 Docker 里，且使用的是 Docker Compose，那么 Host 不能写 `localhost` 或 `127.0.0.1`。因为在容器内部，`localhost` 指向的是当前容器本身，而不是宿主机或其他容器。
你应该使用 Docker Compose 中定义的 服务名称（Service Name）。例如，如果你的 docker-compose.yml 中定义了服务名 `db`，那么在 n8n 的 MariaDB 节点配置中，Host 必须填写 db。
2. 物理机/云服务器环境
如果是本地连接，直接填写 127.0.0.1 或 localhost 即可。如果是远程连接，请确保你填写的是服务器的公网 IP 或内网 IP，并且该 IP 是可被 n8n 访问到的。
解决方案二：端口号 (Port) 的“默认陷阱”
MariaDB 的默认端口是 3306。但在 n8n 的 MariaDB 节点配置中，端口字段默认是空的，还是预填了 3306？这取决于你使用的 n8n 版本。
如果你的 MariaDB 修改了默认端口，或者在 Docker 中映射了不同的宿主机端口（例如映射为 3307），你必须在 n8n 节点中显式填写正确的端口。
笔者经验： 很多时候连接报错
Connection refused，仅仅是因为你忘记填写端口，或者填写了错误的端口。请务必登录数据库服务器，执行SHOW GLOBAL VARIABLES LIKE 'port';确认实际端口。
此外，如果 MariaDB 运行在宿主机，而 n8n 运行在 Docker 容器内，你需要确保 Docker 容器映射了正确的端口，并且防火墙（如 ufw 或 iptables）放行了该端口。
解决方案三：用户权限与认证插件 (User & Auth)
这是最隐蔽但也最致命的配置项。MariaDB 的用户认证机制在不同版本间有差异，这直接导致了 n8n 连接失败。
1. 用户名与密码的准确性
这听起来像废话，但请再检查一遍。特别是密码中的特殊字符，如果你没有使用 n8n 的凭证管理（Credentials），而是手动输入，容易出现格式错误。建议使用 n8n 的 Database -> MariaDB 凭证功能，它能更好地处理密码转义。
2. 认证插件不兼容 (Caching_sha2_password)
如果你使用的是 MySQL 8.0 或较新版本的 MariaDB，默认的认证插件可能是 caching_sha2_password。虽然 n8n 支持它，但在某些特定的网络环境或旧版驱动下，可能会出现握手失败。
解决方案： 登录数据库，为你的用户指定一个更兼容的认证方式：
ALTER USER 'your_user'@'%' IDENTIFIED WITH mysql_native_password BY 'your_password';
FLUSH PRIVILEGES;3. 远程访问权限
默认情况下，MariaDB 只允许本地连接。如果你的 n8n 和数据库不在同一台服务器，你需要授权 n8n 的 IP 访问。
GRANT ALL PRIVILEGES ON your_db_name.* TO 'your_user'@'n8n_server_ip' IDENTIFIED BY 'your_password';
FLUSH PRIVILEGES;如果你不确定 IP，或者在动态网络中，可以使用通配符 '%'（允许任意 IP 连接），但生产环境请谨慎使用。
FAQ：你可能还想问
Q1: 为什么 n8n 连接 MariaDB 时显示 "SSL Connection Error"？
A: 默认配置下，n8n 的 MariaDB 节点可能尝试使用 SSL 连接，而你的数据库并未配置 SSL 证书。在 n8n 的凭证配置中，找到 SSL Options，尝试选择 False 或 Allow 来禁用强制 SSL。
Q2: 连接成功但读取不到数据，是字符集问题吗？
A: 很有可能。如果数据库是 UTF-8，而 n8n 连接时未指定，可能会导致乱码或查询失败。在 n8n 的 MariaDB 节点配置的 Options 选项卡中，可以添加参数：charset: utf8mb4。
Q3: 我的 MariaDB 在云服务器上，n8n 在本地，连不上怎么办？
A: 检查云服务器的安全组规则，确保入站规则允许 n8n 所在公网 IP 访问 3306 端口。同时检查数据库的 bind-address 配置（通常在 /etc/mysql/my.cnf），确保它没有绑定在 127.0.0.1 上，而是绑定在 0.0.0.0 或公网 IP 上。
总结与资源
MariaDB 连接报错，本质上是 Host、Port、User/Privilege 这三要素的匹配问题。按照 N8N大学 给出的步骤，先确认网络可达性，再核对端口，最后检查用户权限，通常都能迎刃而解。
推荐资源：
- N8N大学官网：更多 n8n 节点实战教程。
- n8n 官方数据库凭证文档：深入了解凭证配置。
配置好数据库连接，你的自动化工作流才能真正跑起来。如果还有问题，欢迎在 N8N大学 社区留言，学长帮你排忧解难。
