SharePoint
关于用 ONLYOFFICE 文档替换 Office Online Server
Microsoft 将于 2026 年 12 月 31 日终止对 Office Online Server(OOS)的支持。此后,OOS 将不再获得安全更新、错误修复或技术支持。要继续在 SharePoint Server Subscription Edition 中编辑文档,您可以用 ONLYOFFICE 文档替换 OOS。
OOS 通过 WOPI 连接到 SharePoint。WOPI 是一种基于 REST 的协议,当客户端与您的数据服务器建立连接时,会向一组 REST 端点发出 HTTP 请求。ONLYOFFICE 文档支持同一协议,因此替换 OOS 只需将 SharePoint 的 WOPI 绑定从 OOS 重定向到 ONLYOFFICE 文档。您的文件、文档库和访问权限均保持不变。
除 WOPI 之外,您还可以使用官方 ONLYOFFICE SharePoint 连接器来连接 ONLYOFFICE 文档。两种方式都允许直接在 SharePoint 中编辑文档,但支持的功能和格式有所不同。欲了解更多信息,请访问 ONLYOFFICE 到 SharePoint 连接器的 GitHub 页面。该连接器根据 AGPL-3.0 许可证分发。
要了解有关 ONLYOFFICE SharePoint 连接器如何工作的更多信息,请访问我们的 API 文档页面。
要求
- ONLYOFFICE 文档 v9.4 或更高版本(服务器版本),并已启用 WOPI。请按照此说明启用 WOPI。该实例必须可以从 SharePoint 和任何终端客户端解析和连接,并且 SharePoint 服务器地址必须对 ONLYOFFICE 文档可访问。请参阅官方文档页面以了解有关安装 ONLYOFFICE 文档的更多信息。
- SharePoint Server Subscription Edition
- 具有场管理员权限的 SharePoint 管理 Shell 访问权限
官方连接器的要求列在其对应部分中。
我们强烈建议只选择一种连接 ONLYOFFICE 文档的方式,并且不要将其与 OOS 同时使用。如果文档可以同时通过不同方式打开,可能会出现协作编辑冲突,并导致更改丢失。因此,OOS 和 ONLYOFFICE 文档不能在同一个场中并行运行。
使用 WOPI 替换 Office Online Server
启用授权头
wopi.sendAuthorizationHeader 参数会在 WOPI 请求中添加 Authorization: Bearer <access_token> 头。该参数从 ONLYOFFICE 文档 v9.4 开始提供,默认处于禁用状态。对于 SharePoint Server Subscription Edition,必须启用此参数。否则会出现 Invalid access token 错误,文档编辑失败。
要启用 wopi.sendAuthorizationHeader,请使用以下方式之一:
-
将以下内容添加到
local.json配置文件(在 Linux 和 Docker 中为/etc/onlyoffice/documentserver/local.json,在 Windows 中为%ProgramFiles%\ONLYOFFICE\DocumentServer\config\local.json)。请勿编辑default.json文件:更新 ONLYOFFICE 文档时该文件会被覆盖。{"wopi": {"sendAuthorizationHeader": true}}更改后,请重新启动服务:
DEB/RPM:
systemctl restart ds-converter ds-docserviceDocker:
sudo docker exec <containerID> supervisorctl restart ds:converter ds:docserviceWindows PowerShell:
Restart-Service DsConverterSvc, DsDocServiceSvc -
在商业版本中,也可以通过管理面板配置此参数。
使用 WOPI 时,访问令牌在一段时间后会过期。将 access_token_ttl 属性设置为 10 小时以用于快速协作模式。
将 SharePoint 添加到受信任的主机
从 ONLYOFFICE 文档 v10.0 开始,只有当 IP 过滤器中有规则明确指定某个 WOPI 主机时,服务器才会联系该主机。通配规则 * 不算在内。如果没有这样的规则,ONLYOFFICE 文档会以 403 错误拒绝请求,来自 SharePoint 的文档将无法打开。
将包含您的 SharePoint 服务器主机名或 IP 地址的规则添加到 local.json 配置文件中。您也可以使用通配符模式,例如 *.example.com。规则按从上到下的顺序进行检查,并应用第一条匹配的规则,因此请将您的规则放在通配规则 * 之上。local.json 中的列表会替换默认列表,因此请在列表末尾保留 * 规则:
{
"services": {
"CoAuthoring": {
"ipfilter": {
"rules": [
{"address": "sharepoint.example.com", "allowed": true},
{"address": "*", "allowed": true}
]
}
}
}
}
然后按照上文所述重新启动服务。
在商业版本中,您可以在管理面板的 IP 过滤页面上添加该规则。
删除 Office Online Server 绑定
-
打开您的 SharePoint 服务器并运行 SharePoint 管理 Shell 控制台。检查场上当前的 WOPI 绑定。这些是指向您的 Office Online Server 的绑定:
Get-SPWOPIBinding我们建议保存此命令的输出,因为其中包含 SharePoint 之前使用的 OOS 服务器的名称。
-
删除这些绑定:
Remove-SPWOPIBinding -All:$true
通过 WOPI 连接 ONLYOFFICE 文档
-
在 SharePoint 管理 Shell 控制台中,设置所需的 WOPI 区域:
Set-SPWOPIZone -Zone "external-http"该区域必须与 ONLYOFFICE 文档在其 WOPI 发现中公布的区域一致。默认值为
external-http,由 ONLYOFFICE 文档的wopi.wopiZone参数设置。如果您更改了此参数,请在 SharePoint 中设置相同的区域。 -
根据文件类型创建默认操作的绑定。
一次性为所有文件类型创建绑定:
New-SPWOPIBinding -ServerName ip_or_domain.com:port仅为特定文件类型创建绑定:
New-SPWOPIBinding -ServerName ip_or_domain.com:port -Extension DOCX如果未使用 SSL,请在命令末尾添加
-AllowHTTP。 -
转到您的 SharePoint 文档库并点击任意文档。该文档将在 ONLYOFFICE 文档中打开。
创建新文档
以下说明仅适用于 WOPI 连接方法。
要能够创建新文档,请设置以下描述的参数。此示例仅针对 DOCX 文件,但您可以类似地添加 XLSX、PPTX 和其他文件。
-
启用允许管理内容类型设置:转到文档 → 库设置 → 高级设置。在允许管理内容类型部分中,选择是并点击确定。

-
在文档库中,转到站点内容 → 站点设置 → 站点内容类型。点击创建。填写表单:名称(新文档)、描述。在父内容类型中,选择文档内容类型、文档。在现有组中,选择自定义内容类型并点击确定。

-
在文档库中,转到站点内容 → 站点设置 → 站点内容类型。选择最近添加的新文档。转到高级设置 → 文档模板 → 上传新文档模板。点击选择文件按钮,上传所需的文档并点击确定。

-
转到文档库 → 库设置。在内容类型部分中,选择从现有站点内容类型添加。在从中选择站点内容类型列表中,选择自定义内容类型。在可用站点内容类型字段中,选择新文档。点击添加 > 按钮,然后点击确定。

-
在文档库中,刷新页面并按新建按钮。

-
文档内容类型将自动添加为父类型。它必须被隐藏:转到文档库 → 库设置。在内容类型部分中,选择更改新按钮顺序和默认内容类型。

在可见列中,取消选中文档内容类型的复选框并点击确定。

-
在文档库中,刷新页面并按新建按钮 — 只有新文档菜单项可用。

使用官方连接器替换 Office Online Server
除 WOPI 之外,您还可以使用官方 ONLYOFFICE 连接器将 ONLYOFFICE 文档连接到 SharePoint。与 WOPI 相比,它还支持严格协作模式、变更跟踪功能和文档比较。文档通过文件上下文菜单或功能区中的 Open in ONLYOFFICE 选项打开。
在安装连接器之前,请按照上文删除 Office Online Server 绑定部分中的说明删除 Office Online Server 绑定。
要求
- ONLYOFFICE 文档 v7.1(服务器或云版本)或更高版本。该实例必须可以从 SharePoint 和任何终端客户端解析和连接,并且必须能够直接向 SharePoint 发送 POST 请求。
- SharePoint Server Subscription Edition
- ONLYOFFICE SharePoint 连接器 3.2.0
连接器 3.2.0 版本已在 SharePoint Server Subscription Edition 上通过测试。连接器的早期版本在 SharePoint 2019 上通过测试。
安装和配置
ONLYOFFICE SharePoint 集成解决方案是一个官方的 ONLYOFFICE 连接器,可在 GitHub 页面上根据 GNU AGPL v.3 许可证获得。
-
点击开始,指向所有程序,指向管理工具,然后点击服务,确保 SharePoint 管理服务已启动。
-
点击开始,打开 SharePoint 管理 Shell,并导航到包含 .wsp 文件的目录。
-
运行 Install.ps1 脚本:
PS> .\Install.ps1 -
输入您的 SharePoint 站点地址:
https://<yoursharepointsite>替代步骤 3 和 4,您可以输入以下命令:
Add-SPSolution -LiteralPath <solutionpath>/onlyoffice.wsp在 SharePoint 中央管理主页上,点击系统设置 → 场管理 → 管理场解决方案。在解决方案管理页面上,点击 onlyoffice.wsp,然后点击部署解决方案。
-
在 SharePoint 中央管理主页上,在应用程序管理下,点击管理 Web 应用程序。
-
确保选择您的站点并点击身份验证提供程序图标。
-
在身份验证提供程序弹出窗口中,点击默认区域。
-
在编辑身份验证下,勾选启用匿名访问并点击保存。
-
返回到 Web 应用程序管理,点击匿名策略图标。
-
在匿名访问限制下,选择您的区域,将权限设置为无 – 无策略,然后点击保存。
-
在 SharePoint 中,打开具有管理设置的
/_layouts/15/Onlyoffice/Settings.aspx页面。在 ONLYOFFICE Docs address 字段中,输入以下地址:https://<documentserver>/其中 documentserver 是安装了 ONLYOFFICE 文档的服务器名称。该地址必须对用户浏览器和 SharePoint 服务器可访问。SharePoint 服务器地址也必须对 ONLYOFFICE 文档可访问以确保正确工作。
如果您在 SharePoint 中设置了子站点,您需要另外配置 ONLYOFFICE 文档与每个子站点的连接。转到每个子站点设置并在适当的字段中输入 ONLYOFFICE 文档地址。
要在安装 ONLYOFFICE 文档之前试用该连接器,请在设置中勾选 Connect to the ONLYOFFICE Docs demo server 复选框。演示服务器是一个公共测试服务器,可使用 30 天,因此请勿在其上存储私人或敏感数据。
从 ONLYOFFICE 文档 v7.2 开始,JWT 默认启用,并自动生成密钥。您还需要在 SharePoint 端启用它:在 ONLYOFFICE 文档配置文件中找到您的密钥,然后在连接器设置的 ONLYOFFICE Docs secret key 字段中指定相同的密钥。有关详细信息,请参阅下面的启用 JWT 部分。
如果启用了 JWT 保护,必须在 JWT header 字段中指定自定义头名称,因为 SharePoint 安全策略会阻止外部 'Authorization' 头。此头也应在 ONLYOFFICE 文档签名设置中指定(更多信息请参见此处)。
编译解决方案
有两种方法可以编译 ONLYOFFICE SharePoint 集成解决方案:
-
使用 MS Visual Studio:
- 进入 SharePoint 服务器并在 Visual Studio 中打开此项目。
- 在解决方案资源管理器中,打开项目的快捷菜单,然后选择发布。
- 在发布对话框中,选择发布到文件系统选项按钮。
- 点击发布按钮。当发布过程完成时,将创建解决方案 .wsp 文件。
- 将生成的文件复制到包含 Install.ps1 文件的文件夹(默认情况下为 BuildAndInstall 文件夹)。
-
使用 build.bat 文件:
- 转到 BuildAndInstall 文件夹。
- 运行 build.bat 文件。
- 生成的解决方案 .wsp 文件将被创建并放置到 BuildAndInstall 文件夹中。
工作原理
ONLYOFFICE 集成遵循此处记录的 API。
-
用户导航到 SharePoint 中的文档,并在上下文菜单或功能区中选择 Open in ONLYOFFICE 操作。
-
SharePoint 向编辑器页面发出请求(URL 形式为:
/_layouts/15/Onlyoffice/editorPage.aspx?SPListItemId={ItemId}&SPListURLDir={ListUrlDir}&action=track)。 -
SharePoint 准备一个包含以下属性的 JSON 对象:
- url — ONLYOFFICE 文档用于下载文档的 URL;
- callbackUrl — ONLYOFFICE 文档通知文档编辑状态的 URL;
- DocumentServerHost — 客户端需要回复 ONLYOFFICE 文档服务器的 URL(可以在设置页面中设置);
- Key — 来自 SharePoint 的文件标识符;
- FileName — 文档标题(名称);
- CurrentUserId — 用户标识符;
- CurrentUserLogin — 用户登录名。
-
SharePoint 构建一个页面,填充所有这些值,以便客户端浏览器可以加载编辑器。
-
客户端浏览器向 ONLYOFFICE 文档的 JavaScript 库发出请求,并向 ONLYOFFICE 文档发送带有上述属性的 DocEditor 配置。
-
然后 ONLYOFFICE 文档从 SharePoint 下载文档,用户开始编辑。
-
当所有用户和客户端浏览器完成编辑时,他们关闭编辑窗口。
-
在 10 秒不活动后,ONLYOFFICE 文档向
callbackUrl发送 POST 请求,通知 SharePoint ONLYOFFICE 解决方案客户端已完成文档编辑并关闭。 -
SharePoint 下载新版本的文档,替换旧版本。
要了解更多常见问题及其解决方法,请访问我们的故障排除指南。
启用 JWT
为了保护文档免受未经授权的访问,ONLYOFFICE 编辑器使用 JSON Web Token (JWT)。在初始化文档编辑器和内部 ONLYOFFICE 文档服务之间的命令交换期间,令牌会被添加到配置中。使用密钥对 JSON Web Token 进行签名,并在请求 ONLYOFFICE 文档时验证令牌。
从 ONLYOFFICE 文档 v7.2 开始,JWT 默认启用,并自动生成密钥。您需要在 ONLYOFFICE 文档配置文件中找到您的密钥,然后在连接器设置中指定相同的密钥。
步骤 1: 在 ONLYOFFICE 文档配置文件中找到您的密钥
-
使用任何可用的文本编辑器打开 local.json 文件:
-
对于 Linux:
/etc/onlyoffice/documentserver/local.json -
对于 Windows:
%ProgramFiles%\ONLYOFFICE\DocumentServer\config\local.json -
对于 Docker:使用
docker exec -it <containerID> bash命令进入 ONLYOFFICE 文档容器并打开/etc/onlyoffice/documentserver/local.json。或者,您可以运行:sudo docker exec <containerID> /var/www/onlyoffice/documentserver/npm/json -f /etc/onlyoffice/documentserver/local.json 'services.CoAuthoring.secret.session.string'
local.json 文件应如下所示:
{"services": {"CoAuthoring": {"token": {"enable": {"request": {"inbox": true,"outbox": true},"browser": true}},"secret": {"inbox": {"string": "yoursecret"},"outbox": {"string": "yoursecret"},"session": {"string": "yoursecret"}}}}} -
-
true值在三个部分中指定,这意味着令牌验证已启用:services.CoAuthoring.token.enable.browserservices.CoAuthoring.token.enable.request.inboxservices.CoAuthoring.token.enable.request.outbox
-
自动生成的密钥在三个部分中指定。您可以用自己的密钥替换默认值 — 它在三个部分中必须相同:
services.CoAuthoring.secret.inbox.stringservices.CoAuthoring.secret.outbox.stringservices.CoAuthoring.secret.session.string
-
如果您进行了更改,请保存并重新启动服务:
DEB/RPM:
systemctl restart ds-converter ds-docserviceDocker:
sudo docker exec <containerID> supervisorctl restart ds:converter ds:docserviceWindows PowerShell:
Restart-Service DsConverterSvc, DsDocServiceSvc
步骤 2: 在连接器设置中指定相同的密钥
在连接器设置中,在 ONLYOFFICE Docs secret key 字段中指定相同的密钥并保存设置。如果该字段留空,连接器会显示警告。
功能比较
Office Online Server 和 ONLYOFFICE 文档
下表列出了 Office Online Server 的主要功能与通过 WOPI 连接的 ONLYOFFICE 文档的对应关系。
| 功能 | Office Online Server | ONLYOFFICE 文档(WOPI) |
|---|---|---|
| Word、Excel 和 PowerPoint 文档 | 查看和编辑 | 查看和编辑 |
| OneNote 笔记本 | 查看和编辑 | ✗ |
| Visio 图表 | ✗ | 查看 1 |
| 协作编辑 | ✓ | ✓ |
| 文档库和搜索结果中的预览 | ✓ | 请在您的环境中测试 |
| 访问权限 | 取自 SharePoint | 取自 SharePoint |
1 仅适用于 ONLYOFFICE 文档企业版和开发者版。
Office Online Server 仅提供基于浏览器的 Word、Excel、PowerPoint 和 OneNote 版本。
WOPI 和官方连接器
下表列出了通过 WOPI 和使用官方连接器连接 ONLYOFFICE 文档时可用的主要功能。
| 功能 | WOPI | 官方连接器 |
|---|---|---|
| 打开文档 | 点击文件,或在上下文菜单中选择打开 → 在 office online 中打开 | 上下文菜单或功能区中的 Open in ONLYOFFICE |
| 编辑 DOCX、XLSX、PPTX | ✓ | ✓ |
| 编辑 DOCM、XLSM、PPTM | ✓ | ✓ |
| 编辑 PDF | ✓ | ✓ |
| ODT、ODS、ODP | 编辑 | 仅查看 |
| XLS | 编辑 | 仅查看 |
| DOC、PPT | 仅查看 | 仅查看 |
| 查看 Visio 图表 | ✓ 1 | ✓ |
| OneNote | ✗ | ✗ |
| 快速协作模式 | ✓ | ✓ |
| 严格协作模式 | ✗ 2 | ✓ |
| 变更跟踪 | ✗ | ✓ |
| 评论、内置聊天 | ✓ | ✓ |
| 版本历史 | ✓ 3 | ✓ |
| 比较文档 | ✗ | ✓ |
| 邮件合并 | ✓ | ✓ |
| 从存储中插入图像 | ✗ | ✗ |
| 宏 | JavaScript 宏 | JavaScript 宏 |
| 访问权限 | 取自 SharePoint | 取自 SharePoint |
1 仅适用于 ONLYOFFICE 文档企业版和开发者版。
2 使用 WOPI 时,严格协作模式可能会对访问令牌参数产生负面影响。
3 使用 WOPI 时,编辑器中的版本历史选项会打开 SharePoint 的版本历史页面。内置的 ONLYOFFICE 版本历史仅在使用官方连接器时可用。
支持的格式
WOPI:
- 可查看和编辑:CSV、DOCM、DOCX、DOTM、DOTX、EPUB、FB2、HTML、MD、ODP、ODS、ODT、OTP、OTS、OTT、PDF、POTM、POTX、PPSM、PPSX、PPTM、PPTX、RTF、TSV、TXT、XLS、XLSB、XLSM、XLSX、XLTM、XLTX
- 仅可查看:DJVU、DOC、DOT、DPS、DPT、ET、ETT、FODP、FODS、FODT、GDOC、GSHEET、GSLIDES、HML、HTM、HWP、HWPX、KEY、MHT、MHTML、NUMBERS、ODG、OFD、OXPS、PAGES、POT、PPS、PPT、STW、SXC、SXI、SXW、VSDM、VSDX、VSSM、VSSX、VSTM、VSTX、WPS、WPT、XLT、XML、XPS
编辑 CSV、EPUB、FB2、HTML、MD、ODP、ODS、ODT、OTP、OTS、OTT、RTF、TSV、TXT 和 XLS 文件时,保存后可能会丢失部分格式,因为这些格式不支持编辑器的全部功能。
Visio 格式(VSDM、VSDX、VSSM、VSSX、VSTM、VSTX)仅可在 ONLYOFFICE 文档企业版和开发者版中通过 WOPI 查看。
官方连接器:
- 可查看和编辑:DOCM、DOCX、DOTM、DOTX、PDF、POTM、POTX、PPSM、PPSX、PPTM、PPTX、XLSB、XLSM、XLSX、XLTM、XLTX
- 仅可查看:CSV、DJVU、DOC、DOT、DPS、DPT、EPUB、ET、ETT、FB2、FODP、FODS、FODT、HML、HTM、HTML、HWP、HWPX、KEY、MD、MHT、MHTML、NUMBERS、ODG、ODP、ODS、ODT、OTP、OTS、OTT、OXPS、PAGES、POT、PPS、PPT、RTF、STW、SXC、SXI、SXW、TXT、VSDM、VSDX、VSSM、VSSX、VSTM、VSTX、WPS、WPT、XLS、XLT、XML、XPS
可用的格式取决于您的 ONLYOFFICE 文档版本和所选的连接方式。
版本 3.2.0 的新功能
已添加
- 支持版本历史
- 管理设置中的插件说明和实用链接
- 连接到 ONLYOFFICE 文档演示服务器
- ONLYOFFICE 文档云的链接
- 向 ONLYOFFICE 文档发出的请求 URL 中的
shardkey参数 - JWT 密钥为空时的警告弹窗
完整的变更日志可在此处查看。
常见问题
保持不变的功能
我需要移动或转换文件吗? 不需要。您的文件仍保留在 SharePoint 文档库中。ONLYOFFICE 文档原生支持 DOCX、XLSX 和 PPTX 格式,无需转换。
访问权限会改变吗? 不会。ONLYOFFICE 文档从 SharePoint 获取访问权限。如果用户在 SharePoint 中有权访问某个文件,就可以在 ONLYOFFICE 文档中以相同的权限打开该文件。
多个用户可以同时编辑一个文档吗? 可以。两种连接方式都支持实时协作编辑。用户还可以添加评论,并在内置聊天中交流。
版本历史会保留吗? 会。文件版本仍保留在 SharePoint 中。使用 WOPI 时,编辑器中的版本历史选项会打开 SharePoint 的版本历史页面。官方连接器从 3.2.0 版本开始直接在编辑器中显示版本历史。
有所不同的功能
用户如何打开文档? 使用 WOPI 时,点击文件,或在上下文菜单中选择打开 → 在 office online 中打开。使用官方连接器时,在文件的上下文菜单或功能区中选择 Open in ONLYOFFICE。
文档的显示效果会完全相同吗? 对于大多数文档,兼容性很高。如果文档使用了需要替换的特殊字体或高度自定义的模板,可能会出现细微的视觉差异。
用户会熟悉这个界面吗? 工具栏布局和格式选项遵循用户熟悉的 Microsoft Word、Excel 和 PowerPoint 的使用习惯。某些选项可能位于不同的选项卡上。
VBA 宏会怎样? ONLYOFFICE 文档使用 JavaScript 宏代替 VBA。可以使用 AI 插件将 VBA 代码转换为与 ONLYOFFICE 兼容的 JavaScript。标准宏可以直接转换,而高度自定义的脚本可能需要检查。
用户可以创建新文档吗? 可以。使用 WOPI 时,您需要先向文档库添加自定义内容类型。有关详细信息,请参阅创建新文档部分。
文件预览和嵌入式文档视图可以使用吗? 某些在编辑器之外依赖 Office Online Server 的 SharePoint 功能可能会有不同的表现。我们建议在您的环境中对其进行测试。
不支持的功能
我可以同时使用 OOS 和 ONLYOFFICE 文档吗? 不可以。只能使用一种连接方式。如果文档可以同时通过不同方式打开,可能会导致更改丢失。
使用 WOPI 时哪些功能不可用? 由于 WOPI 架构的限制,通过 WOPI 连接 ONLYOFFICE 文档缺少某些功能:
- 不支持严格协作模式。
- 不支持变更跟踪功能。
- 不支持比较文档。
- 不支持从存储中插入图像。
官方连接器支持除从存储中插入图像以外的所有这些功能。
是否支持 OneNote? 不支持。ONLYOFFICE 文档不支持 OneNote 笔记本。