Docker中PostgreSQL插入大bytea数据时unexpected EOF问题排查

在Docker部署的PostgreSQL环境中，存在两张表：存储常规数据的data_table、存储bytea类型文件数据的data_files_table。使用Go服务（基于sqlx+pgx v4驱动）在同一事务中向两张表插入数据时，插入大文件（大小超过7MB）到data_files_table时偶尔会触发错误：

unexpected EOF

PostgreSQL日志中对应记录为：

could not receive data from client: Connection reset by peer

该问题仅在开发服务器出现，本地环境无复现，调整应用端连接池参数（空闲连接数、最大打开连接数、连接生命周期等）后未解决。

代码实现 #

func (r *repo) CreateGrantWithDocuments(
    ctx context.Context,
    model models.Grant,
    documents []models.GrantDocument,
) (*pgtype.UUID, error) {
    tx, err := r.db.Beginx() // sqlx with pgx driver
    if err != nil {
        return nil, fmt.Errorf("db.Beginx: %w", err)
    }
    defer helpdb.Rollback(ctx, r.log, tx)

    var grantID pgtype.UUID
    err = tx.GetContext(
        ctx, &grantID, createGrantSQL, args...) // args doesn't matter, it's ok; query returns id
    if err != nil {
        return nil, fmt.Errorf("tx.GetContext: %w", err)
    }

    for _, document := range documents {
        data, err := io.ReadAll(document.File)
        if err != nil {
            return nil, fmt.Errorf("io.ReadAll: %w", err)
        }
        if err = document.File.Close(); err != nil { // file is an io.ReadCloser from multipart/form-data request
            return nil, fmt.Errorf("document.File.Close: %w", err)
        }

        _, err = tx.NamedExec(createGrantDocumentSQL, document) // ERROR: unexpected EOF
        if err != nil {
            return nil, fmt.Errorf("tx.NamedExec: %w", err)
        }
    }

    if err = tx.Commit(); err != nil {
        return nil, fmt.Errorf("tx.Commit: %w", err)
    }

    return &grantID, nil
}

依赖版本 #

go 1.19
github.com/jmoiron/sqlx v1.3.4 // db connects
github.com/jackc/pgx/v4 v4.14.0 // db driver

错误成因分析 #

1. TCP连接中断（核心触发原因） #

开发服务器的网络链路中大概率存在中间代理（如Nginx反向代理、Docker网络的端口映射/防火墙），这些组件对单请求的数据包大小或连接超时有限制。当插入大bytea数据时，数据包体积超过代理的client_max_body_size阈值，或数据传输时间超过代理的超时设置，导致连接被主动重置。PostgreSQL端收到连接断开信号后记录Connection reset by peer，Go客户端则因未收到完整响应返回unexpected EOF。

2. pgx驱动的大数据处理缺陷 #

pgx v4.14.0在处理大bytea数据时，默认会将数据一次性加载到内存后再发送，当数据量超过TCP发送缓冲区或中间网络的MTU限制时，容易引发分片传输异常。这种问题在网络稳定性较差的开发环境中更容易暴露。

3. TOAST机制的间接影响 #

PostgreSQL的TOAST机制是自动处理大字段的存储优化，本身不会直接导致错误，但大bytea数据会触发TOAST的分块存储逻辑，增加了单次传输的数据量，相当于放大了现有网络环境的限制，使得连接中断问题更容易被触发。

修复方案 #

1. 调整网络代理/防火墙配置 #

• Nginx代理调整：如果Go服务通过Nginx反向代理，修改nginx.conf增大请求体限制和超时：

  client_max_body_size 50M;  # 根据实际最大文件大小调整
  proxy_connect_timeout 60s;
  proxy_send_timeout 60s;
  proxy_read_timeout 60s;
  

• Docker网络调整：若使用Docker桥接网络，检查MTU是否与宿主机匹配，必要时创建自定义MTU的网络：

  docker network create --driver bridge --opt com.docker.network.driver.mtu=1400 app-network
  

  然后将PostgreSQL和Go服务容器接入该网络。

2. 优化大文件插入逻辑（流式传输） #

避免一次性将大文件加载到内存，改用pgx的流式插入能力，减少单次传输的数据量：

// 替换原有循环内的io.ReadAll和NamedExec逻辑
for _, document := range documents {
    defer document.File.Close() // 延迟关闭文件句柄

    // 预编译插入语句（复用语句提升性能）
    stmt, err := tx.PrepareContext(ctx, createGrantDocumentSQL)
    if err != nil {
        return nil, fmt.Errorf("tx.PrepareContext: %w", err)
    }
    defer stmt.Close()

    // 将document.File（io.Reader）直接作为参数传入，pgx会流式传输数据
    document.GrantID = grantID // 关联已生成的grantID
    _, err = stmt.ExecContext(ctx, document.GrantID, document.File)
    if err != nil {
        return nil, fmt.Errorf("stmt.ExecContext: %w", err)
    }
}

若坚持使用sqlx的NamedExec，需确保结构体中对应bytea的字段为io.Reader类型，而非预加载的[]byte，让驱动自动处理流式传输。

3. 升级pgx驱动版本 #

pgx v4.14.0存在大数据传输相关的已知bug，升级到v4分支的最新稳定版本（如v4.18.1）或直接升级到pgx v5，可修复部分网络传输异常问题。

4. 调整系统级网络参数 #

针对开发服务器的Linux系统，增大TCP缓冲区大小，提升大文件传输的稳定性：

# 临时生效
sysctl -w net.core.rmem_max=16777216
sysctl -w net.core.wmem_max=16777216
# 永久生效，写入/etc/sysctl.conf
echo "net.core.rmem_max=16777216" >> /etc/sysctl.conf
echo "net.core.wmem_max=16777216" >> /etc/sysctl.conf
sysctl -p

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