# 错误代码排查与解决方法

当草料的数据 API 在连接您的 MySQL 5.7 数据库时，可能会遇到以下错误。请根据报错代码选择对应的排查方式。

## 一、数据库服务器不可用或连接超时

含义：无法连接到 MySQL 服务，服务器无响应或被防火墙阻断。

常见原因（MySQL 5.7）

- MySQL 服务未启动
- 提供的主机地址、端口不正确（默认 3306）
- 服务器防火墙/安全组未开放 3306
- MySQL bind-address 仅允许本地访问
- 网络延迟高或链路阻断

排查步骤

1. 检查 MySQL 服务是否运行

    systemctl status mysqld

2. 确认端口开放

    netstat -tunlp | grep 3306

3. 检查防火墙与安全组（云服务器） 3306 是否对外网开放 草料服务器 IP 是否在白名单内
4. 检查 my.cnf 是否限制访问

    bind-address = 127.0.0.1   # 若存在，需要开放为 0.0.0.0

解决方案

- 启动 MySQL 服务
- 开放对应端口
- 将草料服务器 IP 加入白名单
- 修改 bind-address 并重启 MySQL

## 二、库用户没有足够权限执行操作

含义：数据库用户对目标库或表权限不足。

常见原因

- 用户未被授权访问该库
- 缺少 SELECT, INSERT, UPDATE, DELETE 权限
- 权限只授予本地访问（localhost），未授予远程访问

排查步骤

- 执行下方语句查看用户权限：

    SHOW GRANTS FOR 'user'@'%';

解决方案

- 根据 API 使用场景至少授予以下权限：

    GRANT SELECT, INSERT, UPDATE, DELETE ON db_name.* TO 'user'@'%';
    FLUSH PRIVILEGES;

- 若需要创建表，需增加：

    GRANT CREATE ON db_name.* TO 'user'@'%';

## 三、用户名或密码错误导致连接失败

含义：MySQL 拒绝登录。

常见原因

- 账号密码填写错误
- 用户未授权远程登录
- 密码使用特殊字符未正确转义

排查步骤

- 本地测试：

    mysql -u user -p -h 127.0.0.1

- 检查用户是否允许远程登录：

    SELECT host, user FROM mysql.user WHERE user='user';

解决方案

- 确认密码正确
- 允许远程访问：

    UPDATE mysql.user SET host='%' WHERE user='user';
    FLUSH PRIVILEGES;

- 修改密码时避免使用未转义的特殊字符

## 四、数据唯一键冲突导致插入失败或更新失败

常见原因

- 主键重复
- 唯一索引字段重复

排查步骤

- 找出冲突的唯一键
- 查询重复值

    SELECT * FROM table WHERE unique_col = 'value';

解决方案

- 修改数据，使唯一键不冲突

## 五、尝试访问不存在的表

常见原因

- 表名拼写错误
- 表未创建
- 错误的数据库（use 不正确）

排查方法

SHOW TABLES LIKE 'table_name';

解决方案

- 修复表名
- 创建缺失的表
- 在正确的数据库执行操作：

    USE db_name;

## 六、外键约束条件不满足

含义：插入/更新的记录违反外键规则。

常见原因

- 子表引用的父表记录不存在
- 顺序不正确（需先写父表）

排查方法

- 确认外键约束：

    SHOW CREATE TABLE child_table;

解决方案

- 先插入父表，再插入子表
- 确保外键字段值存在于父表

## 七、将不兼容的数据类型插入字段

含义：插入的值与字段类型不匹配，如：

- 字符串写入 INT
- 非法日期格式写入 DATE
- UTF-8 编码错误字符

排查步骤

- 检查字段类型：

    DESCRIBE table;

解决方案

- 调整字段类型或转换数据类型

## 八、数据库服务器关闭或连接中断

含义：连接断开或服务器关闭。

常见原因

- 超时断开连接
- 服务重启
- 数据包过大（超过 max_allowed_packet）

排查方法

- 查看 MySQL 错误日志

    cat /var/log/mysqld.log

解决方案

- 增大超时时间
- 调整 max_allowed_packet
- 优化网络质量

## 九、连接超时导致操作失败

含义：请求执行中断。

常见原因

- 网络抖动
- 查询超时
- 大查询导致连接断开

解决方案

- 优化 SQL
- 增大 net_read_timeout 与 net_write_timeout

## 十、数据库连接或查询资源不足

MySQL 5.7 常见原因

- 连接数超限：MySQL 默认 max_connections（通常为 151）不够用，高并发下被占满。
- 连接未释放：应用程序没有正确关闭数据库连接，导致大量“Sleep”状态的连接占用名额。
- 慢查询堆积：大量复杂查询卡住，占用了所有可用线程。

解决方法

- 临时增加最大连接数（立即生效，重启失效）
- 永久修改（需修改 my.cnf 并重启）
- 清理僵尸连接： 手动 kill 掉 SHOW FULL PROCESSLIST 中长时间处于 Sleep 状态的 Id，或者优化应用代码确保连接及时关闭。

## 十一、数据-违反了数据库的约束条件，如唯一键/外键约束

解决方法

- 确保主键/唯一键无重复
- 外键值在父表中存在
- 修改业务逻辑或表结构

## 十二、SQL语句有了语法错误或逻辑错误

常见原因

- SQL 拼写错误
- 保留字未加反引号
- 权限不足导致语句无法执行

解决方法

- 使用 MySQL 5.7 文档检查 SQL 语法
- 若字段或表名为保留字，例如：order，需要加：

    `order`

## 十三、各种数据库操作异常情况

包含所有 MySQL 无法归类的异常。

排查方向

- 查看 MySQL 错误日志
- 查看慢查询日志
- 检查网络稳定性与连接池设置

如果无法自行解决，联系草料客服，技术辅助解决