前言
做企业项目的人,大多接过这样的需求。
业务部门说:系统里要能在线编辑 Word,客户不想先下载、改完再传回去。
这个需求听起来很普通。真开始找方案,会发现每条路都不好走。
第一个绕不开的问题是私有化部署。
国企、金融机构这类客户的数据不能出内网,系统只能部署在客户自己的服务器或私有云上。SaaS 方案在这一步就用不了,数据出境这一关过不去。
第二个问题是文档编辑要嵌进业务系统。
用户不该被带到另一个独立平台去改文件。他们要在自己的系统里打开、编辑、保存,改完还要回到原来的业务流程。
第三个问题是开发成本。
商业 SDK 按人头收费,五百个用户一年的授权费够养半个前端团队,预算会上很难讲清楚。
自研的成本更高。只是让 .docx 在浏览器里渲染得接近 Word,一个小组就要做大半年,协同算法和格式兼容还没算进去。
三条路都试过,都走不通。那还有什么办法?
这篇文章介绍 OnlyOffice,看看它怎么解决这几个问题。
二、OnlyOffice 是什么?
OnlyOffice 是一个可以私有化部署的在线文档编辑引擎。它支持查看和编辑 Word、Excel、PPT、PDF 和表单,并通过 API 嵌进你自己的系统。

它不是网盘,也不打算取代你业务系统里的协作平台。

可以把它看作一块提供“文档编辑能力”的积木。
用户、权限、文件存储和业务流程仍然由你的系统负责。OnlyOffice 只做三件事:在浏览器里打开 .docx,让用户编辑,改完后通知你把文件存回去。
它有三个版本:开源社区版、企业版和开发者版。
三个版本的核心编辑功能基本相同,区别在授权方式和高级功能。
- 社区版:免费,采用 AGPL v.3 协议,适合小团队和测试环境。
- 企业版:商业授权,面向企业内部部署,额外提供管理面板、高级安全配置和技术支持。
- 开发者版:同样是商业授权,主要区别是支持白标。你可以替换 Logo、修改主题色,把“关于”页面换成自己的品牌。
三、开发者最关心的四项能力
3.1 API 集成
API 集成是 OnlyOffice 最核心的能力,开发者接触它通常也从这里开始。
集成模型分三步:后端生成 config,前端加载编辑器,文档服务回调你的接口完成保存。
config 机制
后端生成一个 JSON,描述这份文档的全部信息,包括文件类型、文档地址、权限、用户信息、界面语言和回调地址。前端拿到这个 JSON 后,用它初始化编辑器。
config 里放哪些字段由你决定。官方文档的集成示例也是这样用的,config 相当于编辑器的“说明书”。
前端加载
在页面里放一个 div,引入 ONLYOFFICE 的 api.js,再执行 new DocsAPI.DocEditor("div-id", config),编辑器就会渲染在这个 div 里。
用户看到的是你系统里的一个页面,文档由 ONLYOFFICE 在背后渲染。
回调保存
用户在编辑器里改完后,ONLYOFFICE 会在保存时向你的 callbackUrl 发送 POST 请求,请求体里带有状态码和新文档的下载地址。
后端收到请求后下载新文件、覆盖存储、返回成功,整个流程就闭环了。
50 多个现成连接器
官方提供了 50 多个现成连接器,覆盖 Nextcloud、Moodle、Odoo、WordPress、SharePoint 等常见系统。如果你的系统正好在其中,接入会很快。
不过更有用的一点是,你完全可以不用连接器,直接调用 API,从零嵌进自己的业务系统。官方连接器本质上就是这套 API 的现成用法示例。看懂一个,自己写一个并不难。

整个流程是:下发 config,文档服务拉取文件,保存时回调后端。
3.2 私有化部署
很多人第一次试用 OnlyOffice,就是为了私有化部署。
部署形态
OnlyOffice 文档服务可以部署在本地服务器、私有云或完全离线的内网环境。
官方下载页提供 Windows 和 Linux 安装包,也提供 Docker 镜像。
企业版产品页写明了:采用自托管部署,数据保留在你自己的基础设施内,第三方无法访问。
用 Docker 一条命令启动
最快的方式是 Docker:
docker run -i -t -d -p 8080:80 onlyoffice/documentserver
再挂载数据目录、配好 JWT,服务就在你的机器上运行起来了。本地服务器、私有云和离线内网用的都是这一套。
为什么私有化很重要
数据掌握在自己手里,才谈得上满足金融、医疗、政府这类客户的合规要求。
文档、用户数据和审计日志都留在你的基础设施里,OnlyOffice 官方接触不到。
SaaS 方案给不了这种保证,自研的成本又太高,私有化部署正好处在两者之间。

文档服务、文件存储和日志都在你自己的基础设施内,官方不接触数据。
3.3 协作能力
协作功能是内置的,不需要额外装插件。
实时编辑
多人同时打开同一份文档时,每个人都能看到其他人的光标、选区和在线状态。
协同编辑有两种模式。快速模式会实时显示所有人的改动。严格模式下,你保存之后其他人才能看到你的修改,适合不想被打扰、专心写自己那部分的时候。

评论
选中一段文字就能添加评论,也可以 @ 提及协作者。评论和修订可以同时使用,适合审阅流程。
版本历史
在编辑器里可以查看文档的历史版本,对比差异,或者回滚到某个版本。

合同、报告、审批稿这类需要留痕的业务场景,离不开版本历史。

几个用户的浏览器只要使用同一个 document.key,打开的就是同一份文档。文档服务负责同步光标和改动,并管理版本历史和评论。
3.4 白标能力
白标是开发者版的核心功能,也是做 SaaS 的团队最在意的一项。
能换哪些内容
通过 editorConfig.customization,你可以替换编辑器界面里的 Logo 和深色主题 Logo,修改点击 Logo 后跳转的 URL,以及“关于”页面里的公司名称、地址、邮箱等信息。主题色也可以改。
这样客户看到的是你的品牌,而不是“由 OnlyOffice 提供技术支持”。
为什么重要
把 SaaS 产品卖给客户时,品牌一致也是产品体验的一部分。
产品里突然冒出一个第三方 Logo,客户会问“这是谁家的”,对产品的信任也会打折扣。有了白标能力,OnlyOffice 就成了你产品里“看不见的引擎”。
补充一点:OnlyOffice 支持离线 AI,但自托管部署后并不能直接使用。你还需要部署本地模型并完成配置,这是另一项工程。
四、实战演示:Spring Boot 接入 OnlyOffice
接入分四步:Docker 部署、后端生成 config、前端加载编辑器、处理保存回调。
先说明示例工程的结构。
后面的代码都来自 onlyoffice-springboot 项目,使用 Spring Boot 3.4.5 和 Java 17。
项目没有引入额外的 JWT 框架,签名和验签直接用 JDK 自带的 HmacSHA256 完成:
onlyoffice-springboot/
├── config/OnlyOfficeProperties.java
├── controller/
│ ├── DocumentController.java
│ ├── FileController.java
│ └── OnlyOfficeController.java
├── service/
│ ├── DocumentStorageService.java
│ ├── FileAccessService.java
│ ├── JwtService.java
│ └── OnlyOfficeCallbackService.java
└── resources/static/
├── index.html
└── editor.html
第一步:Docker 部署,带上 JWT 配置
docker run -i -t -d -p 8080:80 \
-e JWT_ENABLED=true \
-e JWT_SECRET=susantest123456 \
-v /data/onlyoffice/data:/var/www/onlyoffice/Data \
onlyoffice/documentserver
记下 JWT_SECRET,后端生成 config 和校验回调都要用到它。
如果不设置密钥,或者用了弱密钥,文档服务在公网上就等于没有防护。生产环境不要这样做。
容器启动后先别急着写代码,花两分钟确认服务确实已经就绪。
先查出实际的容器名或 ID:
docker ps

更稳妥的做法是在容器内查询版本信息:
docker exec 3eff4ef3b2b6 curl -s http://127.0.0.1:8000/info/info.json | grep buildVersion
正常情况下会输出类似 "buildVersion":"10.0.0" 的内容。
不要在宿主机上直接 curl 容器的 8000 端口。这个端口没有映射到宿主机,查不到是正常的。
最直接的办法是用浏览器访问 http://你的服务器IP:8080/welcome/。看到 “ONLYOFFICE Docs installed successfully” 欢迎页,就说明主体服务已经启动。

如果页面打不开,先用 docker ps 确认容器状态是不是 Up,再用 docker logs 查看有没有报错。
顺便确认一下 JWT 配置是否生效:
docker exec 3eff4ef3b2b6 documentserver-jwt-status.sh
这条命令会显示当前 JWT 的启用状态和密钥。把它和 docker run 里设置的 JWT_SECRET 对比,两者一致就说明配置正确。
后端生成 config 和校验回调时用的都是这个密钥。如果对不上,编辑器会白屏,并提示“文档安全令牌格式不正确”。
项目的配置入口在 application.yml,配置片段如下:
server:
port: ${SERVER_PORT:8081}
address: 0.0.0.0
onlyoffice:
docs-url: ${ONLYOFFICE_DOCS_URL:http://localhost:8080}
public-app-url: ${APP_PUBLIC_URL:https://your-app.example.com}
jwt-secret: ${ONLYOFFICE_JWT_SECRET:}
storage:
directory: ${DOCUMENT_STORAGE_DIR:./data/documents}
这两个地址容易混淆:
docs-url 是浏览器加载 api.js 时使用的地址。
public-app-url 是 ONLYOFFICE 服务端下载文件、发送回调时使用的地址。
本地调试时,public-app-url 不能直接写成 http://localhost:8081。
远程的文档服务访问不到你电脑上的 localhost,最终会在保存时提示“这份文件无法保存”。
下面是 JwtService 的核心源码。它负责为 config 和文件下载地址签发 HS256 令牌,也负责校验回调请求:
@Service
public class JwtService {
private static final Base64.Encoder BASE64_URL_ENCODER =
Base64.getUrlEncoder().withoutPadding();
private static final Base64.Decoder BASE64_URL_DECODER =
Base64.getUrlDecoder();
private static final TypeReference<Map<String, Object>> MAP_TYPE =
new TypeReference<>() {};
private final ObjectMapper objectMapper;
private final OnlyOfficeProperties properties;
public JwtService(ObjectMapper objectMapper, OnlyOfficeProperties properties) {
this.objectMapper = objectMapper;
this.properties = properties;
}
public String sign(Map<String, Object> claims) {
if (!properties.jwtEnabled()) {
throw new IllegalStateException("onlyoffice.jwt-secret 未配置");
}
try {
Map<String, Object> payload = new LinkedHashMap<>(claims);
long now = Instant.now().getEpochSecond();
payload.putIfAbsent("iat", now);
payload.putIfAbsent("exp", now + 3600);
String header = encodeJson(Map.of("alg", "HS256", "typ", "JWT"));
String body = encodeJson(payload);
String signingInput = header + "." + body;
return signingInput + "."
+ BASE64_URL_ENCODER.encodeToString(hmac(signingInput));
} catch (Exception exception) {
throw new IllegalStateException("生成 JWT 失败", exception);
}
}
public Map<String, Object> verify(String token) {
if (!properties.jwtEnabled()) {
return Map.of();
}
if (token == null || token.isBlank()) {
throw new IllegalArgumentException("请求缺少 JWT");
}
try {
String[] parts = token.split("\\.");
if (parts.length != 3) {
throw new IllegalArgumentException("JWT 格式错误");
}
String signingInput = parts[0] + "." + parts[1];
byte[] expected = hmac(signingInput);
byte[] actual = BASE64_URL_DECODER.decode(parts[2]);
if (!MessageDigest.isEqual(expected, actual)) {
throw new IllegalArgumentException("JWT 签名无效");
}
Map<String, Object> claims = objectMapper.readValue(
BASE64_URL_DECODER.decode(parts[1]), MAP_TYPE);
Number expiresAt = (Number) claims.get("exp");
if (expiresAt != null
&& expiresAt.longValue() < Instant.now().getEpochSecond()) {
throw new IllegalArgumentException("JWT 已过期");
}
return claims;
} catch (IllegalArgumentException exception) {
throw exception;
} catch (Exception exception) {
throw new IllegalArgumentException("JWT 校验失败", exception);
}
}
private String encodeJson(Map<String, Object> value) throws Exception {
return BASE64_URL_ENCODER.encodeToString(
objectMapper.writeValueAsBytes(value));
}
private byte[] hmac(String input) throws GeneralSecurityException {
Mac mac = Mac.getInstance("HmacSHA256");
mac.init(new SecretKeySpec(
properties.jwtSecret().getBytes(StandardCharsets.UTF_8),
"HmacSHA256"));
return mac.doFinal(input.getBytes(StandardCharsets.UTF_8));
}
}
这段代码有两处值得注意。
第一,比较签名时用的是 MessageDigest.isEqual,而不是普通的字符串比较。
第二,config 和文件下载各用一个独立的令牌。config 令牌供 ONLYOFFICE 校验编辑器配置。下载令牌额外带有 fileId 和 purpose,只允许文档服务拉取指定的文件。两类令牌的权限分开,出了问题也更容易排查。
第二步:后端生成 config
这一步要注意两件事:document.key 怎么生成,以及文件怎么被访问。
@GetMapping("/config/{fileId}")
public Map<String, Object> getConfig(@PathVariable Long fileId) {
StoredFile file = fileRepository.mustFind(fileId);
// key 用 文件ID + 版本号
String documentKey = file.getId() + "_" + file.getVersion();
Map<String, Object> document = new LinkedHashMap<>();
document.put("fileType", "docx");
document.put("key", documentKey);
document.put("title", file.getOriginalName());
// 这个 url 是 ONLYOFFICE 服务端去拉的,不是浏览器
document.put("url", "https://your-app.com/api/files/" + fileId + "/download");
Map<String, Object> editorConfig = new LinkedHashMap<>();
editorConfig.put("callbackUrl", "https://your-app.com/api/office/callback/" + fileId);
editorConfig.put("lang", "zh-CN");
editorConfig.put("user", Map.of("id", currentUserId(), "name", currentUserName()));
Map<String, Object> config = new LinkedHashMap<>();
config.put("document", document);
config.put("editorConfig", editorConfig);
config.put("token", jwtSigner.sign(config));
return config;
}
document.key 由“文件 ID + 版本号”组成。每次保存成功后版本号加一,下次打开时自然就是新的 key。
不要随手用文件名或时间戳拼 key,很容易出问题。
项目里在上面的基础上完善了 config 的生成逻辑。下面是 OnlyOfficeController 的核心源码,权限、用户、回调地址和配置签名都在这里统一处理:
@GetMapping("/config/{id}")
public Map<String, Object> config(
@PathVariable String id,
@RequestParam(defaultValue = "demo-user") String userId,
@RequestParam(defaultValue = "演示用户") String userName,
@RequestParam(defaultValue = "edit") String mode) {
DocumentInfo file = storageService.get(id);
String normalizedMode = "view".equalsIgnoreCase(mode) ? "view" : "edit";
Map<String, Object> document = new LinkedHashMap<>();
document.put("fileType", file.fileType());
document.put("key", file.documentKey());
document.put("title", file.name());
document.put("url", fileAccessService.createDownloadUrl(file.id()));
document.put("permissions", Map.of(
"edit", "edit".equals(normalizedMode),
"download", true,
"print", true
));
Map<String, Object> customization = new LinkedHashMap<>();
customization.put("autosave", true);
customization.put("compactHeader", false);
customization.put("comments", true);
customization.put("feedback", false);
customization.put("forcesave", false);
customization.put("help", false);
customization.put("hideRightMenu", false);
Map<String, Object> editorConfig = new LinkedHashMap<>();
editorConfig.put("mode", normalizedMode);
editorConfig.put("lang", "zh-CN");
editorConfig.put("callbackUrl", properties.publicUrl(
"/api/office/callback/" + file.id()));
editorConfig.put("user", Map.of(
"id", safeUserValue(userId, "demo-user"),
"name", safeUserValue(userName, "演示用户")
));
editorConfig.put("customization", customization);
editorConfig.put("coEditing", Map.of("mode", "fast", "change", true));
Map<String, Object> config = new LinkedHashMap<>();
config.put("type", "desktop");
config.put("documentType", documentType(file.fileType()));
config.put("document", document);
config.put("editorConfig", editorConfig);
config.put("width", "100%");
config.put("height", "100%");
if (properties.jwtEnabled()) {
config.put("token", jwtService.sign(config));
}
Map<String, Object> response = new LinkedHashMap<>(config);
response.put("docsApiUrl", properties.docsApiUrl());
response.put("documentInfo", file);
return response;
}
private String documentType(String fileType) {
return switch (fileType) {
case "xls", "xlsx", "csv" -> "cell";
case "ppt", "pptx" -> "slide";
case "pdf" -> "pdf";
default -> "word";
};
}
这里的顺序不能反:先把 document 和 editorConfig 填写完整,再对整份 config 签名。
签名的内容必须和前端实际拿到的配置一致。
再说文件访问。config 里的 url 由 ONLYOFFICE 服务端请求,不是浏览器直接请求。
如果文件放在内网,要确保文档服务容器能访问这个地址。否则就会出现浏览器能下载文件,编辑器却一直转圈、提示下载失败的情况。
项目没有把 /api/files/{id}/download 直接对外开放,而是给文档服务签发一个 15 分钟有效的下载令牌。
FileAccessService 的实现如下:
@Service
public class FileAccessService {
private final JwtService jwtService;
private final OnlyOfficeProperties properties;
public FileAccessService(
JwtService jwtService,
OnlyOfficeProperties properties) {
this.jwtService = jwtService;
this.properties = properties;
}
public String createDownloadUrl(String documentId) {
String path = "/api/files/" + documentId + "/download";
if (!properties.jwtEnabled()) {
return properties.publicUrl(path);
}
Map<String, Object> claims = new LinkedHashMap<>();
claims.put("fileId", documentId);
claims.put("purpose", "document-download");
claims.put("iat", Instant.now().getEpochSecond());
claims.put("exp", Instant.now().plusSeconds(900).getEpochSecond());
String token = jwtService.sign(claims);
return UriComponentsBuilder.fromUriString(properties.publicUrl(path))
.queryParam("access_token", token)
.build(true)
.toUriString();
}
public void verifyDownload(String documentId, String token) {
if (!properties.jwtEnabled()) {
return;
}
Map<String, Object> claims = jwtService.verify(token);
if (!documentId.equals(claims.get("fileId"))
|| !"document-download".equals(claims.get("purpose"))) {
throw new IllegalArgumentException("下载令牌与文档不匹配");
}
}
}
文档服务实际拉取文件时,请求的地址类似这样:
https://your-app.example.com/api/files/welcome-word/download?access_token=eyJ...
下载接口先校验令牌,再从存储中读取文件:
@GetMapping("/{id}/download")
public ResponseEntity<byte[]> download(
@PathVariable String id,
@RequestParam(name = "access_token", required = false)
String accessToken) {
fileAccessService.verifyDownload(id, accessToken);
DocumentInfo document = storageService.get(id);
byte[] content = storageService.read(id);
HttpHeaders headers = new HttpHeaders();
headers.setContentType(mediaType(document.fileType()));
headers.setContentDisposition(ContentDisposition.attachment()
.filename(document.name(), StandardCharsets.UTF_8)
.build());
headers.setCacheControl(CacheControl.noStore().cachePrivate()
.maxAge(Duration.ZERO));
return ResponseEntity.ok().headers(headers).body(content);
}
请求这个接口时如果不带 access_token,项目会直接返回 400。
所以即使浏览器知道文件 ID,也拿不到文档内容。只有持有后端签发的短效令牌,文档服务才能拉取文件。
第三步:前端加载编辑器
<div id="office-editor" style="width:100%; height:100vh;"></div>
<script src="https://your-docserver/web-apps/apps/api/documents/api.js"></script>
<script type="module">
const config = await fetch(`/api/office/config/${fileId}`).then(r => r.json());
new DocsAPI.DocEditor("office-editor", config);
</script>
这个示例在脚本里直接使用了顶层 await,所以第二个 script 标签要加上 type="module"。fileId 需要由页面自行提供。
项目没有把 api.js 的地址写死在页面里。它先请求 config,再根据 config 返回的 docsApiUrl 动态加载脚本。
下面是 editor.js 的核心源码:
async function startEditor() {
const query = new URLSearchParams({ userId, userName, mode });
const response = await fetch(
`/api/office/config/${encodeURIComponent(documentId)}?${query}`,
{ cache: "no-store" }
);
const config = await response.json();
if (!response.ok) {
throw new Error(config.message || "无法获取编辑器配置");
}
await loadDocsApi(config.docsApiUrl);
config.events = {
onAppReady: () => {
loadingPanel.hidden = true;
},
onDocumentReady: () => {
setStatus("saved", "文档已加载");
},
onDocumentStateChange: event => {
const changed = Boolean(event?.data);
setStatus(
changed ? "changed" : "idle",
changed ? "有未保存修改" : "编辑器内已同步"
);
},
onError: event => {
const code = event?.data?.errorCode ?? "unknown";
const description =
event?.data?.errorDescription || "ONLYOFFICE 返回未知错误";
showError(`错误码 ${code}:${description}`);
},
onRequestClose: () => {
window.location.href = "/";
}
};
new DocsAPI.DocEditor("office-editor", config);
}
function loadDocsApi(url) {
return new Promise((resolve, reject) => {
const script = document.createElement("script");
script.src = url;
script.async = true;
script.onload = resolve;
script.onerror = () => reject(
new Error("无法加载 ONLYOFFICE api.js,请检查文档服务地址。")
);
document.head.appendChild(script);
});
}
注意,onDocumentStateChange(false) 只表示编辑器内部状态已经同步,并不代表 Spring Boot 已经收到 status=2 并把文件写入磁盘。文件到底有没有保存成功,要看服务端的回调日志。
第四步:处理保存回调
当 status 为 2 或 6 时,后端要下载新文件、更新存储并刷新 key。
@PostMapping("/callback/{fileId}")
public Map<String, Integer> callback(@PathVariable Long fileId,
@RequestBody Map<String, Object> body) {
if (!jwtVerifier.verify(body)) return Map.of("error", 1);
int status = (int) body.get("status");
if (status == 2 || status == 6) {
String downloadUrl = (String) body.get("url");
byte[] newContent = restTemplate.getForObject(downloadUrl, byte[].class);
fileStorage.update(fileId, newContent);
fileRepository.incrementVersion(fileId); // 刷新 key
}
return Map.of("error", 0);
}
上面的代码只保留了回调的主流程。项目里把验签、下载、写文件和升版本拆到了 OnlyOfficeCallbackService 和 DocumentStorageService 中。
下面是 OnlyOfficeCallbackService 的核心源码:
public Map<String, Integer> receive(
String documentId,
Map<String, Object> body) {
try {
Object token = body.get("token");
jwtService.verify(token == null ? null : token.toString());
int status = statusOf(body);
log.info("OnlyOffice callback: document={}, status={}, key={}",
documentId, status, body.get("key"));
if (status == 2 || status == 6) {
Object downloadUrl = body.get("url");
if (!(downloadUrl instanceof String url) || url.isBlank()) {
throw new IllegalArgumentException(
"OnlyOffice 回调缺少保存地址");
}
byte[] content = restClient.get()
.uri(url)
.accept(MediaType.APPLICATION_OCTET_STREAM)
.exchange((request, response) -> {
if (!response.getStatusCode().is2xxSuccessful()) {
throw new IllegalStateException(
"下载 OnlyOffice 文件失败: "
+ response.getStatusCode());
}
byte[] bytes = response.getBody()
.readNBytes(MAX_DOWNLOAD_BYTES + 1);
if (bytes.length > MAX_DOWNLOAD_BYTES) {
throw new IllegalArgumentException(
"OnlyOffice 文件超过 50 MB");
}
return bytes;
});
var updated = storageService.updateContent(documentId, content);
log.info(
"OnlyOffice document saved: document={}, version={}, size={}",
documentId, updated.version(), updated.size());
}
return Map.of("error", 0);
} catch (Exception exception) {
log.error(
"OnlyOffice callback failed: document={}",
documentId, exception);
return Map.of("error", 1);
}
}
private int statusOf(Map<String, Object> body) {
Object value = body.get("status");
if (value instanceof Number number) {
return number.intValue();
}
if (value instanceof String text) {
return Integer.parseInt(text);
}
throw new IllegalArgumentException("OnlyOffice 回调缺少 status");
}
这里的 RestClient 设置了 10 秒连接超时和 60 秒读取超时,下载文件最大限制为 50 MB,防止回调线程被异常地址长时间占用。
先关注下面几个状态码就够了:
| 状态 |
含义 |
处理方式 |
1 |
文档正在编辑 |
记录日志 |
2 |
文档已关闭,需要保存 |
下载文件并更新版本 |
4 |
未修改就关闭 |
返回成功 |
6 |
强制保存 |
下载文件并更新版本 |
7 |
强制保存出错 |
记录日志,不覆盖原文件 |
最后写入磁盘时,项目不直接覆盖目标文件,而是先写临时文件,再做原子替换:
public synchronized DocumentInfo updateContent(
String id,
byte[] content) {
if (content == null || content.length == 0) {
throw new IllegalArgumentException("OnlyOffice 返回了空文件");
}
DocumentInfo current = get(id);
DocumentInfo updated = current.withContent(content.length);
try {
writeContent(updated, content);
documents.put(id, updated);
persistMetadata();
return updated;
} catch (IOException exception) {
throw new IllegalStateException("更新文档内容失败", exception);
}
}
private void writeContent(
DocumentInfo document,
byte[] content) throws IOException {
Path target = contentPath(document);
Path temporary = storageDirectory.resolve(document.id() + ".tmp");
Files.write(temporary, content);
Files.move(
temporary,
target,
StandardCopyOption.REPLACE_EXISTING,
StandardCopyOption.ATOMIC_MOVE
);
}
withContent 会生成新的版本号:
public DocumentInfo withContent(long newSize) {
return new DocumentInfo(
id,
name,
fileType,
version + 1,
newSize,
Instant.now()
);
}
下次打开文档时,会用 id + "_" + version 组成新的 document.key,不会再用到旧缓存。
常见问题
key 不更新,协同会错乱
文件内容已经变了,key 却还是旧的。结果是用户打开后看到缓存的旧版本,或者协同状态混乱。
回调没有保存,用户会以为内容丢了
回调接口返回非零值或者超时,ONLYOFFICE 会认为保存失败。用户下次打开时,看到的还是修改之前的版本。
JWT 不一致,编辑器直接加载失败
后端配置了 JWT,但 Docker 环境变量没有配置,或者配置的值不同,编辑器就会白屏,并提示“文档安全令牌格式不正确”。
运行效果
文档中心首页:

在线编辑 Word 文件:

在线编辑 Excel 文件:

五、版本选型速查
四项能力和实战演示讲完了。真到选型时,问题只有一个:你的场景决定该用哪个版本。
三个版本的功能差别不大,区别在授权方式、并发数和品牌控制权。
| 场景 |
推荐版本 |
关键约束 |
| 小团队、测试 |
社区版 |
AGPL v.3 有传染性;早期版本有 20 并发上限,从 9.4 版本开始已取消 |
| 企业内部部署、保留 OnlyOffice 品牌 |
企业版 |
50 并发起;可按年订阅或购买永久许可 |
| 提供 SaaS 服务、需要白标 |
开发者版 |
支持白标;只能按年订阅 |
| 为每位客户单独部署 |
看品牌需求 |
需要白标选开发者版,保留品牌选企业版 |
六、写在最后
再看开头那三个问题:SaaS 的数据出不了内网,商业 SDK 按人头收费承受不起,自研的隐性成本又太高。这三条路都走不通,大家才会去找别的办法。
OnlyOffice 的做法,是把“文档编辑”从一项外部服务变成一个可以装进自己系统的组件。
数据放在你自己的服务器上,编辑能力通过 API 嵌进业务流程,授权按场景选择,预算也能控制。
它也有局限。社区版受 AGPL 协议约束,老版本还有并发上限。白标只有开发者版才有。离线 AI 需要你自己额外部署模型。但如果你的要求是私有化、可集成、成本可控,OnlyOffice 确实能解决这个问题。
所以,文档协作的另一种选择,既不是更便宜的 SaaS,也不是再造一个自研轮子。它是一个数据留在自己手里、能嵌进自己系统的编辑引擎。
选型前先想清楚两件事:数据要不要留在自己手里?品牌要不要换成自己的?
这两个问题的答案,基本决定了你该选社区版、企业版还是开发者版。剩下的工作,就是一条 Docker 命令加一份 config。如果你在接入过程中遇到其他问题,也欢迎到云栈社区和其他开发者交流。
七、相关链接
更多资料:
作者:苏三