OnlyOffice 编译操作全整理

前言

build_tools 是 ONLYOFFICE 官方开源构建工具仓库，用于自动化拉取源码、环境配置、跨平台编译打包 文档服务、桌面编辑器、转换服务 等核心组件，也是自研定制、离线编译、私有化部署 ONLYOFFICE 的核心工具。本文结合官方 README 文档、目录架构、核心编译脚本，完整讲解目录作用、编译参数、两种编译流程以及最终部署上线全流程。

build_tools 核心功能介绍

该工具集核心作用：统一管理 ONLYOFFICE 全产品线源码拉取、环境依赖校验、多平台编译、资源打包、基础部署预处理，彻底解决跨系统编译环境不一致、编译流程繁琐、版本混乱等问题。

develop 介绍

develop 分为根目录 develop与scripts/develop两大模块，专为源码二次开发、本地调试而生，不属于正式生产编译流程。

1. 核心定位

   面向开发者调试源码、修改前端页面、定制服务逻辑、本地快速测试，轻量化优先，不做严格环境约束。

2. 核心功能

   • 提供开发专用 Docker 环境，一键搭建调试编译容器；

   • 内置前端 JS 独立编译脚本，无需全量编译即可快速改样式、改交互；

   • 封装源码分支切换、本地依赖调试、开发环境配置脚本；

   • 支持 LibreOffice 底层依赖本地编译调试，适配底层格式转换定制；

   • 提供开发模式服务快速启动脚本，方便修改代码即时验证效果。

3. 使用场景

   源码二次开发、功能定制、前端页面修改、本地问题调试、功能自测。

tools 介绍

tools 是正式编译、标准化构建的核心目录，按操作系统划分子目录，是线上编译打包的唯一推荐入口。

1. 核心定位

   统一标准化编译流程，完成系统依赖安装、编译环境初始化、跨架构适配、一键批量编译。

2. 核心功能

   • 分平台管理：linux/win/mac 独立编译工具链，适配不同系统编译规则；

   • 自动依赖安装：内置 deps.py 一键补齐编译所需系统库、Qt 环境、编译工具；

   • 封装一键编译入口 automate.py，整合配置、编译、打包全流程；

   • 支持跨架构编译配置，提供 sysroot 环境适配，实现 x86_64、arm64 架构编译；

   • 编译前环境强校验，提前拦截依赖缺失、版本不匹配等编译错误。

3. 使用场景

   正式版本编译、离线包制作、服务器批量构建、集群部署前置打包。

编译介绍

build_tools 编译依靠三大核心脚本协同完成，configure.py 预配置、make.py 核心编译、automate.py 一键封装，所有编译场景均通过以下参数控制。

1. 三大核心脚本职责

• configure.py：编译前置配置脚本，定义编译平台、架构、模块、源码更新规则；

• make.py：真正执行编译、资源打包、产物生成的核心脚本；

• automate.py：Linux 平台一键整合脚本，自动装依赖 + 调用配置 + 调用编译，最简使用。

2. 高频通用编译参数

3. 常用精简编译命令

# 1. 仅编译文档服务server（最常用）
python3 automate.py --module=server

# 2. 指定编译v9.4.0版本服务端
python3 automate.py --branch=v9.4.0.131 --module=server

# 3. 编译Linux arm64架构文档服务
python3 automate.py --platform=linux --arch=arm64 --module=server --sysroot=1

# 4. 仅编译前端JS资源
python3 make.py OO_ONLY_BUILD_JS=1

# 5. 不更新源码，本地离线编译
python3 configure.py --update=0 --module=server

linux 编译过程（原生宿主机编译）

适合本地服务器长期搭建编译环境，可反复增量编译，完整可直接执行流程：

1. 安装基础依赖

apt update && apt install -y git python3 python3-pip vim

2. 克隆指定版本 build_tools 仓库

git clone -b v9.4.0.131 https://github.com/ONLYOFFICE/build_tools.git
cd build_tools

3. 进入 Linux 编译工具目录

cd tools/linux

4. 自动安装编译全量依赖

python3 deps.py

5. 执行一键编译（仅编译文档服务）

python3 automate.py --module=server

6. 等待编译完成，查看编译产物

编译成功后产物默认输出路径：

build_tools/out/linux_64/onlyoffice/documentserver/

7. 编译结束校验

进入产物目录，确认 DocService、FileConverter 等核心二进制文件生成无误。

Docker 编译过程（推荐首选）

优势：环境完全隔离、不污染宿主机、编译结果统一、零基础可上手、适配所有 Linux 系统，也是官方 README 主推编译方式。

1. 前置准备

宿主机安装 Docker 环境

bash <(curl -sSL https://linuxmirrors.cn/docker.sh)

2. 拉取仓库并进入根目录

git clone -b v9.4.0.131 https://github.com/ONLYOFFICE/build_tools.git
cd build_tools

3. 构建 ONLYOFFICE 专属编译镜像

docker build --tag onlyoffice-builder .

4. 启动容器执行编译，挂载产物到宿主机

mkdir -p out
docker run -d -v $PWD/out:/build_tools/out onlyoffice-builder

5. 实时查看编译进度

docker logs -f $(docker ps -lq)

6. 编译完成获取产物

容器内编译完成后，宿主机 out 目录自动同步全部编译好的服务端程序，无需手动拷贝，直接拿来部署使用。

部署运行过程

编译完成拿到 documentserver 完整程序包后，即可完成本地开发部署与正式运行，分为开发嵌入式运行与独立服务运行两种模式。

1. 梳理编译产物核心目录

documentserver/
├── server/                # 所有服务二进制文件
│   ├── DocService/        # 主文档服务 端口8000
│   ├── FileConverter/     # 文档转换服务
│   └── Common/config/     # 全局配置文件目录
└── ...

2. 运行前置环境

开发测试模式无需安装 RabbitMQ、Redis，仅需配置环境变量即可启动。

3. 开发模式启动（嵌入式转换器，最简运行）

1. 进入主服务目录

cd ~/build_tools/out/linux_64/onlyoffice/documentserver/server/DocService

1. 执行启动命令（固定环境变量）

NODE_ENV=development-linux NODE_CONFIG_DIR=$PWD/../Common/config ./docservice

1. 启动成功标识

   日志输出：Express server listening on port 8000、embedded converter started

   代表主服务 + 内置转换器全部启动成功。

4. 独立转换服务启动（分离部署）

如需拆分服务、提升并发，单独启动转换服务：

cd ../FileConverter
LD_LIBRARY_PATH=$PWD/bin NODE_ENV=development-linux NODE_CONFIG_DIR=$PWD/../Common/config ./converter --parent-port=5000

5. 后台守护运行（正式测试使用）

使用 nohup 放置进程后台运行，关闭终端不停止服务

nohup NODE_ENV=development-linux NODE_CONFIG_DIR=$PWD/../Common/config ./docservice > doc.log 2>&1 &

6. 访问验证

浏览器访问服务器 IP+8000 端口

http://服务器IP:8000

能够正常访问页面即部署运行成功。

7. 日常运维启停

• 查看运行端口：ss -tulpn | grep 8000

• 停止服务：kill -9 进程ID

• 查看运行日志：tail -f doc.log

8. 生产环境补充说明

若用于企业正式线上环境，需额外部署 RabbitMQ+Redis+PostgreSQL，修改配置文件关闭开发模式、开启 JWT 令牌鉴权，关闭嵌入式转换器，使用独立集群化部署架构。