1. 生产环境部署Onlyoffice Documentserver的核心诉求部署一套企业级的Onlyoffice Documentserver需要考虑的核心诉求可以归纳为四个关键点稳定性、安全性、性能和可扩展性。这四点直接决定了在线文档协作平台能否在实际业务场景中可靠运行。先说稳定性问题。在实际项目中我遇到过不少因为容器配置不当导致的随机崩溃。比如有一次客户反馈文档服务每隔几天就会自动重启排查后发现是容器内存限制设置过低当多个用户同时编辑大文档时OOM Killer就会终止进程。后来我们调整为8GB内存限制并启用了自动重启策略--restartalways问题才彻底解决。安全性方面最容易被忽视的是证书管理和网络隔离。有次安全扫描发现我们的测试环境竟然用着自签名证书跑了半年被客户安全团队发了整改通知。现在我会在Docker Compose里直接集成Lets Encrypt自动续期后面会具体演示配置方法。性能优化是个持续过程。曾经有个200人团队抱怨打开Excel特别慢后来我们通过Nginx调优和增加文档缓存层将响应时间从3秒降到了800毫秒左右。关键是要给容器分配足够的CPU资源建议至少4核并且要单独挂载tmpfs来处理临时文件。可扩展性主要体现在架构设计上。去年有个项目从初期50人扩展到300人团队我们通过Kubernetes的HPAHorizontal Pod Autoscaler实现了自动扩容平稳度过了业务增长期。下面这张表格对比了不同规模团队的建议配置团队规模容器数量CPU/内存存储类型网络带宽50人单节点4核/8GB本地SSD100Mbps50-200人双节点8核/16GB云盘/分布式500Mbps200人集群16核/32G分布式缓存1Gbps2. Docker Compose编排实战2.1 基础服务编排直接上干货这是我经过多个项目验证的docker-compose.yml模板version: 3.8 services: documentserver: image: onlyoffice/documentserver:7.1.1 container_name: onlyoffice-ds restart: unless-stopped ports: - 443:443 environment: - JWT_ENABLEDtrue - JWT_SECRETyour_strong_password_here volumes: - ds_data:/var/www/onlyoffice/Data - ds_logs:/var/log/onlyoffice - ./certs:/etc/onlyoffice/documentserver/certs networks: - onlyoffice-net deploy: resources: limits: cpus: 4 memory: 8G volumes: ds_data: driver: local driver_opts: o: bind type: none device: /mnt/onlyoffice/data ds_logs: driver: local driver_opts: o: bind type: none device: /mnt/onlyoffice/logs networks: onlyoffice-net: driver: bridge ipam: config: - subnet: 172.20.0.0/24这个配置有几个关键点值得说明使用了7.1.1这个具体版本号而非latest避免自动升级带来的兼容性问题JWT认证必须开启这是防止未授权访问的第一道防线数据卷采用显式绑定挂载方便后续备份和维护资源限制直接写在compose文件里确保服务不会占用过多主机资源2.2 HTTPS自动化配置生产环境必须上HTTPS我推荐使用Traefik自动管理证书。下面是集成Traefik的增强版配置片段services: traefik: image: traefik:v2.6 command: - --providers.dockertrue - --entrypoints.web.address:80 - --entrypoints.websecure.address:443 - --certificatesresolvers.leresolver.acme.emailadminyourdomain.com - --certificatesresolvers.leresolver.acme.storage/letsencrypt/acme.json - --certificatesresolvers.leresolver.acme.tlschallengetrue ports: - 80:80 - 443:443 volumes: - /var/run/docker.sock:/var/run/docker.sock - ./letsencrypt:/letsencrypt documentserver: labels: - traefik.enabletrue - traefik.http.routers.ds.ruleHost(doc.yourdomain.com) - traefik.http.routers.ds.entrypointswebsecure - traefik.http.routers.ds.tls.certresolverleresolver实测这套配置可以实现自动申请和续期Lets Encrypt证书强制HTTPS跳转基于域名的访问控制证书过期自动更新3. 高可用架构设计3.1 Kubernetes集群部署当团队规模超过200人时单节点部署就会遇到性能瓶颈。这是我们目前在用的Kubernetes部署方案# documentserver-deployment.yaml apiVersion: apps/v1 kind: Deployment metadata: name: onlyoffice-ds spec: replicas: 3 selector: matchLabels: app: onlyoffice-ds strategy: rollingUpdate: maxSurge: 1 maxUnavailable: 0 type: RollingUpdate template: metadata: labels: app: onlyoffice-ds spec: containers: - name: documentserver image: onlyoffice/documentserver:7.1.1 ports: - containerPort: 443 env: - name: JWT_SECRET valueFrom: secretKeyRef: name: onlyoffice-secrets key: jwt-secret resources: limits: cpu: 4 memory: 8Gi requests: cpu: 2 memory: 4Gi volumeMounts: - mountPath: /var/www/onlyoffice/Data name: ds-data subPath: data - mountPath: /var/log/onlyoffice name: ds-logs subPath: logs volumes: - name: ds-data persistentVolumeClaim: claimName: ds-data-pvc - name: ds-logs persistentVolumeClaim: claimName: ds-logs-pvc配套的Service配置apiVersion: v1 kind: Service metadata: name: onlyoffice-service spec: selector: app: onlyoffice-ds ports: - protocol: TCP port: 443 targetPort: 443 type: LoadBalancer这套配置实现了三副本部署单节点故障不影响服务滚动更新策略确保升级不中断业务基于PVC的持久化存储自动负载均衡3.2 数据同步方案高可用架构中最棘手的是文档实时同步问题。我们采用Redis集群PostgreSQL的方案services: redis: image: redis:6.2-alpine deploy: replicas: 3 configs: - source: redis-conf target: /usr/local/etc/redis/redis.conf volumes: - redis-data:/data networks: - onlyoffice-net postgres: image: postgres:13-alpine environment: POSTGRES_PASSWORD_FILE: /run/secrets/db-password volumes: - pg-data:/var/lib/postgresql/data networks: - onlyoffice-net documentserver: environment: - DB_TYPEPOSTGRESQL - DB_HOSTpostgres - DB_PORT5432 - DB_NAMEonlyoffice - DB_USERonlyoffice - REDIS_SERVERredis://redis:6379关键配置说明Redis集群处理实时协作的OP转换PostgreSQL持久化存储文档元数据通过Docker Secret管理数据库密码专用网络隔离提高安全性4. 监控与运维实践4.1 监控方案集成没有监控的生产环境就像盲人摸象。我们使用PrometheusGrafana的方案services: prometheus: image: prom/prometheus volumes: - ./prometheus.yml:/etc/prometheus/prometheus.yml ports: - 9090:9090 grafana: image: grafana/grafana volumes: - grafana-data:/var/lib/grafana ports: - 3000:3000 documentserver: environment: - PROMETHEUS_ENABLEDtrue - PROMETHEUS_PORT9831对应的prometheus.yml配置scrape_configs: - job_name: onlyoffice static_configs: - targets: [documentserver:9831] metrics_path: /metrics这套监控系统可以实时显示文档打开成功率编辑操作延迟并发用户数系统资源使用率协作事件吞吐量4.2 日志收集方案生产环境日志必须集中管理我们采用LokiPromtail方案# 在documentserver容器中添加日志收集器 docker run -d \ --name documentserver \ --log-driverloki \ --log-opt loki-urlhttp://loki:3100/loki/api/v1/push \ --log-opt loki-retries5 \ --log-opt loki-batch-size400 \ onlyoffice/documentserver日志查询示例{container_namedocumentserver} | error | logfmt | duration 2s这个查询可以快速定位所有包含error的日志条目处理时间超过2秒的请求按日志格式自动提取的字段5. 性能调优实战经验5.1 Nginx层优化Onlyoffice底层使用Nginx这几个参数调优后性能提升明显# 在挂载的nginx配置中添加 http { proxy_cache_path /var/cache/nginx levels1:2 keys_zonedoc_cache:10m inactive60m; server { location ~* \.(js|css|png|jpg|jpeg|gif|ico|woff2)$ { expires 365d; add_header Cache-Control public, no-transform; proxy_cache doc_cache; proxy_cache_valid 200 304 12h; proxy_cache_use_stale error timeout updating http_500 http_502 http_503 http_504; } location / { proxy_read_timeout 300; proxy_connect_timeout 300; proxy_send_timeout 300; client_max_body_size 100M; } } }优化效果静态资源缓存命中率提升到92%首屏加载时间减少40%大文件上传超时问题减少80%5.2 内存管理技巧通过调整这些JVM参数解决过内存泄漏问题docker run -d \ --env JAVA_OPTS-Xms4g -Xmx6g -XX:UseG1GC -XX:MaxGCPauseMillis200 \ onlyoffice/documentserver关键参数说明Xms/Xmx 设置堆内存初始和最大值G1垃圾回收器适合大内存场景控制GC停顿时间在200ms内6. 灾备与恢复方案6.1 数据备份策略我们使用这个脚本每天凌晨进行增量备份#!/bin/bash BACKUP_DIR/backup/onlyoffice TIMESTAMP$(date %Y%m%d_%H%M%S) # 备份数据库 docker exec onlyoffice-postgres pg_dump -U onlyoffice $BACKUP_DIR/db_$TIMESTAMP.sql # 备份文档数据 rsync -avz --delete /mnt/onlyoffice/data $BACKUP_DIR/data_$TIMESTAMP # 备份配置 tar -czf $BACKUP_DIR/config_$TIMESTAMP.tar.gz /etc/onlyoffice # 保留最近7天备份 find $BACKUP_DIR -type f -mtime 7 -exec rm {} \;6.2 故障转移演练定期模拟这些故障场景随机kill一个文档服务容器断开网络连接30秒写满磁盘空间模拟CPU 100%负载验证指标服务恢复时间30秒无数据丢失用户会话保持
Onlyoffice Documentserver Docker 生产环境部署与高可用架构实战
发布时间：2026/5/19 9:39:21
1. 生产环境部署Onlyoffice Documentserver的核心诉求部署一套企业级的Onlyoffice Documentserver需要考虑的核心诉求可以归纳为四个关键点稳定性、安全性、性能和可扩展性。这四点直接决定了在线文档协作平台能否在实际业务场景中可靠运行。先说稳定性问题。在实际项目中我遇到过不少因为容器配置不当导致的随机崩溃。比如有一次客户反馈文档服务每隔几天就会自动重启排查后发现是容器内存限制设置过低当多个用户同时编辑大文档时OOM Killer就会终止进程。后来我们调整为8GB内存限制并启用了自动重启策略--restartalways问题才彻底解决。安全性方面最容易被忽视的是证书管理和网络隔离。有次安全扫描发现我们的测试环境竟然用着自签名证书跑了半年被客户安全团队发了整改通知。现在我会在Docker Compose里直接集成Lets Encrypt自动续期后面会具体演示配置方法。性能优化是个持续过程。曾经有个200人团队抱怨打开Excel特别慢后来我们通过Nginx调优和增加文档缓存层将响应时间从3秒降到了800毫秒左右。关键是要给容器分配足够的CPU资源建议至少4核并且要单独挂载tmpfs来处理临时文件。可扩展性主要体现在架构设计上。去年有个项目从初期50人扩展到300人团队我们通过Kubernetes的HPAHorizontal Pod Autoscaler实现了自动扩容平稳度过了业务增长期。下面这张表格对比了不同规模团队的建议配置团队规模容器数量CPU/内存存储类型网络带宽50人单节点4核/8GB本地SSD100Mbps50-200人双节点8核/16GB云盘/分布式500Mbps200人集群16核/32G分布式缓存1Gbps2. Docker Compose编排实战2.1 基础服务编排直接上干货这是我经过多个项目验证的docker-compose.yml模板version: 3.8 services: documentserver: image: onlyoffice/documentserver:7.1.1 container_name: onlyoffice-ds restart: unless-stopped ports: - 443:443 environment: - JWT_ENABLEDtrue - JWT_SECRETyour_strong_password_here volumes: - ds_data:/var/www/onlyoffice/Data - ds_logs:/var/log/onlyoffice - ./certs:/etc/onlyoffice/documentserver/certs networks: - onlyoffice-net deploy: resources: limits: cpus: 4 memory: 8G volumes: ds_data: driver: local driver_opts: o: bind type: none device: /mnt/onlyoffice/data ds_logs: driver: local driver_opts: o: bind type: none device: /mnt/onlyoffice/logs networks: onlyoffice-net: driver: bridge ipam: config: - subnet: 172.20.0.0/24这个配置有几个关键点值得说明使用了7.1.1这个具体版本号而非latest避免自动升级带来的兼容性问题JWT认证必须开启这是防止未授权访问的第一道防线数据卷采用显式绑定挂载方便后续备份和维护资源限制直接写在compose文件里确保服务不会占用过多主机资源2.2 HTTPS自动化配置生产环境必须上HTTPS我推荐使用Traefik自动管理证书。下面是集成Traefik的增强版配置片段services: traefik: image: traefik:v2.6 command: - --providers.dockertrue - --entrypoints.web.address:80 - --entrypoints.websecure.address:443 - --certificatesresolvers.leresolver.acme.emailadminyourdomain.com - --certificatesresolvers.leresolver.acme.storage/letsencrypt/acme.json - --certificatesresolvers.leresolver.acme.tlschallengetrue ports: - 80:80 - 443:443 volumes: - /var/run/docker.sock:/var/run/docker.sock - ./letsencrypt:/letsencrypt documentserver: labels: - traefik.enabletrue - traefik.http.routers.ds.ruleHost(doc.yourdomain.com) - traefik.http.routers.ds.entrypointswebsecure - traefik.http.routers.ds.tls.certresolverleresolver实测这套配置可以实现自动申请和续期Lets Encrypt证书强制HTTPS跳转基于域名的访问控制证书过期自动更新3. 高可用架构设计3.1 Kubernetes集群部署当团队规模超过200人时单节点部署就会遇到性能瓶颈。这是我们目前在用的Kubernetes部署方案# documentserver-deployment.yaml apiVersion: apps/v1 kind: Deployment metadata: name: onlyoffice-ds spec: replicas: 3 selector: matchLabels: app: onlyoffice-ds strategy: rollingUpdate: maxSurge: 1 maxUnavailable: 0 type: RollingUpdate template: metadata: labels: app: onlyoffice-ds spec: containers: - name: documentserver image: onlyoffice/documentserver:7.1.1 ports: - containerPort: 443 env: - name: JWT_SECRET valueFrom: secretKeyRef: name: onlyoffice-secrets key: jwt-secret resources: limits: cpu: 4 memory: 8Gi requests: cpu: 2 memory: 4Gi volumeMounts: - mountPath: /var/www/onlyoffice/Data name: ds-data subPath: data - mountPath: /var/log/onlyoffice name: ds-logs subPath: logs volumes: - name: ds-data persistentVolumeClaim: claimName: ds-data-pvc - name: ds-logs persistentVolumeClaim: claimName: ds-logs-pvc配套的Service配置apiVersion: v1 kind: Service metadata: name: onlyoffice-service spec: selector: app: onlyoffice-ds ports: - protocol: TCP port: 443 targetPort: 443 type: LoadBalancer这套配置实现了三副本部署单节点故障不影响服务滚动更新策略确保升级不中断业务基于PVC的持久化存储自动负载均衡3.2 数据同步方案高可用架构中最棘手的是文档实时同步问题。我们采用Redis集群PostgreSQL的方案services: redis: image: redis:6.2-alpine deploy: replicas: 3 configs: - source: redis-conf target: /usr/local/etc/redis/redis.conf volumes: - redis-data:/data networks: - onlyoffice-net postgres: image: postgres:13-alpine environment: POSTGRES_PASSWORD_FILE: /run/secrets/db-password volumes: - pg-data:/var/lib/postgresql/data networks: - onlyoffice-net documentserver: environment: - DB_TYPEPOSTGRESQL - DB_HOSTpostgres - DB_PORT5432 - DB_NAMEonlyoffice - DB_USERonlyoffice - REDIS_SERVERredis://redis:6379关键配置说明Redis集群处理实时协作的OP转换PostgreSQL持久化存储文档元数据通过Docker Secret管理数据库密码专用网络隔离提高安全性4. 监控与运维实践4.1 监控方案集成没有监控的生产环境就像盲人摸象。我们使用PrometheusGrafana的方案services: prometheus: image: prom/prometheus volumes: - ./prometheus.yml:/etc/prometheus/prometheus.yml ports: - 9090:9090 grafana: image: grafana/grafana volumes: - grafana-data:/var/lib/grafana ports: - 3000:3000 documentserver: environment: - PROMETHEUS_ENABLEDtrue - PROMETHEUS_PORT9831对应的prometheus.yml配置scrape_configs: - job_name: onlyoffice static_configs: - targets: [documentserver:9831] metrics_path: /metrics这套监控系统可以实时显示文档打开成功率编辑操作延迟并发用户数系统资源使用率协作事件吞吐量4.2 日志收集方案生产环境日志必须集中管理我们采用LokiPromtail方案# 在documentserver容器中添加日志收集器 docker run -d \ --name documentserver \ --log-driverloki \ --log-opt loki-urlhttp://loki:3100/loki/api/v1/push \ --log-opt loki-retries5 \ --log-opt loki-batch-size400 \ onlyoffice/documentserver日志查询示例{container_namedocumentserver} | error | logfmt | duration 2s这个查询可以快速定位所有包含error的日志条目处理时间超过2秒的请求按日志格式自动提取的字段5. 性能调优实战经验5.1 Nginx层优化Onlyoffice底层使用Nginx这几个参数调优后性能提升明显# 在挂载的nginx配置中添加 http { proxy_cache_path /var/cache/nginx levels1:2 keys_zonedoc_cache:10m inactive60m; server { location ~* \.(js|css|png|jpg|jpeg|gif|ico|woff2)$ { expires 365d; add_header Cache-Control public, no-transform; proxy_cache doc_cache; proxy_cache_valid 200 304 12h; proxy_cache_use_stale error timeout updating http_500 http_502 http_503 http_504; } location / { proxy_read_timeout 300; proxy_connect_timeout 300; proxy_send_timeout 300; client_max_body_size 100M; } } }优化效果静态资源缓存命中率提升到92%首屏加载时间减少40%大文件上传超时问题减少80%5.2 内存管理技巧通过调整这些JVM参数解决过内存泄漏问题docker run -d \ --env JAVA_OPTS-Xms4g -Xmx6g -XX:UseG1GC -XX:MaxGCPauseMillis200 \ onlyoffice/documentserver关键参数说明Xms/Xmx 设置堆内存初始和最大值G1垃圾回收器适合大内存场景控制GC停顿时间在200ms内6. 灾备与恢复方案6.1 数据备份策略我们使用这个脚本每天凌晨进行增量备份#!/bin/bash BACKUP_DIR/backup/onlyoffice TIMESTAMP$(date %Y%m%d_%H%M%S) # 备份数据库 docker exec onlyoffice-postgres pg_dump -U onlyoffice $BACKUP_DIR/db_$TIMESTAMP.sql # 备份文档数据 rsync -avz --delete /mnt/onlyoffice/data $BACKUP_DIR/data_$TIMESTAMP # 备份配置 tar -czf $BACKUP_DIR/config_$TIMESTAMP.tar.gz /etc/onlyoffice # 保留最近7天备份 find $BACKUP_DIR -type f -mtime 7 -exec rm {} \;6.2 故障转移演练定期模拟这些故障场景随机kill一个文档服务容器断开网络连接30秒写满磁盘空间模拟CPU 100%负载验证指标服务恢复时间30秒无数据丢失用户会话保持
