基于 Collabora 的 Web 端 Office 文档在线编辑集成指南

引言

在 Web 项目中嵌入 Office 文档编辑功能可以显著提升用户体验。Collabora Online 基于 LibreOffice 核心，提供开源解决方案，支持主流格式（DOCX/XLSX/PPTX 等）的实时协作编辑。以下指南详细介绍了如何部署和集成 Collabora，实现媲美 Office 365 的网页端编辑体验。

核心组件与原理

Collabora Online Development Edition (CODE) 服务端提供文档渲染与协作引擎（通过 Docker 部署），前端通过 <iframe> 嵌入编辑窗口。

WOPI 协议 定义 Web 应用与 Office 服务间的通信标准，关键操作包括文件加载、保存回调和权限控制。

部署 Collabora 服务端

环境要求 Linux 服务器（Ubuntu/CentOS）、Docker。

步骤 拉取 Collabora 镜像：

docker pull collabora/code

启动容器：

docker run -t -d -p 9980:9980 \
  -e "domain=<你的 Web 域名>" \
  --cap-add MKNOD \
  collabora/code

注意：默认使用 HTTPS，可通过配置关闭 SSL 协议。

前端集成步骤

场景 点击网页中的 DOCX 文件后打开编辑窗口。

代码示例 构建编辑按钮：

<button onclick="openCollabora('文档 URL')">编辑 DOCX</button>

动态生成 iframe：

function openCollabora(fileUrl) {
  const wopiSrc = `https://<Collabora 服务端 IP>:9980/loleaflet/dist/loleaflet.html?` +
    `WOPISrc=${encodeURIComponent(fileUrl)}` +
    `&access_token=${token}`;
  // 此处传用户 token，或简单点直接生成个时间戳也可以
  const iframe = document.createElement('iframe');
  iframe.src = wopiSrc;
  iframe.style = 'width:100%; height:80vh; border:none;';
  document.body.appendChild(iframe);
}

注意 iframe 不成功，可能是 Collabora 的 loolwsd.xml 配置的问题，找到 loolwsd.xml 中的 frame_ancestors 配置项，改为 <frame_ancestors>*</frame_ancestors> 即可。

参数解析

• WOPISrc：文档在你的服务上的访问地址（需实现 WOPI 协议端点）。
• fileUrl 示例：https://your-domain.com/wopi/files/{fileId}。
• 解释 fileId：后端会通过 fileId 对文件进行定位处理。

实现 WOPI 后端接口（Java 示例）

代码示例 检查文件权限：

@RestController
@RequestMapping("/wopi")
public class WOPIController {
    // 检查文件权限，向前端提供这个 api 接口就可以，保存接口会通过 wopi 协议自动调用
    @GetMapping("/files/{fileId}")
    public ResponseEntity<Map> checkFileInfo(@PathVariable String fileId) {
        return ResponseEntity.ok(Map.of(
            "BaseFileName", "document.docx",
            "OwnerId", "user123",
            "Size", 10240,
            "UserCanWrite", true // 控制编辑权限
        ));
    }

    // 查看
    @GetMapping("/files/{fileId}/contents")
    public ResponseEntity<UrlResource> getFile(@PathVariable String fileId) {
        // 根据 fileId 获取文件可下载的 url 地址
        String url = getFileUrl(fileId); // getFileUrl 方法自行实现
        UrlResource resource = new UrlResource(url);
        // 设置响应头
        HttpHeaders headers = new HttpHeaders();
        headers.add(HttpHeaders.CONTENT_DISPOSITION, "attachment; filename=\"" + tFileInfDO.getFileOldName() + "\"");
        return ResponseEntity.ok()
            .contentType(MediaType.parseMediaType("application/octet-stream"))
            .headers(headers)
            .body(resource);
    }

    // 保存文档
    @PostMapping("/files/{fileId}/contents")
    public void saveFile(@PathVariable String fileId, @RequestBody byte[] content) {
        // 将 content 写入你的存储系统
    }
}

高级功能：自定义工具栏按钮

代码示例 添加打印按钮：

const params = new URLSearchParams({
  'WOPISrc': fileUrl,
  'permission': 'edit',
  'custom_settings': JSON.stringify({
    'ToolbarCustomization': [{ "name": ".uno:Print", "type": "action" }]
  })
});
iframe.src = `https://collabora-host/loleaflet.html?${params}`;

支持动作列表 参考 Collabora 官方文档。

结语

通过 Collabora 和 WOPI 协议，可以在 Web 应用中嵌入全功能 Office 编辑器，显著提升生产力。下一步可以尝试集成 OnlyOffice 或实现版本历史功能。