一、为什么选择OnlyOffice？

随着远程办公、协同办公需求激增，私有化部署的在线文档编辑工具成为企业刚需。OnlyOffice以其易用性，高度兼容Office格式、支持多人在线协同等特性，成为一种理想方案。

需要注意：onlyoffice是AGPL v3.0 license，使用AGPLv3意味着任何基于ONLYOFFICE的二次开发代码都必须开源，企业商用需注意合规风险。

二、服务部署实战（Linux/Docker版）

推荐方案：Docker一键部署

 # 创建数据目录
mkdir -p /onlyoffice/{postgresql,docserver,logs}

# 启动容器（注意替换your-domain.com）
docker run -i -t -d -p 8080:80 --restart=always \
  -v /onlyoffice/postgresql:/var/lib/postgresql \
  -v /onlyoffice/docserver:/var/www/onlyoffice/Data \
  -v /onlyoffice/logs:/var/log/onlyoffice \
  -e JWT_ENABLED=true \
  -e JWT_SECRET=your_strong_password \
  --name onlyoffice \
   onlyoffice/documentserver

关键参数说明：

• JWT_ENABLED：必开启！保障API通信安全
• JWT_SECRET：后端Java代码需保持一致
• 目录挂载：避免容器更新时数据丢失验证安装：访问 http://服务器IP:8080 出现欢迎页即部署成功

三、前端接入（Vue3 + OnlyOffice API）（此为大模型生成代码片段）

具体可以参考onlyoffice官方文档：
https://api.onlyoffice.com/zh-CN/docs/docs-api/get-started/basic-concepts/

步骤1：引入官方编辑组件

 <!-- 在index.html头部添加 -->
 <script src="http://onlyoffice-server:8080/web-apps/apps/api/documents/api.js"></script>

步骤2：封装Vue编辑器组件

<template>
  <div id="editor" style="height:800px"></div>
</template>


<script setup>
import { ref, onMounted } from 'vue';


const props = defineProps({
  config: {
    type: Object,
    required: true
  }
});


let docEditor = null;


onMounted(() => {
  window.Asc.plugin.init(() => {
    docEditor = new window.Asc.CEditor('editor');
    docEditor.init(props.config);
  });
});
</script>

配置模板示例：

const config = {
  document: {
    fileType: 'docx',
    key: Date.now(), // 唯一标识！协同必用
    title: '合同草案.docx',
    url: 'https://your-domain.com/file/download?fileId=123'
  },
  documentType: 'word',
  token: jwtToken // 后端生成
  editorConfig: {
    callbackUrl: 'https://your-domain.com/save?fileId=123', // 文档保存回调接口
    user: { 
      id: 'user-001', 
      name: '张三' 
    },
    customization: {
      autosave: true, // 开启自动保存
      compactToolbar: true // 简化工具栏
    }
  }
}

四、后端集成（Java SpringBoot）（此为大模型生成代码片段）

具体可以参考onlyoffice官方文档：
https://api.onlyoffice.com/zh-CN/docs/docs-api/get-started/basic-concepts/

核心1：生成安全令牌

import io.jsonwebtoken.Jwts;
import javax.crypto.spec.SecretKeySpec;


public String generateToken(Map<String, Object> claims) {
  return Jwts.builder()
    .setClaims(claims)
    .signWith(new SecretKeySpec(jwtSecret.getBytes(), "HmacSHA256"))
    .compact();
}

核心2：保存回调处理（重要，回调函数）

@PostMapping("/save")
public ResponseEntity<?> saveCallback(@RequestBody SaveRequest request) {
  // 1. 验证JWT签名（防止恶意请求）
  if (!jwtUtil.verify(request.getToken())) {
    return ResponseEntity.status(403).build();
  }


  // 2. 获取文档变更下载链接
  String fileUrl = request.getUrl();


  // 3. 发起HTTP请求下载新版文件
  byte[] newFile = restTemplate.getForObject(fileUrl, byte[].class);


  // 4. 覆盖原文件（如OSS/MinIO存储）
  storageService.upload(request.getKey(), newFile);


  return ResponseEntity.ok().build();
}

对象映射示例（SaveRequest.java）：

@Data
public class SaveRequest {
    @JsonProperty("key")
    private String key; // 与前端初始化时的key对应


    @JsonProperty("url")
    private String url; // OnlyOffice服务生成的临时下载地址


    @JsonProperty("token")
    private String token; // JWT验证凭据


    // 注意：实际字段高达30+，推荐用Map接收后取关键值
}

前端和onlyoffice服务端之间主要是通过加密后的token进行权限校验，所以需要我们后端服务生成加密的token，里面常常会封装一系列参数配置，常用的一些配置参数

详细的配置信息请看官方文档：
https://api.onlyoffice.com/zh-CN/docs/docs-api/usage-api/advanced-parameters/

下图为测试项目中的一些配置信息

下图是接入后的实际效果

五、常见配置处理

1、主题色

主题色变更需要在onlyoffice服务内，

/var/www/onlyoffice/documentserver/web-apps/apps/common/main/resources/themes

目录下增加自己的主题配置文件，test-theme.json

{
    "colors": {
        "toolbar-header-document": "#5f9fff",
        "toolbar-header-spreadsheet": "#5ec9a6",
        "toolbar-header-presentation": "#ff7b7b",
        "toolbar-header-pdf": "#ffbf5c"
    },
    "id": "theme-test",
    "name": "Test theme",
    "type": "light"
}

对应的色彩

2、字体文件

字体范围尽可能提前上传一些常用字体，删除内置的一些不用的字体，防止生成的文件需要业务上做其他的一些处理的时候无法读取正确的内容。字体需要上传字体到容器里/usr/share/fonts下，然后在/usr/bin下执行
./documentserver-generate-allfonts.sh

执行成功后可以到/usr/share/fonts/truetype下看是否已经加载进去新增的字体

3、前端跨域问题

可以通过nginx配置转发请求，解决前端跨域问题（当前版本是7.5.1）

location ~ ^/(web-apps|7.5.1-23) {
        proxy_pass http://192.168.1.222:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header REMOTE-HOST $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto  $scheme;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_buffer_size 2048k;
        proxy_buffers 16 2048k;
        proxy_busy_buffers_size 5048k;
        proxy_temp_file_write_size 5048k;
    }
    location ~ ^/cache/files {
        proxy_pass http://192.168.1.222:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header REMOTE-HOST $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto  $scheme;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_buffer_size 2048k;
        proxy_buffers 16 2048k;
        proxy_busy_buffers_size 5048k;
        proxy_temp_file_write_size 5048k;
    }

六、避坑指南：高频问题解决方案

Q1：字体缺失导致中文乱码？

dockercp /fonts/simsun.ttc onlyoffice:/usr/share/fonts

2. 重建字体缓存：

docker exec onlyoffice bash -c "apt update && apt install -y xfonts-utils"
docker exec onlyoffice bash -c "/usr/bin/documentserver-generate-allfonts.sh"

Q2：协同编辑时用户名称显示为“未知用户”？

• 原因：未正确传递user配置
• 检查：前端config中的user.id必须为非空字符串

Q3：文档保存后出现副本文件？

• 根因：回调接口未正确处理版本覆盖
• 方案：在Java下载文件时，先删除OSS存储中的旧文件再上传

Q4：前端请求跨域问题（CORS）？

在Nginx配置：

location ~ ^/(web-apps|7.5.1-23) {
        proxy_pass http://192.168.1.222:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header REMOTE-HOST $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto  $scheme;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_buffer_size 2048k;
        proxy_buffers 16 2048k;
        proxy_busy_buffers_size 5048k;
        proxy_temp_file_write_size 5048k;
    }
    location ~ ^/cache/files {
        proxy_pass http://192.168.1.222:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header REMOTE-HOST $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto  $scheme;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_buffer_size 2048k;
        proxy_buffers 16 2048k;
        proxy_busy_buffers_size 5048k;
        proxy_temp_file_write_size 5048k;
    }

Q5: 下载失败（常见错误）

检查：在编辑器加载过程中会显示"下载失败"消息。

文档编辑服务无法上传文件进行编辑。

检查 document.url 中指定的文件的链接是否正确。该链接必须可以从文档编辑服务访问。

Q6: 没有变化（常见错误）

检查：编辑后关闭编辑器时，文档管理器中的文件不变。

文档编辑服务无法将数据发送到文档存储服务。

检查 editorConfig.callbackUrl 链接是否正确。文档管理器中的保存必须通过回调处理程序实现。

Q7: 无法保存（常见错误）

编辑器加载了"无法保存文档"消息。

文档编辑服务无法连接到 editorConfig.callbackUrl 地址的文档存储服务。

检查回调处理程序是否正常工作。文档存储服务必须返回 {"error": 0}作为响应。

Q8: 文件版本已更改（常见错误）

检查：编辑器加载了"文件版本已更改。将重新加载页面"消息。

文档编辑服务无法打开之前编辑和保存过的文件来进行编辑。

不要忘记，每次编辑和保存文档时，都必须重新生成document.key。

Q9: 文件版本打不开

检查：文档编辑服务无法打开文件版本。

检查 setHistoryData 方法中的changesUrl链接是否与previous.url参数对应。Q10: 没有协作编辑

检查：当不同用户打开文档进行编辑时，无法进行共同编辑。

文档编辑服务打开两个不同的文件进行编辑。

检查document.key值是否一致以便能够共同编辑同一个文档。key 值在保存后必须改变，不同文档必须不同，并且在共同编辑同一个文档时必须相同。

Q11: 令牌无效

编辑器加载了"文档安全令牌没有正确生成。请联系您的文档服务器管理员"消息。

文档编辑服务会请求一个加密签名。

检查牌是否正确。令牌必须根据 JWT（JSON Web 令牌）标准生成并存在于 ONLYOFFICE 文档服务器配置中。

Q12: 拒绝访问

编辑器加载时显示“您正在尝试执行您无权执行的操作。请联系您的文档服务器管理员。”消息。

文档编辑服务无法执行用户请求的操作。

此问题可能由于以下原因而发生：

• 这是编辑器的错误，它传递了服务器检查认为存在安全违规的参数。
• 更改浏览器中打开的配置中的访问权限（可能是与错误填写缺失配置字段相关的编辑器错误）。
• 尝试在查看器中保存文档或编辑器错误地在查看器中打开。
• 执行了 downloadAs 方法，但用户无权下载文档。
• 更改用户名（仅限匿名用户）。
• 错误原因不仅限于提供的示例。此列表还可扩展。
• 更多的故障排查可参考官方文档：https://api.onlyoffice.com/zh-CN/docs/docs-api/more-information/troubleshooting/

七、性能优化建议

1. 分离存储：文档存放至OSS/S3，OnlyOffice服务仅做编辑
2. 负载均衡：通过Nginx横向扩展Documentserver节点
3. 文件预览优化：用onlyoffice-documentserver-ie包替代全功能包

结语

近期又有接入OnlyOffice，对接步骤和问题又得重新来一遍，很浪费时间，整理下前期对接中的一些经验文字，主要是问题解决思路，以供参考。

OnlyOffice的深度整合大幅提升了企业文档处理效率，且避免了SaaS服务的数据安全风险。要想获得更多的使用体验，详细可参考官方文档
https://api.onlyoffice.com/zh-CN/docs