数据库连接失败时，应依次检查default.yaml配置、连接池参数、启用健康检测、直连测试及驱动版本兼容性。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
如果您尝试启动Hermes Agent，但服务日志中持续出现数据库连接拒绝、超时或认证失败等错误，则很可能是数据库连接配置不正确或连接池状态异常。以下是解决此问题的步骤：
一、检查environments/default.yaml中的基础连接参数
该配置文件定义了Hermes Agent访问数据库所需的全部连接凭证与池化行为，任何拼写错误、端口偏差或权限缺失都会直接导致连接失败。需逐项核对数据库地址、端口、用户名、密码及数据库名称是否与实际部署环境一致。
1、打开文件environments/default.yaml，定位database节点下的host、port、username、password、name字段。
2、确认host值未误填为localhost（当数据库运行在Docker容器或远程服务器时，应使用容器名或IP地址）。
3、验证port是否与数据库监听端口一致，例如PostgreSQL默认为5432，MySQL默认为3306。
4、检查username和password是否具备目标数据库的CONNECT权限及对应schema的USAGE、SELECT、INSERT等必要权限。
二、验证连接池核心参数设置合理性
连接池参数若超出数据库服务端限制或系统资源承载能力，将引发连接被拒绝、空闲连接被强制回收或获取连接无限等待等问题。必须确保max_connections不超过数据库max_connections变量值，且min_connections与idle_timeout协同匹配业务低峰期需求。
1、登录数据库执行SHOW VARIABLES LIKE 'max_connections';（MySQL）或SHOW max_connections;（PostgreSQL），记录返回数值。
2、对比environments/default.yaml中database.connection_pool.max_connections是否小于该值，建议保留至少20%余量。
3、检查idle_timeout是否大于数据库侧wait_timeout（MySQL）或tcp_keepalives_idle（PostgreSQL），避免连接被服务端单方面断开后Agent仍尝试复用。
4、确认min_connections不为0，否则在低负载下连接池可能完全清空，首次请求时因新建连接延迟而触发connection_timeout失败。
三、启用连接健康检测与泄漏诊断
Hermes Agent内置ConnectionPoolMonitor支持运行时连接有效性校验，可主动识别已失效连接并触发自动清理，防止因网络抖动或数据库重启导致的“幽灵连接”堆积。
1、在启动脚本或agent_loop.py中确认已导入ConnectionPoolMonitor类。
2、调用ConnectionPoolMonitor().get_status()方法，检查返回结果中is_valid字段是否全为True，active_count是否持续高于max_connections。
3、若发现leaked_connections数量增长，立即排查未显式关闭session或未正确使用context manager（如with语句）的数据库操作代码段。
4、在配置中添加validate_on_borrow: true（若底层驱动支持），确保每次从池中取出连接前执行SELECT 1类轻量探针。
四、切换连接模式并绕过连接池直连测试
当怀疑连接池逻辑本身存在兼容性缺陷或初始化异常时，可通过临时禁用连接池、改用直连方式验证数据库服务可达性与认证有效性，从而隔离问题域。
1、在environments/default.yaml中注释或删除整个connection_pool块，仅保留host、port、username、password、name等基础连接字段。
2、修改数据库驱动初始化逻辑，将create_engine(..., poolclass=NullPool)显式传入（适用于SQLAlchemy后端）。
3、重启Hermes Agent，观察日志是否仍报连接失败；若直连成功，则问题明确指向连接池配置或池管理器实现。
4、成功后立即恢复connection_pool配置，并基于直连阶段获取的响应时间反推合理的connection_timeout与retry_attempts值。
五、检查Python依赖与驱动版本兼容性
特定版本的数据库驱动（如psycopg2-binary、PyMySQL）与Hermes Agent所用SQLAlchemy或异步引擎（如asyncpg）之间可能存在ABI冲突或API变更，导致连接建立流程中断或认证协议解析失败。
1、执行pip list | grep -E "(sqlalchemy|psycopg|pymysql|asyncpg)"，确认驱动版本符合environments/requirements.txt中声明范围。
2、若使用PostgreSQL，优先选用psycopg2-binary>=2.9.7而非2.8.x系列，后者存在SSL握手兼容性缺陷。
3、若使用MySQL，禁用PyMySQL转而安装mysqlclient，因其C扩展对连接复用与超时控制更稳定。
4、在虚拟环境中执行python -c "import sqlalchemy; print(sqlalchemy.__version__)"，确保为2.0.0+，旧版不支持modern connection pool参数语法。
