自建在线文档编辑服务：基于 Collabora CODE + Spring Boot + Vue 3 的完整实现

项目地址：https://gitee.com/hhs_3/online-view

前言

在办公协同场景中，在线文档编辑是刚需功能。市面上有腾讯文档、石墨文档等 SaaS 产品，但在企业内网或需要私有化部署的场景下，自建一套在线文档编辑系统就很有必要了。

经过一番调研和实践，我基于 Collabora CODE + Spring Boot + Vue 3 实现了一套完整的在线文档编辑服务，支持 Word、Excel、PPT 等多种格式的在线预览和编辑，并开源分享给大家。

项目特性

多格式支持：Word、Excel、PPT、PDF、ODF 等主流办公文档格式
多文件源：支持本地文件系统和 MinIO 对象存储，通过适配器模式轻松扩展
在线编辑：基于 Collabora CODE 的实时协作编辑能力
在线预览：独立的预览功能，只读查看文档
文件管理：上传、下载、删除、新建文件夹，完整的文件生命周期管理
目录导航：左侧目录树 + 右侧文件列表的经典布局
分页加载：无限滚动，大数据量下也能流畅使用

技术栈

组件	技术	版本
后端	Spring Boot	3.4.0
运行时	Java	17
前端	Vue 3 + Vite	3.4.x
UI组件库	Element Plus	2.6.x
文档引擎	Collabora CODE	24.04
对象存储	MinIO	Latest

系统架构

复制代码

┌─────────────────────────────────────────────────────────────────┐
│                          用户浏览器                              │
│                    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 方法	路径	说明
CheckFileInfo	GET	/wopi/files/{fileId}	获取文件元信息
GetFile	GET	/wopi/files/{fileId}/contents	获取文件内容
PutFile	POST	/wopi/files/{fileId}/contents	保存文件内容

适配器模式

系统通过适配器模式支持多种文件存储后端：

复制代码

FileSourceAdapter (接口)
        │
   ┌────┴────┐
   │         │
LocalAdapter  MinioAdapter
(本地磁盘)    (对象存储)

这样设计的好处是：

业务代码与存储实现解耦
新增存储类型只需实现接口
可在配置文件中切换存储类型

数据流向

用户编辑文档的完整流程：

复制代码

① 用户点击"编辑"
        ↓
② 前端请求后端获取编辑器 URL
        ↓
③ 前端 iframe 加载 Collabora
        ↓
④ Collabora 通过 WOPI 协议回调后端获取文件
        ↓
⑤ Collabora 渲染文档并展示
        ↓
⑥ 用户编辑文档
        ↓
⑦ Collabora 自动保存，回调后端 WOPI PutFile
        ↓
⑧ 后端写入存储，完成保存

部署踩坑记录

坑1：CentOS 7 YUM 源失效

CentOS 7 官方源已停止维护，需要替换为阿里云镜像源：

bash 复制代码

curl -o /etc/yum.repos.d/CentOS-Base.repo https://mirrors.aliyun.com/repo/Centos-7.repo
sed -i 's/$releasever/7/g' /etc/yum.repos.d/CentOS-Base.repo
yum clean all && yum makecache -y

坑2：Docker Compose 段错误

CentOS 7 与 Docker Compose v2 存在 glibc 兼容问题，解决方案是使用 DaoCloud 镜像下载二进制文件：

bash 复制代码

sudo curl -L https://get.daocloud.io/docker/compose/releases/download/v2.24.6/docker-compose-$(uname -s)-$(uname -m) -o /usr/local/bin/docker-compose
sudo chmod +x /usr/local/bin/docker-compose

坑3：Collabora 镜像拉取超时

国内直连 Docker Hub 超时，使用华为云镜像：

bash 复制代码

docker pull swr.cn-north-4.myhuaweicloud.com/ddn-k8s/docker.io/collabora/code:24.04.9.1.1
docker tag swr.cn-north-4.myhuaweicloud.com/ddn-k8s/docker.io/collabora/code:24.04.9.1.1 collabora/code:latest

坑4：iframe 嵌入 CSP 错误

最常见的问题，错误信息：

复制代码

Refused to frame 'http://192.168.51.10:9980/' because it violates
the following Content Security Policy directive: "frame-ancestors ..."

解决方案 ：配置 net.frame_ancestors 参数：

yaml 复制代码

environment:
  - "extra_params=--o:ssl.enable=false --o:ssl.termination=false --o:net.frame_ancestors=http://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

bash 复制代码

#启动
docker-compose up -d
# 查看容器实时日志（排错用）
docker-compose logs -f
# 重启容器
docker-compose restart
# 停止容器
docker-compose stop
# 关闭并删除容器（保留镜像）
docker-compose down
# 查看容器状态
docker-compose ps
# 进入容器内部
docker exec -it collabora_code bash
# 查看配置文件
docker exec -it collabora_code cat /etc/coolwsd/coolwsd.xml

2. 启动后端

bash 复制代码

cd backend
./mvnw clean package -DskipTests
java -jar target/online-view-1.0.0-SNAPSHOT.jar

3. 启动前端

bash 复制代码

cd frontend
npm install
npm run dev

4. 访问应用

浏览器访问 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！

参考资料：