onlyoffice集成oa系统常见问题源于路径配置错误或认证缺失，需通过api嵌入、插件模块化、sso联合认证、反向代理及jwt密钥同步五种方式解决，核心是确保jwt签名一致、url可达、权限字段完整。
如果您正在尝试将OnlyOffice集成至企业OA系统，但遇到文档无法加载、权限校验失败或编辑器空白等问题，则很可能是由于集成路径未正确配置或认证机制缺失。以下是解决此问题的步骤：
一、API接口嵌入集成
该方法通过调用OnlyOffice Document Server提供的标准RESTful API与前端JS SDK（api.js），在OA页面中动态生成编辑器iframe容器，实现文档的在线预览与协同编辑。其核心在于服务端生成含JWT签名的配置对象，并由前端初始化编辑器实例。
1、在OA系统后端服务中引入OnlyOffice JWT签名逻辑，使用OnlyOffice配置的secret密钥对文档元数据（如title、url、callbackUrl）进行HS256签名。
2、构造包含document、editorConfig、token字段的JSON对象，其中document.url必须指向可通过OA服务器网络直接访问的文档存储地址（如内网NAS路径或OA文件服务直链）。
3、在OA前端页面中引入OnlyOffice api.js脚本：https://docserver.corp.internal/web-apps/apps/api/documents/api.js，注意域名必须与OnlyOffice反向代理配置一致。
4、调用new DocsAPI.DocEditor("placeholder", config)初始化编辑器，确保容器DOM元素ID与参数中id值匹配。
二、插件式模块化集成
该方式将OnlyOffice功能封装为OA平台原生插件，在OA管理后台统一启用与配置，避免侵入主应用代码。适用于支持插件扩展架构的OA系统（如泛微e-cology、致远A8、蓝凌EKP等）。
1、基于OA平台插件开发规范创建独立模块，定义菜单入口（如“在线编辑”按钮）、权限控制策略及上下文参数传递机制。
2、在插件后端实现文档元信息转换逻辑：将OA内部文件ID映射为OnlyOffice可识别的document.key，并生成对应下载URL与保存回调地址。
3、插件前端调用OA平台提供的iframe容器API，注入OnlyOffice编辑器URL，URL中携带已签名的token参数与callbackUrl参数。
4、配置插件级JWT密钥与OnlyOffice Document Server保持一致，并在插件配置页提供docServerUrl和secret输入项供管理员填写。
三、单点登录（SSO）联合认证集成
该方案通过OAuth 2.0或SAML协议打通OA用户体系与OnlyOffice权限模型，使用户无需二次登录即可进入编辑界面，同时实现细粒度文档访问控制。OnlyOffice通过JWT中的permissions字段控制编辑/评论/下载等操作权限。
1、在OA系统中启用OAuth 2.0 Provider功能，注册OnlyOffice为受信任客户端，获取client_id与client_secret。
2、OnlyOffice Document Server配置tokenInBox与inbox参数，使其在加载时向OA OAuth端点发起授权请求，获取含用户身份与权限声明的JWT。
3、OA系统在签发JWT时，必须包含permissions.edit、permissions.download、permissions.print等布尔字段，并设置exp过期时间（建议≤3600秒）。
4、OnlyOffice前端初始化时自动携带该JWT至document.serverUrl请求头，Document Server验证通过后返回渲染资源。
四、反向代理统一入口集成
该方法不修改OA代码，而是在网络层统一处理OnlyOffice访问路径，解决跨域、同源策略及内网解析失效问题。适用于OA与OnlyOffice部署于不同子网或不同物理服务器的场景。
1、在OA前置Nginx服务器中添加location块，将/onlyoffice/路径全部代理至OnlyOffice Document Server后端地址，例如proxy_pass http://192.168.5.20:8080/;。
2、配置proxy_set_header Host $host;与proxy_set_header X-Forwarded-Proto $scheme;，确保OnlyOffice内部重定向与SSL识别正常。
3、在OA前端调用api.js时，将docServerUrl设为https://oa.corp.internal/onlyoffice/，而非原始IP+端口地址。
4、在OnlyOffice配置文件/etc/onlyoffice/documentserver/local.json中，将services.CoAuthoring.server.port设为0，并启用useProxy选项，强制使用反向代理头信息判断请求来源。
五、JWT签名密钥同步配置
所有集成方式均依赖JWT签名验证，若OnlyOffice Document Server与OA系统使用的密钥不一致，将导致invalid token错误且编辑器无法加载。密钥必须严格一致且定期轮换。
1、在OnlyOffice Document Server中定位配置文件：/etc/onlyoffice/documentserver/local.json，找到token.inbox.inbox与token.outbox.outbox节点，填入与OA系统完全相同的base64编码密钥字符串。
2、执行supervisorctl restart all重启OnlyOffice服务，使配置生效。
3、在OA系统中确认JWT生成逻辑使用相同算法（HS256）、相同密钥、相同payload结构（至少包含exp、iat、document.key、editorConfig.user.id字段）。
4、使用在线JWT解码工具（如jwt.io）比对OA签发的token与OnlyOffice日志中接收到的token载荷是否一致，重点关注iss、aud字段是否被Document Server接受。
