本文基于生产环境真实踩坑经验，深入分析ONLYOFFICE Document Server与PostgreSQL搭配时的稳定性问题，并提供经过验证的参数优化方案，助你解决90%的部署故障。

---

1. 背景说明

在企业私有化部署场景中，ONLYOFFICE Document Server（由 ONLYOFFICE 提供）常与 PostgreSQL 搭配使用。在实际生产环境中，经常会出现以下现象：

• 长时间编辑后偶发保存失败

• 高并发协作时文档异常

• 转换任务间歇性失败

• 数据库日志出现 connection reset

• 报错 too many clients already

很多团队第一反应是：数据库性能不够？

事实上，在 80% 的案例中，问题并非数据库性能瓶颈，而是默认参数未适配长连接型应用。本文将系统分析 ONLYOFFICE + PostgreSQL 的运行特性，并给出生产级稳定性优化方案。

---

2. 理解 ONLYOFFICE 与 PostgreSQL 的真实关系

2.1 常见误区

误区： 用户长时间编辑 = 数据库长时间持有事务

真实情况： ONLYOFFICE 的架构分层如下：

功能	组件
实时协作数据	内存
状态缓存	Redis
文件存储	本地 / 对象存储
元数据与任务状态	PostgreSQL

PostgreSQL 不在实时编辑数据主路径上。 它承担的是：

• 文档元信息

• 转换任务状态

• 回调记录

• 控制层数据持久化

这意味着：PostgreSQL 是“控制平面数据库”，而不是“数据平面数据库”。因此其稳定性关键在于：

• 连接可靠性

• 资源可用性

• 网络持久性

而非单纯 SQL 性能。

---

3. 生产环境最常见的 4 类问题

以下按照实际发生概率排序。

3.1 TCP Idle 断连（最高频）

典型现象

• 编辑 30~120 分钟后保存失败

• 数据库日志显示：

connection reset by peer
server closed the connection unexpectedly

根因分析

默认 PostgreSQL 配置：

tcp_keepalives_idle = 0

系统默认值通常为 7200 秒（2 小时）。如果环境中存在：

• 防火墙 idle 超时 30 分钟

• NAT 设备 1 小时回收连接

• 云负载均衡 3500 秒断开

则网络设备会先关闭连接，下一次数据库访问时，连接已失效。

推荐配置

tcp_keepalives_idle = 60
tcp_keepalives_interval = 10
tcp_keepalives_count = 5

效果：

• 60 秒无数据即发送探测

• 约 120 秒内确认连接状态

• 防止网络设备回收连接

这是生产环境最关键的一项配置！

3.2 max_connections 不足

默认值：

max_connections = 100

在以下场景极易触顶：

• 30+ 并发编辑

• 多 worker 模式

• 转换任务并发

• 多租户部署

报错表现：

FATAL: too many clients already

推荐建议

并发编辑用户	推荐连接数
≤ 20	150
20–50	300
50–100	500
> 100	建议 PgBouncer

建议预留 2 倍安全冗余。

3.3 容器资源限制 / OOM

在 Docker 环境中：

• shared_buffers 太小

• 容器 memory limit 太低

• 未关闭 swap

可能导致：

• PostgreSQL 被 OOM Kill

• 全部文档瞬间断开

建议：

• 生产环境内存 ≥ 4GB

• 中型部署 ≥ 8GB

• 禁用 swap

• 容器 memory limit ≥ 实际使用内存 + 30%

3.4 WAL 与 Checkpoint 抖动

ONLYOFFICE 特点：

• 高频小事务

• 自动保存

• 转换写入频繁

若默认 shared_buffers = 128MB，容易导致：

• Checkpoint 频繁

• WAL 刷盘抖动

• 响应时间波动

---

4. 生产级 PostgreSQL 推荐参数模板

假设环境：

• 16GB 内存

• SSD

• 50 并发编辑

建议配置如下：

max_connections = 300

shared_buffers = 4GB
effective_cache_size = 12GB
work_mem = 16MB
maintenance_work_mem = 512MB

wal_buffers = 16MB
checkpoint_completion_target = 0.9

tcp_keepalives_idle = 60
tcp_keepalives_interval = 10
tcp_keepalives_count = 5

statement_timeout = 30000
lock_timeout = 5000
idle_in_transaction_session_timeout = 600000
idle_session_timeout = 1800000

核心原则：

• 内存利用最大化

• 连接可持续

• 防止僵尸事务

• 控制锁等待

---

5. 容量估算方法

经验公式：

数据库连接数 ≈ (编辑用户数 × 1.5) + (转换并发 × 3) + worker 冗余

示例：

• 40 编辑

• 5 转换

(40 × 1.5) + (5 × 3) = 75

建议配置：

max_connections ≥ 200

---

6. 高可用建议

企业级推荐：

• 主从复制

• WAL 归档

• 定期 pg_basebackup

监控指标：

• 当前连接数

• 活跃事务

• Checkpoint 频率

• WAL 生成速率

• IO wait

可选组件：

• PgBouncer（连接池）

• Patroni（自动故障转移）

---

7. 关键结论

ONLYOFFICE + PostgreSQL 不稳定的根本原因通常不是：

• SQL 性能不足

• 查询过慢

• 数据量过大

而是：

• TCP Keepalive 未配置

• max_connections 不足

• 容器资源受限

• 默认参数未适配长连接应用

只要做好三件事，就能解决 90% 的问题：

1. tcp_keepalives_idle = 60

2. max_connections ≥ 200

3. shared_buffers ≥ 内存 25%

---

8. 总结

ONLYOFFICE 是典型的 长连接 + 间歇访问数据库 架构。它对数据库的要求不是“极高性能”，而是：

• 连接稳定

• 资源充足

• 参数合理

在生产环境中，只需针对 PostgreSQL 做针对性调优，即可获得极高稳定性。

相关资源

---

OnlyOffice最新版本镜像：

https://moqisoft.github.io/docs/install/docker

中国版介绍：

https://moqisoft.github.io/docs/product/summary

中国版技术交流：183026419（https://qm.qq.com/q/uMwFyL5Wn0 ）