OnlyOffice 如何构建开发镜像并代码调试？

在 OnlyOffice 的开发过程中，经常需要对 sdkjs、web-apps 或 server 模块进行修改和调试。本文将详细介绍如何搭建 OnlyOffice 开发环境，实现代码的实时调试和修改，而无需重新编译整个复杂的核心产品。

1 系统要求

1.1 Windows 系统

需要安装最新版本的 Docker Desktop for Windows。

注意：Docker Desktop 安装后不会自动启动，需要手动启动 Docker Desktop 应用程序。

注意：如果在使用 “Use WSL 2 instead of Hyper-V” 安装选项时遇到问题，请尝试不使用此选项重新安装。

1.2 Linux 或 macOS 系统

需要安装最新版本的 Docker。

2 创建开发 Docker 镜像

为了创建能够包含外部非压缩 sdkjs 代码的镜像，需要执行以下命令：

2.1 克隆开发环境到工作目录

git clone https://github.com/ONLYOFFICE/build_tools.git

2.2 修改 Docker 镜像

注意：不要在 docker 命令前加 sudo。这里 有说明如何在不使用 sudo 的情况下使用 docker。

cd build_tools/develop
docker pull onlyoffice/documentserver
docker build --no-cache -t documentserver-develop .

注意：末尾的点是必需的。

注意：有时脚本可能因网络错误而失败，只需重新启动即可。

3 克隆开发模块

将开发模块克隆到工作目录：


sdkjs 仓库位于 这里
web-apps 仓库位于 这里
server 仓库位于 这里

git clone https://github.com/ONLYOFFICE/sdkjs.git
git clone https://github.com/ONLYOFFICE/web-apps.git
git clone https://github.com/ONLYOFFICE/server.git

4 启动带有外部文件夹的服务器

要将外部文件夹挂载到容器中，需要传递 “-v” 参数以及所需文件夹的相对路径。文件夹
sdkjs 和
web-apps 是正常开发工作流程所必需的。文件夹
server 是可选的。

注意：在包含
sdkjs、
web-apps… 的当前工作目录中运行命令。

注意：ONLYOFFICE 服务器使用端口 80。查找使用端口 80 的其他应用程序并停止它。

注意：使用
sdkjs 和
web-apps 启动服务器需要 15 分钟，使用
server 需要 20 分钟。

4.1 Windows (PowerShell) 上的 docker run

注意：以管理员身份运行 PowerShell 以修复安装 node_modules 时的 EACCES 错误。

使用
sdkjs 和
web-apps 运行：

docker run -i -t -p 80:80 --restart=always -e ALLOW_PRIVATE_IP_ADDRESS=true -e JWT_ENABLED=false -v $pwd/sdkjs:/var/www/onlyoffice/documentserver/sdkjs -v $pwd/web-apps:/var/www/onlyoffice/documentserver/web-apps documentserver-develop

或使用
sdkjs、
web-apps 和
server 运行：

docker run -i -t -p 80:80 --restart=always -e ALLOW_PRIVATE_IP_ADDRESS=true -e JWT_ENABLED=false -v $pwd/sdkjs:/var/www/onlyoffice/documentserver/sdkjs -v $pwd/web-apps:/var/www/onlyoffice/documentserver/web-apps -v $pwd/server:/var/www/onlyoffice/documentserver/server documentserver-develop

4.2 Linux 或 macOS 上的 docker run

使用
sdkjs 和
web-apps 运行：

docker run -i -t -p 80:80 --restart=always -e ALLOW_PRIVATE_IP_ADDRESS=true -e JWT_ENABLED=false -v $(pwd)/sdkjs:/var/www/onlyoffice/documentserver/sdkjs -v $(pwd)/web-apps:/var/www/onlyoffice/documentserver/web-apps documentserver-develop

或使用
sdkjs、
web-apps 和
server 运行：

docker run -i -t -p 80:80 --restart=always -e ALLOW_PRIVATE_IP_ADDRESS=true -e JWT_ENABLED=false -v $(pwd)/sdkjs:/var/www/onlyoffice/documentserver/sdkjs -v $(pwd)/web-apps:/var/www/onlyoffice/documentserver/web-apps -v $(pwd)/server:/var/www/onlyoffice/documentserver/server documentserver-develop

5 打开编辑器

服务器成功启动后，您将看到类似这样的 Docker 日志消息：

[Date] [WARN] [localhost] [docId] [userId] nodeJS

要尝试文档编辑器，请打开浏览器标签页并在 URL 栏中输入 http://localhost/example。

注意：为 localhost 页面禁用广告拦截器。它可能会阻止某些脚本（如 Analytics.js）。

6 修改源代码

6.1 修改
sdkjs 中的内容

以下步骤演示如何在每个打开的文档中插入图片 URL：

编辑源文件。让我们在每个打开的文档中插入一个图片 URL。
以下命令在事件
this.sendEvent('asc_onDocumentContentReady'); 之后插入（如果有问题，您可以替换 URL）

this.AddImageUrl(['http://localhost/example/images/logo.png']);
在文件
sdkjs/common/apiBase.js 中。

Windows (PowerShell) 上修改 sdkjs

(Get-Content sdkjs/common/apiBase.js) -replace "this.sendEvent('asc_onDocumentContentReady');", "this.sendEvent('asc_onDocumentContentReady');this.AddImageUrl(['http://localhost/example/images/logo.png']);"  | Set-Content sdkjs/common/apiBase.js

Linux 或 macOS 上修改 sdkjs

sed -i "s,this.sendEvent('asc_onDocumentContentReady');,this.sendEvent('asc_onDocumentContentReady');this.AddImageUrl(['http://localhost/example/images/logo.png']);," sdkjs/common/apiBase.js

删除浏览器缓存或硬刷新页面
Ctrl + Shift + R

在浏览器中打开新文件

6.2 修改
server 中的内容

以下步骤演示如何在每次打开文档时发送
"Hello World!" 聊天消息：

编辑源文件。让我们在每次打开文档时发送
"Hello World!" 聊天消息。
以下命令在函数
sendAuthInfo 中插入
yield* onMessage(ctx, conn, {"message": "Hello World!"});
在文件
server/DocService/sources/DocsCoServer.js 中。

Windows (PowerShell) 上修改 server

(Get-Content server/DocService/sources/DocsCoServer.js) -replace 'opt_hasForgotten, opt_openedAt) {', 'opt_hasForgotten, opt_openedAt) {yield* onMessage(ctx, conn, {"message": "Hello World!"});' | Set-Content server/DocService/sources/DocsCoServer.js

Linux 或 macOS 上修改 server

sed -i 's#opt_hasForgotten, opt_openedAt) {#opt_hasForgotten, opt_openedAt) {yield* onMessage(ctx, conn, {"message": "Hello World!"});#' server/DocService/sources/DocsCoServer.js

重启文档服务器进程

注意：在
docker ps 的结果中查找
CONTAINER_ID。

docker exec -it CONTAINER_ID supervisorctl restart all

在浏览器中打开新文件

7 启动带有附加功能（插件）的服务器

要获得附加功能和品牌，您需要连接品牌文件夹、附加插件文件夹并传递命令行参数。

例如，使用
onlyoffice 品牌和插件：
sdkjs-forms、
sdkjs-ooxml、
web-apps-mobile 运行：

7.1 Windows (PowerShell) 上使用品牌的 docker run

注意：以管理员身份运行 PowerShell 以修复安装 node_modules 时的 EACCES 错误。

docker run -i -t -p 80:80 --restart=always -e ALLOW_PRIVATE_IP_ADDRESS=true -e JWT_ENABLED=false `
    -v $pwd/sdkjs:/var/www/onlyoffice/documentserver/sdkjs -v $pwd/web-apps:/var/www/onlyoffice/documentserver/web-apps `
    -v $pwd/onlyoffice:/var/www/onlyoffice/documentserver/onlyoffice -v $pwd/sdkjs-ooxml:/var/www/onlyoffice/documentserver/sdkjs-ooxml -v $pwd/sdkjs-forms:/var/www/onlyoffice/documentserver/sdkjs-forms -v $pwd/web-apps-mobile:/var/www/onlyoffice/documentserver/web-apps-mobile `
    documentserver-develop args --branding onlyoffice --branding-url 'https://github.com/ONLYOFFICE/onlyoffice.git' --siteUrl localhost

7.2 Linux 或 macOS 上使用品牌的 docker run

docker run -i -t -p 80:80 --restart=always -e ALLOW_PRIVATE_IP_ADDRESS=true -e JWT_ENABLED=false 
    -v $(pwd)/sdkjs:/var/www/onlyoffice/documentserver/sdkjs -v $(pwd)/web-apps:/var/www/onlyoffice/documentserver/web-apps 
    -v $(pwd)/onlyoffice:/var/www/onlyoffice/documentserver/onlyoffice -v $(pwd)/sdkjs-ooxml:/var/www/onlyoffice/documentserver/sdkjs-ooxml -v $(pwd)/sdkjs-forms:/var/www/onlyoffice/documentserver/sdkjs-forms -v $(pwd)/web-apps-mobile:/var/www/onlyoffice/documentserver/web-apps-mobile 
    documentserver-develop args --branding onlyoffice --branding-url 'https://github.com/ONLYOFFICE/onlyoffice.git' --siteUrl localhost

8 开发调试技巧

8.1 实时代码修改

通过挂载本地代码目录到容器中，您可以直接在本地编辑器中修改代码，修改会立即反映到运行的服务器中。这大大提高了开发效率。

8.2 日志查看

可以通过以下命令查看容器日志：

docker logs -f CONTAINER_ID

8.3 进入容器调试

如果需要在容器内部进行调试，可以使用：

docker exec -it CONTAINER_ID bash

8.4 重启服务

当修改了 server 端代码后，需要重启相关服务：

docker exec -it CONTAINER_ID supervisorctl restart all

9 常见问题

9.1 端口冲突

如果端口 80 被占用，可以修改端口映射：

-p 8080:80  # 使用 8080 端口访问

9.2 权限问题

在 Windows 上，确保以管理员身份运行 PowerShell。在 Linux 上，确保当前用户在 docker 组中。

9.3 网络问题

如果遇到网络问题，可以尝试使用国内镜像源或配置代理。

通过本指南，您可以快速搭建 OnlyOffice 开发环境，实现高效的代码调试和开发工作流程。这种方式避免了每次修改都需要重新编译整个项目的繁琐过程，大大提升了开发效率。