跪拜 Guibai
← All articles
Backend

OnlyOffice: The Self-Hosted Document Editor That Gives Enterprises a Third Path

By 苏三说技术 ·
Read original on juejin.cn ↗ Google Translate ↗ Alt translation

Regulated industries now have a viable middle ground between expensive per-seat SDK licensing and months of self-built document rendering: data stays on your infrastructure while users get a full-fidelity editor inside your own app. For SaaS vendors, the developer edition's white-labeling removes the third-party trust problem that otherwise kills embedded editing products.

Summary

Enterprise developers face a familiar dead end: SaaS editors fail data-stays-on-premises requirements, commercial SDKs charge per seat, and building a .docx renderer from scratch burns half a team for months. OnlyOffice offers a fourth alternative: a document editing engine you deploy yourself, embed via API, and control end to end.

The integration model is clean and developer-friendly. The backend generates a config JSON describing the document and editor settings; the frontend loads ONLYOFFICE's api.js and initializes the editor in a div; and the document server POSTs to your callback endpoint when saving, carrying a status and download URL. Private deployment works with a single Docker command, collaboration is built in (real-time cursors, comments, version history), and the developer edition adds white-labeling so SaaS vendors can strip all OnlyOffice branding.

A complete Spring Boot 3.4.5 + Java 17 example demonstrates the full loop: Docker deployment with JWT, config generation with a versioned document.key, short-lived download tokens for file access, callback handling with status codes 2 and 6 triggering saves, and atomic file replacement. The article also warns about key pitfalls: mismatched JWT secrets white-screen the editor, stale document keys break collaboration, and a callback returning non-zero makes users lose edits.

Takeaways
— OnlyOffice supports Word, Excel, PPT, PDF, and forms, with three editions: community (free, AGPL v.3), enterprise (commercial, internal deployment), and developer (commercial, adds white-labeling).
— The API integration model is three steps: backend generates a config JSON, frontend loads api.js and calls new DocsAPI.DocEditor(divId, config), and the document server POSTs to your callbackUrl on save.
— Private deployment runs with a one-line Docker command: docker run -i -t -d -p 8080:80 onlyoffice/documentserver.
— JWT must be enabled and the JWT_SECRET must match between the Docker container and the backend; a mismatch causes the editor to white-screen with "document security token format is incorrect".
— document.key should be composed of file ID plus version number; after a save, the version increments, ensuring the next open gets a fresh key and avoiding stale caches.
— Directory access uses a 15-minute download token signed by the backend; the document service pulls files via that token, while browsers without a token get a 400.
— Callback status codes: 2 (doc closed, needs save) and 6 (force save) trigger downloading the new file and updating the version; 1 and 7 are logged, 4 returns success without changes.
— The community edition's 20-concurrent-user limit was removed starting with version 9.4, but AGPL v.3 copyleft still applies.
— White-labeling is only available in the developer edition, which is licensed yearly; the enterprise edition keeps OnlyOffice branding.
Conclusions

The three-tier licensing scheme is deliberately structured to push SaaS vendors toward the developer edition: white-labeling is the one feature that directly affects their revenue, so the article's advice to 'decide on brand needs first' is effectively a decision to pay for it.

The callback design treats document.key as the source of truth for caching; a stale key causes silent collaboration corruption, which makes version-aware key generation a correctness requirement rather than an optimization.

The article's 50 MB download cap and atomic file replacement show that production-grade integration is about defending against slow or malicious document servers, not just wiring endpoints together.

Concepts & terms
document.key
A string identifier that OnlyOffice uses to track the current version of a document in its cache. It must change when the file content changes; otherwise the editor may show stale content or misbehave in collaborative sessions.
White-labeling
The ability to replace a product's branding (logos, theme colors, About page) with your own, so end users see your brand instead of the underlying vendor's name. OnlyOffice reserves this capability for its developer edition.
AGPL v.3
The Affero General Public License version 3, a copyleft license requiring that any modified version distributed or offered as a network service also release its source code under AGPL. OnlyOffice's community edition uses this license, meaning any derivative service must share its code.
Source: juejin.cn ↗ Google Translate ↗ Backup ↗