使用 ONLYOFFICE 文档的管理面板

概述

从 9.1 版本开始，ONLYOFFICE 管理面板提供了一个安全的 Web 界面，用于管理服务器配置和监控。本指南说明了如何设置和使用认证系统。

初始设置

默认情况下，管理面板是禁用的。请按照 http://example.com/welcome 页面上的说明启动它。

example.com 是安装了 ONLYOFFICE 文档的服务器的名称。

首次安装

当您首次启动管理面板时，需要进行初始设置：

1. 打开管理面板 Web 界面。

   在 http://example.com/welcome 页面上，点击 Admin Panel。在出现的对话框中，点击 Open Admin Panel。

2. 创建第一个管理员。

   服务器会自动检测到未配置管理员密码。此时会打开一个页面，其中包含创建第一个管理员的命令。第一个管理员只能在主机上创建。

   

   请使用与您的安装方式相符的命令：

   Linux：

   sudo documentserver-admin create-admin

   Docker：

   docker exec -it <container> documentserver-admin create-admin

   将 <container> 替换为容器 ID 或名称。要查找它，请运行 docker ps。

   Kubernetes：

   kubectl exec -it <pod> -- documentserver-admin create-admin

   将 <pod> 替换为 Pod 名称。要查找它，请运行 kubectl get pods。

   Windows：

   "%ProgramFiles%\ONLYOFFICE\DocumentServer\bin\documentserver-admin.bat" create-admin

   按照命令行提示设置管理员密码。

3. 重新加载页面并登录。

   重新加载管理面板页面，输入您创建的密码，然后点击登录。

   

   将创建 runtime.json 文件，其中将包含管理面板中修改的设置。该文件优先于其他配置文件，如 local.json、default.json、production.json 等。

   runtime.json 文件可以在以下位置找到：

   • 对于 Linux - /var/www/onlyoffice/Data/runtime.json

   • 对于 Docker - /var/www/onlyoffice/Data/runtime.json（首先，使用 docker exec -it <containerid> bash 命令进入 ONLYOFFICE 文档容器）

   • 对于 Windows - %ProgramData%/ONLYOFFICE/Data/runtime.json

     默认情况下，ProgramData 是 Windows Server 中的一个隐藏文件夹，您可以在文件资源管理器选项中启用显示隐藏项目来查看它。

安全注意事项

• 第一个管理员只能在主机上使用 documentserver-admin create-admin 创建。
• 管理员密码以 passwordHash 的形式存储在 runtime.json 中。
• 不会传输或记录任何密码 — 仅存储安全的哈希值。

常规登录

初始设置完成后：

1. 导航到 http://example.com/admin。

2. 输入您的管理员密码。

3. 点击登录。

   

4. 您的会话有效期为 1 小时。

会话详情

• 会话使用安全的仅限 HTTP 的 Cookie。
• 它们会在 1 小时不活动后自动过期。
• 应用了 SameSite=Strict 保护以防止 CSRF 攻击。

更改密码

要更改您的管理员密码：

1. 登录管理面板。
2. 转到更改密码页面。
3. 输入您当前的密码。
4. 输入您的新密码。
5. 确认新密码。
6. 点击保存更改。

更改密码后，您的会话保持活动状态。

密码哈希详情

• 算法： PBKDF2-SHA256（600,000 次迭代，OWASP 2023）。
• 跨平台： 哈希值可以通过 Python 或 Node.js 生成。

在外部生成密码哈希

OpenSSL 3.0+（推荐 - MCF 格式）：

PASSWORD="YourPassword"; I=600000; S=$(openssl rand -base64 16 | tr -d '\n'); H=$(openssl kdf -binary -keylen 32 -kdfopt digest:SHA256 -kdfopt pass:UTF8:"$PASSWORD" -kdfopt salt:base64:"$S" -kdfopt iter:$I PBKDF2 | base64 | tr -d '\n'); echo "\$pbkdf2-sha256\$$I\$$S\$$H"

Node.js：

node -e "const crypto=require('crypto');const p=process.argv[1];const s=crypto.randomBytes(16);const sb=s.toString('base64').replace(/\+/g,'.').replace(/=/g,'');crypto.pbkdf2(p,s,600000,32,'sha256',(e,k)=>{const h=k.toString('base64').replace(/\+/g,'.').replace(/=/g,'');console.log('\$pbkdf2-sha256\$600000\$'+sb+'\$'+h)})" "YourPassword"

检查 OpenSSL 版本：

openssl version
# OpenSSL 3.0.0 或更新版本 - ✓ 使用 openssl kdf 命令
# OpenSSL 1.x - ✓ 使用 openssl keyutl 命令

将生成的哈希添加到 runtime.json 文件中：

{
  "adminPanel": {
    "passwordHash": "$pbkdf2-sha256$600000$..."
  }
}

密码重置 / 恢复

如果您知道当前密码，请使用管理面板中的更改密码页面。

如果您忘记了管理员密码，请在服务器上运行以下命令：

Linux：

sudo documentserver-admin reset-admin-password

Docker：

docker exec -it <container> documentserver-admin reset-admin-password

将 <container> 替换为容器 ID 或名称。要查找它，请运行 docker ps。

Kubernetes：

kubectl exec -it <pod> -- documentserver-admin reset-admin-password

将 <pod> 替换为 Pod 名称。要查找它，请运行 kubectl get pods。

Windows：

"%ProgramFiles%\ONLYOFFICE\DocumentServer\bin\documentserver-admin.bat" reset-admin-password

按照命令行提示设置新的管理员密码。

故障排除

管理面板尚未配置

问题： 管理面板页面仍然显示不存在管理员帐户。

解决方案：

• 在主机上使用 documentserver-admin create-admin 创建第一个管理员。
• 对于 Docker，请在 ONLYOFFICE 文档容器内运行该命令：docker exec -it <container> documentserver-admin create-admin。将 <container> 替换为 docker ps 中显示的容器 ID 或名称。
• 命令行完成后，重新加载管理面板页面，并使用您创建的密码登录。

设置

ONLYOFFICE 管理面板的设置页面提供了一套工具，用于监控服务器配置、管理证书、自定义字体等。以下是对本节功能的简要说明。

配置

使用此选项卡，您可以：

• 查看服务器配置。此处显示最终配置，所有参数通过所有配置文件重新定义。敏感参数（密码、密钥、秘密）显示为 REDACTED。
• 复制配置文件的内容。
• 将所有配置设置重置为默认值。此操作无法撤销。

许可证

使用此选项卡，您可以上传产品许可证并查看许可证信息：

• 构建：类型（企业版、开发者版）、模式（试用、生产）、发布日期。
• 许可证：开始日期、许可证有效截止日期。
• 编辑器和实时查看器的连接限制。

点击立即购买按钮以购买许可证。您将被重定向到 ONLYOFFICE 官方网站的相应页面。

要上传许可证：

1. 点击浏览按钮选择许可证文件。
2. 点击应用许可证按钮。

PDF 签名

使用此选项卡，您可以添加 PKCS#12（.p12/.pfx）证书，用于签署提交的 PDF 表单。当点击完成并提交按钮提交时，填写的 PDF 表单将被签名。

要使用现有文件（私钥和 .crt / .pem 证书）创建 .p12/.pfx 证书，您可以从命令行使用 openssl：

openssl pkcs12 -export -out certificate.pfx -inkey privatekey.key -in certificate.crt

要从头创建证书：

1. 生成私钥：

   openssl genrsa -out privatekey.key 2048

2. 创建证书签名请求（CSR）：

   openssl req -new -key privatekey.key -out request.csr

3. 生成自签名证书：

   openssl x509 -req -days 365 -in request.csr -signkey privatekey.key -out certificate.crt

4. 创建 PKCS#12 文件：

   openssl pkcs12 -export -out certificate.pfx -inkey privatekey.key -in certificate.crt

获得 .p12/.pfx 证书后，您可以将其上传到管理面板中的“证书文件”字段。如果证书受密码保护，请在“证书密码”字段中输入您的密码。然后保存设置。

HTTPS / SSL

使用此选项卡，您可以从 letsencrypt.org 服务安装新的 CA 签名证书，以启用安全的 HTTPS 协议。

备注

为了成功生成 Let's Encrypt 证书，必须打开端口 80 和 443。您的 DNS 记录中的 A 记录必须将您的域名指向安装了 ONLYOFFICE 文档的服务器的 IP 地址。

1. 在域名字段中指定您的域名。
2. 在电子邮件字段中指定您的电子邮件地址。
3. 点击安装证书按钮。

字体

使用此选项卡，您可以添加新的自定义字体：

1. 点击浏览按钮选择字体文件，或将其拖放到此处。
2. 点击生成按钮。

管理您添加的自定义字体：

• 按名称筛选所有字体以找到所需的字体。
• 勾选“仅显示自定义”选项，以便在列表中仅显示自定义字体。
• 勾选“标记所有自定义字体以删除”选项，然后点击生成按钮以删除所选的自定义字体。

服务

使用此选项卡，您可以启用或禁用特定服务的公共 API 端点。

备注

禁用某项服务后，其公共 API 请求将立即被拒绝并返回 HTTP 403。依赖已禁用端点的集成将停止工作，直到重新启用该服务。

可用选项如下：

• 转换公共 API。 启用或禁用转换端点。禁用后可能会导致使用转换服务的连接器无法正常工作。由编辑器发起的转换不受影响。
• Document Builder 公共 API。 启用或禁用文档生成端点。
• AI 功能。 启用或禁用编辑器中的 AI 工具以及 /ai-proxy 端点。禁用后，AI 工具将从发送给编辑器的插件列表中移除，并且 /ai-proxy 请求将被拒绝。

关闭

使用此选项卡，您可以在因应用程序更新或服务器重启等原因需要停止 ONLYOFFICE 文档时，强制断开 ONLYOFFICE 文档用户的连接，以避免数据丢失。

1. 点击关闭按钮以阻止新的编辑器连接并关闭现有会话。当以这种方式停止服务器时，用户将正确断开与编辑器的连接，并且他们的更改将被保存。
2. 点击恢复按钮使服务器恢复正常模式，并允许新的编辑器连接。

高级选项

使用此选项卡，您可以配置高级安全选项和文档组装选项。

备注

禁用验证会使服务器容易受到中间人攻击。仅在与使用自签名证书或其他不受信任证书的服务集成时，将其用作临时解决方法。安装正确的证书后，请重新启用验证。

可用选项如下：

• 验证 TLS/SSL 证书（rejectUnauthorized）。 验证传出 HTTPS 请求的远程证书。
• 验证下载文件的完整性（checksumVerification）。 根据完整性标头检查下载的内容。
• 以原始格式组装文档（assemblyFormatAsOrigin）。 在最终组装期间保留文档的原始格式。

IP 过滤

IP 过滤页面可用于定义此服务器允许联系哪些主机。添加一条指定主机的规则，即可允许服务器联系该主机。通配规则 * 匹配任何主机。

要求受信任的 WOPI 主机用于控制通配规则 * 是否足以信任某个主机。启用时（默认），只有明确指定该主机的规则才有效 — 通配规则无效。

规则按从上到下的顺序进行评估，并应用第一条匹配的规则。请将 WOPI 存储主机的规则添加到通配规则 * 之上。

网络请求

网络请求选项卡用于控制哪些调用方可以访问此服务器，以及如何过滤传出连接。

可用选项如下：

• 对请求使用 IP 过滤。 将 IP 规则应用于传入请求。禁用时，不检查客户端地址；传出的 WOPI 目标仍由相同的规则授权。
• 允许私有 IP 地址。 允许向私有地址范围和环回地址发出传出请求。这不会使 WOPI 主机成为受信任的主机。
• 允许元 IP 地址。 允许向 0.0.0.0 和 :: 发出传出请求。云元数据地址和链路本地地址对 WOPI 仍保持阻止状态。

WOPI 设置

WOPI 设置页面可用于配置文档编辑的 WOPI 支持，包括受信任的 WOPI 主机、SharePoint 集成的兼容性设置、文档锁定行为以及加密密钥管理。

使用页面顶部的 WOPI 开关可完全启用或禁用 WOPI 支持。

受信任的 WOPI 主机

此部分用于决定此服务器允许联系哪些文档存储主机。受信任主机列表在 IP 过滤页面上管理，而不是在 WOPI 设置页面上。

要求受信任的 WOPI 主机用于控制 IP 过滤页面上的通配规则 * 是否足以信任某个主机。启用时（默认），只有明确指定该主机的规则才有效 — 通配规则无效。IP 过滤规则始终用于 WOPI 目标；此选项不会关闭该过滤。

如果未配置受信任的 WOPI 主机，将显示警告，并且在您添加指定存储主机的规则之前，无法打开文档。

要将 WOPI 主机添加到允许列表：

1. 在 WOPI 设置页面上，打开受信任的 WOPI 主机部分。在警告消息中，点击 IP 过滤链接。
2. 在 IP 过滤页面上，添加一条指定您的 WOPI 存储主机的规则。保存规则后，该主机即成为 WOPI 的受信任主机。

备注

启用要求受信任的 WOPI 主机后，IP 过滤中的通配规则 * 不会使主机成为受信任的主机。请添加一条明确指定存储主机的规则。

兼容性

此部分用于为 SharePoint 和其他兼容 WOPI 的存储集成配置 WOPI 发现和请求兼容性设置。

WOPI 区域

指定 ONLYOFFICE 文档公布的发现区域。此值必须与 SharePoint 端使用 Set-SPWOPIZone PowerShell 命令配置的区域一致。可用值：

• external-https
• external-http（默认）
• internal-https
• internal-http

要检查 SharePoint 端当前配置的区域，请使用以下 PowerShell 命令：

Get-SPWOPIZone

要更改 SharePoint 端的区域，请使用以下 PowerShell 命令：

Set-SPWOPIZone -Zone "external-http"

发送 Authorization 标头

启用后，会向 WOPI 请求添加 Authorization: Bearer <access_token> 标头。根据 WOPI 规范，这是可选的，但某些 SharePoint 配置需要它：

• SharePoint Subscription Edition： 必须启用此选项。如果没有 Authorization 标头，将出现 Invalid access token 错误，并且文档编辑会失败。
• SharePoint 2019： 此选项是可选的。使用 URI 中传递的令牌即可正常连接，但启用该标头也不会导致任何问题。

这对应于 wopi.sendAuthorizationHeader 配置参数（默认为 false）。

锁定设置

此部分用于配置 WOPI 会话的文档锁定刷新间隔。

刷新锁定间隔

指定文档锁定的刷新频率。请使用 <number><unit> 格式，其中单位为 s（秒）、m（分钟）或 h（小时）。示例：10m、1h、30s。默认值为 10m。

密钥管理

此部分可用于轮换 WOPI 加密密钥。当前公钥字段显示用于 WOPI 请求身份验证的有效公钥。

要轮换密钥，请勾选轮换密钥复选框，然后点击保存更改。当前密钥将被移至“旧”密钥，并生成新密钥。

备注

请勿在 24 小时内多次轮换密钥。存储可能无法及时刷新，从而导致身份验证失败。