CodeIgniter对接Oracle偶发连接失败，重试即可成功求助

架构老林

2026-8-22

偶发CodeIgniter OCI8 Oracle连接超时失败（重试即成功）的排查与解决思路

问题背景

团队维护的CodeIgniter PHP项目已稳定运行3年，通过oci8驱动连接Oracle数据库，近期远程API调用偶发出现Unable to connect to your database server using the provided settings错误（报错定位在Loader.php 338、346行），故障特征：

首次调用会触发整整1分钟超时后失败，立即重试相同参数请求则成功
每小时约出现50次，服务器CPU、RAM资源利用率无异常

排查与解决方向

1. 配置OCI8连接超时参数

CodeIgniter默认未显式设置OCI8连接超时，依赖系统默认值可能导致长时间等待，可在database.php中添加专属超时配置：

$db['default']['connect_timeout'] = 10; // 单位：秒，缩短连接超时时间
$db['default']['timeout'] = 10; // 部分OCI8版本支持此参数

同时检查PHP配置文件中的oci8.privileged_connect等参数，确保无特殊连接限制。

2. 检查Oracle端连接资源限制

Oracle的processes、sessions参数接近上限时，新连接会被排队直至超时，可执行以下SQL查询确认：

-- 查看当前会话数
SELECT COUNT(*) FROM v$session;
-- 查看进程数上限
SELECT value FROM v$parameter WHERE name = 'processes';
-- 查看会话数上限
SELECT value FROM v$parameter WHERE name = 'sessions';

若当前会话数接近上限，联系DBA调整参数，同时排查是否存在未释放的死连接。

3. 调整CodeIgniter连接复用策略

尝试开启持久化连接，减少频繁创建新连接的压力（注意持久化连接的会话状态残留问题）：

$db['default']['pconnect'] = TRUE; // 开启持久化连接

同时确保PHP配置中oci8.max_persistent、oci8.persistent_timeout参数设置合理，避免持久连接耗尽；若项目有会话级配置（如NLS参数），需在每次请求开始时重置会话状态。

4. 排查网络层面隐性超时

应用服务器与Oracle服务器之间的防火墙、负载均衡可能存在空闲连接超时规则，导致旧连接被断开后复用失败：

在Oracle服务器的sqlnet.ora中设置SQLNET.EXPIRE_TIME，定期检测空闲连接避免被防火墙断开：
```
SQLNET.EXPIRE_TIME = 10
```
检查防火墙是否有连接空闲超时设置，必要时调整超时时间。

5. 捕获OCI8底层错误日志

CodeIgniter的错误提示较笼统，需获取OCI8原始错误信息定位问题：

测试环境可开启数据库调试模式：
```
$db['default']['db_debug'] = TRUE;
```

在Loader.php报错位置附近添加代码捕获底层错误：

// 在Loader.php 338行连接失败逻辑后添加
if (!isset($this->db->conn_id)) {
    $oci_error = oci_error();
    error_log('OCI8 Connection Error Details: ' . print_r($oci_error, TRUE));
}

查看PHP错误日志获取具体错误码（如ORA-12170: TNS:Connect timeout occurred），精准定位问题。

6. 实现连接自动重试逻辑

利用重试即可成功的特性，在CodeIgniter数据库连接逻辑中添加自动重试：

扩展OCI8驱动类，在db_connect方法中添加重试逻辑（建议备份系统文件后修改，或创建自定义驱动继承oci8_driver）：

function db_connect($persistent = FALSE)
{
    $retry_times = 2;
    for ($i = 0; $i < $retry_times; $i++) {
        $conn = parent::db_connect($persistent);
        if ($conn) {
            return $conn;
        }
        usleep(100000); // 等待100毫秒后重试
    }
    return FALSE;
}

内容的提问来源于stack exchange，提问作者Zar Tel