跳到主要内容

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-docservice

    Docker:

    sudo docker exec <containerID> supervisorctl restart ds:converter ds:docservice

    Windows 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 绑定​

  1. 打开您的 SharePoint 服务器并运行 SharePoint 管理 Shell 控制台。检查场上当前的 WOPI 绑定。这些是指向您的 Office Online Server 的绑定:

    Get-SPWOPIBinding

    我们建议保存此命令的输出,因为其中包含 SharePoint 之前使用的 OOS 服务器的名称。

  2. 删除这些绑定:

    Remove-SPWOPIBinding -All:$true

通过 WOPI 连接 ONLYOFFICE 文档​

  1. 在 SharePoint 管理 Shell 控制台中,设置所需的 WOPI 区域:

    Set-SPWOPIZone -Zone "external-http"

    该区域必须与 ONLYOFFICE 文档在其 WOPI 发现中公布的区域一致。默认值为 external-http,由 ONLYOFFICE 文档的 wopi.wopiZone 参数设置。如果您更改了此参数,请在 SharePoint 中设置相同的区域。

  2. 根据文件类型创建默认操作的绑定。

    一次性为所有文件类型创建绑定:

    New-SPWOPIBinding -ServerName ip_or_domain.com:port

    仅为特定文件类型创建绑定:

    New-SPWOPIBinding -ServerName ip_or_domain.com:port -Extension DOCX

    如果未使用 SSL,请在命令末尾添加 -AllowHTTP。

  3. 转到您的 SharePoint 文档库并点击任意文档。该文档将在 ONLYOFFICE 文档中打开。

创建新文档​

重要

以下说明仅适用于 WOPI 连接方法。

要能够创建新文档,请设置以下描述的参数。此示例仅针对 DOCX 文件,但您可以类似地添加 XLSX、PPTX 和其他文件。

  1. 启用允许管理内容类型设置:转到文档 → 库设置 → 高级设置。在允许管理内容类型部分中,选择是并点击确定。

    允许管理内容类型

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

    创建站点内容类型

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

    上传文档模板

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

    将内容类型添加到库

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

    新建按钮

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

    更改新建按钮顺序

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

    隐藏文档内容类型

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

    新文档菜单项

使用官方连接器替换 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 许可证获得。

  1. 点击开始,指向所有程序,指向管理工具,然后点击服务,确保 SharePoint 管理服务已启动。

  2. 点击开始,打开 SharePoint 管理 Shell,并导航到包含 .wsp 文件的目录。

  3. 运行 Install.ps1 脚本:

    PS> .\Install.ps1
  4. 输入您的 SharePoint 站点地址:

    https://<yoursharepointsite>

    替代步骤 3 和 4,您可以输入以下命令:

    Add-SPSolution -LiteralPath <solutionpath>/onlyoffice.wsp

    在 SharePoint 中央管理主页上,点击系统设置 → 场管理 → 管理场解决方案。在解决方案管理页面上,点击 onlyoffice.wsp,然后点击部署解决方案。

  5. 在 SharePoint 中央管理主页上,在应用程序管理下,点击管理 Web 应用程序。

  6. 确保选择您的站点并点击身份验证提供程序图标。

  7. 在身份验证提供程序弹出窗口中,点击默认区域。

  8. 在编辑身份验证下,勾选启用匿名访问并点击保存。

  9. 返回到 Web 应用程序管理,点击匿名策略图标。

  10. 在匿名访问限制下,选择您的区域,将权限设置为无 – 无策略,然后点击保存。

  11. 在 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:

    1. 进入 SharePoint 服务器并在 Visual Studio 中打开此项目。
    2. 在解决方案资源管理器中,打开项目的快捷菜单,然后选择发布。
    3. 在发布对话框中,选择发布到文件系统选项按钮。
    4. 点击发布按钮。当发布过程完成时,将创建解决方案 .wsp 文件。
    5. 将生成的文件复制到包含 Install.ps1 文件的文件夹(默认情况下为 BuildAndInstall 文件夹)。
  • 使用 build.bat 文件:

    1. 转到 BuildAndInstall 文件夹。
    2. 运行 build.bat 文件。
    3. 生成的解决方案 .wsp 文件将被创建并放置到 BuildAndInstall 文件夹中。

工作原理​

ONLYOFFICE 集成遵循此处记录的 API。

  1. 用户导航到 SharePoint 中的文档,并在上下文菜单或功能区中选择 Open in ONLYOFFICE 操作。

  2. SharePoint 向编辑器页面发出请求(URL 形式为:/_layouts/15/Onlyoffice/editorPage.aspx?SPListItemId={ItemId}&SPListURLDir={ListUrlDir}&action=track)。

  3. SharePoint 准备一个包含以下属性的 JSON 对象:

    • url — ONLYOFFICE 文档用于下载文档的 URL;
    • callbackUrl — ONLYOFFICE 文档通知文档编辑状态的 URL;
    • DocumentServerHost — 客户端需要回复 ONLYOFFICE 文档服务器的 URL(可以在设置页面中设置);
    • Key — 来自 SharePoint 的文件标识符;
    • FileName — 文档标题(名称);
    • CurrentUserId — 用户标识符;
    • CurrentUserLogin — 用户登录名。
  4. SharePoint 构建一个页面,填充所有这些值,以便客户端浏览器可以加载编辑器。

  5. 客户端浏览器向 ONLYOFFICE 文档的 JavaScript 库发出请求,并向 ONLYOFFICE 文档发送带有上述属性的 DocEditor 配置。

  6. 然后 ONLYOFFICE 文档从 SharePoint 下载文档,用户开始编辑。

  7. 当所有用户和客户端浏览器完成编辑时,他们关闭编辑窗口。

  8. 在 10 秒不活动后,ONLYOFFICE 文档向 callbackUrl 发送 POST 请求,通知 SharePoint ONLYOFFICE 解决方案客户端已完成文档编辑并关闭。

  9. SharePoint 下载新版本的文档,替换旧版本。

要了解更多常见问题及其解决方法,请访问我们的故障排除指南。

启用 JWT​

为了保护文档免受未经授权的访问,ONLYOFFICE 编辑器使用 JSON Web Token (JWT)。在初始化文档编辑器和内部 ONLYOFFICE 文档服务之间的命令交换期间,令牌会被添加到配置中。使用密钥对 JSON Web Token 进行签名,并在请求 ONLYOFFICE 文档时验证令牌。

从 ONLYOFFICE 文档 v7.2 开始,JWT 默认启用,并自动生成密钥。您需要在 ONLYOFFICE 文档配置文件中找到您的密钥,然后在连接器设置中指定相同的密钥。

步骤 1: 在 ONLYOFFICE 文档配置文件中找到您的密钥

  1. 使用任何可用的文本编辑器打开 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"
    }
    }
    }
    }
    }
  2. true 值在三个部分中指定,这意味着令牌验证已启用:

    • services.CoAuthoring.token.enable.browser
    • services.CoAuthoring.token.enable.request.inbox
    • services.CoAuthoring.token.enable.request.outbox
  3. 自动生成的密钥在三个部分中指定。您可以用自己的密钥替换默认值 — 它在三个部分中必须相同:

    • services.CoAuthoring.secret.inbox.string
    • services.CoAuthoring.secret.outbox.string
    • services.CoAuthoring.secret.session.string
  4. 如果您进行了更改,请保存并重新启动服务:

    DEB/RPM:

    systemctl restart ds-converter ds-docservice

    Docker:

    sudo docker exec <containerID> supervisorctl restart ds:converter ds:docservice

    Windows PowerShell:

    Restart-Service DsConverterSvc, DsDocServiceSvc

步骤 2: 在连接器设置中指定相同的密钥

在连接器设置中,在 ONLYOFFICE Docs secret key 字段中指定相同的密钥并保存设置。如果该字段留空,连接器会显示警告。

功能比较​

Office Online Server 和 ONLYOFFICE 文档​

下表列出了 Office Online Server 的主要功能与通过 WOPI 连接的 ONLYOFFICE 文档的对应关系。

功能Office Online ServerONLYOFFICE 文档(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 笔记本。

观看视频​