搞在线文档编辑绕不开OnlyOffice这个名字。社区版免费、支持docx/xlsx/pptx在线预览和协同编辑、有现成的Docker镜像说实话在内网或者公网搭一套自用的在线办公环境OnlyOffice是性价比最高的选择之一。但部署本身不复杂复杂的是“怎么让它跑得稳、访问得安全”尤其是HTTPS——我见过太多人在这一步卡住页面能打开但编辑器加载失败、保存时报错、浏览器提示混合内容、回调地址对不上……这篇就专门讲清楚Docker部署OnlyOffice的完整流程以及解决HTTPS访问的几种可行方案。内容会覆盖为什么用Docker部署、部署前的规划和准备、具体命令和参数、Nginx反向代理/官方SSL脚本/Lets Encrypt三种HTTPS方案、常见问题与排障实录。我尽量把每一步为什么这么做讲明白而不是只丢命令让你抄。1. 为什么用Docker部署OnlyOffice1.1 自建在线编辑为什么选OnlyOffice在线文档编辑这个领域可选的开源方案其实不少比如Collabora Online基于LibreOffice、Apache Tika搭配前端预览、或者直接用NextCloud自带的编辑器。但真要说“以Office文档为核心、协同体验接近原生Office”的OnlyOffice几乎是唯一一个把兼容性做到这个程度的开源产品。我实测下来的感受是它对docx、xlsx、pptx的渲染还原度非常高表格里的公式、图表、条件格式基本不丢PPT的动画虽然不能100%还原但日常查看和编辑足够了。而且它支持多人同时编辑同一个文档光标、选区同步都挺流畅这个体验在开源方案里很难得。另一个关键点是集成能力。Spring Boot、Java Web项目、NextCloud、ownCloud、Confluence、Jira都能和它集成集成的核心逻辑其实很简单——你的应用调用OnlyOffice的API把文档路径、编辑权限、回调地址告诉它由OnlyOffice负责渲染和编辑再把结果回调给你。这种松耦合的设计对二次开发非常友好。1.2 Docker部署解决了什么问题如果没有Docker部署OnlyOffice会是一场小灾难。它依赖的组件相当多Node.js运行环境、PostgreSQL数据库、RabbitMQ消息队列、Redis缓存、Nginx、LibreOffice组件、以及一大堆系统库。手动安装的话光是版本兼容问题就能让你折腾一整天。而官方提供的onlyoffice/documentserver镜像把这些依赖全部打包好了。你不需要关心PostgreSQL装在哪个目录、RabbitMQ的默认账号密码是什么、LibreOffice的字体该往哪里放拉镜像、跑容器、映射端口一条命令的事。更重要的是Docker带来的隔离性和可移植性。你的宿主机可能同时跑着别的Java服务、MySQL、Redis如果直接装OnlyOffice它自带的PostgreSQL、RabbitMQ会跟现有环境抢端口、抢依赖、抢内存。容器化之后所有依赖都隔离在容器内部端口通过映射暴露互不干扰。还有一点是升级和维护方便。OnlyOffice新版本发布后拉新镜像、重建容器、迁移数据卷基本就完成了升级。比起在裸机上改配置文件、手动装依赖体验好太多。1.3 镜像选择与部署架构的取舍官方镜像只有两个onlyoffice/documentserver文档服务社区版和onlyoffice/documentserver-ee企业版带更多功能。绝大多数场景用社区版就够了对应Docker Hub上的标签是latest或具体的版本号比如7.5.1。这里有个重要的知识点早期版本的镜像把PostgreSQL、RabbitMQ、Redis都打在了同一个容器里用supervisor统一管理这就是“单容器”架构。到了后续版本官方虽然仍然提供单容器镜像但内部已经变成了一个“容器里有多个服务”的模式。如果你用Docker Compose官方也会推荐拆成多个独立容器来部署。我的建议是如果只是自己用、或者团队内部小规模使用单容器方案完全够省事如果是生产环境、并发较高、需要分别维护数据库和队列那就用Docker Compose拆开部署便于独立扩容和日志排查。后面的实战部分两种方式都会讲。2. 部署前的准备与关键参数规划2.1 Docker环境别让基础问题拖慢进度开始部署前先确认宿主机上有Docker环境。Linux服务器上一般用官方安装脚本curl -fsSL https://get.docker.com | bash systemctl enable docker systemctl start dockerWindows和macOS用户装Docker Desktop注意Windows的话一定要在BIOS里开启CPU虚拟化否则启动时会报“virtualization support wasnt detected”之类的错误。装好之后用docker version命令确认客户端和服务端都在正常运行。OnlyOffice容器本身对配置的要求不算高但也不是随便一个小机器就能带得动的。文档转换、图片预览、协同编辑都需要CPU和内存尤其是多人同时编辑大文档时内存占用会明显上升。我自己的经验是2核4G的机器可以跑但多人协同会有点吃力4核8G比较舒服如果是要频繁做文档格式转换CPU核心数更重要。确认网络环境也能访问Docker Hub或者配置好镜像加速。这一步虽然简单但国内服务器上真没配加速的话拉一个几个GB的镜像能等到怀疑人生。2.2 端口、数据卷与域名规划部署前花几分钟把下面几个问题定下来能省掉后面一大半的麻烦端口规划。OnlyOffice容器默认监听80端口HTTP和443端口HTTPS。宿主机上如果80端口已经被Nginx、Apache或者其他服务占了就要考虑改映射端口或者直接用后面会讲的“复用宿主机Nginx”方案。数据持久化。容器这东西最大的特点就是“随时可以销毁重建”但文档数据、数据库数据、配置文件不能丢。所以部署时必须要做数据卷映射把容器内的关键目录映射到宿主机上。我习惯在宿主机建一个统一目录比如/app/onlyoffice下面再按功能分目录结构清晰也好备份。域名规划。如果只是通过IP访问部署简单很多但如果要上HTTPS尤其要用Lets Encrypt这种免费证书就必须有一个真实域名。没有域名的话就只能用自签名证书浏览器会提示不安全内网用问题不大公网环境强烈不推荐。2.3 HTTPS证书提前弄好别等部署完再想开始部署之前先把证书准备好。证书有几种来源商业证书阿里云、腾讯云、DigiCert这些服务商都有价格从几十到几千不等适合企业用户。Lets Encrypt免费证书90天有效期可以自动化续期个人站长和中小团队用这个最合适。自签名证书openssl命令可以自己签发成本为零但浏览器会提示“不安全”需要手动信任。不管用哪种你最后需要的是两个文件证书文件.crt或.pem和私钥文件.key。这两个文件在后面的HTTPS配置里都要用建议提前整理到一个目录里。3. Docker部署OnlyOffice实战3.1 最简部署一条命令跑通服务先把服务跑起来后面再慢慢加HTTPS。最基础的部署命令如下docker run -i -t -d -p 80:80 \ --restartalways \ --name onlyoffice \ -v /app/onlyoffice/Data:/var/www/onlyoffice/Data \ -v /app/onlyoffice/logs:/var/log/onlyoffice \ -v /app/onlyoffice/lib:/var/lib/onlyoffice \ -v /app/onlyoffice/db:/var/lib/postgresql \ onlyoffice/documentserver:latest逐个解释一下关键参数-p 80:80把容器的80端口映射到宿主机80端口这样访问服务器IP就是访问OnlyOffice。--restartalways容器异常退出后自动重启服务器重启后容器也会自动拉起这个参数在生产环境几乎是必须的。-v数据卷映射。Data目录存文档和缓存logs目录存日志lib目录存配置db目录存PostgreSQL的数据。映射出来之后即使容器被删了数据和配置也还在。镜像比较大首次拉取可能要几分钟。启动后用下面的命令确认状态docker ps docker logs -f onlyoffice启动完成后浏览器访问http://服务器IP如果能看到一个欢迎页面或者Welcome页面说明部署成功了。也可以用接口来验证curl http://localhost/healthcheck返回true的话文档服务已经正常启动。需要注意的是第一次启动时容器内部要做初始化建库、导配置、启动子服务可能一两分钟内healthcheck还不返回true稍微等一下再看。3.2 生产级部署Docker Compose方案单容器适合快速验证但生产环境我更推荐用Docker Compose把文档服务、数据库、缓存、队列拆开管理。创建docker-compose.ymlversion: 3 services: onlyoffice-documentserver: image: onlyoffice/documentserver:latest container_name: onlyoffice-documentserver restart: always ports: - 80:80 - 443:443 environment: - JWT_ENABLEDtrue - JWT_SECRETyour-strong-secret-key - JWT_HEADERAuthorization - JWT_IN_BODYtrue volumes: - /app/onlyoffice/Data:/var/www/onlyoffice/Data - /app/onlyoffice/logs:/var/log/onlyoffice - /app/onlyoffice/lib:/var/lib/onlyoffice - /app/onlyoffice/db:/var/lib/postgresql这是单容器版用Compose管理的写法比直接在命令行传参好维护得多。用docker compose up -d启动用docker compose down停止未来升级镜像也只要改一下版本号再重新构建。如果你想把PostgreSQL、RabbitMQ、Redis也拆出来单独部署网上有不少完整的Compose编排但我个人建议除非有明确需求否则别拆。维护成本会上去而且官方单容器镜像内部已经对这些组件做了性能调优拆开反而不一定更快。3.3 部署后的初始化检查与JWT配置服务跑起来之后有几件事必须做。配置JWT密钥。从7.2版本开始OnlyOffice默认启用了JWTJSON Web Token认证。你的业务系统比如Spring Boot后端调用OnlyOffice API时必须在请求头里带上token而且这个token是用你配置的密钥签名的。如果密钥不匹配编辑器会加载失败或保存报错。上面Compose配置里的JWT_SECRET就是干这个的。你自己业务系统里集成时也要用同一个密钥来生成token。官方建议生产环境一定要改掉默认值这个密钥相当于整个文档服务的“通行证”泄露了别人就可能任意存取文档。检查数据目录权限。如果挂载数据卷之后容器反复重启多半是目录权限问题。宿主机上执行chmod -R 755 /app/onlyoffice chown -R 1000:1000 /app/onlyoffice容器内的用户UID是1000把数据目录的属主改成1000能避免很多奇怪的问题。确认服务健康。除了/healthcheck接口还可以看/welcome页面能看到版本号说明一切正常。后续每次重启服务器用docker ps确认容器自动拉起来了如果没起来检查--restart策略和Docker服务本身。4. 解决HTTPS访问三种方案详解4.1 为什么OnlyOffice默认只有HTTP刚部署完的OnlyOffice默认只提供HTTP服务容器内部的Nginx监听80端口没有任何SSL配置。这在局域网里用没问题但一旦走出内网就有三个麻烦第一是数据明文传输文档内容在传输过程中可以被抓包看到企业的内部合同、财务表格裸奔风险很大。第二是浏览器安全策略越来越严格很多协作功能和API接口要求必须是HTTPS环境下才工作正常。第三是第三方集成如果你要把OnlyOffice嵌入到一个HTTPS的Web系统里浏览器会默认阻止从HTTPS页面请求HTTP资源也就是“Mixed Content”问题。所以部署完做的第一件事就是把HTTPS给配上。4.2 方案一Nginx反向代理处理HTTPS这是我最推荐的方式因为灵活、可扩展到多服务、证书管理方便。思路是在宿主机上装一个Nginx对外提供443端口和证书收到的请求转发给OnlyOffice容器的80端口。宿主机Nginx的关键配置如下server { listen 443 ssl; server_name your-domain.com; # 证书路径按你自己的实际位置修改 ssl_certificate /etc/nginx/ssl/your-domain.com.crt; ssl_certificate_key /etc/nginx/ssl/your-domain.com.key; ssl_protocols TLSv1.2 TLSv1.3; ssl_ciphers HIGH:!aNULL:!MD5; client_max_body_size 100m; 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; # 这个Header特别关键告诉OnlyOffice原始请求是HTTPS proxy_set_header X-Forwarded-Proto $scheme; proxy_http_version 1.1; # OnlyOffice协同编辑依赖WebSocket必须支持Upgrade proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection upgrade; } }有几点要特别提醒X-Forwarded-Proto这个头必须设置否则OnlyOffice内部生成资源链接时还是用HTTP浏览器访问时又会触发混合内容拦截。Upgrade和Connection头必须配置对不然在线协同的时候实时同步会失败表现为“只有自己能看到自己的修改别人不同步”。client_max_body_size设大一点否则用户上传大文档时会直接收到413错误50M或100M是比较合理的取值。配置完记得让宿主机Nginx转发80到443实现HTTP自动跳转HTTPSserver { listen 80; server_name your-domain.com; return 301 https://$host$request_uri; }这个方案的优点很明显OnlyOffice容器不需要做任何改动证书和代理逻辑都放在宿主机Nginx这一层未来换证书、调整策略都很方便。如果宿主机上还跑着别的Web服务也可以共用一个Nginx统一管理。4.3 方案二官方SSL脚本直接启用HTTPSOnlyOffice官方镜像里其实自带了一个SSL配置脚本可以不用额外部署Nginx直接在容器内启用HTTPS。流程是这样的先把证书和私钥拷贝到容器里然后执行脚本。# 把证书文件拷贝到容器 docker cp /path/to/your-domain.crt onlyoffice:/usr/share/ca-certificates/onlyoffice/ docker cp /path/to/your-domain.key onlyoffice:/usr/share/ca-certificates/onlyoffice/ # 进入容器执行SSL配置脚本 docker exec -it onlyoffice bash -c bash /usr/bin/onlyoffice-documentserver-ssl.sh脚本执行过程中会检查容器内是否已经有证书没有的话会用openssl生成一个自签名证书。执行完成后容器内部的Nginx会自动加载SSL配置并监听443端口。如果你用的是自签名证书脚本生成的证书有效期默认是365天到期后需要重新生成。商业证书、Lets Encrypt证书则无此烦恼。这个方案的优点是省事、不需要额外组件适合“不想动宿主机环境”的情况。缺点也有每次证书更新都要重新拷文件、重跑脚本不如Nginx方案灵活。另外如果你同时还要在宿主机上部署别的服务那容器内顶HTTPS就有点浪费了——反正宿主机都要装Nginx不如让它一并干了。4.4 方案三Lets Encrypt免费证书自动化如果你有域名那我最建议用Lets Encrypt的免费证书配上自动续期证书管理的成本几乎为零。思路是先在宿主机装好certbot用webroot方式或者standalone方式签发证书然后把证书路径配置到宿主机Nginx里再用cron或systemd timer实现自动续期。基于Nginx方案的完整流程# 安装certbot和nginx插件 apt install certbot python3-certbot-nginx # 签发证书自动修改Nginx配置 certbot --nginx -d your-domain.com --redirectcertbot会自动检测你Nginx配置里对应域名的server块签发证书并自动改写SSL配置--redirect参数会顺便把HTTP跳转HTTPS也配了。证书快到期时可以手动执行certbot renew或者配置定时任务自动续期。Lets Encrypt证书有效期只有90天续期是必须的。在/etc/cron.d/certbot里添加0 3 * * * root certbot renew --quiet --deploy-hook systemctl reload nginx--deploy-hook里的命令会在证书成功续期后重新加载Nginx让新证书生效。我个人非常推荐这套组合OnlyOffice容器只负责文档服务宿主机Nginx负责HTTPS和域名分发certbot负责证书的签发和续期。稳定跑了一年多没因为证书问题出过故障。4.5 三种方案怎么选一张对比表方案优点缺点适用场景Nginx反向代理灵活、证书好管理、可多域名复用宿主机代理需要额外部署Nginx生产环境首选官方SSL脚本无需额外组件、配置简单证书更新繁琐、不便于扩展其他服务临时环境、不愿动宿主机Lets Encrypt自动化免费、自动续期、省心必须要有域名有公网域名且需要长期使用不管选哪种方案最后都要验证一下浏览器用https://你的域名访问地址栏出现小锁图标能正常打开OnlyOffice并且能新建、编辑、保存文档才算真正搞定。5. 常见问题与排查实录5.1 高频故障速查表跑了一段时间之后我把团队和读者遇到最多的问题整理成了一个表希望帮你少走弯路故障现象可能原因解决办法页面打不开端口无法访问防火墙或安全组未放行端口检查宿主机iptables和云安全组规则healthcheck一直返回false容器初始化未完成或内部服务崩溃看docker logs onlyoffice等1-2分钟再试编辑器加载空白/一直转圈JWT密钥不匹配检查OnlyOffice容器和业务系统的JWT_SECRET是否一致在线编辑保存失败回调地址用了HTTP把Document Server地址改成HTTPS浏览器提示混合内容页面是HTTPS但资源请求是HTTP给Nginx加X-Forwarded-Proto头重新配置证书协同编辑不实时同步WebSocket升级失败检查Nginx的Upgrade和Connection头配置上传大文件413client_max_body_size太小Nginx中调大该参数证书不被信任自签名证书未导入信任库生产环境换用正规证书或手动信任5.2 几个印象深刻的排障案例讲两个我自己踩过、也帮别人排查过的真实案例可能有点啰嗦但确实值得记一下。第一个案例HTTPS配好了但保存文档时提示“服务器无法保存文件”。通过查看OnlyOffice容器日志发现回调请求发送后业务系统返回了401。查下来发现是业务系统在接收OnlyOffice回调时校验了JWT token但业务系统里的JWT密钥和OnlyOffice容器里的密钥不一致。这种问题在集成阶段特别容易出现——两边分别配置却忘了保持同步。排查办法是打开业务系统和OnlyOffice的日志找到回调请求比对Authorization头里的token和业务系统验签结果。也可以用在线工具解析JWT payload看看用的算法和密钥是否正确。第二个案例用户通过HTTPS访问后浏览器反复提示“不安全”点开详情发现证书显示的是IP地址而不是域名。后来才确认Nginx配置文件里的server_name写的是IP但证书是用域名签发的。浏览器在做HTTPS证书校验时会校验访问的域名和证书里的Common Name或Subject Alternative Name是否匹配不匹配就会提示不安全。解决办法是更新Nginx配置把server_name改成和证书匹配的域名。5.3 部署与维护的经验心得最后分享几点我个人的经验和习惯不一定都是技术问题但对实际运维很有帮助。先HTTP后HTTPS。第一次部署千万不要一上来就配443先把HTTP流程跑通——能访问、能新建文档、能在线编辑确认基础功能没问题再上HTTPS。这样排查问题时能减少一半变量。给JWT密钥单独建一个配置文件。不要把密钥直接写在命令里后续要改密钥或者迁移服务时容易漏。建议用一个环境变量文件比如.env统一管理Docker Compose会自动读取业务系统也保持引用同一个配置源。数据卷备份别忘。OnlyOffice的关键数据都在/app/onlyoffice下面定期打包备份这个目录就相当于备份了所有文档和配置。我自己是写了个cron任务每天凌晨压缩并上传到对象存储出问题时能恢复到一个小时甚至一天前的状态。关注OnlyOffice官方更新日志。它的版本更新频率不高但每次更新往往伴随着安全修复和新特性。关注GitHub上的release页面有更新时先在测试环境验证确认业务系统兼容再升级。关于证书的几个安全细节不管用哪种方案证书相关有几件小事容易忽略也一并说一下。私钥权限。证书文件可以适当放开但私钥文件.key一定要收紧权限建议chmod 600。如果私钥泄露别人就能给你的域名“伪造”证书用户访问时会看到假的站点。证书链完整性。有些证书颁发机构会要求你把中间证书和服务器证书合并成一个.crt文件配置的时候如果漏了中间证书浏览器会提示“证书链不完整”。检查方法是用openssl s_client -connect your-domain.com:443 -servername your-domain.com看输出中的证书链是否完整。端口443要放行。这一点听起来像是废话但真的会有人忘了。公网服务器一定要检查安全组和防火墙把443端口放行不然证书配得再好也是白搭。Docker部署OnlyOffice这件事本身真不复杂难点都在细节上。尤其是HTTPS一路配下来你会发现真正让你头疼的往往不是命令本身而是各种隐性问题Header少了、密钥不一致、域名不对、证书链不完整……每个问题单独看都不难但串起来就很容易让人焦头烂额。我个人实际操作中的体会是把步骤拆细、每步验证通过再继续比一口气执行完一堆命令要靠谱得多。先把容器跑起来验证HTTP再配HTTPS验证证书和代理最后再接入业务系统验证JWT和回调。每一步的验证方式都很简单却能在关键时刻帮你精准定位问题。希望这篇能给你的OnlyOffice部署之路省点时间。
Docker部署OnlyOffice完整指南：三种HTTPS访问解决方案详解
搞在线文档编辑绕不开OnlyOffice这个名字。社区版免费、支持docx/xlsx/pptx在线预览和协同编辑、有现成的Docker镜像说实话在内网或者公网搭一套自用的在线办公环境OnlyOffice是性价比最高的选择之一。但部署本身不复杂复杂的是“怎么让它跑得稳、访问得安全”尤其是HTTPS——我见过太多人在这一步卡住页面能打开但编辑器加载失败、保存时报错、浏览器提示混合内容、回调地址对不上……这篇就专门讲清楚Docker部署OnlyOffice的完整流程以及解决HTTPS访问的几种可行方案。内容会覆盖为什么用Docker部署、部署前的规划和准备、具体命令和参数、Nginx反向代理/官方SSL脚本/Lets Encrypt三种HTTPS方案、常见问题与排障实录。我尽量把每一步为什么这么做讲明白而不是只丢命令让你抄。1. 为什么用Docker部署OnlyOffice1.1 自建在线编辑为什么选OnlyOffice在线文档编辑这个领域可选的开源方案其实不少比如Collabora Online基于LibreOffice、Apache Tika搭配前端预览、或者直接用NextCloud自带的编辑器。但真要说“以Office文档为核心、协同体验接近原生Office”的OnlyOffice几乎是唯一一个把兼容性做到这个程度的开源产品。我实测下来的感受是它对docx、xlsx、pptx的渲染还原度非常高表格里的公式、图表、条件格式基本不丢PPT的动画虽然不能100%还原但日常查看和编辑足够了。而且它支持多人同时编辑同一个文档光标、选区同步都挺流畅这个体验在开源方案里很难得。另一个关键点是集成能力。Spring Boot、Java Web项目、NextCloud、ownCloud、Confluence、Jira都能和它集成集成的核心逻辑其实很简单——你的应用调用OnlyOffice的API把文档路径、编辑权限、回调地址告诉它由OnlyOffice负责渲染和编辑再把结果回调给你。这种松耦合的设计对二次开发非常友好。1.2 Docker部署解决了什么问题如果没有Docker部署OnlyOffice会是一场小灾难。它依赖的组件相当多Node.js运行环境、PostgreSQL数据库、RabbitMQ消息队列、Redis缓存、Nginx、LibreOffice组件、以及一大堆系统库。手动安装的话光是版本兼容问题就能让你折腾一整天。而官方提供的onlyoffice/documentserver镜像把这些依赖全部打包好了。你不需要关心PostgreSQL装在哪个目录、RabbitMQ的默认账号密码是什么、LibreOffice的字体该往哪里放拉镜像、跑容器、映射端口一条命令的事。更重要的是Docker带来的隔离性和可移植性。你的宿主机可能同时跑着别的Java服务、MySQL、Redis如果直接装OnlyOffice它自带的PostgreSQL、RabbitMQ会跟现有环境抢端口、抢依赖、抢内存。容器化之后所有依赖都隔离在容器内部端口通过映射暴露互不干扰。还有一点是升级和维护方便。OnlyOffice新版本发布后拉新镜像、重建容器、迁移数据卷基本就完成了升级。比起在裸机上改配置文件、手动装依赖体验好太多。1.3 镜像选择与部署架构的取舍官方镜像只有两个onlyoffice/documentserver文档服务社区版和onlyoffice/documentserver-ee企业版带更多功能。绝大多数场景用社区版就够了对应Docker Hub上的标签是latest或具体的版本号比如7.5.1。这里有个重要的知识点早期版本的镜像把PostgreSQL、RabbitMQ、Redis都打在了同一个容器里用supervisor统一管理这就是“单容器”架构。到了后续版本官方虽然仍然提供单容器镜像但内部已经变成了一个“容器里有多个服务”的模式。如果你用Docker Compose官方也会推荐拆成多个独立容器来部署。我的建议是如果只是自己用、或者团队内部小规模使用单容器方案完全够省事如果是生产环境、并发较高、需要分别维护数据库和队列那就用Docker Compose拆开部署便于独立扩容和日志排查。后面的实战部分两种方式都会讲。2. 部署前的准备与关键参数规划2.1 Docker环境别让基础问题拖慢进度开始部署前先确认宿主机上有Docker环境。Linux服务器上一般用官方安装脚本curl -fsSL https://get.docker.com | bash systemctl enable docker systemctl start dockerWindows和macOS用户装Docker Desktop注意Windows的话一定要在BIOS里开启CPU虚拟化否则启动时会报“virtualization support wasnt detected”之类的错误。装好之后用docker version命令确认客户端和服务端都在正常运行。OnlyOffice容器本身对配置的要求不算高但也不是随便一个小机器就能带得动的。文档转换、图片预览、协同编辑都需要CPU和内存尤其是多人同时编辑大文档时内存占用会明显上升。我自己的经验是2核4G的机器可以跑但多人协同会有点吃力4核8G比较舒服如果是要频繁做文档格式转换CPU核心数更重要。确认网络环境也能访问Docker Hub或者配置好镜像加速。这一步虽然简单但国内服务器上真没配加速的话拉一个几个GB的镜像能等到怀疑人生。2.2 端口、数据卷与域名规划部署前花几分钟把下面几个问题定下来能省掉后面一大半的麻烦端口规划。OnlyOffice容器默认监听80端口HTTP和443端口HTTPS。宿主机上如果80端口已经被Nginx、Apache或者其他服务占了就要考虑改映射端口或者直接用后面会讲的“复用宿主机Nginx”方案。数据持久化。容器这东西最大的特点就是“随时可以销毁重建”但文档数据、数据库数据、配置文件不能丢。所以部署时必须要做数据卷映射把容器内的关键目录映射到宿主机上。我习惯在宿主机建一个统一目录比如/app/onlyoffice下面再按功能分目录结构清晰也好备份。域名规划。如果只是通过IP访问部署简单很多但如果要上HTTPS尤其要用Lets Encrypt这种免费证书就必须有一个真实域名。没有域名的话就只能用自签名证书浏览器会提示不安全内网用问题不大公网环境强烈不推荐。2.3 HTTPS证书提前弄好别等部署完再想开始部署之前先把证书准备好。证书有几种来源商业证书阿里云、腾讯云、DigiCert这些服务商都有价格从几十到几千不等适合企业用户。Lets Encrypt免费证书90天有效期可以自动化续期个人站长和中小团队用这个最合适。自签名证书openssl命令可以自己签发成本为零但浏览器会提示“不安全”需要手动信任。不管用哪种你最后需要的是两个文件证书文件.crt或.pem和私钥文件.key。这两个文件在后面的HTTPS配置里都要用建议提前整理到一个目录里。3. Docker部署OnlyOffice实战3.1 最简部署一条命令跑通服务先把服务跑起来后面再慢慢加HTTPS。最基础的部署命令如下docker run -i -t -d -p 80:80 \ --restartalways \ --name onlyoffice \ -v /app/onlyoffice/Data:/var/www/onlyoffice/Data \ -v /app/onlyoffice/logs:/var/log/onlyoffice \ -v /app/onlyoffice/lib:/var/lib/onlyoffice \ -v /app/onlyoffice/db:/var/lib/postgresql \ onlyoffice/documentserver:latest逐个解释一下关键参数-p 80:80把容器的80端口映射到宿主机80端口这样访问服务器IP就是访问OnlyOffice。--restartalways容器异常退出后自动重启服务器重启后容器也会自动拉起这个参数在生产环境几乎是必须的。-v数据卷映射。Data目录存文档和缓存logs目录存日志lib目录存配置db目录存PostgreSQL的数据。映射出来之后即使容器被删了数据和配置也还在。镜像比较大首次拉取可能要几分钟。启动后用下面的命令确认状态docker ps docker logs -f onlyoffice启动完成后浏览器访问http://服务器IP如果能看到一个欢迎页面或者Welcome页面说明部署成功了。也可以用接口来验证curl http://localhost/healthcheck返回true的话文档服务已经正常启动。需要注意的是第一次启动时容器内部要做初始化建库、导配置、启动子服务可能一两分钟内healthcheck还不返回true稍微等一下再看。3.2 生产级部署Docker Compose方案单容器适合快速验证但生产环境我更推荐用Docker Compose把文档服务、数据库、缓存、队列拆开管理。创建docker-compose.ymlversion: 3 services: onlyoffice-documentserver: image: onlyoffice/documentserver:latest container_name: onlyoffice-documentserver restart: always ports: - 80:80 - 443:443 environment: - JWT_ENABLEDtrue - JWT_SECRETyour-strong-secret-key - JWT_HEADERAuthorization - JWT_IN_BODYtrue volumes: - /app/onlyoffice/Data:/var/www/onlyoffice/Data - /app/onlyoffice/logs:/var/log/onlyoffice - /app/onlyoffice/lib:/var/lib/onlyoffice - /app/onlyoffice/db:/var/lib/postgresql这是单容器版用Compose管理的写法比直接在命令行传参好维护得多。用docker compose up -d启动用docker compose down停止未来升级镜像也只要改一下版本号再重新构建。如果你想把PostgreSQL、RabbitMQ、Redis也拆出来单独部署网上有不少完整的Compose编排但我个人建议除非有明确需求否则别拆。维护成本会上去而且官方单容器镜像内部已经对这些组件做了性能调优拆开反而不一定更快。3.3 部署后的初始化检查与JWT配置服务跑起来之后有几件事必须做。配置JWT密钥。从7.2版本开始OnlyOffice默认启用了JWTJSON Web Token认证。你的业务系统比如Spring Boot后端调用OnlyOffice API时必须在请求头里带上token而且这个token是用你配置的密钥签名的。如果密钥不匹配编辑器会加载失败或保存报错。上面Compose配置里的JWT_SECRET就是干这个的。你自己业务系统里集成时也要用同一个密钥来生成token。官方建议生产环境一定要改掉默认值这个密钥相当于整个文档服务的“通行证”泄露了别人就可能任意存取文档。检查数据目录权限。如果挂载数据卷之后容器反复重启多半是目录权限问题。宿主机上执行chmod -R 755 /app/onlyoffice chown -R 1000:1000 /app/onlyoffice容器内的用户UID是1000把数据目录的属主改成1000能避免很多奇怪的问题。确认服务健康。除了/healthcheck接口还可以看/welcome页面能看到版本号说明一切正常。后续每次重启服务器用docker ps确认容器自动拉起来了如果没起来检查--restart策略和Docker服务本身。4. 解决HTTPS访问三种方案详解4.1 为什么OnlyOffice默认只有HTTP刚部署完的OnlyOffice默认只提供HTTP服务容器内部的Nginx监听80端口没有任何SSL配置。这在局域网里用没问题但一旦走出内网就有三个麻烦第一是数据明文传输文档内容在传输过程中可以被抓包看到企业的内部合同、财务表格裸奔风险很大。第二是浏览器安全策略越来越严格很多协作功能和API接口要求必须是HTTPS环境下才工作正常。第三是第三方集成如果你要把OnlyOffice嵌入到一个HTTPS的Web系统里浏览器会默认阻止从HTTPS页面请求HTTP资源也就是“Mixed Content”问题。所以部署完做的第一件事就是把HTTPS给配上。4.2 方案一Nginx反向代理处理HTTPS这是我最推荐的方式因为灵活、可扩展到多服务、证书管理方便。思路是在宿主机上装一个Nginx对外提供443端口和证书收到的请求转发给OnlyOffice容器的80端口。宿主机Nginx的关键配置如下server { listen 443 ssl; server_name your-domain.com; # 证书路径按你自己的实际位置修改 ssl_certificate /etc/nginx/ssl/your-domain.com.crt; ssl_certificate_key /etc/nginx/ssl/your-domain.com.key; ssl_protocols TLSv1.2 TLSv1.3; ssl_ciphers HIGH:!aNULL:!MD5; client_max_body_size 100m; 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; # 这个Header特别关键告诉OnlyOffice原始请求是HTTPS proxy_set_header X-Forwarded-Proto $scheme; proxy_http_version 1.1; # OnlyOffice协同编辑依赖WebSocket必须支持Upgrade proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection upgrade; } }有几点要特别提醒X-Forwarded-Proto这个头必须设置否则OnlyOffice内部生成资源链接时还是用HTTP浏览器访问时又会触发混合内容拦截。Upgrade和Connection头必须配置对不然在线协同的时候实时同步会失败表现为“只有自己能看到自己的修改别人不同步”。client_max_body_size设大一点否则用户上传大文档时会直接收到413错误50M或100M是比较合理的取值。配置完记得让宿主机Nginx转发80到443实现HTTP自动跳转HTTPSserver { listen 80; server_name your-domain.com; return 301 https://$host$request_uri; }这个方案的优点很明显OnlyOffice容器不需要做任何改动证书和代理逻辑都放在宿主机Nginx这一层未来换证书、调整策略都很方便。如果宿主机上还跑着别的Web服务也可以共用一个Nginx统一管理。4.3 方案二官方SSL脚本直接启用HTTPSOnlyOffice官方镜像里其实自带了一个SSL配置脚本可以不用额外部署Nginx直接在容器内启用HTTPS。流程是这样的先把证书和私钥拷贝到容器里然后执行脚本。# 把证书文件拷贝到容器 docker cp /path/to/your-domain.crt onlyoffice:/usr/share/ca-certificates/onlyoffice/ docker cp /path/to/your-domain.key onlyoffice:/usr/share/ca-certificates/onlyoffice/ # 进入容器执行SSL配置脚本 docker exec -it onlyoffice bash -c bash /usr/bin/onlyoffice-documentserver-ssl.sh脚本执行过程中会检查容器内是否已经有证书没有的话会用openssl生成一个自签名证书。执行完成后容器内部的Nginx会自动加载SSL配置并监听443端口。如果你用的是自签名证书脚本生成的证书有效期默认是365天到期后需要重新生成。商业证书、Lets Encrypt证书则无此烦恼。这个方案的优点是省事、不需要额外组件适合“不想动宿主机环境”的情况。缺点也有每次证书更新都要重新拷文件、重跑脚本不如Nginx方案灵活。另外如果你同时还要在宿主机上部署别的服务那容器内顶HTTPS就有点浪费了——反正宿主机都要装Nginx不如让它一并干了。4.4 方案三Lets Encrypt免费证书自动化如果你有域名那我最建议用Lets Encrypt的免费证书配上自动续期证书管理的成本几乎为零。思路是先在宿主机装好certbot用webroot方式或者standalone方式签发证书然后把证书路径配置到宿主机Nginx里再用cron或systemd timer实现自动续期。基于Nginx方案的完整流程# 安装certbot和nginx插件 apt install certbot python3-certbot-nginx # 签发证书自动修改Nginx配置 certbot --nginx -d your-domain.com --redirectcertbot会自动检测你Nginx配置里对应域名的server块签发证书并自动改写SSL配置--redirect参数会顺便把HTTP跳转HTTPS也配了。证书快到期时可以手动执行certbot renew或者配置定时任务自动续期。Lets Encrypt证书有效期只有90天续期是必须的。在/etc/cron.d/certbot里添加0 3 * * * root certbot renew --quiet --deploy-hook systemctl reload nginx--deploy-hook里的命令会在证书成功续期后重新加载Nginx让新证书生效。我个人非常推荐这套组合OnlyOffice容器只负责文档服务宿主机Nginx负责HTTPS和域名分发certbot负责证书的签发和续期。稳定跑了一年多没因为证书问题出过故障。4.5 三种方案怎么选一张对比表方案优点缺点适用场景Nginx反向代理灵活、证书好管理、可多域名复用宿主机代理需要额外部署Nginx生产环境首选官方SSL脚本无需额外组件、配置简单证书更新繁琐、不便于扩展其他服务临时环境、不愿动宿主机Lets Encrypt自动化免费、自动续期、省心必须要有域名有公网域名且需要长期使用不管选哪种方案最后都要验证一下浏览器用https://你的域名访问地址栏出现小锁图标能正常打开OnlyOffice并且能新建、编辑、保存文档才算真正搞定。5. 常见问题与排查实录5.1 高频故障速查表跑了一段时间之后我把团队和读者遇到最多的问题整理成了一个表希望帮你少走弯路故障现象可能原因解决办法页面打不开端口无法访问防火墙或安全组未放行端口检查宿主机iptables和云安全组规则healthcheck一直返回false容器初始化未完成或内部服务崩溃看docker logs onlyoffice等1-2分钟再试编辑器加载空白/一直转圈JWT密钥不匹配检查OnlyOffice容器和业务系统的JWT_SECRET是否一致在线编辑保存失败回调地址用了HTTP把Document Server地址改成HTTPS浏览器提示混合内容页面是HTTPS但资源请求是HTTP给Nginx加X-Forwarded-Proto头重新配置证书协同编辑不实时同步WebSocket升级失败检查Nginx的Upgrade和Connection头配置上传大文件413client_max_body_size太小Nginx中调大该参数证书不被信任自签名证书未导入信任库生产环境换用正规证书或手动信任5.2 几个印象深刻的排障案例讲两个我自己踩过、也帮别人排查过的真实案例可能有点啰嗦但确实值得记一下。第一个案例HTTPS配好了但保存文档时提示“服务器无法保存文件”。通过查看OnlyOffice容器日志发现回调请求发送后业务系统返回了401。查下来发现是业务系统在接收OnlyOffice回调时校验了JWT token但业务系统里的JWT密钥和OnlyOffice容器里的密钥不一致。这种问题在集成阶段特别容易出现——两边分别配置却忘了保持同步。排查办法是打开业务系统和OnlyOffice的日志找到回调请求比对Authorization头里的token和业务系统验签结果。也可以用在线工具解析JWT payload看看用的算法和密钥是否正确。第二个案例用户通过HTTPS访问后浏览器反复提示“不安全”点开详情发现证书显示的是IP地址而不是域名。后来才确认Nginx配置文件里的server_name写的是IP但证书是用域名签发的。浏览器在做HTTPS证书校验时会校验访问的域名和证书里的Common Name或Subject Alternative Name是否匹配不匹配就会提示不安全。解决办法是更新Nginx配置把server_name改成和证书匹配的域名。5.3 部署与维护的经验心得最后分享几点我个人的经验和习惯不一定都是技术问题但对实际运维很有帮助。先HTTP后HTTPS。第一次部署千万不要一上来就配443先把HTTP流程跑通——能访问、能新建文档、能在线编辑确认基础功能没问题再上HTTPS。这样排查问题时能减少一半变量。给JWT密钥单独建一个配置文件。不要把密钥直接写在命令里后续要改密钥或者迁移服务时容易漏。建议用一个环境变量文件比如.env统一管理Docker Compose会自动读取业务系统也保持引用同一个配置源。数据卷备份别忘。OnlyOffice的关键数据都在/app/onlyoffice下面定期打包备份这个目录就相当于备份了所有文档和配置。我自己是写了个cron任务每天凌晨压缩并上传到对象存储出问题时能恢复到一个小时甚至一天前的状态。关注OnlyOffice官方更新日志。它的版本更新频率不高但每次更新往往伴随着安全修复和新特性。关注GitHub上的release页面有更新时先在测试环境验证确认业务系统兼容再升级。关于证书的几个安全细节不管用哪种方案证书相关有几件小事容易忽略也一并说一下。私钥权限。证书文件可以适当放开但私钥文件.key一定要收紧权限建议chmod 600。如果私钥泄露别人就能给你的域名“伪造”证书用户访问时会看到假的站点。证书链完整性。有些证书颁发机构会要求你把中间证书和服务器证书合并成一个.crt文件配置的时候如果漏了中间证书浏览器会提示“证书链不完整”。检查方法是用openssl s_client -connect your-domain.com:443 -servername your-domain.com看输出中的证书链是否完整。端口443要放行。这一点听起来像是废话但真的会有人忘了。公网服务器一定要检查安全组和防火墙把443端口放行不然证书配得再好也是白搭。Docker部署OnlyOffice这件事本身真不复杂难点都在细节上。尤其是HTTPS一路配下来你会发现真正让你头疼的往往不是命令本身而是各种隐性问题Header少了、密钥不一致、域名不对、证书链不完整……每个问题单独看都不难但串起来就很容易让人焦头烂额。我个人实际操作中的体会是把步骤拆细、每步验证通过再继续比一口气执行完一堆命令要靠谱得多。先把容器跑起来验证HTTP再配HTTPS验证证书和代理最后再接入业务系统验证JWT和回调。每一步的验证方式都很简单却能在关键时刻帮你精准定位问题。希望这篇能给你的OnlyOffice部署之路省点时间。
