# 17.11 OnlyOffice 部署（基于 PostgreSQL）

OnlyOffice 是一个开源的在线文档编辑器，可以与 Nextcloud 等平台集成。本节将介绍基于 PostgreSQL 数据库在 FreeBSD 上部署 OnlyOffice 的方法。

## 安装 Nextcloud 和 Nginx

OnlyOffice 需要与 Nextcloud 配合使用，首先请读者在其他机器上安装 Nextcloud 和 Nginx。

## 安装 OnlyOffice

Nextcloud 和 Nginx 准备好后，可以开始安装 OnlyOffice 文档服务器。

使用 pkg 包管理器安装 OnlyOffice 是最快捷的方式，执行以下命令即可完成安装。

```sh
# pkg install onlyoffice-documentserver
```

或者使用 Ports 方式安装 OnlyOffice，需要先进入对应的目录再执行编译安装命令。

```sh
# cd /usr/ports/www/onlyoffice-documentserver/ 
# make install clean
```

## 查看 OnlyOffice 安装信息

目录结构：

```sh
/
├── usr
│   └── local
│       ├── etc
│       │   ├── onlyoffice
│       │   │   └── documentserver
│       │   │       ├── local.json                      # OnlyOffice 本地配置文件
│       │   │       ├── default.json                    # OnlyOffice 默认配置文件
│       │   │       ├── nginx
│       │   │       │   └── ds.conf                     # OnlyOffice Nginx 配置
│       │   │       └── supervisor
│       │   │           └── *.conf                      # OnlyOffice supervisord 配置
│       │   └── supervisord.conf                        # supervisord 主配置文件
│       ├── bin
│       │   ├── documentserver-pluginsmanager.sh       # 插件管理器脚本
│       │   └── documentserver-update-securelink.sh    # 安全链接更新脚本
│       └── www
│           └── onlyoffice
│               └── documentserver
│                   └── server
│                       └── schema
│                           ├── postgresql
│                           │   ├── createdb.sql      # PostgreSQL 数据库创建脚本
│                           │   └── upgrade           # PostgreSQL 升级脚本
│                           └── mysql
│                               ├── createdb.sql      # MySQL 数据库创建脚本
│                               └── upgrade           # MySQL 升级脚本
└── var
    ├── log
    │   └── onlyoffice
    │       └── documentserver
    │           └── converter
    │               └── out.log                        # OnlyOffice 日志文件
    └── db
        └── rabbitmq
            └── .erlang.cookie                          # RabbitMQ Erlang Cookie
```

安装完成后，建议查看安装包的说明文档，了解必要的配置和注意事项：

```sh
# pkg info -D onlyoffice-documentserver
onlyoffice-documentserver-8.2.0.143_4:
On install:
CONFIGURATION:
-------------
# 配置：
# 以下是有关如何配置 OnlyOffice 文档服务器的详细说明。

The configuration file can be found (or created) at the following path:
  /usr/local/etc/onlyoffice/documentserver/local.json
# 配置文件位于以下路径（或创建）：
# /usr/local/etc/onlyoffice/documentserver/local.json

The default values are available in the default.json configuration file,
which is available in the folders above. Please do not edit the contents of the
default.json file directly. The default values will be restored each time you
upgrade Document Server to a new version and all your changes will be lost.
# 默认值可以在 default.json 配置文件中找到，该文件位于上述文件夹中。
# 请不要直接编辑 default.json 文件的内容，因为每次升级文档服务器时，所有更改都会丢失，恢复默认值。

1. Enable services at startup in the /etc/rc.conf file:
  nginx_enable="YES"
  rabbitmq_enable="YES"
  supervisord_enable="YES"
# 1. 在 /etc/rc.conf 文件中启用启动时的服务：
#   设置 nginx_enable="YES"
#   设置 rabbitmq_enable="YES"
#   设置 supervisord_enable="YES"

  Optionally in case of a jail with local IP and no internet access:
    update /etc/hosts in order to resolve your nextcloud server to its local IP
# 如果在没有互联网访问的 jail 环境中运行（本地 IP），可以选择：
# 更新 /etc/hosts 文件，以将 Nextcloud 服务器解析到其本地 IP。

2. Install a database server and set up the database (either PostgreSQL or MySQL):
  For PostgreSQL (don't forget to change the password):
    # service postgresql initdb
    # service postgresql start
    # psql -U postgres -c "CREATE DATABASE onlyoffice;"
    # psql -U postgres -c "CREATE USER onlyoffice WITH password 'onlyoffice';"
    # psql -U postgres -c "GRANT ALL privileges ON DATABASE onlyoffice TO onlyoffice;"
    # psql -U postgres -c "ALTER DATABASE onlyoffice OWNER to onlyoffice;"
    # psql -hlocalhost -Uonlyoffice -d onlyoffice -f /usr/local/www/onlyoffice/documentserver/server/schema/postgresql/createdb.sql
# 2. 安装数据库服务器并设置数据库（可选 PostgreSQL 或 MySQL）：
# 对于 PostgreSQL（别忘了更改密码）：
#   初始化数据库、启动 PostgreSQL 服务并创建所需数据库和用户。

    Optionally in case of a jail with local IP:
      update /var/db/postgres/data13/pg_hba.conf accordingly
# 如果是在本地 IP 的 jail 环境中运行，还可以选择更新 /var/db/postgres/data13/pg_hba.conf 文件。

  For MySQL don't forget to change the password):
    # service mysql-server start
    # mysql -u root -p -e "CREATE DATABASE onlyoffice DEFAULT CHARACTER SET utf8 DEFAULT COLLATE utf8_general_ci;"
    # mysql -u root -p -e "CREATE USER 'onlyoffice'@'localhost' IDENTIFIED BY 'onlyoffice';"
    # mysql -u root -p -e "GRANT ALL privileges ON  onlyoffice.* TO 'onlyoffice'@'localhost';"
    # mysql -u onlyoffice -D onlyoffice -p < /usr/local/www/onlyoffice/documentserver/server/schema/mysql/createdb.sql
# 对于 MySQL（别忘了更改密码）：
#   启动 MySQL 服务并创建所需数据库、用户及权限。

3. Create a new rabbitmq user for the ONLYOFFICE Document Server configuration (don't forget to change the password):
  # service rabbitmq start
  # rabbitmqctl --erlang-cookie `cat /var/db/rabbitmq/.erlang.cookie` add_user onlyoffice password
  # rabbitmqctl --erlang-cookie `cat /var/db/rabbitmq/.erlang.cookie` set_user_tags onlyoffice administrator
  # rabbitmqctl --erlang-cookie `cat /var/db/rabbitmq/.erlang.cookie` set_permissions -p / onlyoffice ".*" ".*" ".*"
  and change it in /usr/local/etc/onlyoffice/documentserver/local.json accordingly.
# 3. 为 ONLYOFFICE 文档服务器配置创建新的 rabbitmq 用户（别忘了更改密码）：
#   启动 rabbitmq 服务并添加新用户并设置权限，确保在配置文件 `/usr/local/etc/onlyoffice/documentserver/local.json` 中做相应更改。

4. Set up supervisord in order to execute documentserver services:
  - let supervisord.conf load files contained in this directory by adding to
    /usr/local/etc/supervisord.conf:
[include]
files = /usr/local/etc/onlyoffice/documentserver/supervisor/*.conf

  - start supervisord:
    # service supervisord start
# 4. 设置 supervisord 来执行文档服务器服务：
#   配置 supervisord 加载文件，并启动 supervisord 服务。

5. Set up nginx:
  - For HTTP include the following in your /usr/local/etc/nginx/nginx.conf file:
      include /usr/local/etc/onlyoffice/documentserver/nginx/ds.conf;
# 5. 设置 nginx：
#   为 HTTP 设置 Nginx 配置，确保在 nginx.conf 文件中包含 ds.conf 配置。

NOTE: documentserver-update-securelink.sh will only update ./nginx/ds.conf and local.json under /usr/local/etc/onlyoffice/documentserver/!
  - run documentserver-update-securelink.sh once for creating a very secret string

  - start nginx:
    # service nginx start
# 注意：documentserver-update-securelink.sh 仅会更新 ./nginx/ds.conf 和 /usr/local/etc/onlyoffice/documentserver/ 下的 local.json 文件！
#   运行该脚本一次以生成一个 secret 字符串，并启动 nginx 服务。

6. Follow the following doc If you want to use Onlyoffice with Nextcloud:
  - https://api.onlyoffice.com/editors/nextcloud
# 6. 如果你想将 OnlyOffice 与 Nextcloud 配合使用，请参考以下文档：
#   https://api.onlyoffice.com/editors/nextcloud

7. Install OnlyOffice plugins (you'll need internet):
  # /usr/local/bin/documentserver-pluginsmanager.sh --update=/usr/local/www/onlyoffice/documentserver/sdkjs-plugins/plugin-list-default.json
# 7. 安装 OnlyOffice 插件（需要互联网连接）：
#   使用插件管理器更新插件列表。

8. Enjoy.
# 8. 完成安装，享受使用 OnlyOffice 的体验。

On upgrade from onlyoffice-documentserver<7.1.0.215:
If you are upgrading onlyoffice-documentserver from a version prior to 7.1.0.215,
you need to update the database schema:
  For PostgreSQL:
    psql -U postgres -d onlyoffice -f /usr/local/www/onlyoffice/documentserver/server/schema/postgresql/upgrade/upgradev710.sql
  For MySQL:
    mysql -u onlyoffice -D onlyoffice -p < /usr/local/www/onlyoffice/documentserver/server/schema/mysql/upgrade/upgradev710.sql
# 从 onlyoffice-documentserver<7.1.0.215 升级：
#   如果是从较旧版本（7.1.0.215 之前）升级，需要更新数据库模式：
#   PostgreSQL 和 MySQL 的更新命令。

On upgrade from onlyoffice-documentserver>7.1.0.215<7.2.1.34:
If you are upgrading onlyoffice-documentserver from a version prior to 7.2.1.34,
you need to update the database schema:
  For PostgreSQL:
    psql -U postgres -d onlyoffice -f /usr/local/www/onlyoffice/documentserver/server/schema/postgresql/upgrade/upgradev720.sql
  For MySQL:
    mysql -u onlyoffice -D onlyoffice -p < /usr/local/www/onlyoffice/documentserver/server/schema/mysql/upgrade/upgradev720.sql
# 从 onlyoffice-documentserver>7.1.0.215<7.2.1.34 升级：
#   如果是从 7.2.1.34 之前的版本升级，需要更新数据库模式：
#   PostgreSQL 和 MySQL 的更新命令。
```

## 配置服务

了解完安装信息后，需要配置 OnlyOffice 相关服务的开机自启。

```sh
# service nginx enable
# service rabbitmq enable
# service supervisord enable
```

## 配置数据库

OnlyOffice 需要一个数据库来存储数据，本节使用 PostgreSQL 作为数据库。请读者自行参照本书其他章节，完成 PostgreSQL 数据库的安装、初始化和服务自启。

然后执行以下命令使用数据库：

```sh
# psql -U postgres -c "CREATE DATABASE onlyoffice;"
# psql -U postgres -c "CREATE USER onlyoffice WITH password 'onlyoffice';"
# psql -U postgres -c "GRANT ALL privileges ON DATABASE onlyoffice TO onlyoffice;"
# psql -U postgres -c "ALTER DATABASE onlyoffice OWNER to onlyoffice;"
# psql -hlocalhost -Uonlyoffice -d onlyoffice -f /usr/local/www/onlyoffice/documentserver/server/schema/postgresql/createdb.sql
```

## 配置 rabbitmq

OnlyOffice 需要使用 RabbitMQ 作为消息队列服务。开启服务：

```sh
# service rabbitmq start
```

第一步：

```sh
# rabbitmqctl --erlang-cookie `cat /var/db/rabbitmq/.erlang.cookie` add_user onlyoffice password  # 注意：会卡几分钟，下同

Error: unable to perform an operation on node 'rabbit@ykla'. Please see diagnostics information and suggestions below.

Most common reasons for this are:

 * Target node is unreachable (e.g. due to hostname resolution, TCP connection or firewall issues)
 * CLI tool fails to authenticate with the server (e.g. due to CLI tool's Erlang cookie not matching that of the server)
 * Target node is not running

In addition to the diagnostics info below:

 * See the CLI, clustering and networking guides on https://rabbitmq.com/documentation.html to learn more
 * Consult server logs on node rabbit@ykla
 * If target node is configured to use long node names, don't forget to use --longnames with CLI tools

DIAGNOSTICS
===========

attempted to contact: [rabbit@ykla]

rabbit@ykla:
  * connected to epmd (port 4369) on ykla
  * epmd reports node 'rabbit' uses port 25672 for inter-node and CLI tool traffic
  * can't establish TCP connection to the target node, reason: timeout (timed out)
  * suggestion: check if host 'ykla' resolves, is reachable and ports 25672, 4369 are not blocked by firewall

Current node details:
 * node name: 'rabbitmqcli-719-rabbit@ykla'
 * effective user's home directory: /root
 * Erlang cookie hash: mmhdcv/DKEfjrCrCEaZMvQ==
```

第二步：

```sh
# rabbitmqctl --erlang-cookie `cat /var/db/rabbitmq/.erlang.cookie` set_user_tags onlyoffice administrator
Error: unable to perform an operation on node 'rabbit@ykla'. Please see diagnostics information and suggestions below.

Most common reasons for this are:

 * Target node is unreachable (e.g. due to hostname resolution, TCP connection or firewall issues)
 * CLI tool fails to authenticate with the server (e.g. due to CLI tool's Erlang cookie not matching that of the server)
 * Target node is not running

In addition to the diagnostics info below:

 * See the CLI, clustering and networking guides on https://rabbitmq.com/documentation.html to learn more
 * Consult server logs on node rabbit@ykla
 * If target node is configured to use long node names, don't forget to use --longnames with CLI tools

DIAGNOSTICS
===========

attempted to contact: [rabbit@ykla]

rabbit@ykla:
  * connected to epmd (port 4369) on ykla
  * epmd reports node 'rabbit' uses port 25672 for inter-node and CLI tool traffic
  * can't establish TCP connection to the target node, reason: timeout (timed out)
  * suggestion: check if host 'ykla' resolves, is reachable and ports 25672, 4369 are not blocked by firewall

Current node details:
 * node name: 'rabbitmqcli-882-rabbit@ykla'
 * effective user's home directory: /root
 * Erlang cookie hash: mmhdcv/DKEfjrCrCEaZMvQ==
```

第三步：

```sh
#  rabbitmqctl --erlang-cookie `cat /var/db/rabbitmq/.erlang.cookie` set_permissions -p / onlyoffice ".*" ".*" ".*"
Error: unable to perform an operation on node 'rabbit@ykla'. Please see diagnostics information and suggestions below.

Most common reasons for this are:

 * Target node is unreachable (e.g. due to hostname resolution, TCP connection or firewall issues)
 * CLI tool fails to authenticate with the server (e.g. due to CLI tool's Erlang cookie not matching that of the server)
 * Target node is not running

In addition to the diagnostics info below:

 * See the CLI, clustering and networking guides on https://rabbitmq.com/documentation.html to learn more
 * Consult server logs on node rabbit@ykla
 * If target node is configured to use long node names, don't forget to use --longnames with CLI tools

DIAGNOSTICS
===========

attempted to contact: [rabbit@ykla]

rabbit@ykla:
  * connected to epmd (port 4369) on ykla
  * epmd reports node 'rabbit' uses port 25672 for inter-node and CLI tool traffic
  * can't establish TCP connection to the target node, reason: timeout (timed out)
  * suggestion: check if host 'ykla' resolves, is reachable and ports 25672, 4369 are not blocked by firewall

Current node details:
 * node name: 'rabbitmqcli-636-rabbit@ykla'
 * effective user's home directory: /root
 * Erlang cookie hash: mmhdcv/DKEfjrCrCEaZMvQ==
```

## 允许局域网访问

OnlyOffice 默认配置不允许私有 IP 地址访问，需要修改配置以允许局域网访问。故需将以下片段加入 `/usr/local/etc/onlyoffice/documentserver/local.json`：

```json
  "request-filtering-agent" : {
				"allowPrivateIPAddress": true,
				"allowMetaIPAddress": true
			},
```

即：

```json
{
  "services": {
    "CoAuthoring": {
      "sql": {
        "type": "postgres",
        "dbHost": "localhost",
        "dbPort": "5432",
        "dbName": "onlyoffice",
        "dbUser": "onlyoffice",
        "dbPass": "onlyoffice"
      },
  "request-filtering-agent" : {
				"allowPrivateIPAddress": true,
				"allowMetaIPAddress": true
			},
      "token": {
        "enable": {
          "request": {
            "inbox": false,
            "outbox": false
          },
          "browser": false

//……此处省略其他配置……

```

## 配置 Nginx

需要配置 Nginx 来提供 OnlyOffice 的 Web 访问服务。编辑 `/usr/local/etc/nginx/nginx.conf`

将

```nginx
include /usr/local/etc/onlyoffice/documentserver/nginx/ds.conf;
```

放到 http 的括号里：

示例：

```nginx

//……省略其他配置……

http {
    include       mime.types;
    default_type  application/octet-stream;
    include /usr/local/etc/onlyoffice/documentserver/nginx/ds.conf;

//……省略其他配置……

```

## 配置 supervisord

OnlyOffice 使用 supervisord 来管理其服务进程。编辑 `/usr/local/etc/supervisord.conf`，翻到最底下，找到 `;[include]`，并删去前面的分号：

即：

```ini
[include]
;files = relative/directory/*.ini
files = /usr/local/etc/onlyoffice/documentserver/supervisor/*.conf
```

```sh
# service supervisord start
```

## 启动文档

所有配置完成后，可以启动 OnlyOffice 文档服务。

```sh
# documentserver-update-securelink.sh
ds:docservice: stopped
ds:docservice: started
ds:converter: stopped
ds:converter: started
Performing sanity check on nginx configuration:
nginx: the configuration file /usr/local/etc/nginx/nginx.conf syntax is ok
nginx: configuration file /usr/local/etc/nginx/nginx.conf test is successful
```

直接打开 IP 地址，应如下图所示：

![Document Server is running](https://338876981-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FCJR3FQGH1PkdRtOljuxb%2Fuploads%2Fgit-blob-894139f4d0ced593465f0284860ce9678a0b803b%2Fdocumentserver1.png?alt=media)

## 配置 Nextcloud

OnlyOffice 文档服务启动后，需要在 Nextcloud 中配置 OnlyOffice 插件。打开 Nextcloud：

安装 onlyoffice 插件，可以直接访问 `ip/nextcloud/index.php/settings/apps/office/onlyoffice`：

![onlyoffice](https://338876981-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FCJR3FQGH1PkdRtOljuxb%2Fuploads%2Fgit-blob-7ca9a6a03aa5553eb0fcf5d3c4de7ec1059bec7b%2Fdocumentserver2.png?alt=media)

点击头像，然后再点击管理设置，找到 onlyoffice，设置如下（注意看看那个密钥是不是真的为空）：

![onlyoffice](https://338876981-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FCJR3FQGH1PkdRtOljuxb%2Fuploads%2Fgit-blob-a15dc62ed37f2dd65a482913306067344847c6de%2Fdocumentserver3.png?alt=media)

## 完成

所有配置完成后，可以测试 OnlyOffice 功能，预览几个文件：

![onlyoffice](https://338876981-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FCJR3FQGH1PkdRtOljuxb%2Fuploads%2Fgit-blob-32424ac41095acafb5ca60ef5e1e2a5ad5302740%2Fdocumentserver4.png?alt=media)

![onlyoffice](https://338876981-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FCJR3FQGH1PkdRtOljuxb%2Fuploads%2Fgit-blob-bca31faa0d1946186339e012f07f030fe5920979%2Fdocumentserver5.png?alt=media)

![onlyoffice](https://338876981-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FCJR3FQGH1PkdRtOljuxb%2Fuploads%2Fgit-blob-81d416508c2ab90ecc6276b414929ac64a2d96ca%2Fdocumentserver6.png?alt=media)

## 参考文献

* OnlyOffice Forum. How to allow Private IP to access onlyOffice documentServer?\[EB/OL]. \[2026-03-25]. <https://forum.onlyoffice.com/t/how-to-allow-private-ip-to-access-onlyoffice-documentserver/5755/2>. 提供了私有 IP 地址访问 OnlyOffice 的配置方法

## 故障排除与未竟事宜

在使用 OnlyOffice 过程中如遇到问题，可以查看相关日志文件进行排查。本节还列出了一些有待完善的事项。

OnlyOffice 的日志位于 `/var/log/onlyoffice/documentserver/converter/out.log`。

## 课后习题

1. 在 Apache 服务器上部署 OnlyOffice。
2. 重构 OnlyOffice 最小化部署方案，移除 supervisord 进程管理器，改用 FreeBSD rc.d 脚本直接管理各个服务进程，贡献至上游。
3. 修改 OnlyOffice 默认的请求过滤配置，重新启用私有 IP 地址限制，同时配置仅允许来自特定 Nextcloud 实例的请求，验证配置变更效果。