做在线文档编辑的这几年被问得最多的一类问题就是OnlyOffice 配置 MinIO 文件存储到底怎么配。这个问题的坑在于很多人以为它是一步配置实际上它至少牵扯三层MinIO 对象存储、你的业务后端常见是 Spring Boot、以及 OnlyOffice Document Server 自身。三者之间的网络可达性、URL 签名、回调幂等、缓存 key 复用任何一个环节出问题表现都是文档打不开或者改完了还是旧内容而且报错信息往往含糊得让人抓狂。这篇就把我自己搭过的这套链路完整拆一遍从 MinIO 的桶策略和预签名 URL到 Java 侧的上传封装再到 OnlyOffice 的编辑器配置对象、回调状态码、以及保存结果写回 MinIO 的全过程。适合已经能跑通 OnlyOffice 基础 Demo、准备把文件主存储换成对象存储的开发者也适合正在做信创环境麒麟 V10、欧拉部署的同学参考。下面按先分清层次、再动手、最后排错的顺序来。1. 先把两个存储分清楚不然方向从一开始就是错的1.1 Document Server 默认根本不存你的文档很多人第一次装完 OnlyOffice Document Server跑去容器里找文档发现/var/www/onlyoffice/Data/cache/下面有一堆乱七八糟的目录和.bin文件就以为这就是文件存储。其实不是。Document Server 本质是一个编辑服务它的角色更像渲染器 协同引擎而不是网盘。完整的流程是这样的你的业务系统生成一个编辑器配置对象里面带着document.url文档下载地址和callbackUrl回调地址用户在浏览器里打开编辑器页面Document Server 拿着document.url去主动下载这份文档下载到本地缓存目录做格式转换比如 docx 转成内部的 bin 格式开始编辑和协同用户关闭编辑器后Document Server 通过callbackUrlPOST一个 JSON 给你的业务系统里面的url字段是它提供的编辑后文件下载地址你的业务系统去 GET 这个url把新版本文件存回自己的存储这里就是 MinIO然后返回{error:0}。看明白这个链路就清楚了Document Server 只是中转真正的文件存储是你的业务系统那一侧。它的 cache 目录是临时工作区理论上可以随时清空当然实际别乱清正在编辑的会话会直接崩。1.2 配置 MinIO 文件存储其实是两件不同的事这也是为什么同一个标题下不同人的答案驴唇不对马嘴。我把它拆成两个层次层次存什么由谁控制典型需求业务主存储层文档的正式版本、历史版本、附件你的业务后端Spring Boot 等替换本地磁盘/NAS做成对象存储统一管理Document Server 缓存层编辑中的中间态、转换产物、协同数据Document Server 自身配置缓存目录占空间太大、多副本部署需要共享缓存绝大多数说OnlyOffice 配置 MinIO的人真正要的是第一层。第二层属于进阶选项Document Server 从 7.x 之后确实支持把缓存放到 S3 兼容存储上这个我放在第 5 节讲因为它的字段名在不同版本之间会变改之前必须对着自己版本的default.json核对。提示如果你只是想文件别存在服务器本地磁盘上那 90% 的工作量在业务后端跟 Document Server 的配置文件一点关系都没有。先把这个认知摆正能省掉至少两天瞎折腾。1.3 为什么我不建议一上来就把缓存也搬到 MinIO缓存层外置的收益是多副本 Document Server 可以共享缓存代价是引入了一个强依赖MinIO 一抖动全员文档打不开。我见过一次事故就是缓存桶被误删了策略导致 Document Server 所有请求 403表现是编辑器页面白屏、只有一行 The document could not be saved。排查了两小时才发现不是 OnlyOffice 的问题。所以我的一般建议是先把业务主存储切到 MinIO跑稳定一到两个月确认 MinIO 的可用性、监控、备份都到位了再考虑缓存外置。两件事分阶段做出问题了才知道该往哪个方向查。2. MinIO 侧的准备桶、凭证和那个最容易被忽略的预签名有效期2.1 单机模式够不够什么时候必须上分布式开发测试环境用单机单盘就行一条命令的事。但要注意 MinIO 有个特点单机单盘模式下没有纠删码保护也没有版本管理之外的数据冗余磁盘坏了数据就没了。分布式模式至少要 4 个节点或者单节点 4 盘用纠删码把数据切成 N 份。这里有个特别容易踩的坑分布式集群的盘数一旦确定就不能随随便便加盘扩容。MinIO 的纠删码集合erasure set是固定的加盘需要新建 Server Pool 做横向扩展而不是往现有集群里插两块盘。我见过有人按普通 NAS 的思路把盘插满结果集群起不来数据还差点丢。一个最小可用的单机启动命令Linux# 数据目录和配置目录 mkdir -p /data/minio /etc/minio export MINIO_ROOT_USERminioadmin export MINIO_ROOT_PASSWORD换成你自己的强密码 # 前台启动先验证能不能跑通 minio server /data/minio --address :9000 --console-address :9001生产环境别用nohup糊弄老老实实写 systemd unit让 systemd 管进程和日志。MINIO_ROOT_USER这个变量在旧版本里叫MINIO_ACCESS_KEY新版改了名字照着旧教程配会发现凭证不生效这是个高频问题。2.2 桶策略别为了省事关掉鉴权热词里有个minio ?max-keys 我的意思是不想让匿名用户访问这个这个问题非常有代表性。当你在浏览器里访问 MinIO 的桶地址看到类似?max-keys1000的请求返回AccessDenied通常意味着有匿名调用方在尝试列举对象。这不是 bug这是鉴权在正常工作。正确的做法是桶策略保持私有用带签名的临时 URL给外部访问。运维命令如下# 用 mc 客户端连接 mc alias set local http://127.0.0.1:9000 minioadmin 你的密码 # 建桶 mc mb local/office-docs # 明确关闭匿名访问默认就是关闭的但显式设置一遍防止有人手滑开过 mc anonymous set none local/office-docs # 查看当前策略确认是 private mc anonymous get local/office-docs我强烈反对的做法是给整个桶配download匿名策略然后靠URL 没人知道来当安全措施。桶名 对象名一旦泄漏所有文档就全公开了。文件名的可枚举性比你想的高得多。2.3 预签名 URL 的有效期短了会崩长了有风险MinIO 的预签名 URL 最长有效期是7 天超过会直接报错。但实际该设多长是个需要权衡的事设太短比如 5 分钟用户打开编辑器去泡了杯咖啡回来点保存Document Server 中途要重新拉取文档时 URL 已经过期报 403文档直接打不开设太长比如 7 天一旦 URL 泄漏攻击窗口就是 7 天。我实测下来比较稳的区间是2 到 24 小时。但更推荐的做法是别直接用预签名 URL而是在业务侧暴露一个稳定的下载接口比如/api/doc/{docId}/raw?tokenxxxtoken 是自己签的短期凭证。这样做的好处URL 形态稳定不会因为换 MinIO 端点而失效可以做访问审计谁在什么时候拉取了哪份文档不受 S3 预签名最大 7 天的限制顺便解决了下面这个最阴间的坑。注意预签名 URL 是跟 Host 绑定的。如果你生成 URL 时用的 endpoint 是http://127.0.0.1:9000而 Document Server 用的是http://192.168.1.10:9000去访问签名校验必然失败报SignatureDoesNotMatch。这个坑我踩过排查的时候一脸懵因为两边访问桶都正常就是预签名 URL 403。解决办法就是生成 URL 时用的 endpoint 必须和实际访问方用的地址完全一致。2.4 麒麟 V10 / 欧拉上的几个安装细节信创环境的问题集中在三点。第一是架构先uname -m确认是x86_64还是aarch64下错包会报 cannot execute binary file。第二是 systemd 单元里的用户权限MinIO 建议用独立的minio-user跑数据目录用chown -R minio-user:minio-user /data/minio否则启动时报权限拒绝。第三是防火墙除了 9000API和 9001控制台如果走 Nginx 反代还要放行 80/443。欧拉和麒麟上都遇到过 SELinux 拦截的情况表现为进程起来了但访问 403 或连接被重置。临时验证可以用getenforce看状态确认是 SELinux 之后再决定是加策略还是关掉。生产环境我不建议直接setenforce 0那是掩耳盗铃。3. Spring Boot 侧把文档主存储真正切到 MinIO3.1 依赖与配置项的写法MinIO 官方 Java SDK 的坐标是io.minio:minio当前稳定线在 8.5.x。加进pom.xml之后配置文件里最少要有这几项minio: endpoint: http://192.168.1.10:9000 access-key: minioadmin secret-key: 你的密码 bucket: office-docs # 关键生成给 OnlyOffice 用的 URL 时用哪个地址 public-endpoint: http://192.168.1.10:9000 # 预签名有效期单位秒 presign-expiry: 43200这里endpoint和public-endpoint分开是有原因的如果 MinIO 部署在内网、外面通过 Nginx 域名访问那么后端 SDK 走内网地址更快而给 Document Server 用的 URL 必须是它能访问到的那个地址。我在本地开发时经常两个设成一样但生产环境一定要分开配。初始化客户端的代码很直接Configuration public class MinioConfig { Bean public MinioClient minioClient(MinioProperties props) { return MinioClient.builder() .endpoint(props.getEndpoint()) .credentials(props.getAccessKey(), props.getSecretKey()) .build(); } }如果你的 MinIO 走的是 IP 端口这种路径风格访问不需要额外配置useVirtualHosting但如果你用了域名并且是按虚拟主机风格bucket.domain.com访问那就得注意 SDK 这边的行为差异否则签名会算错。3.2 上传、下载、删除的最小封装真正用起来核心就三个方法。上传的时候有两点必须注意public String upload(String objectName, InputStream in, long size, String contentType) { minioClient.putObject(PutObjectArgs.builder() .bucket(props.getBucket()) .object(objectName) .stream(in, size, -1) // partSize 传 -1让 SDK 自己算 .contentType(contentType) // 必须显式指定否则默认是 octet-stream .build()); return objectName; }第一个点是contentType。MinIO 默认给的是application/octet-streamDocument Server 下载时如果拿不到正确的 MIME有些场景下会拒绝解析。docx 是application/vnd.openxmlformats-officedocument.wordprocessingml.documentxlsx 和 pptx 各有各的长串。我一般写个扩展名到 MIME 的映射表比Files.probeContentType靠谱因为后者依赖操作系统的 mime.types 库在不同发行版上结果可能不一样。第二个点是stream方法的第二个参数size不能传 -1。传了 -1 或者一个偏小的值S3 分片上传时最后一个分片的大小会算错表现是文件上传成功但内容末尾缺一截。这个 bug 极难发现因为接口返回是成功的只有下载下来对比才知道。3.3 中文文件名和下载响应头对象名objectName我建议不要用原始文件名而是用业务ID/版本号/时间戳这种形式原始文件名单独存在数据库里。原因有三个中文和特殊字符在 URL 里需要编码处理不好就是 400同名文件会覆盖对象名里带斜杠可以做前缀查询方便按业务维度清理。如果确实需要让用户下载时保留原文件名用Content-Disposition响应头String encoded URLEncoder.encode(fileName, StandardCharsets.UTF_8).replace(, %20); response.setHeader(Content-Disposition, attachment; filename*UTF-8 encoded);用filename*UTF-8这个语法别用filename否则中文在某些浏览器上会变成乱码。3.4 大文件与断点续传超过 100MB 的文件putObject一次性传会占用大量内存。SDK 在partSize传 -1 时会自动分片但分片的最小单位是 5MBS3 协议硬性要求。如果要自己控制分片实现断点续传流程是createMultipartUpload→ 多次uploadPart→completeMultipartUpload中间把uploadId和已完成的分片号持久化断网重连后从没传完的分片继续。这里有个细节分片上传如果中途放弃必须调abortMultipartUpload否则这些分片会一直占着存储空间而且mc ls里看不到只有mc admin相关的命令才能查出来。我见过一个桶不知不觉涨了几百 GB全是没清理的残留分片。4. OnlyOffice 编辑器配置与回调让编辑结果回到 MinIO4.1 编辑器配置对象的构造这是整个链路里最关键的一段代码。一个能用的配置大致长这样MapString, Object config new HashMap(); MapString, Object document new HashMap(); document.put(fileType, ext); // docx / xlsx / pptx document.put(key, buildKey(docId, version, fileHash)); document.put(title, fileName); document.put(url, downloadUrl); // Document Server 要能访问到 MapString, Object editorConfig new HashMap(); editorConfig.put(callbackUrl, callbackUrl); editorConfig.put(lang, zh-CN); editorConfig.put(user, Map.of(id, userId, name, userName)); MapString, Object customization new HashMap(); customization.put(forcesave, true); // 允许强制保存 customization.put(autosave, true); editorConfig.put(customization, customization); config.put(document, document); config.put(editorConfig, editorConfig); config.put(type, desktop);lang这个参数控制界面语言zh-CN是简体中文。如果要支持多语言就把用户的语言偏好传进来Document Server 内置了相当多的语言包常见语种基本都有。4.2 key 的生成规则坑最多的地方document.key是 Document Server 用来标识这是哪一份文档的哪个版本的字符串。它的规则是同一个 key 代表同一份内容。这句话听起来很废话但坑全在它身上。典型事故你用docId当 key。用户打开文档 A编辑保存成功内容写回了 MinIO。用户再打开文档 A发现还是旧内容。原因是 Document Server 看到 key 没变直接用了本地缓存压根没去下载新的。正确的做法是让 key 跟着内容变化public String buildKey(Long docId, int version, String fileMd5) { // 文件内容哈希是最可靠的但每次算 md5 有开销 // 折中方案文件ID 版本号 return docId _v version; }每次保存成功版本号加一key 就变了Document Server 就会重新拉取。key 的长度限制是128 个字符以内只能用数字、字母和少数字符别往里塞中文或者横杠之外的花哨符号。注意key 变化太频繁也有副作用。如果用户在编辑过程中你的业务逻辑改了版本号协同时的用户会被踢出去重新加载。所以版本号只在保存成功后递增不要在编辑开始时递增。4.3 回调接口要处理的状态码Document Server 回调过来的 JSON 里status字段决定你该干什么status含义业务侧该做什么1用户正在编辑记录一下什么都不做2所有用户已关闭文档可以保存下载新文件并写回 MinIO3保存出错记日志告警4文档已关闭但没有修改什么都不做6强制保存forcesave 触发下载并写回但不要递增版本号7强制保存时出错记日志告警这里 status 6 的处理要特别小心。如果每次强制保存都递增版本号key 就变了用户下次打开会以为是新文档历史版本列表会被污染。我的做法是status 6 时把内容写成一个草稿版本覆盖当前版本但不递增主版本号。回调必须返回{error: 0}否则 Document Server 会认为保存失败并重试。返回非 0 或者超时都会导致重试风暴。4.4 写回 MinIO 的那几行代码注意一点回调 JSON 里的url是Document Server 自己提供的临时下载地址不是你的 MinIO 地址。所以写回的逻辑是从 DS 拉新文件 → 传到 MinIOPostMapping(/callback) public MapString, Object callback(RequestBody MapString, Object body) { int status (int) body.get(status); if (status ! 2 status ! 6) { return Map.of(error, 0); } String docId (String) body.get(key); String newFileUrl (String) body.get(url); // 从 Document Server 拉取编辑后的文件 byte[] data restTemplate.getForObject(newFileUrl, byte[].class); // 写回 MinIO对象名带版本号 String objectName docId / nextVersion .docx; minioClient.putObject(PutObjectArgs.builder() .bucket(bucket).object(objectName) .stream(new ByteArrayInputStream(data), data.length, -1) .contentType(DOCX_MIME) .build()); return Map.of(error, 0); }必须做幂等。Document Server 在回调超时、返回非 0、或者网络抖动时会重复推送同一个回调。如果不做幂等你会生成一堆重复版本。我一般用key 文件内容 md5做去重算一下新文件的 md5跟当前版本比对一样就直接返回成功不写盘。4.5 用户说编辑完没保存到底发生了什么这是客服反馈里最高频的一句话。实际排查下来八成不是没保存而是保存了但用户看到的是缓存。三个方向依次查status 2 的回调有没有到你的接口看业务日志和 Nginx access log回调到了MinIO 里新对象有没有生成mc ls看一眼对象大小和修改时间新对象有key 有没有变没变就是第 4.2 节说的问题。还有一种少见情况是用户直接关了浏览器标签页而不是点编辑器里的关闭按钮。这时候 status 2 不会立即触发得等一段时间或者用户主动点保存。forcesave: true就是缓解这个问题的它会按 Document Server 配置的间隔自动保存一次。但间隔是在 DS 的配置文件里定的不是前端参数。5. 把 Document Server 的缓存也搬到 S3 兼容存储上5.1 什么情况下值得折腾这一层只有两个场景我认为值得第一Document Server 做了多副本部署比如 K8s 里跑三个 Pod 做负载均衡缓存必须共享第二服务器本地磁盘特别小缓存经常把盘撑满。单副本部署的话把缓存外置带来的收益远小于风险。缓存目录读写非常频繁对象存储的延迟比本地磁盘高一个数量级编辑大文档时的体验会明显变差。5.2 配置改法与版本差异Document Server 的配置在/etc/onlyoffice/documentserver/local.jsonDocker 部署的话是容器内对应路径。缓存外置的配置段落挂在services.CoAuthoring下涉及存储类型、endpoint、凭证、桶名、以及useVirtualHosting这几个关键项。具体字段名在不同版本之间有变化。我踩过一次坑照着网上某篇博客改了结果 DS 启动直接失败因为那个字段在 7.4 之后改名了。正确姿势是先打开同目录下的default.json搜索storage或者s3看当前版本实际支持哪些字段再往local.json里覆盖。local.json是增量覆盖文件只写你要改的节点即可不用复制整个配置。改之前必须备份cp /etc/onlyoffice/documentserver/local.json \ /etc/onlyoffice/documentserver/local.json.bak.$(date %F)改完重启服务Docker 是supervisorctl restart all或者直接重启容器。5.3 验证缓存真的落到 S3 了改完之后不能只看服务起没起来。验证方法是打开一份文档在编辑状态下用mc ls看那个缓存桶里有没有新对象产生。如果对象是空的或者没有说明配置没生效DS 还在用本地目录。还有一个隐蔽的点缓存桶和业务文档桶一定要分开。如果共用一个桶你在用mc清理业务数据的时候很可能顺手把 DS 的缓存清了正在编辑的用户会瞬间崩掉。桶名建议带明确前缀比如onlyoffice-cache一眼能看出用途。6. 联调排查从打不开文档到保存后内容没变6.1 第一步永远是确认网络可达性Document Server 访问不到你给的document.url是最常见的原因占了我遇到问题的一半以上。排查顺序进 Document Server 容器里 curl 一下那个 URL看返回是什么。这一步直接决定后面往哪查如果是Connection refused说明地址不对。最常见的是用了127.0.0.1或者localhost但 DS 在容器里那个地址指向的是容器自己如果是 403大概率是预签名 URL 的 Host 不匹配回看 2.3 节如果是 404检查对象名是不是被 URL 编码处理错了中文对象名尤其容易出问题。Docker 部署的情况下访问宿主机服务的正确写法是宿主机的真实内网 IP或者用host.docker.internalLinux 上需要额外加--add-host参数。本地开发时用 MinIO 的容器名做 DNS同一 Docker 网络内也可以。6.2 回调没触发或者超时如果日志里完全看不到回调请求先检查callbackUrl是不是 DS 能访问到的地址。同样的道理别写localhost。如果回调到了但一直超时看你的处理逻辑耗时。Document Server 对回调有超时限制大概在几十秒量级。如果你的实现是下载文件 → 写 MinIO → 解析内容入库 → 生成缩略图一条龙同步做完大文件很容易超时。正确的做法是回调里只做下载和写盘的同步操作拿到文件后立刻返回{error:0}其余的重活丢到消息队列异步做。这个改动我做过之后超时告警直接降了一大截。6.3 保存成功了打开还是旧内容这是 4.2 节的 key 问题前面讲过了不重复。补充一个排查技巧Document Server 的日志里会打印每个请求的 key你可以拿它跟数据库里的版本号对一下。日志位置在/var/log/onlyoffice/documentserver/converter/out.log和docservice/out.log后者更常看。6.4 Nginx 反代 MinIO 的几个必配项如果你在 MinIO 前面挂了 Nginx有三个配置不加会出问题location / { proxy_pass http://127.0.0.1:9000; proxy_set_header Host $http_host; # 关键透传原始 Host否则预签名 URL 校验失败 client_max_body_size 2048m; # 大文件上传必须放开 proxy_request_buffering off; # 上传大文件时不缓冲整个请求体 proxy_read_timeout 300s; proxy_send_timeout 300s; }proxy_set_header Host $http_host这行是最容易漏的。默认 Nginx 会把 Host 改成proxy_pass里的地址导致 S3 签名算法算出来的 Host 跟你生成 URL 时用的不一致直接 403。7. 我实际跑下来固化的参数清单把上面这些内容压成一张表配置的时候可以直接对照配置项推荐值说明MinIO 预签名有效期43200 秒12 小时太短会导致编辑中途 403太长有泄漏风险document.key 长度小于 128 字符超长会被 DS 截断导致 key 冲突forcesavetrue防止用户关标签页丢内容回调响应时间3 秒以内超时会触发重试风暴分片上传 partSize不小于 5MBS3 协议硬性限制缓存桶与业务桶必须分开避免清理时误伤Nginx client_max_body_size2048m按你最大的文档类型调整最后分享一个我自己用的小技巧在开发环境我会把 Document Server 的document.url指向一个带时间戳的调试接口每次请求都记一条日志包含请求方 IP、User-Agent、URL、响应码。调试期把这几行日志打开上面 6.1 节那四种情况基本一眼就能定位比进容器里 curl 快得多。上线前记得把这个调试接口关掉或者加个开关别让它成为信息泄漏的口子。
OnlyOffice 对接 MinIO：Spring Boot 文档存储与回调
做在线文档编辑的这几年被问得最多的一类问题就是OnlyOffice 配置 MinIO 文件存储到底怎么配。这个问题的坑在于很多人以为它是一步配置实际上它至少牵扯三层MinIO 对象存储、你的业务后端常见是 Spring Boot、以及 OnlyOffice Document Server 自身。三者之间的网络可达性、URL 签名、回调幂等、缓存 key 复用任何一个环节出问题表现都是文档打不开或者改完了还是旧内容而且报错信息往往含糊得让人抓狂。这篇就把我自己搭过的这套链路完整拆一遍从 MinIO 的桶策略和预签名 URL到 Java 侧的上传封装再到 OnlyOffice 的编辑器配置对象、回调状态码、以及保存结果写回 MinIO 的全过程。适合已经能跑通 OnlyOffice 基础 Demo、准备把文件主存储换成对象存储的开发者也适合正在做信创环境麒麟 V10、欧拉部署的同学参考。下面按先分清层次、再动手、最后排错的顺序来。1. 先把两个存储分清楚不然方向从一开始就是错的1.1 Document Server 默认根本不存你的文档很多人第一次装完 OnlyOffice Document Server跑去容器里找文档发现/var/www/onlyoffice/Data/cache/下面有一堆乱七八糟的目录和.bin文件就以为这就是文件存储。其实不是。Document Server 本质是一个编辑服务它的角色更像渲染器 协同引擎而不是网盘。完整的流程是这样的你的业务系统生成一个编辑器配置对象里面带着document.url文档下载地址和callbackUrl回调地址用户在浏览器里打开编辑器页面Document Server 拿着document.url去主动下载这份文档下载到本地缓存目录做格式转换比如 docx 转成内部的 bin 格式开始编辑和协同用户关闭编辑器后Document Server 通过callbackUrlPOST一个 JSON 给你的业务系统里面的url字段是它提供的编辑后文件下载地址你的业务系统去 GET 这个url把新版本文件存回自己的存储这里就是 MinIO然后返回{error:0}。看明白这个链路就清楚了Document Server 只是中转真正的文件存储是你的业务系统那一侧。它的 cache 目录是临时工作区理论上可以随时清空当然实际别乱清正在编辑的会话会直接崩。1.2 配置 MinIO 文件存储其实是两件不同的事这也是为什么同一个标题下不同人的答案驴唇不对马嘴。我把它拆成两个层次层次存什么由谁控制典型需求业务主存储层文档的正式版本、历史版本、附件你的业务后端Spring Boot 等替换本地磁盘/NAS做成对象存储统一管理Document Server 缓存层编辑中的中间态、转换产物、协同数据Document Server 自身配置缓存目录占空间太大、多副本部署需要共享缓存绝大多数说OnlyOffice 配置 MinIO的人真正要的是第一层。第二层属于进阶选项Document Server 从 7.x 之后确实支持把缓存放到 S3 兼容存储上这个我放在第 5 节讲因为它的字段名在不同版本之间会变改之前必须对着自己版本的default.json核对。提示如果你只是想文件别存在服务器本地磁盘上那 90% 的工作量在业务后端跟 Document Server 的配置文件一点关系都没有。先把这个认知摆正能省掉至少两天瞎折腾。1.3 为什么我不建议一上来就把缓存也搬到 MinIO缓存层外置的收益是多副本 Document Server 可以共享缓存代价是引入了一个强依赖MinIO 一抖动全员文档打不开。我见过一次事故就是缓存桶被误删了策略导致 Document Server 所有请求 403表现是编辑器页面白屏、只有一行 The document could not be saved。排查了两小时才发现不是 OnlyOffice 的问题。所以我的一般建议是先把业务主存储切到 MinIO跑稳定一到两个月确认 MinIO 的可用性、监控、备份都到位了再考虑缓存外置。两件事分阶段做出问题了才知道该往哪个方向查。2. MinIO 侧的准备桶、凭证和那个最容易被忽略的预签名有效期2.1 单机模式够不够什么时候必须上分布式开发测试环境用单机单盘就行一条命令的事。但要注意 MinIO 有个特点单机单盘模式下没有纠删码保护也没有版本管理之外的数据冗余磁盘坏了数据就没了。分布式模式至少要 4 个节点或者单节点 4 盘用纠删码把数据切成 N 份。这里有个特别容易踩的坑分布式集群的盘数一旦确定就不能随随便便加盘扩容。MinIO 的纠删码集合erasure set是固定的加盘需要新建 Server Pool 做横向扩展而不是往现有集群里插两块盘。我见过有人按普通 NAS 的思路把盘插满结果集群起不来数据还差点丢。一个最小可用的单机启动命令Linux# 数据目录和配置目录 mkdir -p /data/minio /etc/minio export MINIO_ROOT_USERminioadmin export MINIO_ROOT_PASSWORD换成你自己的强密码 # 前台启动先验证能不能跑通 minio server /data/minio --address :9000 --console-address :9001生产环境别用nohup糊弄老老实实写 systemd unit让 systemd 管进程和日志。MINIO_ROOT_USER这个变量在旧版本里叫MINIO_ACCESS_KEY新版改了名字照着旧教程配会发现凭证不生效这是个高频问题。2.2 桶策略别为了省事关掉鉴权热词里有个minio ?max-keys 我的意思是不想让匿名用户访问这个这个问题非常有代表性。当你在浏览器里访问 MinIO 的桶地址看到类似?max-keys1000的请求返回AccessDenied通常意味着有匿名调用方在尝试列举对象。这不是 bug这是鉴权在正常工作。正确的做法是桶策略保持私有用带签名的临时 URL给外部访问。运维命令如下# 用 mc 客户端连接 mc alias set local http://127.0.0.1:9000 minioadmin 你的密码 # 建桶 mc mb local/office-docs # 明确关闭匿名访问默认就是关闭的但显式设置一遍防止有人手滑开过 mc anonymous set none local/office-docs # 查看当前策略确认是 private mc anonymous get local/office-docs我强烈反对的做法是给整个桶配download匿名策略然后靠URL 没人知道来当安全措施。桶名 对象名一旦泄漏所有文档就全公开了。文件名的可枚举性比你想的高得多。2.3 预签名 URL 的有效期短了会崩长了有风险MinIO 的预签名 URL 最长有效期是7 天超过会直接报错。但实际该设多长是个需要权衡的事设太短比如 5 分钟用户打开编辑器去泡了杯咖啡回来点保存Document Server 中途要重新拉取文档时 URL 已经过期报 403文档直接打不开设太长比如 7 天一旦 URL 泄漏攻击窗口就是 7 天。我实测下来比较稳的区间是2 到 24 小时。但更推荐的做法是别直接用预签名 URL而是在业务侧暴露一个稳定的下载接口比如/api/doc/{docId}/raw?tokenxxxtoken 是自己签的短期凭证。这样做的好处URL 形态稳定不会因为换 MinIO 端点而失效可以做访问审计谁在什么时候拉取了哪份文档不受 S3 预签名最大 7 天的限制顺便解决了下面这个最阴间的坑。注意预签名 URL 是跟 Host 绑定的。如果你生成 URL 时用的 endpoint 是http://127.0.0.1:9000而 Document Server 用的是http://192.168.1.10:9000去访问签名校验必然失败报SignatureDoesNotMatch。这个坑我踩过排查的时候一脸懵因为两边访问桶都正常就是预签名 URL 403。解决办法就是生成 URL 时用的 endpoint 必须和实际访问方用的地址完全一致。2.4 麒麟 V10 / 欧拉上的几个安装细节信创环境的问题集中在三点。第一是架构先uname -m确认是x86_64还是aarch64下错包会报 cannot execute binary file。第二是 systemd 单元里的用户权限MinIO 建议用独立的minio-user跑数据目录用chown -R minio-user:minio-user /data/minio否则启动时报权限拒绝。第三是防火墙除了 9000API和 9001控制台如果走 Nginx 反代还要放行 80/443。欧拉和麒麟上都遇到过 SELinux 拦截的情况表现为进程起来了但访问 403 或连接被重置。临时验证可以用getenforce看状态确认是 SELinux 之后再决定是加策略还是关掉。生产环境我不建议直接setenforce 0那是掩耳盗铃。3. Spring Boot 侧把文档主存储真正切到 MinIO3.1 依赖与配置项的写法MinIO 官方 Java SDK 的坐标是io.minio:minio当前稳定线在 8.5.x。加进pom.xml之后配置文件里最少要有这几项minio: endpoint: http://192.168.1.10:9000 access-key: minioadmin secret-key: 你的密码 bucket: office-docs # 关键生成给 OnlyOffice 用的 URL 时用哪个地址 public-endpoint: http://192.168.1.10:9000 # 预签名有效期单位秒 presign-expiry: 43200这里endpoint和public-endpoint分开是有原因的如果 MinIO 部署在内网、外面通过 Nginx 域名访问那么后端 SDK 走内网地址更快而给 Document Server 用的 URL 必须是它能访问到的那个地址。我在本地开发时经常两个设成一样但生产环境一定要分开配。初始化客户端的代码很直接Configuration public class MinioConfig { Bean public MinioClient minioClient(MinioProperties props) { return MinioClient.builder() .endpoint(props.getEndpoint()) .credentials(props.getAccessKey(), props.getSecretKey()) .build(); } }如果你的 MinIO 走的是 IP 端口这种路径风格访问不需要额外配置useVirtualHosting但如果你用了域名并且是按虚拟主机风格bucket.domain.com访问那就得注意 SDK 这边的行为差异否则签名会算错。3.2 上传、下载、删除的最小封装真正用起来核心就三个方法。上传的时候有两点必须注意public String upload(String objectName, InputStream in, long size, String contentType) { minioClient.putObject(PutObjectArgs.builder() .bucket(props.getBucket()) .object(objectName) .stream(in, size, -1) // partSize 传 -1让 SDK 自己算 .contentType(contentType) // 必须显式指定否则默认是 octet-stream .build()); return objectName; }第一个点是contentType。MinIO 默认给的是application/octet-streamDocument Server 下载时如果拿不到正确的 MIME有些场景下会拒绝解析。docx 是application/vnd.openxmlformats-officedocument.wordprocessingml.documentxlsx 和 pptx 各有各的长串。我一般写个扩展名到 MIME 的映射表比Files.probeContentType靠谱因为后者依赖操作系统的 mime.types 库在不同发行版上结果可能不一样。第二个点是stream方法的第二个参数size不能传 -1。传了 -1 或者一个偏小的值S3 分片上传时最后一个分片的大小会算错表现是文件上传成功但内容末尾缺一截。这个 bug 极难发现因为接口返回是成功的只有下载下来对比才知道。3.3 中文文件名和下载响应头对象名objectName我建议不要用原始文件名而是用业务ID/版本号/时间戳这种形式原始文件名单独存在数据库里。原因有三个中文和特殊字符在 URL 里需要编码处理不好就是 400同名文件会覆盖对象名里带斜杠可以做前缀查询方便按业务维度清理。如果确实需要让用户下载时保留原文件名用Content-Disposition响应头String encoded URLEncoder.encode(fileName, StandardCharsets.UTF_8).replace(, %20); response.setHeader(Content-Disposition, attachment; filename*UTF-8 encoded);用filename*UTF-8这个语法别用filename否则中文在某些浏览器上会变成乱码。3.4 大文件与断点续传超过 100MB 的文件putObject一次性传会占用大量内存。SDK 在partSize传 -1 时会自动分片但分片的最小单位是 5MBS3 协议硬性要求。如果要自己控制分片实现断点续传流程是createMultipartUpload→ 多次uploadPart→completeMultipartUpload中间把uploadId和已完成的分片号持久化断网重连后从没传完的分片继续。这里有个细节分片上传如果中途放弃必须调abortMultipartUpload否则这些分片会一直占着存储空间而且mc ls里看不到只有mc admin相关的命令才能查出来。我见过一个桶不知不觉涨了几百 GB全是没清理的残留分片。4. OnlyOffice 编辑器配置与回调让编辑结果回到 MinIO4.1 编辑器配置对象的构造这是整个链路里最关键的一段代码。一个能用的配置大致长这样MapString, Object config new HashMap(); MapString, Object document new HashMap(); document.put(fileType, ext); // docx / xlsx / pptx document.put(key, buildKey(docId, version, fileHash)); document.put(title, fileName); document.put(url, downloadUrl); // Document Server 要能访问到 MapString, Object editorConfig new HashMap(); editorConfig.put(callbackUrl, callbackUrl); editorConfig.put(lang, zh-CN); editorConfig.put(user, Map.of(id, userId, name, userName)); MapString, Object customization new HashMap(); customization.put(forcesave, true); // 允许强制保存 customization.put(autosave, true); editorConfig.put(customization, customization); config.put(document, document); config.put(editorConfig, editorConfig); config.put(type, desktop);lang这个参数控制界面语言zh-CN是简体中文。如果要支持多语言就把用户的语言偏好传进来Document Server 内置了相当多的语言包常见语种基本都有。4.2 key 的生成规则坑最多的地方document.key是 Document Server 用来标识这是哪一份文档的哪个版本的字符串。它的规则是同一个 key 代表同一份内容。这句话听起来很废话但坑全在它身上。典型事故你用docId当 key。用户打开文档 A编辑保存成功内容写回了 MinIO。用户再打开文档 A发现还是旧内容。原因是 Document Server 看到 key 没变直接用了本地缓存压根没去下载新的。正确的做法是让 key 跟着内容变化public String buildKey(Long docId, int version, String fileMd5) { // 文件内容哈希是最可靠的但每次算 md5 有开销 // 折中方案文件ID 版本号 return docId _v version; }每次保存成功版本号加一key 就变了Document Server 就会重新拉取。key 的长度限制是128 个字符以内只能用数字、字母和少数字符别往里塞中文或者横杠之外的花哨符号。注意key 变化太频繁也有副作用。如果用户在编辑过程中你的业务逻辑改了版本号协同时的用户会被踢出去重新加载。所以版本号只在保存成功后递增不要在编辑开始时递增。4.3 回调接口要处理的状态码Document Server 回调过来的 JSON 里status字段决定你该干什么status含义业务侧该做什么1用户正在编辑记录一下什么都不做2所有用户已关闭文档可以保存下载新文件并写回 MinIO3保存出错记日志告警4文档已关闭但没有修改什么都不做6强制保存forcesave 触发下载并写回但不要递增版本号7强制保存时出错记日志告警这里 status 6 的处理要特别小心。如果每次强制保存都递增版本号key 就变了用户下次打开会以为是新文档历史版本列表会被污染。我的做法是status 6 时把内容写成一个草稿版本覆盖当前版本但不递增主版本号。回调必须返回{error: 0}否则 Document Server 会认为保存失败并重试。返回非 0 或者超时都会导致重试风暴。4.4 写回 MinIO 的那几行代码注意一点回调 JSON 里的url是Document Server 自己提供的临时下载地址不是你的 MinIO 地址。所以写回的逻辑是从 DS 拉新文件 → 传到 MinIOPostMapping(/callback) public MapString, Object callback(RequestBody MapString, Object body) { int status (int) body.get(status); if (status ! 2 status ! 6) { return Map.of(error, 0); } String docId (String) body.get(key); String newFileUrl (String) body.get(url); // 从 Document Server 拉取编辑后的文件 byte[] data restTemplate.getForObject(newFileUrl, byte[].class); // 写回 MinIO对象名带版本号 String objectName docId / nextVersion .docx; minioClient.putObject(PutObjectArgs.builder() .bucket(bucket).object(objectName) .stream(new ByteArrayInputStream(data), data.length, -1) .contentType(DOCX_MIME) .build()); return Map.of(error, 0); }必须做幂等。Document Server 在回调超时、返回非 0、或者网络抖动时会重复推送同一个回调。如果不做幂等你会生成一堆重复版本。我一般用key 文件内容 md5做去重算一下新文件的 md5跟当前版本比对一样就直接返回成功不写盘。4.5 用户说编辑完没保存到底发生了什么这是客服反馈里最高频的一句话。实际排查下来八成不是没保存而是保存了但用户看到的是缓存。三个方向依次查status 2 的回调有没有到你的接口看业务日志和 Nginx access log回调到了MinIO 里新对象有没有生成mc ls看一眼对象大小和修改时间新对象有key 有没有变没变就是第 4.2 节说的问题。还有一种少见情况是用户直接关了浏览器标签页而不是点编辑器里的关闭按钮。这时候 status 2 不会立即触发得等一段时间或者用户主动点保存。forcesave: true就是缓解这个问题的它会按 Document Server 配置的间隔自动保存一次。但间隔是在 DS 的配置文件里定的不是前端参数。5. 把 Document Server 的缓存也搬到 S3 兼容存储上5.1 什么情况下值得折腾这一层只有两个场景我认为值得第一Document Server 做了多副本部署比如 K8s 里跑三个 Pod 做负载均衡缓存必须共享第二服务器本地磁盘特别小缓存经常把盘撑满。单副本部署的话把缓存外置带来的收益远小于风险。缓存目录读写非常频繁对象存储的延迟比本地磁盘高一个数量级编辑大文档时的体验会明显变差。5.2 配置改法与版本差异Document Server 的配置在/etc/onlyoffice/documentserver/local.jsonDocker 部署的话是容器内对应路径。缓存外置的配置段落挂在services.CoAuthoring下涉及存储类型、endpoint、凭证、桶名、以及useVirtualHosting这几个关键项。具体字段名在不同版本之间有变化。我踩过一次坑照着网上某篇博客改了结果 DS 启动直接失败因为那个字段在 7.4 之后改名了。正确姿势是先打开同目录下的default.json搜索storage或者s3看当前版本实际支持哪些字段再往local.json里覆盖。local.json是增量覆盖文件只写你要改的节点即可不用复制整个配置。改之前必须备份cp /etc/onlyoffice/documentserver/local.json \ /etc/onlyoffice/documentserver/local.json.bak.$(date %F)改完重启服务Docker 是supervisorctl restart all或者直接重启容器。5.3 验证缓存真的落到 S3 了改完之后不能只看服务起没起来。验证方法是打开一份文档在编辑状态下用mc ls看那个缓存桶里有没有新对象产生。如果对象是空的或者没有说明配置没生效DS 还在用本地目录。还有一个隐蔽的点缓存桶和业务文档桶一定要分开。如果共用一个桶你在用mc清理业务数据的时候很可能顺手把 DS 的缓存清了正在编辑的用户会瞬间崩掉。桶名建议带明确前缀比如onlyoffice-cache一眼能看出用途。6. 联调排查从打不开文档到保存后内容没变6.1 第一步永远是确认网络可达性Document Server 访问不到你给的document.url是最常见的原因占了我遇到问题的一半以上。排查顺序进 Document Server 容器里 curl 一下那个 URL看返回是什么。这一步直接决定后面往哪查如果是Connection refused说明地址不对。最常见的是用了127.0.0.1或者localhost但 DS 在容器里那个地址指向的是容器自己如果是 403大概率是预签名 URL 的 Host 不匹配回看 2.3 节如果是 404检查对象名是不是被 URL 编码处理错了中文对象名尤其容易出问题。Docker 部署的情况下访问宿主机服务的正确写法是宿主机的真实内网 IP或者用host.docker.internalLinux 上需要额外加--add-host参数。本地开发时用 MinIO 的容器名做 DNS同一 Docker 网络内也可以。6.2 回调没触发或者超时如果日志里完全看不到回调请求先检查callbackUrl是不是 DS 能访问到的地址。同样的道理别写localhost。如果回调到了但一直超时看你的处理逻辑耗时。Document Server 对回调有超时限制大概在几十秒量级。如果你的实现是下载文件 → 写 MinIO → 解析内容入库 → 生成缩略图一条龙同步做完大文件很容易超时。正确的做法是回调里只做下载和写盘的同步操作拿到文件后立刻返回{error:0}其余的重活丢到消息队列异步做。这个改动我做过之后超时告警直接降了一大截。6.3 保存成功了打开还是旧内容这是 4.2 节的 key 问题前面讲过了不重复。补充一个排查技巧Document Server 的日志里会打印每个请求的 key你可以拿它跟数据库里的版本号对一下。日志位置在/var/log/onlyoffice/documentserver/converter/out.log和docservice/out.log后者更常看。6.4 Nginx 反代 MinIO 的几个必配项如果你在 MinIO 前面挂了 Nginx有三个配置不加会出问题location / { proxy_pass http://127.0.0.1:9000; proxy_set_header Host $http_host; # 关键透传原始 Host否则预签名 URL 校验失败 client_max_body_size 2048m; # 大文件上传必须放开 proxy_request_buffering off; # 上传大文件时不缓冲整个请求体 proxy_read_timeout 300s; proxy_send_timeout 300s; }proxy_set_header Host $http_host这行是最容易漏的。默认 Nginx 会把 Host 改成proxy_pass里的地址导致 S3 签名算法算出来的 Host 跟你生成 URL 时用的不一致直接 403。7. 我实际跑下来固化的参数清单把上面这些内容压成一张表配置的时候可以直接对照配置项推荐值说明MinIO 预签名有效期43200 秒12 小时太短会导致编辑中途 403太长有泄漏风险document.key 长度小于 128 字符超长会被 DS 截断导致 key 冲突forcesavetrue防止用户关标签页丢内容回调响应时间3 秒以内超时会触发重试风暴分片上传 partSize不小于 5MBS3 协议硬性限制缓存桶与业务桶必须分开避免清理时误伤Nginx client_max_body_size2048m按你最大的文档类型调整最后分享一个我自己用的小技巧在开发环境我会把 Document Server 的document.url指向一个带时间戳的调试接口每次请求都记一条日志包含请求方 IP、User-Agent、URL、响应码。调试期把这几行日志打开上面 6.1 节那四种情况基本一眼就能定位比进容器里 curl 快得多。上线前记得把这个调试接口关掉或者加个开关别让它成为信息泄漏的口子。
