OnlyOffice配置HTTPS：Nginx反向代理与WebSocket代理实战

最近有同事在生产环境倒腾 OnlyOffice问我最多的一个问题就是明明服务已经跑起来了浏览器地址栏也正常打开为什么集成到系统里一编辑文档就报错、或者保存时提示“无法连接到文档服务器”。排查到最后几乎都是同一个原因——OnlyOffice 还停留在 HTTP 明文访问而业务系统已经是 HTTPS 了。浏览器把“HTTPS 页面里发起 HTTP 请求”的行为直接视为混合内容咔嚓一下给你拦掉。这篇就专门写 OnlyOffice 配置 HTTPS 访问这件事从方案选型到 Nginx 反向代理再到常见坑位的排查一次性说清楚。我自己经历过从裸 IP 访问到正规域名 HTTPS 的整个改造过程也会把踩过的问题一并列出来给正在做同样事情的运维、开发同学当一份参考。这篇文章适合的对象很明确要么你已经部署好了 OnlyOffice Document Server 正在为编辑页打不开发愁要么你准备在自建网盘、OA、项目管理软件里集成 OnlyOffice趁早把 HTTPS 链路设计对省得后面返工。1. 整体设计与方案选型1.1 为什么 HTTPS 会是刚需而不仅仅是“更好”先说一个很多新手容易忽略的点OnlyOffice 本身是一个浏览器端在线编辑套件前端通过 JavaScript SDK 加载文档编辑器编辑器内部再去访问文档转换、协同编辑的接口。也就是说页面里会有大量的 XHR 和 WebSocket 请求动态发生。如果你把业务系统跑在 HTTPS 下而文档服务地址还是 http:// 开头现代浏览器会严格拦截这类跨协议请求。常见的表现包括编辑器加载到一半白屏控制台报Mixed Content错误文档能打开但“保存”按钮一直转圈协同编辑时连接状态异常多人同时编辑时看不到对方的光标。解决办法只有一个方向让 OnlyOffice 的访问地址和上层业务系统保持同样的协议也就是说给它也配上 HTTPS。这里要提一个容易被带偏的思路。有人可能在容器层面直接把 OnlyOffice 容器内部 Nginx 改造成监听 443或者把证书挂载进容器。这个方案不能说完全不行但维护成本高升级镜像后配置容易丢而且 TLS 证书续期、多站点扩展都麻烦。我更推荐在宿主机上用一个独立的 Nginx 做反向代理统一终结 TLS再把请求转给 OnlyOffice 容器的 80 端口。这样职责清晰证书管理也集中在一个入口。1.2 两种主流架构对比直挂证书 vs 反向代理我自己实际做过两种测试结论非常明确反向代理是更适合绝大部分团队的方案。对比维度容器内直接改 HTTPSNginx 反向代理统一终结 TLS配置复杂度需要改容器内 Nginx 配置且改完要重启容器只需要在宿主机写一份标准 Nginx server 配置证书更新每次续期后都要重新挂载或重启容器在宿主机更新证书reload Nginx 即可多站点扩展一个容器锁死一个证书域名可以按 server_name 路由多个域名升级 OnlyOffice 版本新镜像可能覆盖掉你的自定义配置容器保持默认代理层不受影响问题排查出问题要进容器里查日志链路清晰宿主 Nginx 日志、容器日志分开看所以在下面的实操环节我默认采用“宿主机 Nginx 反向代理 容器保持 80 端口”的架构。这套方案我在 Ubuntu 20.04/22.04 和 CentOS 7 上都搭过配置思路完全一致。1.3 配置 HTTPS 涉及的关键技术点先捋一下整个链路里的核心要素避免后面操作时一头雾水TLS 证书生产环境推荐 Lets Encrypt 免费证书或者云厂商的证书服务内网测试可以用自签名证书Nginx 反向代理监听 443把/和/websocket请求转发到 OnlyOffice 容器WebSocket 代理OnlyOffice 的协同编辑依赖 WebSocket 长连接Nginx 必须正确配置 Upgrade 头X-Forwarded-Proto 请求头让 OnlyOffice 内部知道客户端是通过 HTTPS 访问的保证生成的下载、回调地址正确JWT 密钥OnlyOffice 8.x 以后默认开启 JWT 校验应用服务和文档服务必须保持一致。这几个点里WebSocket 和 X-Forwarded-Proto 是配置完 HTTPS 后最容易出问题的细节。很多同学只代理了常规的/路径结果文档能打开但无法协同编辑还有的改了 HTTPS 后文档地址正常了但 OnlyOffice 生成的回调地址又变回了 HTTP导致保存动作失败问题就在转发头没设置完整。2. 配置前的准备与信息梳理2.1 确认 OnlyOffice 的部署形态动手之前先确认你手里的 OnlyOffice 是什么形态。目前最主流的是 Docker 安装的 Document Server镜像名为onlyoffice/documentserver。也有不少人用 Linux 包直接安装在宿主机上那种情况 Nginx 会直接占用 80 端口你配置 HTTPS 的方式会稍微不同。我用 Docker 部署的场景更多所以下面的步骤以 Docker 部署为准。如果你是通过 RPM/DEB 包直接安装的先把/etc/onlyoffice/documentserver/里的配置路径、Nginx 站点配置路径找到核心思路仍然是再加一层 443 监听或修改默认站点配置。实际操作时我建议先在浏览器里用http://服务器IP访问一次 OnlyOffice 首页确认服务本身是健康的再去搞 HTTPS。否则 HTTPS 配好了发现容器起不来会干扰排查视线。2.2 准备域名和证书HTTPS 证书是绑定域名的。如果还在用裸 IP 访问先决定一件事你是否有域名可以把文档服务单独解析出来。强烈建议给 OnlyOffice 分配一个独立域名比如doc.example.com不要图省事和业务系统共用域名。独立域名在证书管理、故障隔离、跨域配置方面都省心得多。证书获取有两条路如果你有公网域名且服务器有公网 IP用 Lets Encrypt 是最省钱的方案。装好certbot后一条命令就能签发证书还能配置自动续期。如果服务器只在内网使用比如企业内网部署的 OA 系统那可以用自签名证书。浏览器会提示“不安全”但可以通过把证书导入到企业内部 CA 或各终端信任列表来消除告警。我个人在测试阶段也会用自签名证书等正式上线前再换受信任的证书。关于证书文件的路径Nginx 配置时用到的是两个文件证书公钥.crt或.pem和私钥.key。Lets Encrypt 签发的证书一般会存放在/etc/letsencrypt/live/你的域名/目录下文件分别是fullchain.pem和privkey.pem。2.3 梳理访问链路与会话流程在配置前你脑子里要有一条清晰的请求链路否则出了问题很难定位。正常的访问流程是这样的用户打开业务系统页面业务系统通过 HTTPS 加载https://doc.example.com/web-apps/apps/api/documents/api.js浏览器向doc.example.com:443发起请求宿主机 Nginx 接收请求解密 TLS转发到本地容器的127.0.0.1:80OnlyOffice 容器处理请求返回编辑页所需的 JS、CSS、HTML用户编辑文档时OnlyOffice 再去请求编辑器的回调地址、协同服务地址、WebSocket 地址。所以要保证整条链路里所有请求走的都是https://doc.example.com。任何一个环节出现 HTTP 或 IP 直连浏览器就会出现混合内容或跨域问题。这也是为什么我总是强调只有域名 HTTPS 才能做到统一协议。3. 实操Nginx 反向代理与 HTTPS 配置3.1 启动 OnlyOffice 容器的推荐参数如果还没部署 OnlyOffice下面是经过我多次实践后的一个可靠启动命令。注意端口映射我建议映射到回环地址而不是直接-p 80:80这样宿主机上的 Nginx 通过内网访问不会把容器直接暴露到外网安全性更好。docker run -i -t -d \ --name onlyoffice-document-server \ --restartalways \ -e JWT_ENABLEDtrue \ -e JWT_SECRETyour-strong-secret-key \ -v /app/onlyoffice/logs:/var/log/onlyoffice \ -v /app/onlyoffice/data:/var/www/onlyoffice/Data \ -v /app/onlyoffice/lib:/var/lib/onlyoffice \ -v /app/onlyoffice/db:/var/lib/postgresql \ -p 127.0.0.1:80:80 \ onlyoffice/documentserver这里有几个参数值得你注意JWT_SECRET默认也是启用的但如果之前用老版本没配置过集成时尤其容易遇到“文档服务响应无效”之类的提示。务必记下这个密钥后面集成业务系统时需要用到。数据目录挂载Data、lib、db、logs四个目录是官方推荐要挂出来的否则容器重建后证书、数据库、文档数据全部丢失。端口映射我在宿主机 Nginx 配置里会把请求转发到127.0.0.1:80所以这里映射的是回环地址。如果你图省事之前已经用了-p 80:80那宿主机 Nginx 再监听 80 就会冲突。处理办法是调整映射端口或者让 Nginx 直接监听 443 和另一个端口用于跳转具体看你现场情况。容器起来后先用curl http://127.0.0.1测试一下能不能返回 HTML。能返回说明 Each 层是好的。3.2 编写 Nginx 反向代理配置下面是我目前在生产环境使用的一份配置去掉了无关的动静分离等花活只保留核心内容逻辑清晰好排查。# 用于将 HTTP 请求统一跳转到 HTTPS server { listen 80; server_name doc.example.com; # 证书自动续期时会用到 /.well-known 路径要放行 location /.well-known/acme-challenge/ { root /var/www/certbot; } location / { return 301 https://$host$request_uri; } } # HTTPS 正式入口 server { listen 443 ssl; http2 on; server_name doc.example.com; # 证书路径根据实际环境调整 ssl_certificate /etc/letsencrypt/live/doc.example.com/fullchain.pem; ssl_certificate_key /etc/letsencrypt/live/doc.example.com/privkey.pem; ssl_protocols TLSv1.2 TLSv1.3; ssl_ciphers HIGH:!aNULL:!MD5; # 上传文档时文件可能比较大限制设大一些 client_max_body_size 100m; # 超时时间适当放宽文档转换大文件时不容易断 proxy_connect_timeout 600; proxy_read_timeout 600; proxy_send_timeout 600; location / { proxy_pass http://127.0.0.1:80; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; proxy_buffering off; } # OnlyOffice 协同编辑依赖 WebSocket location /websocket { proxy_pass http://127.0.0.1:80/websocket; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection upgrade; proxy_set_header Host $host; proxy_set_header X-Forwarded-Proto $scheme; proxy_read_timeout 3600s; proxy_send_timeout 3600s; } }配置里几个容易被忽略的细节我逐个说明。第一个是proxy_set_header X-Forwarded-Proto $scheme;。OnlyOffice 内部会根据这个头判断当前请求是 http 还是 https继而生成正确的回调地址。我曾经建过没有加这个头的环境结果 HTTPS 访问正常但保存文档时回调地址写成http://前端一直报“文档保存失败”排查了很久才定位到是这个头缺失。第二个是/websocket的代理。OnlyOffice 各版本的协同编辑模块都在这个路径下必须把 WebSocket 升级请求原样转发。这里有两个要点一是proxy_http_version必须设为 1.1二是必须显式设置Upgrade和Connection头。如果你的在线编辑只是单机单用户不用多人同时改一份文档WebSocket 断了可能感知不明显但只要两人同时编辑就会立刻暴露。第三个是proxy_buffering off;。老版本编辑文档时偶尔出现“文件上传失败”和 Nginx 缓冲导致响应体被截断有关关闭缓冲后这个问题就没有再出现过。3.3 证书部署与 Nginx 验证流程证书文件放到服务器后记得先检查权限。Nginx 的 master 进程以 root 启动但 worker 进程通常以 nginx 用户运行证书私钥文件至少要保证能被 nginx 用户读取否则 reload 时会报权限错误。一般做法是sudo chmod 755 /etc/letsencrypt/live/ sudo chmod 644 /etc/letsencrypt/live/doc.example.com/fullchain.pem sudo chmod 644 /etc/letsencrypt/live/doc.example.com/privkey.pem配置写完后先做语法检查nginx -t看到syntax is ok和test is successful后再 reloadsystemctl reload nginx这时从浏览器访问https://doc.example.com正常情况下地址栏出现小锁页面可以正常打开 OnlyOffice 文档编辑器的欢迎页或测试页。3.4 用 curl 验证 HTTPS 链路浏览器能访问只能说明基本通了建议再用 curl 做几个级别的验证可以快速定位问题在人、网络还是配置。# 验证证书链和站点响应 curl -v https://doc.example.com/ # 验证 WebSocket 升级是否正常 curl -v -H Connection: Upgrade -H Upgrade: websocket \ -H Sec-WebSocket-Version: 13 -H Sec-WebSocket-Key: SGVsbG9Xb3JsZGV2LmNvbQ \ https://doc.example.com/websocket第一个命令能看出证书是否被信任、是否完整。第二个命令如果返回 101 Switching Protocols说明 WebSocket 代理是通的。如果返回 200 或 4xx大概率是 Nginx 没有正确识别 WebSocket 升级请求去检查proxy_set_header Upgrade和Connection的配置。4. 应用层联动让在线编辑真正跑在 HTTPS 下4.1 前端初始化时的配置修改OnlyOffice 的编辑器前端初始化代码里有一段类似这样的配置new DocsAPI.DocEditor(placeholder, { document: { fileType: docx, key: unique-key, title: example.docx, url: https://your-app.example.com/files/download }, documentType: word, editorConfig: { callbackUrl: https://your-app.example.com/callback, lang: zh-CN, user: { id: user-001, name: 张三 } }, height: 700px, width: 100% });在 HTTPS 配置完成后你要重点检查这里面的url和callbackUrl是不是以https://开头。很多项目里这个地址是后端动态拼接的如果后端配置的协议还是 HTTP那么即使用户通过 HTTPS 打开了页面文档下载请求还是会发到 HTTP 地址照样被浏览器拦截。这里我建议后端在生成这些地址时不要硬编码协议而是直接读取当前请求的协议头和 Host确保地址始终与页面保持一致。如果你用的是 Spring Boot、Java、.NET 这类框架它们的工具类通常能根据X-Forwarded-Proto自动生成正确地址前提是你已经在 Nginx 里把这个头设置对了。4.2 JWT 校验与跨域配置OnlyOffice 8.x 之后Document Server 默认启用 JWT 鉴权。如果你在容器启动时通过环境变量设置了JWT_SECRET那么在集成配置里也必须设置同样的密钥。有一种很常见的情况你在部署时用了默认随机密钥应用端又没同步结果前端加载完编辑器后任何文档操作都报错。解决方案就是统一密钥。如果你不想用 JWT可以直接在容器环境变量里加JWT_ENABLEDfalse。但我不建议生产环境这么干因为 OnlyOffice 的服务端口通常会在内网暴露没有鉴权的话任何人都可以调用转换接口容易被滥用。跨域的问题在 HTTPS 下反而简单了。因为前端页面和文档服务只要都是相同协议就可以通过设置Access-Control-Allow-Origin来放行。Nginx 里可以加以下配置来解决一些跨域报错add_header Access-Control-Allow-Origin https://your-app.example.com always; add_header Access-Control-Allow-Methods GET, POST, OPTIONS always; add_header Access-Control-Allow-Headers Authorization, Content-Type, X-Requested-With always;不过要小心如果 OnlyOffice 是给多个不同的业务系统共用Access-Control-Allow-Origin写死一个域名会挡住其他来源。更稳妥的做法是只保持默认通过 JWT 和网络策略来控制访问。4.3 私网地址访问限制问题这是一个非常隐蔽的坑只在纯内网部署时会出现。OnlyOffice 出于安全考虑默认不允许文档服务回调私网 IP或保留网段的地址。比如你的业务系统是http://192.168.1.100:8080OnlyOffice 回调这个地址时会被它内部直接拒绝界面上表现就是文档一直打不开或者保存失败。在 OnlyOffice 较新的版本中这个限制可以通过环境变量控制。启动容器时加入-e ALLOW_PRIVATE_IP_ADDRESStrue如果你用的镜像版本没有这个环境变量也可以去容器内修改/etc/onlyoffice/documentserver/local.json把allowPrivateIPAddress改为true然后重启容器或相关服务。但要注意这个开关在生产公网环境下会有一定风险开启前要确保 OnlyOffice 服务不对公网随意开放最好只用防火墙限制来源 IP。4.4 多语言与本地化配置HTTPS 配好后你会顺手遇到另一个高频问题英文界面用着别扭想改成中文。这个和 HTTPS 没有直接关系但在做 OnlyOffice 集成时几乎是必配项。前端初始化时指定语言editorConfig: { lang: zh-CN }服务端配置中可以在容器环境变量里加-e LANGUAGEzh-CN。不过实际我发现大多数项目是在前端配置里控制界面语言服务端环境变量更多影响的是模板文档的语言。两个地方建议都设置成中文避免用户看到的界面和系统语言不一致。5. 常见问题与排查技巧实录5.1 高频错误速查表把我在实际运维中遇到的、以及社区里高频出现的问题整理成下表每一行都对应一个实际症状你可以照着快速定位不用从头到尾扫日志。症状可能原因排查方向页面报 Mixed Content编辑器白屏业务系统是 HTTPS文档服务地址仍是 HTTP检查前端加载的 api.js 地址是否以 https 开头文档能打开但保存转圈回调地址是 HTTP 或不可达检查X-Forwarded-Proto、callbackUrl多人协同编辑不生效WebSocket 代理未配置或配置错误检查 Nginx 的 /websocket location编辑器提示“文档服务响应无效”JWT 密钥前后端不一致统一容器环境变量和应用端配置转换大文件时超时Nginx 代理超时太短调大proxy_read_timeout、proxy_send_timeout证书安装后浏览器提示不安全证书链不完整或自签名证书未信任使用 fullchain 证书或将自签名证书加入系统信任库容器和 Nginx 争抢 80 端口端口映射冲突构建-p 127.0.0.1:80:80的回环映射方式OnlyOffice 无法访问内网系统私网地址限制设置ALLOW_PRIVATE_IP_ADDRESStrue这张表我每次排查 OnlyOffice 问题时都会过一遍大多数问题都能对号入座。5.2 从日志入手的排查方法论界面报错信息往往很模糊真正有信息量的是日志文件。OnlyOffice 容器主要看这几个日志容器访问错误日志docker logs onlyoffice-document-server可以看到请求到达情况OnlyOffice 自身日志挂载目录/app/onlyoffice/logs/下的docservice、converter日志Nginx 宿主机访问日志/var/log/nginx/access.log和error.log。我在排查“保存失败”这类问题时会先同时 tail 三份日志宿主机 Nginx 日志、OnlyOffice 日志、业务系统日志。打开编辑页后做一次保存动作观察请求是从哪一步断的如果宿主机 Nginx 日志里根本没有/callback请求说明前端没有发起回调问题大概率在业务系统的回调地址或 JWT 校验如果 Nginx 有请求但容器日志报 401 或签名错误那就是密钥不一致如果容器有请求但报连接超时可能是文档服务器访问回调地址时网络不通检查私网限制和防火墙。这样一个链路一个环节地排除比盲目改配置有效率得多。5.3 罕见但坑人的几个细节前面提到的都是高频问题下面几个是我实际踩过、但网上很少详细说的细节特别拿出来提醒你。第一个是容器重建后数据丢失。如果你没有挂载数据卷只是用docker run启动容器后面因为升级或改配置重建容器会发现文档数据、用户配置全部丢失小则影响使用大则造成工作成果丢失。我碰到过不止一次。所以部署 OnlyOffice 时一定要把数据和配置目录挂出来这比 HTTPS 配置本身还重要。第二个是证书自动续期后忘记 reload Nginx。Lets Encrypt 证书有效期是 90 天certbot 自动续期成功后只是把新证书写到磁盘Nginx 并不会自动加载新证书。如果续期后不systemctl reload nginx在证书到期后的很长一段时间里客户端访问会出现证书不匹配或直接无法连接。解决方法是配置一条--deploy-hook systemctl reload nginx的续期钩子这个我在自动化脚本里加上后再没出过问题。第三个是 IPv6 的坑。如果你的服务器开启了 IPv6而 DNS 解析返回了 AAAA 记录Nginx 默认只监听 IPv4 的 443 端口时用户访问会长时间无法连接。遇到这种问题检查 Nginx 的 listen 指令是否有[::]:443没有的话加上或者干脆把 DNS 的 AAAA 记录删掉只保留 A 记录。这个坑很隐蔽因为很多问题排查顺序是从证书、代理配置开始很少有人会想到是 IPv6 监听问题。第四个是 OnlyOffice 版本升级带来的配置变化。我在多个项目里从 7.x 升到 8.x 时发现 JWT 默认启用策略有变化原有的环境变量部分失效导致集成方报错。升级前务必先看官方 Release Notes尤其是关于环境变量、JWT、配置文件的变更说明再决定升级步骤。最后一个建议把所有配置尽量都放到容器环境变量和 Nginx 配置里不要靠每次启动后进容器手改配置文件。因为容器是临时的重建后一切手工修改都会丢失。我自己的做法是写一份 docker-compose.yml 托管 OnlyOffice 和环境变量Nginx 配置也放进版本控制这样无论在哪台机器上重新部署只要跑一遍 compose 和 Nginx 配置文件环境就能完整复现。这个习惯帮我省了非常多重复排障的时间。实际生产环境里我还见过有人把 OnlyOffice 放在办公室内网外部访问通过内网穿透到公网域名。这种场景下 HTTPS 配置思路是一样的但要多注意内网穿透工具本身的 TLS 卸载和 Nginx 证书冲突问题。建议只在一层做 TLS 终结不要层层加密、层层解密否则问题会非常难以排查。我个人的体会是OnlyOffice 配置 HTTPS 本身并不复杂真正的复杂度在于你要对整个请求链路的每一跳都有数从 DNS 到 Nginx再到容器内服务哪一层掉了链子都会表现为“文档打不开”。按本文的顺序把证书、代理、WebSocket、转发头都做对再配合日志逐层排查基本就能稳住了。