📑 Office 在线编辑

平台集成 OnlyOffice 免费社区版作为文档编辑、预览服务，支持 Word、Excel、PPT 在线编辑。

@onlyoffice/document-editor-vue 等 npm 包只负责在前端加载编辑器。在线协同、文档转换和保存仍需要运行中的 ONLYOFFICE Docs 文档服务；该服务可以自行部署或使用供应商云服务，不能仅靠 npm 安装前端组件替代。Docker 是一种部署方式，并非协议要求。

若改用供应商云服务，还需按该实例要求完成 JWT 配置签名、文件回源和保存回调适配；当前吾码配置不能只替换 OnlyOfficeApiBase 就视为云服务验收通过。

文件柜中的 Office 文档

在 文件柜 的私有桶或公有桶中，双击 doc/docx/xls/xlsx/ppt/pptx/csv 文件，或点击其「预览」，会进入在线编辑页。PDF 继续使用文件柜的浏览器内置预览。打开和保存均要求已登录的文件柜平台管理员，以及当前租户的权威文件柜菜单；页面参数本身不授予编辑权限。

版本与存储

文件柜默认开启手动版本管理。首次打开显示 v1.0.0；每次点击「保存为新版本」生成 v1.0.1、v1.0.2 等版本，历史版本可在编辑页切换查看。历史版本只读，最新版本可继续编辑。原文件对象键保持不变，因此文件柜列表、原下载链接和引用该键的业务记录始终指向最新内容。历史快照与版本索引存放在当前租户的私有对象存储 .microi-office-history 前缀，由平台按原文件键生成，不由浏览器指定；文件柜列表不显示该内部目录。单文件重命名或移动会迁移历史索引和快照，物理删除会清理历史；文件柜的「移入回收站」只做软删除，恢复后历史仍可用。整文件夹移动或重命名仍按现有对象存储目录行为执行，不会批量迁移子文件的 Office 版本；跨平台文件同步也只同步所选原文件，不能当成版本历史迁移。切换 OSS、MinIO、S3 前须迁移该前缀与原文件对象，并按目标存储重新验收历史预览。

权限与保存

保存时后端重新核验当前文件柜菜单、管理员身份、桶类型和原对象，校验 OnlyOffice 导出域名及文件内容，并用共享 Redis 租约串行保存同一文件。若版本已变化，页面会要求刷新后再编辑。浏览器关闭前未点击「保存为新版本」的内容不构成吾码历史版本；协同编辑的实时会话仍由 ONLYOFFICE Docs 负责。私有文件及历史快照通过带当前对象上下文的临时审计代理地址供文档服务读取，文档服务必须能够访问平台公网 ApiBase。

当前文件柜功能复用既有 OnlyOfficeApiBase 配置，不新增编辑器选择开关。Univer 的开源前端 SDK 可用于嵌入式表格和定制界面，但要完整覆盖现有 Office 文件协同、Office 格式导入导出和历史版本，还需要独立的服务端集成及相应授权；不能将 npm 安装开源包视为等价替换。

🐳 通过 Docker 编排部署 OnlyOffice

💡 提示

如遇 onlyoffice/documentserver 拉取超时，可使用吾码公开镜像：registry.cn-hangzhou.aliyuncs.com/microios/onlyoffice-documentserver:202509

展开查看 JSON 配置（22 行）

json

version: '3.8'
services:
  microi-onlyoffice:
    image: onlyoffice/documentserver
    container_name: microi-onlyoffice
    logging:
      driver: "json-file"
      options:
        max-size: "10m"
        max-file: "10"
    restart: always
    tty: true
    stdin_open: true
    ports:
      - "1020:80"
    environment:
      - JWT_ENABLED=false
    volumes:
      - /microi/onlyoffice/DocumentServer/logs:/var/log/onlyoffice
      - /microi/onlyoffice/DocumentServer/data:/var/www/onlyoffice/Data
      - /microi/onlyoffice/DocumentServer/lib:/var/lib/onlyoffice
      - /microi/onlyoffice/DocumentServer/db:/var/lib/postgresql

⚙️ 设置反向代理与平台配置

假设反向代理地址为：https://net.itdos.net:1021
在平台 系统设置 中设置 OnlyOfficeApiBase 字段值为 https://net.itdos.net:1021（若无此字段则先创建）

💡 效果

配置完成后，平台中所有 PPT、Excel、Word 格式的附件将默认通过 OnlyOffice 在线打开。

🔗 文件下载正常，但 OnlyOffice 提示“下载失败”

浏览器能下载文件，不代表 OnlyOffice 文档服务器也能访问同一个地址。OnlyOffice 会在服务器端再次请求文件；如果平台生成的文档地址是 localhost、127.0.0.1 或仅内网可达地址，浏览器下载可能正常，但远程文档服务器会提示“下载失败”。

请同时确认：

生产环境的 ApiBase 应配置为平台真实 API 地址；接口引擎响应文件通过 /online-office?fileUrl=... 预览时，本地 localhost 地址会由平台后端安全读取并缓存到公网 FileServer，不会直接交给远程 OnlyOffice。
系统设置的 FileServer 是可访问的公有文件域名。
私有文件仍由 /api/HDFS/OpenPrivateFile 审计代理提供临时地址，不应把对象存储真实签名地址直接暴露给 OnlyOffice。
在线预览获取私有文件地址时传 ForOfficePreview:true；平台会优先用系统设置的公网 ApiBase 生成审计代理地址。
文件地址的 HEAD 探测也返回 200 和正确的 Content-Type/Content-Length；OnlyOffice 可能先用 HEAD 检查文件，只有 GET 可下载而 HEAD=405 仍会导致预览一直加载。

var result = V8.Method.GetPrivateFileUrl({
  OsClient: V8.OsClient,
  FilePathName: '/itdos/file/20260721/example.xlsx',
  Limit: true,
  ForOfficePreview: true
});

🌐 匿名只读在线预览公有文件或接口引擎响应文件

/online-office 支持不登录访问，但匿名访问有固定安全边界：

公有存储模式只允许当前 OsClient 目录下的 filePathName；私有文件必须登录。
接口模式只允许当前平台正式 ApiBase，或由同端口本地后端读取的 loopback /apiengine/... 响应文件地址，并且 URL 必须显式携带当前 OsClient；不接受任意第三方 URL。
匿名访问始终为只读，即使 URL 传 canEdit=1 也不会获得编辑权限。
匿名页面自动隐藏左侧系统菜单、顶部导航和页签；登录用户按原有系统布局打开。
不要把合同、身份证、工资单等敏感文件上传到公有桶后通过匿名链接发送。

公有文件示例：

text

http://localhost:1988/?OsClient=iTdos#/online-office?fileName=example.xlsx&filePathName=%2Fitdos%2Foffice-demo%2Fexample.xlsx&isPrivate=0&canEdit=0

接口引擎响应文件示例：

text

http://localhost:1988/?OsClient=iTdos#/online-office?fileUrl=https%3A%2F%2Flocalhost%3A7266%2Fapiengine%2Fexport-excel-advanced-demo-preview--OsClient--iTdos--&fileName=%E5%90%BE%E7%A0%81V8%E9%AB%98%E7%BA%A7Excel%E5%A4%9ASheet%E7%A4%BA%E4%BE%8B.xlsx&fileType=xlsx&canEdit=0

fileUrl 必须整体执行 URL 编码。页面先调用匿名安全中转接口，由当前平台后端读取该接口引擎的文件响应，再按 URL 和文件名的 SHA-256 写入当前租户 office-preview 公有对象目录（Redis 共享缓存 10 分钟）；OnlyOffice 最终读取公网 FileServer 静态地址。因此开发环境可以直接传同端口 localhost/127.0.0.1 接口地址，不要求远程 OnlyOffice 能访问开发机。中转不是通用代理：只允许当前平台、当前 OsClient 的单层 /apiengine/{key}，不跟随重定向，并限制 50MB 和 Office/PDF/CSV 文件头。

主要参数：

参数	说明
`fileName`	带扩展名的文件名，OnlyOffice 据此识别 Word/Excel/PPT 类型
`fileUrl`	匿名响应文件接口地址；仅允许当前平台 `/apiengine/...`，必须显式包含当前 `OsClient`
`fileType`	当 `fileUrl` 路径没有扩展名时指定 `xlsx/docx/pptx/pdf`；Excel 接口未传时默认 `xlsx`
`filePathName`	当前租户公有存储相对路径；匿名访问不能传其它租户路径或任意外部 URL
`isPrivate`	`0` 为公有文件；`1` 必须登录后获取临时审计代理地址
`canEdit`	是否申请编辑；只有登录态有效，匿名场景强制为 `0`
`hdfs`	文件存储类型，如 `Aliyun`

🧪 高级 Excel 下载与在线预览示例

官方接口引擎提供两个匿名文件响应地址：

export-excel-advanced-demo：直接下载 5 Sheet .xlsx，包含截图同款申请单、主子表分组、复杂合并表头、标准表格和边框样式库。
export-excel-advanced-demo-preview：同样直接响应并下载 .xlsx，专门作为可传给 /online-office?fileUrl=... 的示例接口地址；必须同时开启【允许匿名】和【响应文件】。

text

/apiengine/export-excel-advanced-demo--OsClient--iTdos--
/apiengine/export-excel-advanced-demo-preview--OsClient--iTdos--

直接访问第二个接口会下载 Excel。需要在线查看时，把完整接口地址 URL 编码后传给 /online-office 的 fileUrl，页面会透明完成公有预览缓存，再把整个前端链接发送给客户；客户无需登录，打开后强制只读且不显示系统菜单和顶部页签。

📑 Office 在线编辑 ​

文件柜中的 Office 文档 ​

版本与存储 ​

权限与保存 ​

🐳 通过 Docker 编排部署 OnlyOffice ​

⚙️ 设置反向代理与平台配置 ​

🔗 文件下载正常，但 OnlyOffice 提示“下载失败” ​

🌐 匿名只读在线预览公有文件或接口引擎响应文件 ​

🧪 高级 Excel 下载与在线预览示例 ​

📑 Office 在线编辑

文件柜中的 Office 文档

版本与存储

权限与保存

🐳 通过 Docker 编排部署 OnlyOffice

⚙️ 设置反向代理与平台配置

🔗 文件下载正常，但 OnlyOffice 提示“下载失败”

🌐 匿名只读在线预览公有文件或接口引擎响应文件

🧪 高级 Excel 下载与在线预览示例