Filestash WOPI 编辑器插件实战：接入 Collabora 与 OnlyOffice 在线编辑 Word/Excel/PPT

Filestash WOPI 编辑器插件实战接入 Collabora 与 OnlyOffice 在线编辑 Word/Excel/PPT【免费下载链接】filestash:file_folder: Universal File Storage Client项目地址: https://gitcode.com/GitHub_Trending/fi/filestash本文基于 Filestash 仓库中的plg_editor_wopi插件完整讲解如何通过 WOPI 协议让 Filestash 接入 Collabora Online 或 OnlyOffice Document Server实现网页内直接编辑 Word、Excel、PowerPoint 等办公文档。读完你将掌握WOPI 服务的 Docker 启动方式、features.office.*全部配置项及其环境变量、docker-compose 一体化部署写法以及插件从“点击文件”到“文档回写存储后端”的完整请求链路与安全设计。插件定位Filestash 如何获得 Office 在线编辑能力WOPIWeb-based Open Platform Integration是微软 Office Online 推出的一套基于 REST 的文件协作协议Collabora Online 与 OnlyOffice Document Server 均实现了该协议的“Host宿主端对接接口”。Filestash 本身只是一个通用的文件存储前端Universal File Storage Client它不内置任何 Office 渲染引擎而是通过server/plugin/plg_editor_wopi这个 Go 插件扮演 WOPI Host 的角色插件启动后向 WOPI 服务如 Collabora的/hosting/discovery端点发现支持的文件类型与编辑地址浏览器打开文档时Filestash 返回一个内嵌 iframe 的 HTML 页面将文档以 WOPI 标准接口文件信息查询、读取、写回暴露给 Office 服务Office 服务完成编辑后通过PUT/POST contents接口把结果写回 Filestash 背后的任意存储后端本地磁盘、S3、NFS 等取决于所配置的 backend 插件。插件的注册入口在 index.go其init()中做了两件事在 Onload 钩子里读取配置并若启用注册 XDG Open 覆盖规则通过Hooks.Register.HttpEndpoint(WOPIRoutes)注册 HTTP 路由。快速开始启动一个 WOPI 服务插件自带的 README.md 给出了两条最小化的 Docker 启动命令分别对应两种主流实现# collabora: http://localhost:9980/hosting/discovery docker run --rm --networkhost -e extra_params--o:ssl.enablefalse collabora/code # onlyoffice: http://localhost/hosting/discovery docker run --networkhost -e WOPI_ENABLEDtrue --rm onlyoffice/documentserver两者差别值得注意服务默认发现地址关键环境变量说明Collabora Online (collabora/code)http://localhost:9980/hosting/discoveryextra_params--o:ssl.enablefalse关闭容器内 SSL便于用--networkhost直接以 HTTP 访问 9980 端口OnlyOffice (onlyoffice/documentserver)http://localhost/hosting/discoveryWOPI_ENABLEDtrue必须显式开启 WOPI否则只监听 80 端口且不暴露 WOPI 接口这两条命令使用--networkhost直接复用宿主机网络栈是最简单的本地验证方式——把office_server指向对应地址、在 Filestash 管理后台开启features.office.enable即可联调。配置项详解features.office 与三个环境变量插件的全部配置在 config.go 中以Config.Get(...).Schema(...)形式声明共 4 个字段且每个字段都支持环境变量覆盖适合容器化部署配置路径环境变量默认值含义features.office.enableOFFICE_URL设置后默认开启false总开关。描述文案为 Enable/Disable the wopi office suite and options to manage word, excel and powerpoint documents关闭时全部 WOPI 路由返回 404features.office.office_serverOFFICE_URLhttp://127.0.0.1:9980WOPI 服务端地址Location of your WOPI Office server即 discovery 请求所拼的基地址features.office.filestash_serverOFFICE_FILESTASH_URLhttp://app:8334从 Office 服务视角回看 Filestash 的地址。官方描述明确提示docker/k8s 等花式网络下必填单机部署保持默认即可features.office.rewrite_discovery_urlOFFICE_REWRITE_URL空将 discovery 返回的urlsrc的 host/scheme 重写为浏览器可达的地址。官方示例场景docker 中 Office 通过http://wopi_service:9980解析服务但该主机名浏览器不认识需重写为http://localhost:9980之类非 docker/k8s 部署保持为空从 config.go 源码可以看到环境变量只影响表单默认值f.Default因此在管理后台手动修改配置后环境变量不会再覆盖已保存的值而OFFICE_URL有一个特殊行为——只要设置就会把enable的默认值翻转为true这让容器编排里设置一个 URL 即自动启用成为可能。一体化部署仓库内置的 docker-compose 方案仓库的 docker-compose.yml 提供了一份与上述配置项严格对应的完整部署模板包含两个服务app: container_name: filestash image: machines/filestash:latest restart: always environment: - APPLICATION_URL - CANARYtrue - OFFICE_URLhttp://wopi_server:9980 - OFFICE_FILESTASH_URLhttp://app:8334 - OFFICE_REWRITE_URLhttp://127.0.0.1:9980 ports: - 8334:8334 volumes: - filestash:/app/data/state/ wopi_server: container_name: filestash_wopi image: collabora/code:24.04.10.2.1 restart: always environment: - extra_params--o:ssl.enablefalse - aliasgroup1https://.*:443 command: - /bin/bash - -c - | curl -o /usr/share/coolwsd/browser/dist/branding-desktop.css https://gist.githubusercontent.com/mickael-kerjean/bc1f57cd312cf04731d30185cc4e7ba2/raw/d706dcdf23c21441e5af289d871b33defc2770ea/destop.css /bin/su -s /bin/bash -c /start-collabora-online.sh cool user: root ports: - 9980:9980这份模板恰好演示了三个 URL 配置项在容器网络中的典型取值OFFICE_URLhttp://wopi_server:9980Filestash 容器用 compose 服务名wopi_server访问 CollaboraOFFICE_FILESTASH_URLhttp://app:8334Collabora 容器回拉文件时访问 Filestash 容器名appOFFICE_REWRITE_URLhttp://127.0.0.1:9980浏览器在宿主机上所以最终 iframe 地址要重写到宿主机的回环地址。此外aliasgroup1https://.*:443让 Collabora 信任任意 443 端口来源配合force_ssl场景命令中的curl ... branding-desktop.css是自定义品牌样式可按需删除。若选用 OnlyOffice则把镜像换成onlyoffice/documentserver、设置WOPI_ENABLEDtrue并按其端口约定调整三个 URL 即可。请求链路解析一从点击文件到打开编辑器哪些文件会走 WOPI 编辑器在 index.go 中WOPIOverrides注册到Hooks.Register.XDGOpen即打开文件的路由钩子见 plugin.go 的XDGOpen注册接口。其判断逻辑是一段 MIME 白名单if (mime application/word || mime application/msword || mime application/vnd.oasis.opendocument.text || mime application/vnd.oasis.opendocument.spreadsheet || mime application/excel || mime application/vnd.ms-powerpoint || ... ) { return [appframe, {endpoint: /api/wopi/iframe}]; }覆盖的类型包括 Word 97application/word、application/msword、PowerPointapplication/powerpoint、application/vnd.ms-powerpoint以及 ODF 的文本/表格/演示三类。命中后以appframe模式全屏 iframe加载/api/wopi/iframe端点。iframe 端点与 discovery 四步流程/api/wopi/iframe路由在 handler.go 中注册并套了middleware.SessionStartmiddleware.LoggedInOnly两层中间件——只有登录会话才能拿到编辑器页面。其处理函数IframeContentHandler调用wopiDiscovery后者完整实现了 WOPI 的发现流程源码中的四个步骤注释清晰fetch discoveryGETserver_url() /hosting/discovery非 200 即失败parse discovery将 XML 响应反序列化为WOPIDiscovery → WOPINetZone → WOPIApp → WOPIAction结构wopi-discovery下的net-zone/app/action节点取ext与urlsrc属性find URLsrc用文件扩展名去掉前导.在所有 net-zone/app/action 中匹配找不到则返回ErrNotFoundbuild the iframe URL拼接WOPISrc参数并在此处应用rewrite_url()——若配置了features.office.rewrite_discovery_url则把urlsrc的 scheme 与 host 整体替换为该值这正是容器内部主机名浏览器不可达场景的解法。返回的 HTML 是一个极简页面一个隐藏 iframe、一个以access_token为隐藏域并targetwopi_frame的 POST 表单、以及自动submit()的脚本。页面还内置了postMessage消息桥——当 Office 侧上报App_LoadingStatus状态为Initialized/Document_Loaded时宿主回复Host_PostmessageReady并淡入 iframe、移除加载骨架若收到Action_Load_Resp且带errorMsg则向父页面广播错误。WOPISrc 的结构与安全签名第 4 步拼出的WOPISrc是整个协议的安全核心其格式为{signed_id}::{base64url(path)}[::{share_id}]第一段id由 crypto.go 中的GenerateID生成——它把会话等参数做签名哈希故意跳过password、path、session、timestamp字段源码中这几个 case 为空实现从而既绑定会话身份、又不在 URL 中泄露明文路径第二段是文件的完整路径的 base64url 编码第三段可选仅当当前处于分享share上下文时追加ctx.Share.Id。Office 服务在后续每次文件 API 调用中都会原样带回这个WOPISrcFilestash 只需解码第二段即可还原路径第一段则用于验证请求确实出自当初那次发现握手。请求链路解析二WOPI 文件 API 的三个端点handler.go 中WOPIRoutes注册的三个端点正是 WOPI Host 规范要求的接口族路由方法处理函数作用/api/wopi/files/{path64}GETWOPIHandler_CheckFileInfo返回文件元信息 JSONBaseFileName、UserCanWrite由permissions.CanEdit(ctx)决定、IsAdminUser、IsAnonymousUser固定true即对外始终表现为匿名用户不泄露 Filestash 内部分权/api/wopi/files/{path64}/contentsGETWOPIHandler_GetFile通过ctx.Backend.Cat(fullpath)取流并io.Copy给 Office 服务/api/wopi/files/{path64}/contentsPOSTWOPIHandler_PutFile将 Office 回传的r.Body经ctx.Backend.Save(fullpath, ...)写回存储后端三个端点都包在WOPIExecute里其内部由wopiToCommonAPI中间件完成协议适配extractInfo解析{path64}中backendID::b64(path)::shareID结构base64 解码得到真实路径若带shareID则将其转为查询参数share否则把 URL 上的access_token改写为 Filestash 内部 API 使用的authorization参数并统一删除access_key之后由 PathBuilder 把路径与当前会话的 chroot 拼接并做前缀校验防止越权访问会话目录之外的路径再交给对应 handler。这条链路的工程含义是Office 服务不需要理解 Filestash 的会话、分享与鉴权模型它只需要遵守 WOPI 规范所有WOPI 语言 → Filestash 内部 API 语言的翻译都被收敛在wopiToCommonAPI一个中间件里。同时CheckFileInfo中UserCanWrite直接复用权限系统的CanEdit意味着分享链接的只读/可编辑属性会自然传导到 Office 编辑器——只读分享打开后 Collabora/OnlyOffice 界面即呈现只读状态。小结与适用边界plg_editor_wopi是一个典型的薄插件 外部重服务架构Filestash 侧代码量很小3 个 Go 文件复杂度全部交给 Collabora/OnlyOffice 容器承担。使用时需注意几点插件启用与否由features.office.enable决定未启用时/api/wopi/files/*直接 404而/api/wopi/iframe依赖登录会话三个 URL 配置项分别服务三个视角Filestash→Office、Office→Filestash、浏览器→Office单机部署只有第一个是必需的docker/k8s 部署通常需要三者齐备若文件类型不在 WOPI 服务的 discovery 清单内例如旧版.xls二进制格式第 3 步匹配不到urlsrc会返回ErrNotFound编辑器不会打开——这是预期行为而非故障仓库中另有一个平行的plg_editor_onlyoffice插件走的是 OnlyOffice 私有编辑 API 而非 WOPI 协议两者定位不同按需选择其一即可。对需要把任意存储后端S3、WebDAV、NFS……快速包装成类 Office 365 体验的团队来说这条OFFICE_URL OFFICE_FILESTASH_URL OFFICE_REWRITE_URL的三变量配置路径是当前仓库内最轻量的落地方案。【免费下载链接】filestash:file_folder: Universal File Storage Client项目地址: https://gitcode.com/GitHub_Trending/fi/filestash创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考