项目地址https://gitee.com/hhs_3/online-view前言在办公协同场景中在线文档编辑是刚需功能。市面上有腾讯文档、石墨文档等 SaaS 产品但在企业内网或需要私有化部署的场景下自建一套在线文档编辑系统就很有必要了。经过一番调研和实践我基于Collabora CODESpring BootVue 3实现了一套完整的在线文档编辑服务支持 Word、Excel、PPT 等多种格式的在线预览和编辑并开源分享给大家。项目特性多格式支持Word、Excel、PPT、PDF、ODF 等主流办公文档格式多文件源支持本地文件系统和 MinIO 对象存储通过适配器模式轻松扩展在线编辑基于 Collabora CODE 的实时协作编辑能力在线预览独立的预览功能只读查看文档文件管理上传、下载、删除、新建文件夹完整的文件生命周期管理目录导航左侧目录树 右侧文件列表的经典布局分页加载无限滚动大数据量下也能流畅使用技术栈组件技术版本后端Spring Boot3.4.0运行时Java17前端Vue 3 Vite3.4.xUI组件库Element Plus2.6.x文档引擎Collabora CODE24.04对象存储MinIOLatest系统架构┌─────────────────────────────────────────────────────────────────┐ │ 用户浏览器 │ │ http://192.168.30.64:3000 │ └─────────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────┐ │ 前端 (Vue 3 Vite) │ │ 目录树 │ 文件列表 │ 在线编辑器 │ 上传/下载 │ └─────────────────────────────────────────────────────────────────┘ │ REST API ▼ ┌─────────────────────────────────────────────────────────────────┐ │ 后端 (Spring Boot 8080) │ │ FileController │ WopiController │ FileService │ CollaboraService│ │ │ │ │ ┌─────────────┴─────────────┐ │ │ ▼ ▼ │ │ LocalAdapter MinioAdapter │ └─────────────────────────────────────────────────────────────────┘ │ │ ▼ ▼ ┌─────────────┐ ┌─────────────┐ │ 本地磁盘 │ │ MinIO │ └─────────────┘ └─────────────┘ │ │ WOPI Protocol ▼ ┌─────────────────────────┐ │ Collabora CODE Server │ │ http://192.168.51.10:9980 │ │ 文档渲染 编辑 转换 │ └─────────────────────────┘核心设计WOPI 协议 适配器模式WOPI 协议WOPI (Web Application Open Platform Interface) 是微软定义的协议用于 Web 应用与 Office Online/Collabora 等文档编辑器集成。核心操作包括操作HTTP 方法路径说明CheckFileInfoGET/wopi/files/{fileId}获取文件元信息GetFileGET/wopi/files/{fileId}/contents获取文件内容PutFilePOST/wopi/files/{fileId}/contents保存文件内容适配器模式系统通过适配器模式支持多种文件存储后端FileSourceAdapter (接口) │ ┌────┴────┐ │ │ LocalAdapter MinioAdapter (本地磁盘) (对象存储)这样设计的好处是业务代码与存储实现解耦新增存储类型只需实现接口可在配置文件中切换存储类型数据流向用户编辑文档的完整流程① 用户点击编辑 ↓ ② 前端请求后端获取编辑器 URL ↓ ③ 前端 iframe 加载 Collabora ↓ ④ Collabora 通过 WOPI 协议回调后端获取文件 ↓ ⑤ Collabora 渲染文档并展示 ↓ ⑥ 用户编辑文档 ↓ ⑦ Collabora 自动保存回调后端 WOPI PutFile ↓ ⑧ 后端写入存储完成保存部署踩坑记录坑1CentOS 7 YUM 源失效CentOS 7 官方源已停止维护需要替换为阿里云镜像源curl-o/etc/yum.repos.d/CentOS-Base.repo https://mirrors.aliyun.com/repo/Centos-7.reposed-is/$releasever/7/g/etc/yum.repos.d/CentOS-Base.repo yum clean allyum makecache-y坑2Docker Compose 段错误CentOS 7 与 Docker Compose v2 存在 glibc 兼容问题解决方案是使用 DaoCloud 镜像下载二进制文件sudocurl-Lhttps://get.daocloud.io/docker/compose/releases/download/v2.24.6/docker-compose-$(uname-s)-$(uname-m)-o/usr/local/bin/docker-composesudochmodx /usr/local/bin/docker-compose坑3Collabora 镜像拉取超时国内直连 Docker Hub 超时使用华为云镜像dockerpull swr.cn-north-4.myhuaweicloud.com/ddn-k8s/docker.io/collabora/code:24.04.9.1.1dockertag swr.cn-north-4.myhuaweicloud.com/ddn-k8s/docker.io/collabora/code:24.04.9.1.1 collabora/code:latest坑4iframe 嵌入 CSP 错误最常见的问题错误信息Refused to frame http://192.168.51.10:9980/ because it violates the following Content Security Policy directive: frame-ancestors ...解决方案配置net.frame_ancestors参数environment:-extra_params--o:ssl.enablefalse --o:ssl.terminationfalse --o:net.frame_ancestorshttp://192.168.51.10:* http://192.168.30.64:* http://localhost:*注意必须使用--o:net.frame_ancestors不是--o:frame_ancestors必须包含协议前缀http://或https://多个地址用空格分隔坑5使用 localhost 访问前端如果通过localhost:3000访问前端会触发 CSP 问题。必须使用部署 IP 访问前端例如http://192.168.30.64:3000。快速开始1. 启动 Collabora CODE#启动docker-composeup-d# 查看容器实时日志排错用docker-composelogs-f# 重启容器docker-composerestart# 停止容器docker-composestop# 关闭并删除容器保留镜像docker-composedown# 查看容器状态docker-composeps# 进入容器内部dockerexec-itcollabora_codebash# 查看配置文件dockerexec-itcollabora_codecat/etc/coolwsd/coolwsd.xml2. 启动后端cdbackend ./mvnw clean package-DskipTestsjava-jartarget/online-view-1.0.0-SNAPSHOT.jar3. 启动前端cdfrontendnpminstallnpmrun dev4. 访问应用浏览器访问http://你的IP:3000注意不要用 localhost运行效果文件列表在线预览在线编辑重要说明Collabora CODE (Collabora Online Development Edition) 是开源版本官方明确声明不推荐用于生产环境部署。如需生产环境使用建议选择Collabora Online官方商业版提供企业级支持OnlyOffice完全开源方案永中Office/WPS国产化需求写在最后这个项目涵盖了前后端分离、WOPI 协议、适配器模式、Docker 部署等多个技术点适合作为学习参考。所有部署过程中遇到的坑都整理成了文档希望能帮到有同样需求的朋友。完整代码和详细部署文档请访问https://gitee.com/hhs_3/online-view欢迎 Star、Fork 和 PR参考资料Collabora Online 官方文档WOPI 协议规范MinIO 官方文档
自建在线文档编辑服务：基于 Collabora CODE + Spring Boot + Vue 3 的完整实现
项目地址https://gitee.com/hhs_3/online-view前言在办公协同场景中在线文档编辑是刚需功能。市面上有腾讯文档、石墨文档等 SaaS 产品但在企业内网或需要私有化部署的场景下自建一套在线文档编辑系统就很有必要了。经过一番调研和实践我基于Collabora CODESpring BootVue 3实现了一套完整的在线文档编辑服务支持 Word、Excel、PPT 等多种格式的在线预览和编辑并开源分享给大家。项目特性多格式支持Word、Excel、PPT、PDF、ODF 等主流办公文档格式多文件源支持本地文件系统和 MinIO 对象存储通过适配器模式轻松扩展在线编辑基于 Collabora CODE 的实时协作编辑能力在线预览独立的预览功能只读查看文档文件管理上传、下载、删除、新建文件夹完整的文件生命周期管理目录导航左侧目录树 右侧文件列表的经典布局分页加载无限滚动大数据量下也能流畅使用技术栈组件技术版本后端Spring Boot3.4.0运行时Java17前端Vue 3 Vite3.4.xUI组件库Element Plus2.6.x文档引擎Collabora CODE24.04对象存储MinIOLatest系统架构┌─────────────────────────────────────────────────────────────────┐ │ 用户浏览器 │ │ http://192.168.30.64:3000 │ └─────────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────┐ │ 前端 (Vue 3 Vite) │ │ 目录树 │ 文件列表 │ 在线编辑器 │ 上传/下载 │ └─────────────────────────────────────────────────────────────────┘ │ REST API ▼ ┌─────────────────────────────────────────────────────────────────┐ │ 后端 (Spring Boot 8080) │ │ FileController │ WopiController │ FileService │ CollaboraService│ │ │ │ │ ┌─────────────┴─────────────┐ │ │ ▼ ▼ │ │ LocalAdapter MinioAdapter │ └─────────────────────────────────────────────────────────────────┘ │ │ ▼ ▼ ┌─────────────┐ ┌─────────────┐ │ 本地磁盘 │ │ MinIO │ └─────────────┘ └─────────────┘ │ │ WOPI Protocol ▼ ┌─────────────────────────┐ │ Collabora CODE Server │ │ http://192.168.51.10:9980 │ │ 文档渲染 编辑 转换 │ └─────────────────────────┘核心设计WOPI 协议 适配器模式WOPI 协议WOPI (Web Application Open Platform Interface) 是微软定义的协议用于 Web 应用与 Office Online/Collabora 等文档编辑器集成。核心操作包括操作HTTP 方法路径说明CheckFileInfoGET/wopi/files/{fileId}获取文件元信息GetFileGET/wopi/files/{fileId}/contents获取文件内容PutFilePOST/wopi/files/{fileId}/contents保存文件内容适配器模式系统通过适配器模式支持多种文件存储后端FileSourceAdapter (接口) │ ┌────┴────┐ │ │ LocalAdapter MinioAdapter (本地磁盘) (对象存储)这样设计的好处是业务代码与存储实现解耦新增存储类型只需实现接口可在配置文件中切换存储类型数据流向用户编辑文档的完整流程① 用户点击编辑 ↓ ② 前端请求后端获取编辑器 URL ↓ ③ 前端 iframe 加载 Collabora ↓ ④ Collabora 通过 WOPI 协议回调后端获取文件 ↓ ⑤ Collabora 渲染文档并展示 ↓ ⑥ 用户编辑文档 ↓ ⑦ Collabora 自动保存回调后端 WOPI PutFile ↓ ⑧ 后端写入存储完成保存部署踩坑记录坑1CentOS 7 YUM 源失效CentOS 7 官方源已停止维护需要替换为阿里云镜像源curl-o/etc/yum.repos.d/CentOS-Base.repo https://mirrors.aliyun.com/repo/Centos-7.reposed-is/$releasever/7/g/etc/yum.repos.d/CentOS-Base.repo yum clean allyum makecache-y坑2Docker Compose 段错误CentOS 7 与 Docker Compose v2 存在 glibc 兼容问题解决方案是使用 DaoCloud 镜像下载二进制文件sudocurl-Lhttps://get.daocloud.io/docker/compose/releases/download/v2.24.6/docker-compose-$(uname-s)-$(uname-m)-o/usr/local/bin/docker-composesudochmodx /usr/local/bin/docker-compose坑3Collabora 镜像拉取超时国内直连 Docker Hub 超时使用华为云镜像dockerpull swr.cn-north-4.myhuaweicloud.com/ddn-k8s/docker.io/collabora/code:24.04.9.1.1dockertag swr.cn-north-4.myhuaweicloud.com/ddn-k8s/docker.io/collabora/code:24.04.9.1.1 collabora/code:latest坑4iframe 嵌入 CSP 错误最常见的问题错误信息Refused to frame http://192.168.51.10:9980/ because it violates the following Content Security Policy directive: frame-ancestors ...解决方案配置net.frame_ancestors参数environment:-extra_params--o:ssl.enablefalse --o:ssl.terminationfalse --o:net.frame_ancestorshttp://192.168.51.10:* http://192.168.30.64:* http://localhost:*注意必须使用--o:net.frame_ancestors不是--o:frame_ancestors必须包含协议前缀http://或https://多个地址用空格分隔坑5使用 localhost 访问前端如果通过localhost:3000访问前端会触发 CSP 问题。必须使用部署 IP 访问前端例如http://192.168.30.64:3000。快速开始1. 启动 Collabora CODE#启动docker-composeup-d# 查看容器实时日志排错用docker-composelogs-f# 重启容器docker-composerestart# 停止容器docker-composestop# 关闭并删除容器保留镜像docker-composedown# 查看容器状态docker-composeps# 进入容器内部dockerexec-itcollabora_codebash# 查看配置文件dockerexec-itcollabora_codecat/etc/coolwsd/coolwsd.xml2. 启动后端cdbackend ./mvnw clean package-DskipTestsjava-jartarget/online-view-1.0.0-SNAPSHOT.jar3. 启动前端cdfrontendnpminstallnpmrun dev4. 访问应用浏览器访问http://你的IP:3000注意不要用 localhost运行效果文件列表在线预览在线编辑重要说明Collabora CODE (Collabora Online Development Edition) 是开源版本官方明确声明不推荐用于生产环境部署。如需生产环境使用建议选择Collabora Online官方商业版提供企业级支持OnlyOffice完全开源方案永中Office/WPS国产化需求写在最后这个项目涵盖了前后端分离、WOPI 协议、适配器模式、Docker 部署等多个技术点适合作为学习参考。所有部署过程中遇到的坑都整理成了文档希望能帮到有同样需求的朋友。完整代码和详细部署文档请访问https://gitee.com/hhs_3/online-view欢迎 Star、Fork 和 PR参考资料Collabora Online 官方文档WOPI 协议规范MinIO 官方文档
