常见问题

部署与形态

ATKONOFFICE 是 SaaS 吗？需要联网到厂商服务器吗？

不是 SaaS。ATKONOFFICE 是私有化中间件，所有组件部署在企业内部环境里。整个「打开—编辑—保存」链路不依赖、不回连厂商任何服务器，支持完全内网部署。

终端用户需要装什么？

一次性安装一个轻量的 Windows 桌面客户端（标准简体中文安装向导，支持自定义安装目录），并确保本机装有 Office 组件（MS Office / WPS Office）作为编辑引擎——客户端不捆绑、也不改动既有安装。装好后从网页点开即用，日常使用不需重复安装。未装客户端时前端 open() 会自动弹出内建引导。

能在企业内批量部署客户端吗？

可以。安装包支持静默安装（命令行加 /S）：除系统提权提示外无任何界面，适合经企业软件分发平台批量下发，装完即刻可用，无需终端用户手工操作。

支持哪些操作系统 / 浏览器？

终端编辑目前面向 Windows 桌面环境（编辑引擎复用本机已安装的 Office 组件）。浏览器端主流现代浏览器均可发起编辑。

后端前面有 nginx / 网关 / 负载均衡，要注意什么？

文档下载与保存走普通 HTTP，常规反代即可；业务页的实时事件回推走 WebSocket，有三条硬性转发要求与两条安全前置（升级头透传、超时覆盖编辑会话、控制帧转发；WS 端点日志不记查询串、生产必须 wss），缺了各有各的坏法。逐条说明与可直接抄的 nginx 配方见部署要求。

支持多实例 / 集群部署吗？

支持多实例负载分担 / 横向扩容：每实例配置一个指向自己的对外地址、负载均衡按路径前缀精确转发，做法见部署要求 · 多实例部署。两条边界如实说明：节点重启 / 摘除 / 滚动更新会中断该节点上正在编辑的会话（终端用户需关窗重开），请安排在维护窗口内；加 / 减节点是配置事件（改该节点配置 + 负载均衡规则），不是加副本自动生效。

文档能打开也能保存，但业务页收不到任何事件回推 / 保存后页面没反应？

事件回推走 WebSocket 面——这个症状说明 WS 面断了而 HTTP 面正常，先别查前端事件代码。按命中率排查：

1. 反向代理没透传 WS 升级头：WS 端点须以 HTTP/1.1 转发 Upgrade / Connection 头，见部署要求；
2. 后端应用缺 spring-boot-starter-websocket：SDK 不传递该依赖，缺失时不报任何错、事件通道整体不注册，见开始 · 安装；
3. 全站登录拦截把 WS 端点或客户端会话端点拦下了：这两类调用不携带浏览器登录态，须放行，见端点 · 谁在调用、怎么鉴权；
4. 多实例部署下按实例路由没配对：监听浏览器端 SDK 的 ws_ticket_node_mismatch 错误码即可确认，见部署要求 · 多实例部署。

编辑能力

支持哪些文档格式？

覆盖 Word / Excel / PPT 三大类主流办公格式及其同类格式，打开和保存后的文件类型与原文档一致。当前各类能力范围见产品概述 · 支持的文档类型。

是「真编辑」还是在线预览？

是真编辑。客户端复用本机已安装的 Office 组件（MS Office / WPS Office）作为编辑引擎，排版、样式、公式、图表保持原样，所见即所得，不是预览或在线重排。

能限制用户只能查看不能改吗？

可以。支持只读打开；Word 另有仅修订 / 仅批注两种受控模式，Excel 有提交表单模式。

集成与开发

接入需要改造现有系统吗？

不需要大规模改造。服务端加依赖、浏览器端加 npm 包、接自有存储、少量配置即可。可先在一个业务点接入验证，再逐步推广。最小闭环见开始。

文档存在哪里？厂商能看到吗？

存在集成方自有存储里（数据库 / 对象存储 / 文件系统均可）。厂商看不到、也不留存——字节只在业务后端与终端用户之间流动。往哪存由 save 路由决定，从哪取由解析器决定。

需要同时用两个 SDK 吗？

是的。服务端 SDK（Java）负责签发与回写，浏览器端 SDK（JS）负责在网页里发起编辑。两者配合完成完整闭环。

服务端 SDK 支持哪些 Spring Boot 版本？

同时发布两套制品：Spring Boot 3.x / JDK 17（jakarta，无尾缀正式版）与 Spring Boot 2.7 / JDK 8（javax，-javax 兼容版），API 完全一致，按大版本二选一，见开始 · 安装。⚠️ Spring Boot 2.6 及以下不支持：应用可正常启动、零报错零警告，但自动装配不会生效、端点一个都不会注册。

加了依赖、应用正常启动，但 SDK 的端点全是 404？

启动日志里有没有 Mapping servlet: 'atkonofficeRpcServlet' 一类的映射记录是分水岭（措辞随 Spring Boot 版本可能略有差异）：没有 → 自动装配未生效，最常见原因是 Spring Boot 版本低于 2.7（见上一问）；有 → 装配正常，查请求是否真的打到了应用本体（网关前缀改写、context-path）。

在 addCorsMappings / 拦截器（HandlerInterceptor）里配的东西对 SDK 端点不生效？

SDK 自动挂载的端点不经过 Spring MVC，MVC 层机制（addCorsMappings / interceptor / @ControllerAdvice）对它们一概无效，servlet 容器层机制（Filter / Spring Security 过滤器链）才有效。判断规则、可直接抄的 servlet 级 CORS 配方、以及一处容易误导排查方向的假象，见端点 · 这些端点不经过 Spring MVC。

授权 / license 是怎么回事？

ATKONOFFICE 是需授权的商业产品，授权决策在服务端完成。终端用户可在客户端激活框输入授权码激活，或由管理员在后端预置授权码。未授权时文档字节被拒发，但不影响先完成集成对接，详见产品授权。

打开模式（编辑 / 只读）在前端还是后端决定？

后端决定。打开模式是文档级业务决策，由业务后端在 host-page 路由里用 AtkonofficeOpenMode 裁决，浏览器只透传 params。推荐一功能一路由，见业务参数透传与分流。