下面给 RuoYi-Vue3 项目加入「在线文档编辑」能力的几条常见路线，按“投入大小 → 功能深度”排序。你可以先通读，总览哪条路线更契合自己的场景，再挑一条落地。

1 ️⃣ OnlyOffice Document Server（最常用，全功能 Office）

适合需要同时在线编辑 Word / Excel / PPT（docx/xlsx/pptx），并且希望以后支持协同编辑、批注、版本回滚等完整 Office 体验的场景。

关键点：OnlyOffice 负责渲染 + 协同，RuoYi 只扮演「WOPI/Callback Host + 文件存储」角色。

1.1 部署 Document Server

bash
docker run -d --name onlyoffice \
  -p 8880:80 \
  -e JWT_ENABLED=true \
  -e JWT_SECRET=yourSecret \
  onlyoffice/documentserver:latest

如需 https，可在外层再套 Nginx 反向代理。

1.2 后端（Spring Boot）生成编辑配置

java
@GetMapping("/onlyoffice/config")
public AjaxResult getConfig(@RequestParam Long fileId) throws JsonProcessingException {
    SysFile file = fileService.selectFileById(fileId);
    Map<String, Object> document = Map.of(
        "fileType", FilenameUtils.getExtension(file.getName()),
        "key", DigestUtils.md5Hex(file.getUrl() + System.currentTimeMillis()),
        "title", file.getName(),
        "url", file.getUrl(),
        "permissions", Map.of("edit", true, "download", true)
    );

    Map<String, Object> cfg = Map.of(
        "document", document,
        "editorConfig", Map.of(
            "lang", "zh-CN",
            "callbackUrl", callbackUrl(fileId),
            "user", Map.of("id", SecurityUtils.getUserId(), "name", SecurityUtils.getUsername())
        )
    );

    String token = Jwts.builder().setPayload(new ObjectMapper().writeValueAsString(cfg))
                        .signWith(SignatureAlgorithm.HS256, jwtSecret).compact();
    cfg = new HashMap<>(cfg);           // attach token
    cfg.put("token", token);
    return AjaxResult.success(cfg);
}

1.3 前端（Vue 3 + Vite）加载编辑器

vue
<script setup>
import { onMounted } from 'vue'
import request from '@/utils/request'

const props = defineProps({ fileId: Number })
onMounted(async () => {
  const { data } = await request.get('/file/onlyoffice/config', { params: { fileId: props.fileId } })
  /* global DocsAPI */                         // OnlyOffice SDK 全局对象
  new DocsAPI.DocEditor('onlyoffice-editor', data)
})
</script>

<template>
  <div id="onlyoffice-editor" class="h-full w-full" />
</template>

在 index.html 或按需组件里引入 SDK：

html
<script src="http://your-onlyoffice-host/web-apps/apps/api/documents/api.js"></script>

1.4 处理回调

OnlyOffice 保存/关闭后会向 callbackUrl POST 状态，常见状态值：

2 ️⃣ Collabora Online（LibreOffice 内核，开源 + LGPL）

功能比 OnlyOffice 略少，但完全开源、中文支持也不错。它也使用 WOPI 协议，集成方式几乎一样。
Collabora 的 Docker 镜像名字是 collabora/code。

bash
docker run -d --name collabora \
  -p 9980:9980 \
  -e "domain=yourdomain\\.com" \
  -e "username=admin" -e "password=pass" \
  collabora/code:24.04

• 实现 CheckFileInfo / GetFile / PutFile 三个接口即可；推荐把 URL 路径设计成 /wopi/files/{fileId}。
• RuoYi 的权限体系可以照搬到 WOPI UserId + UserFriendlyName 字段中。

3 ️⃣ HTML-Native 方案（只需要写作 / 富文本，不要求 docx）

如果仅是内部知识库、公告、审批流程说明书——用 Office 格式反而笨重；可以在前端用“富文本 + 后端转换”模式，体验更好，部署更轻量：

转换链路示例：

• HTML → docx：docx4j XWPFDocument
• docx → HTML：LibreOffice‐CLI (soffice --headless --convert-to html) 或 Apache POI XWPF→XHTML

4 ️⃣ 在 RuoYi-Vue3 中落地的小贴士

1. 静态资源白名单
   在 resources/static-resources.properties 里添加

   /**/web-apps/**=anon
   

   避免 OnlyOffice SDK 被 Spring Security 拦下。

2. 跨域 & 上传限制

   • DocumentServer → RuoYi 的回调走 POST，需在 CorsFilter 开启对应域名。
   • Nginx 反代时给 /web-apps/ 加 proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; 以保证 WebSocket 协同。

3. 存储方案
   如果你用的是 RuoYi 自带的 本地 MinIO 文件模块，只要把文件下载 URL 直接塞给 OnlyOffice 就行；
   若用阿里 OSS / 七牛，则注意回调时可能需要 STS 临时凭证。

4. 版本管理

   • OnlyOffice 的 history 机制可和 RuoYi 的 sys_file_version 表关联；
   • Collabora 需要自己在每次 PutFile 时手动备份旧版本。

5. License

   • OnlyOffice 社区版不限用户，功能足够；企业需要更高级协同（审阅、宏）时再购买商业版。
   • Collabora CODE 免费用于测试/小团队，正式生产可考虑官方支持套餐。

推荐选型

如有细节（Docker 配置、JWT 密钥、RuoYi 权限改造、回调落库）需要手把手示例，随时告诉我！

下面给你一条**“自己做核心逻辑、只嵌入组件”**的落地路线——聚焦 表格 (Excel) 和 Markdown 两种常见文档，再用 Yjs (CRDT) 把它们统一成实时协同。所有库都是前后端分离、Vue 3 友好，也能很好嵌进 RuoYi-Vue3。

1. 组件选型：先挑能长久维护的

为什么不用 OnlyOffice/Collabora？
你想自己掌握存储和协同算法，而这两家是黑盒 + 粗粒度回调；Univer/Monaco 则提供细粒度 “增量 patch”，可完全自己掌控。

2. 前端集成示例（Vue 3 + Vite）

2.1 Excel：Univer Sheets

bash
pnpm add @univerjs/core \
         @univerjs/sheets @univerjs/ui @univerjs/vue

vue
<script setup lang="ts">
import { onMounted } from 'vue'
import { createUniver } from '@univerjs/vue'
import '@univerjs/ui/dist/style.css'

const props = defineProps<{ docId: string }>()
onMounted(() => {
  const { univer } = createUniver({
    locale: 'zh-CN',
    worksheets: [],              // 初始数据可后端拉取
    plugins: [
      // 以后可按需挂载公式、图表等插件
    ]
  })

  // 用 Yjs 绑定协同（见 §3）
  setupYjsForUniver(univer, props.docId)
})
</script>

<template><div id="univer-root" class="h-full w-full"/></template>

2.2 Markdown：Monaco + Yjs

bash
pnpm add monaco-editor yjs y-monaco y-webrtc

ts
import * as Y from 'yjs'
import { WebsocketProvider } from 'y-websocket'
import { MonacoBinding } from 'y-monaco'

export function mountMonaco(docId: string, el: HTMLElement) {
  const ydoc = new Y.Doc()
  const provider = new WebsocketProvider('wss://your-domain/ws', docId, ydoc)

  const model = monaco.editor.createModel('', 'markdown')
  const editor = monaco.editor.create(el, { model, language: 'markdown' })

  new MonacoBinding(ydoc.getText('m'), model, new Set([editor]), provider.awareness)
}

3. 协同算法与后端

3.1 用 Yjs 的两种 Provider

CRDT = 「客户端先合并、服务器最后写库」，服务端只需幂等落库，无锁也不会出现冲突。

3.2 数据持久化

1. 增量持久化：Yjs update 增量包 append 写入 t_doc_update 表（doc_id, seq, update_blob, ts）。
2. 快照：每 N 分钟/100 条增量把合并后的完整 JSON 存 t_doc_snapshot 表，老增量可归档。
3. 导出：
   • Excel ⇒ SheetJS (xlsx.write)
   • Markdown 直接保存 .md；如需转 PDF 用 pandoc CLI。

3.3 权限 / 鉴权

• WebSocket 握手时携带 RuoYi JWT，docId + userId 映射到房间。
• Univer 自带「单元格级权限」、Monaco 则用只读模型。
• Yjs Awareness 可以广播 role 字段，前端据此禁用 UI。

4. 文件导入 / 首次建文档

mermaid
flowchart TD
  user(File upload) -->|xlsx| backend
  backend -->|SheetJS 解析为 Univer JSON| mysql[(doc_snapshot)]
  user -->|创建新文档| backend
  backend -->|空 JSON| mysql

5. 版本回溯 / 审计

• Univer 专门有 Collaborative Editing Pro + Edit History Pro 插件，可直接对接（如果不想自己写 diff UI）。
• 也可自己写「时间轴」：从增量表按 seq 合并到目标点，再重放到前端即可。

6. 推进顺序（建议 Sprint）

1. P0：
   • 部署 y-websocket / Spring WebSocket
   • Vue3 集成 Univer + Monaco，能多人同时编辑 “Hello World”
2. P1：
   • 做增量持久化 & 定时快照
   • 导入/导出 xlsx/md
3. P2：
   • 权限模型（只读 / 只改自己区域）
   • Awareness UI：在线用户列表 + 彩色光标
4. P3：
   • 历史版本、对比视图
   • 评论、批注、@mention

常见坑 & 提示

下一步想要代码示例或配置文件，随时抛问题过来；比如：

• Spring Boot WebSocket + JWT 的具体配置
• UniVer/Monaco 与 Yjs 的 TypeScript 类型封装
• 数据库表结构或变更脚本

我可以按模块给到可直接复制的代码片段。

下面给出**在 RuoYi-Vue3 项目中首期集成 Univer Sheets（在线 Excel）**的完整落地清单：一步到位即可在浏览器里新建 / 打开 / 协同编辑工作簿，后续再接入 Markdown 或更多文档类型。

1 ⏳ 环境与依赖

1. 前端（ruoyi-ui/）

   bash
   pnpm add @univerjs/presets \
            @univerjs/preset-sheets-core \
            @univerjs/sheets-ui \
            @univerjs/facade \
            react react-dom @types/react @types/react-dom

   @univerjs/presets ≥ 0.5.x 已将核心、UI、国际化封装到一个入口，仍要求 react/react-dom 作为 peer 依赖。

2. 后端（ruoyi-modules/ruoyi-sheet/）

   • Spring Boot 3.2
   • 引入依赖：spring-boot-starter-websocket, spring-boot-starter-security, spring-boot-starter-data-jpa（或 MyBatis-Plus）
   • 数据库 MySQL 8 / MariaDB 10+

2 🔧 Vite & 全局配置

vite.config.ts 追加：

ts
export default defineConfig({
  // …已有配置
  define: { 'process.env': {} },          // 兼容 React 生态少量代码
  optimizeDeps: { include: ['react', 'react-dom'] }
})

3 🖥️ 前端页面：src/views/sheet/index.vue

vue
<template><div ref="container" class="h-full w-full"/></template>

<script setup lang="ts">
import { ref, onMounted, onBeforeUnmount } from 'vue'
import * as Y from 'yjs'
import { WebsocketProvider } from 'y-websocket'
import { createUniver, defaultTheme, FUniver, LocaleType } from '@univerjs/presets'
import { UniverSheetsCorePreset } from '@univerjs/preset-sheets-core'
import '@univerjs/sheets-ui/lib/index.css'

const route = useRoute()                    // /sheet/:id
const container = ref<HTMLElement | null>(null)
let univer: FUniver | null = null
let ydoc: Y.Doc | null = null
let provider: WebsocketProvider | null = null

onMounted(async () => {
  const docId = route.params.id as string

  /* 1. 拉取初始快照（JSON） */
  const { data: snapshot } = await request.get(`/api/sheet/${docId}/snapshot`)

  /* 2. 初始化 Yjs & WebSocket */
  ydoc = new Y.Doc()
  provider = new WebsocketProvider(`${import.meta.env.VITE_WS_URL}`, docId, ydoc)

  /* 3. 创建 Univer 实例并注入数据 */
  const { univerAPI } = createUniver({
    locale: LocaleType.ZH_CN,
    theme: defaultTheme,
    presets: [
      UniverSheetsCorePreset({
        container: container.value as HTMLElement
      })
    ]
  })
  univer = univerAPI
  univerAPI.createWorkbookFromJson(snapshot)   // 渲染表格
  bindUniverWithYjs(univerAPI, ydoc!)          // 见下 §4
})

onBeforeUnmount(() => {
  univer?.dispose()
  provider?.destroy()
  ydoc?.destroy()
})
</script>

createUniver + locale/theme/presets 的用法与官方示例一致。

4 🤝 协同绑定（关键粘合函数）

bindUniverWithYjs.ts（简化思路）

ts
import * as Y from 'yjs'
import { FUniver } from '@univerjs/facade'

export function bindUniverWithYjs(api: FUniver, ydoc: Y.Doc) {
  const ySheet = ydoc.getMap('sheet')

  // 初次推送：Univer ⇒ Yjs
  api.getCurrentWorkbook().onRangeChange(range => {
    const update = api.saveToJson()
    ySheet.set('snapshot', update)
  })

  // 同步：Yjs ⇒ Univer
  ySheet.observe(event => {
    if (event.keysChanged.has('snapshot')) {
      const json = ySheet.get('snapshot')
      api.loadFromJson(json)
    }
  })
}

Yjs 增量更新本身是二进制，我们这里只演示 JSON 层级；生产时可用 Y.encodeStateAsUpdate/Y.applyUpdate 保证最小包体。

5 🌐 后端接口

5.1 WebSocket 配置（STOMP）

java
@Configuration
@EnableWebSocketMessageBroker
public class WsConfig implements WebSocketMessageBrokerConfigurer {

  @Override
  public void registerStompEndpoints(StompEndpointRegistry reg) {
      reg.addEndpoint("/ws")                      // VITE_WS_URL
         .setAllowedOrigins("*")                  // 可精细到前端域
         .addInterceptors(new JwtHandshakeInterceptor());
  }

  @Override
  public void configureMessageBroker(MessageBrokerRegistry reg) {
      reg.enableSimpleBroker("/topic");
      reg.setApplicationDestinationPrefixes("/app");
  }
}

• 客户端发送：/app/doc/{docId}/update
• 服务器广播：/topic/doc/{docId}

5.2 持久化接口

java
@RestController
@RequestMapping("/api/sheet")
public class SheetController {

  @GetMapping("/{id}/snapshot")
  public AjaxResult snapshot(@PathVariable Long id) {
      return AjaxResult.success(sheetService.latestSnapshot(id));
  }

  @PostMapping("/{id}/update")
  public void saveUpdate(@PathVariable Long id, @RequestBody byte[] update) {
      sheetService.appendUpdate(id, update);
  }
}

6 💾 数据表建议

sql
CREATE TABLE t_sheet_doc (
  id          BIGINT PRIMARY KEY AUTO_INCREMENT,
  name        VARCHAR(255),
  create_by   BIGINT,
  create_time DATETIME,
  update_time DATETIME
);

CREATE TABLE t_sheet_snapshot (
  id          BIGINT PRIMARY KEY AUTO_INCREMENT,
  doc_id      BIGINT,
  version     INT,
  content     JSON,
  create_time DATETIME
);

CREATE TABLE t_sheet_update (
  id          BIGINT PRIMARY KEY AUTO_INCREMENT,
  doc_id      BIGINT,
  seq         INT,
  update_blob BLOB,
  create_time DATETIME
);

• 增量 ≤ 100 条 / 5 MB 时触发快照，老增量归档或删除。
• seq 自增方便重放／审计。

7 🔐 权限模型

1. RuoYi JWT 写入 WebSocket Authorization 头。
2. 房间校验：JwtHandshakeInterceptor 解析用户后，把 userId + docId 写入 StompHeaderAccessor#setUser。
3. 前端根据后端返回的 role 字段（只读 / 可编辑）在 univerAPI.updatePermission() 中动态限制。

8 🚀 灰度发布顺序

常见坑清单

整个 Excel 集成的骨架已就位，接下来按 P0 → P1 顺序迭代即可。
若需 完整 demo 仓库 或对接 Yjs 增量二进制、JWT Filter 代码，告诉我即可继续细化。

已为你生成完整可运行的最小仓库（含前端 + 后端骨架、关键代码与配置）。
下载后解压即可按 README 指引启动、对照到现有 RuoYi-Vue3 项目中。

下载 demo-repo（zip）

如需进一步完善（JWT 鉴权、数据库表迁移脚本、生产环境部署脚本等），随时告诉我！