企业官网建设流程全解析

搞在线文档编辑，绕不开OnlyOffice这个名字。社区版免费、支持docx/xlsx/pptx在线预览和协同编辑、有现成的Docker镜像，说实话，在内网或者公网搭一套自用的在线办公环境，OnlyOffice是性价比最高的选择之一。但部署本身不复杂，复杂的是“怎么让它跑得稳、访问得安全”，尤其是HTTPS——我见过太多人在这一步卡住：页面能打开但编辑器加载失败、保存时报错、浏览器提示混合内容、回调地址对不上……这篇就专门讲清楚Docker部署OnlyOffice的完整流程，以及解决HTTPS访问的几种可行方案。

内容会覆盖：为什么用Docker部署、部署前的规划和准备、具体命令和参数、Nginx反向代理/官方SSL脚本/Let's Encrypt三种HTTPS方案、常见问题与排障实录。我尽量把每一步为什么这么做讲明白，而不是只丢命令让你抄。

1. 为什么用Docker部署OnlyOffice

1.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 docker

Windows和macOS用户装Docker Desktop，注意Windows的话一定要在BIOS里开启CPU虚拟化，否则启动时会报“virtualization support wasn't 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，尤其要用Let's Encrypt这种免费证书，就必须有一个真实域名。没有域名的话，就只能用自签名证书，浏览器会提示不安全，内网用问题不大，公网环境强烈不推荐。

2.3 HTTPS证书：提前弄好，别等部署完再想

开始部署之前，先把证书准备好。证书有几种来源：

• 商业证书：阿里云、腾讯云、DigiCert这些服务商都有，价格从几十到几千不等，适合企业用户。
• Let's Encrypt免费证书：90天有效期，可以自动化续期，个人站长和中小团队用这个最合适。
• 自签名证书：openssl命令可以自己签发，成本为零，但浏览器会提示“不安全”，需要手动信任。

不管用哪种，你最后需要的是两个文件：证书文件（.crt或.pem）和私钥文件（.key）。这两个文件在后面的HTTPS配置里都要用，建议提前整理到一个目录里。

3. Docker部署OnlyOffice实战

3.1 最简部署：一条命令跑通服务

先把服务跑起来，后面再慢慢加HTTPS。最基础的部署命令如下：

docker run -i -t -d -p 80:80 \ --restart=always \ --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。
• --restart=always：容器异常退出后自动重启，服务器重启后容器也会自动拉起，这个参数在生产环境几乎是必须的。
• -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.yml：

version: "3" services: onlyoffice-documentserver: image: onlyoffice/documentserver:latest container_name: onlyoffice-documentserver restart: always ports: - "80:80" - "443:443" environment: - JWT_ENABLED=true - JWT_SECRET=your-strong-secret-key - JWT_HEADER=Authorization - JWT_IN_BODY=true 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默认启用了JWT（JSON 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自动跳转HTTPS：

server { listen 80; server_name your-domain.com; return 301 https://$host$request_uri; }

这个方案的优点很明显：OnlyOffice容器不需要做任何改动，证书和代理逻辑都放在宿主机Nginx这一层，未来换证书、调整策略都很方便。如果宿主机上还跑着别的Web服务，也可以共用一个Nginx统一管理。

4.3 方案二：官方SSL脚本直接启用HTTPS

OnlyOffice官方镜像里其实自带了一个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天，到期后需要重新生成。商业证书、Let's Encrypt证书则无此烦恼。

这个方案的优点是省事、不需要额外组件，适合“不想动宿主机环境”的情况。缺点也有：每次证书更新都要重新拷文件、重跑脚本，不如Nginx方案灵活。另外，如果你同时还要在宿主机上部署别的服务，那容器内顶HTTPS就有点浪费了——反正宿主机都要装Nginx，不如让它一并干了。

4.4 方案三：Let's Encrypt免费证书自动化

如果你有域名，那我最建议用Let's Encrypt的免费证书，配上自动续期，证书管理的成本几乎为零。

思路是：先在宿主机装好certbot，用webroot方式或者standalone方式签发证书，然后把证书路径配置到宿主机Nginx里，再用cron或systemd timer实现自动续期。

基于Nginx方案的完整流程：

# 安装certbot和nginx插件 apt install certbot python3-certbot-nginx # 签发证书，自动修改Nginx配置 certbot --nginx -d your-domain.com --redirect

certbot会自动检测你Nginx配置里对应域名的server块，签发证书并自动改写SSL配置，--redirect参数会顺便把HTTP跳转HTTPS也配了。证书快到期时，可以手动执行certbot renew或者配置定时任务自动续期。

Let's 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 三种方案怎么选：一张对比表

不管选哪种方案，最后都要验证一下：浏览器用https://你的域名访问，地址栏出现小锁图标，能正常打开OnlyOffice并且能新建、编辑、保存文档，才算真正搞定。

5. 常见问题与排查实录

5.1 高频故障速查表

跑了一段时间之后，我把团队和读者遇到最多的问题整理成了一个表，希望帮你少走弯路：

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部署之路省点时间。