当前位置：首页 > article >正文

OnlyOffice 全面指南：从基础使用到深度自定义

article 2025/2/8 15:03:18

一、基础概念

1.1 OnlyOffice 是什么？

OnlyOffice 是一款开源的办公套件，提供文档处理、电子表格、幻灯片编辑等功能，支持实时协作和云端存储集成。其核心组件包括：

Document Server：负责文档渲染与协作的核心服务。
Integration Example：与Nextcloud、OwnCloud等平台集成的示例代码库。
前端编辑器：基于Web的WYSIWYG编辑器界面。

1.2 核心功能特性

实时协作（多人同时编辑）
版本历史与恢复
支持Office格式（DOCX, XLSX, PPTX）及ODF
跨平台兼容性（Windows/Linux/macOS）

二、基础使用文档

2.1 安装与启动

Docker部署(推荐)

docker run -i -t -d -p 9898:80 --name onlyoffice --restart=always -e TZ="Asia/Shanghai" \
-v /usr/local/onlyoffice/logs:/var/log/onlyoffice \
-v /usr/local/onlyoffice/data:/var/www/onlyoffice/Data \
-v /usr/local/onlyoffice/lib:/var/lib/onlyoffice \
-v /usr/local/onlyoffice/db:/var/lib/postgresql \
-e JWT_ENABLED=false onlyoffice/documentserver:latest

如果需要开启jwt验证，则使用下面的命令

docker run -i -t -d -p 9898:80 --name onlyoffice --restart=always -e TZ="Asia/Shanghai" \
-v /usr/local/onlyoffice/logs:/var/log/onlyoffice \
-v /usr/local/onlyoffice/data:/var/www/onlyoffice/Data \
-v /usr/local/onlyoffice/lib:/var/lib/onlyoffice \
-v /usr/local/onlyoffice/db:/var/lib/postgresql \
-e JWT_ENABLED=true \
-e JWT_SECRET=wclflow \
-e JWT_HEADER=token \
onlyoffice/documentserver:latest

检查是否安装成功，访问web页面(如果访问不了，查看是否防火墙问题)

http://容器所在主机IP:9898/welcome/

在这里插入图片描述
出现上图，则表示onlyoffice服务安装成功

关键目录说明

/var/log/onlyoffice：日志文件存放位置
/var/www/onlyoffice/Data：文档存储与配置文件

前端页面配置：

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title>Title</title>
    <!-- 此处的ip,我onlyoffice所在的机器ip是192.168.7.46，你要改成你自己的服务IP -->
    <script src="http://192.168.7.46:9898/web-apps/apps/api/documents/api.js"></script>
</head>
<body style="margin:0px;padding:0px;">
    <div id="placeholder" class = "nav" style="width:100%;height:100%;min-height:900px;"></div>
</body>
<script>
    new DocsAPI.DocEditor("placeholder", {
        "document": {
            "fileType": "docx", //文件类型，我用的docx文件，你可以根据需要改其他格式等
            "key": "12qNAFE", //文件key，确保唯一就行,这里的key跟多人协同编辑有关
            "title": "aaa测试.docx", //文件名称
            "url": "http://192.168.2.67:8888/group1/M00/03/38/wKgCQ2aGTaCAMYg8AAAoaT_K4_U80.docx" //文件地址，你可以根据需要改其他地址，前提是本地或外网能够访问的到
        },
 
        "documentType": "word",//文件类型，上面的fileType进行对应匹配
        "type": "desktop",
        "width": "100%",
        "height": "900px",
        "editorConfig": {
            "callbackUrl": ""  // 修改保存后回调地址
        },
        "permissions": {
            "edit": false,  // 可编辑
            "comment": true, // 可评论
            "download": true, // 可下载
            "fillForms": true, // 
            "print": true, // 可打印
            "review": true // 可预览
        },
        "token":"如果你开启了jwt验证，则这里必须填写jwttoken,jwttoken最好由后台提供，后台具体怎么生成jwttoken，百度一下"
    });
</script>
</html>

三、常见配置错误与解决方案

3.1 端口冲突问题

错误现象：

Address already in use 或无法启动服务
解决方案：

# 查找占用端口的进程
sudo lsof -i :80

# 修改OnlyOffice端口
编辑 /etc/onlyoffice/documentserver/local.json
{
  "server": {
    "port": 8080  # 改为空闲端口
  }
}

3.2 存储权限问题

错误日志：

Error: EACCES: permission denied, mkdir ‘/var/www/onlyoffice/Data’
修复步骤：

sudo chown -R onlyoffice:onlyoffice /var/www/onlyoffice/Data
sudo chmod -R 755 /var/www/onlyoffice

3.3 SSL证书配置错误

典型报错：

SEC_ERROR_UNKNOWN_ISSUER 或页面加载不完全

正确配置方法：

{
  "server": {
    "https": {
      "cert": "/path/to/fullchain.pem",
      "key": "/path/to/privkey.pem"
    }
  }
}

重启服务后执行：

sudo supervisorctl restart all

四、深度自定义指南

4.1 界面主题定制

修改CSS文件实现主题换肤：

css
/* /var/www/onlyoffice/documentserver/web-apps/apps/documenteditor/main/styles/colors.css /
:root {
–color-primary: #2ecc71; / 修改主色调 */
–header-background: #34495e;
}

4.2 插件开发

myplugin/
├── config.json
├── index.html
└── code.js

示例 config.json：

{
  "name": "WordCounter",
  "guid": "asc.{FFE1F462-1EA2-4396-BF25-7DA4F64C535D}",
  "basePath": "/myplugin/",
  "initData": {"url": "code.js"}
}

4.3 Webhook集成

配置实时通知（以Node.js示例）：

app.post('/webhook', (req, res) => {
  const { event, data } = req.body;
  if (event === 'document.changed') {
    console.log(`文档 ${data.key} 被修改`);
  }
  res.status(200).end();
});