Windows下安装OnlyOffice

ONLYOFFICE DocumentServer 是一套面向文档协作的服务端程序，擅长处理 Word、Excel、PPT 等格式的在线预览与协同编辑。很多团队把它架在 Windows 服务器上，用来给内部系统提供文档预览能力。本文按实际安装顺序，把从环境依赖到排障的全过程梳理一遍，重点说明三个容易被忽略的前置组件和两个高频报错的处理方式。

一、安装前先确认系统版本

DocumentServer 的 Windows 安装包对系统有明确要求，官方支持的是 Windows Server 2012 R2 及以上版本。如果你的机器是更早的 Server 2012 或 Windows 7，安装程序很可能在中途失败。这一点在下载页面会单独标注，动手前先在「此电脑 → 属性」里核对一下系统名称和配置。

另一件容易被忽略的事：DocumentServer 本身不自带运行所需的消息队列和数据库，它需要 Erlang、RabbitMQ、PostgreSQL 三个组件配合。其中 Erlang 与 RabbitMQ 有严格的版本对应关系，装错版本会出现运行时无法启动的情况。

二、安装 Erlang 24.2

Erlang 负责 RabbitMQ 的底层运行基础，DocumentServer 官方给出的推荐版本是 Erlang 24.2。

• 打开 Erlang 官方下载页面，找到 Windows 64 位安装包，文件形如 otp_win64_24.2.exe。
• 下载到本地后双击运行，按向导逐步点击下一步即可，默认安装路径通常位于 C:\Program Files\Erlang OTP 24.2。
• 安装过程中如果提示缺少 Visual C++ 运行库，先安装对应的 VC++ Redistributable 再重试。

装完后可以开一个命令行窗口，输入 erl 回车，能进入 Erlang 提示符说明安装成功，输入 halt(). 退出。

三、安装 RabbitMQ 3.9.12

RabbitMQ 是消息中间件，与 Erlang 版本必须匹配。官方给出的配套版本是 RabbitMQ 3.9.12。

• 到 RabbitMQ 的 GitHub Releases 页面下载 rabbitmq-server-3.9.12.exe。
• 双击安装，按默认设置一路下一步。安装程序会自动尝试注册 Erlang 节点，这一步必须建立在 Erlang 已装好的前提下。
• 安装完成后不要急着改任何配置，采用默认配置先跑通，后续出问题再调整。

四、安装 PostgreSQL 并准备专用库与账号

PostgreSQL 用来存放 DocumentServer 的运行数据。官方要求版本 12.9 或更高。

• 从 PostgreSQL 官网下载页面的 Windows 段安装，安装过程中会要求设置超级用户密码，记住它。
• 安装完成后，用 pgAdmin 或命令行登录，新建两个对象供后续使用：一个名为 onlyoffice 的数据库，一个名为 onlyoffice 的登录用户，并给该用户授予 onlyoffice 库的完整权限。
• 这两个名字不是随意起的，DocumentServer 安装程序会按约定去连接同名库，提前建好可以省掉后面改配置文件的麻烦。

五、安装 DocumentServer 本体

到 ONLYOFFICE 官方下载页取社区版安装包（Download ONLYOFFICE Docs）。

安装时有几个选项需要留意：

• 如果需要在安装时指定服务端口，可以在命令行用参数方式启动安装，形如 .\onlyoffice-documentserver.exe /DS_PORT=8080。
• 安装向导里若出现 certbot（自动申请证书）相关勾选项而你并不需要 HTTPS 证书，务必取消勾选，否则会尝试联网申请导致安装挂起。
• 安装结束后，服务默认并不会自动拉起。需要用管理员权限打开命令行，执行 net start DsExampleSvc 启动服务。
• 若希望机器重启后服务自动运行，执行 sc.exe config DsExampleSvc start= auto。注意 start= 后面必须跟空格再加 auto，这是 sc 命令的固有写法。

六、排障一：打开文件时提示下载失败

现象是文档能打开但预览不了，或者提示下载失败。这类问题通常出在请求过滤上：DocumentServer 默认不允许文档服务访问私有 IP 地址，而你后端的文件存储服务往往就架在内网地址上。

处理方式：打开 ONLYOFFICE\DocumentServer\config\default.json，把下面这段配置里的 false 改成 true。

"request-filtering-agent":{
"allowPrivateIPAddress":true,
"allowMetaIPAddress":true
}

这里的 meta 指的是文档元数据请求，内网环境下同样需要放开，只开一个 allowPrivateIPAddress 往往还不够。

七、排障二：提示无法生成，请联系管理员

如果日志里能看到回调但编辑界面报错「无法生成，请联系管理员」，基本是 JWT 校验没过。文件服务通过 callbackUrl 去回调文档存储服务，两边 token 对不上就会中断。

处理方式：打开 ONLYOFFICE\DocumentServer\config\local.json，把 token 相关的开关全部置为 false。

"token":{
"enable":{
"request":{
"inbox":false,
"outbox":false
},
"browser":false
},
"inbox":{
"header":"Authorization"
},
"outbox":{
"header":"Authorization"
}
}

这里关闭的是 JWT 验证。需要提醒的是，关掉校验后本地直接访问文档服务入口（例如 http://localhost/example/）打开文件时也可能报错，这是预期行为——生产环境建议保留 token 校验，只在内网调试阶段临时关闭。

八、改完配置怎么生效

JSON 属于服务运行时读取的配置，改完不会自动生效。做法有两步：先在「服务」面板里找到 DocumentServer 相关服务重启一次，再用 sc.exe config 确认自启动策略没被改动。如果重启后仍然报错，优先看 ONLYOFFICE\DocumentServer\log 目录下的日志，报错行号一般能直接指到问题字段。

九、实践中值得注意的几件事

• 三个依赖组件尽量一次装齐，不要先跳过某个等用到时再补，版本错配排查成本很高。
• 端口冲突是安装失败的常见原因，8080 这类端口先确认没被占用。
• 安装路径里尽量不要出现中文和空格，改配置文件时路径出错会比较难定位。
• 社区版功能与商业版在部分高级协作特性上有差异，选型前先确认需要的编辑能力是否在社区版内。

按上面顺序走一遍，文档服务的安装和基础排障基本都能覆盖。真正复杂的场景是和现有对象存储、鉴权体系的对接，那部分需要根据自己的存储服务地址单独配置回调。

qidao123.com企服评测-应用市场 编辑提示