Seafile 支持通过 OnlyOffice 文档服务器在线预览和编辑 Office 文件。使用前，需要先部署 OnlyOffice，并在 Seafile 中启用相应配置。
OnlyOffice 可以作为 Docker 容器部署在 Seafile 所在服务器上，也可以独立部署在其他服务器上。本文以 Seafile 14.0 和 13.0 的 Docker 部署为例。
部署 OnlyOffice
准备工作
-
Seafile 已正常运行，服务器具有足够的 CPU、内存和磁盘空间运行 OnlyOffice。
-
已配置 Seafile 的访问域名，建议使用 HTTPS，并确保客户端能够访问 OnlyOffice 的地址。
-
以下命令假设 Seafile 的 Docker Compose 文件和 .env 位于 /opt/seafile 。如果实际部署目录不同，请使用对应路径。
1. 下载 Docker Compose 文件
在 Seafile 的部署目录执行以下命令。
Seafile 14.0：
cd /opt/seafile
wget https://manual.seafile.com/14.0/repo/docker/onlyoffice.yml
Seafile 13.0：
cd /opt/seafile
wget https://manual.seafile.com/13.0/repo/docker/onlyoffice.yml
2. 修改
.env
编辑
/opt/seafile/.env
，将
onlyoffice.yml
添加到
COMPOSE_FILE
列表中，
保留现有的其他 Compose 文件
。
例如，原配置为：
COMPOSE_FILE='seafile-server.yml,caddy.yml,seadoc.yml'
修改为：
COMPOSE_FILE='seafile-server.yml,caddy.yml,seadoc.yml,onlyoffice.yml'
以上仅为示例。若已经启用 SeaSearch、通知服务器等其他组件，也应保留对应的
.yml
文件。
然后在
.env
中设置 OnlyOffice 所需的变量：
# OnlyOffice 镜像
ONLYOFFICE_IMAGE=onlyoffice/documentserver:8.1.0.1
# OnlyOffice 持久化数据目录
ONLYOFFICE_VOLUME=/opt/onlyoffice
# 对外访问 OnlyOffice 的端口
ONLYOFFICE_PORT=6233
# Seafile 与 OnlyOffice 共享的 JWT 密钥
ONLYOFFICE_JWT_SECRET=请替换为随机生成的密钥
变量
作用
示例或默认值
ONLYOFFICE_IMAGE
OnlyOffice 文档服务器镜像
onlyoffice/documentserver:8.1.0.1
ONLYOFFICE_VOLUME
日志、数据和内部持久化目录的宿主机路径
/opt/onlyoffice
ONLYOFFICE_PORT
通过 Caddy 对外提供 OnlyOffice 服务的端口
6233
ONLYOFFICE_JWT_SECRET
Seafile 与 OnlyOffice 之间验证请求的共享密钥
必须设置
使用随机字符串作为 JWT 密钥。例如，已安装
pwgen
时，可以运行：
pwgen -s 40 1
将生成的字符串分别填入
.env
的
ONLYOFFICE_JWT_SECRET
和
seahub_settings.py
的
ONLYOFFICE_JWT_SECRET
。两处内容必须完全相同。请妥善保存密钥，不要使用示例占位符。
如果使用 HTTPS，请同时确认 Seafile 的
.env
中配置了：
SEAFILE_SERVER_PROTOCOL=https
默认
onlyoffice.yml
将宿主机的
6233
端口绑定到
Caddy
，再由 Caddy 转发到 OnlyOffice 容器。无需额外将 OnlyOffice 容器的端口直接发布到宿主机。若未使用 Caddy，应按
使用其他反向代理
配置独立代理和端口转发。
3. 配置 Seafile
编辑 Seafile 的
seahub_settings.py
。Docker 默认部署时，宿主机上的路径通常为：
/opt/seafile-data/seafile/conf/seahub_settings.py
加入以下配置，并将域名、端口和 JWT 密钥替换为实际值：
ENABLE_ONLYOFFICE = True
ONLYOFFICE_APIJS_URL = 'https://seafile.example.com:6233/web-apps/apps/api/documents/api.js'
ONLYOFFICE_JWT_SECRET = '请替换为与 .env 一致的 JWT 密钥'
ONLYOFFICE_APIJS_URL
必须是浏览器可以访问的 OnlyOffice JavaScript API 地址。若修改
ONLYOFFICE_PORT
、使用独立域名或通过其他反向代理访问，应同步调整该 URL。采用 HTTPS 时，应使用有效的 TLS 证书。
以下设置具有默认值，只有需要更改预览或编辑范围时才需要显式配置：
# 允许在线预览的文件类型
ONLYOFFICE_FILE_EXTENSION = (
'doc', 'docx', 'ppt', 'pptx', 'xls', 'xlsx',
'odt', 'fodt', 'odp', 'fodp', 'ods', 'fods',
'ppsx', 'pps', 'csv'
)
# 允许在线编辑的文件类型
ONLYOFFICE_EDIT_FILE_EXTENSION = ('docx', 'pptx', 'xlsx', 'csv')
# 预览文件大小上限：30 MB
OFFICE_PREVIEW_MAX_SIZE = 30 * 1024 * 1024
仅列出文件扩展名并不意味着 OnlyOffice 一定支持该格式的所有编辑或预览功能，具体支持能力以所使用的 OnlyOffice 版本为准。
4. 启动并验证服务
在包含
.env
的部署目录中执行：
cd /opt/seafile
docker compose config --quiet
docker compose down
docker compose up -d
docker compose down
会中断当前服务；请在合适的维护时间执行，且不要附加
-v
参数以免误删数据卷。
查看容器状态和日志：
docker compose ps
docker logs --tail 100 seafile-onlyoffice
若使用本文的 Caddy 配置和 HTTPS，打开：
https://seafile.example.com:6233/welcome
页面显示
Document Server is running
，表示 OnlyOffice 文档服务器已启动。随后登录 Seafile，在网页端打开一个支持的 Office 文件，检查是否能够正常预览和编辑。
注意：
欢迎页能够打开不代表 Seafile 与 OnlyOffice 已完全连通。只有在实际打开、编辑并保存文档成功后，才能确认集成正常。
高级配置
OnlyOffice 支持通过自定义
local-production-linux.json
文件调整文档服务器行为。此类设置应在了解配置含义的情况下使用。
例如，在宿主机上创建
/opt/seafile/local-production-linux.json
：
nano /opt/seafile/local-production-linux.json
以下示例配置自动组装以及文件转换重试次数：
{
"services": {
"CoAuthoring": {
"autoAssembly": {
"enable": true,
"interval": "5m"
}
}
},
"FileConverter": {
"converter": {
"downloadAttemptMaxCount": 3
}
}
}
然后编辑
onlyoffice.yml
，在
services.onlyoffice.volumes
中
保留原有三个持久化挂载
，并增加配置文件挂载：
services:
onlyoffice:
volumes:
- ${ONLYOFFICE_VOLUME:-/opt/onlyoffice}/logs:/var/log/onlyoffice
- ${ONLYOFFICE_VOLUME:-/opt/onlyoffice}/data:/var/www/onlyoffice/Data
- ${ONLYOFFICE_VOLUME:-/opt/onlyoffice}/lib:/var/lib/onlyoffice
- /opt/seafile/local-production-linux.json:/etc/onlyoffice/documentserver/local-production-linux.json
以上是
services.onlyoffice
下
volumes
字段的修改示例
，不要用它覆盖
onlyoffice.yml
中的其他字段，包括镜像、环境变量、网络、Caddy 标签等。
修改后，验证 Compose 配置并重新创建相关服务：
cd /opt/seafile
docker compose config --quiet
docker compose up -d --force-recreate onlyoffice
使用独立部署的 OnlyOffice
在 Seafile 的
seahub_settings.py
中加入：
ENABLE_ONLYOFFICE = True
ONLYOFFICE_APIJS_URL = 'https://office.example.com/web-apps/apps/api/documents/api.js'
ONLYOFFICE_JWT_SECRET = '请替换为 OnlyOffice 服务器配置的 JWT 密钥'
OFFICE_PREVIEW_MAX_SIZE = 30 * 1024 * 1024
其中，
office.example.com
应替换为独立 OnlyOffice 服务器的域名；
ONLYOFFICE_JWT_SECRET
必须与该文档服务器的 JWT 密钥一致。
重新加载 Seafile 配置，例如 Docker 部署可以执行：
cd /opt/seafile
docker compose restart seafile
最后分别检查 OnlyOffice 欢迎页、Seafile 中的 Office 预览及文档保存功能。若两台服务器位于不同网络，应确保浏览器能够访问 OnlyOffice，并且 OnlyOffice 能够访问 Seafile 提供的文件内容和回调地址。
常见问题
打开文件时提示“下载失败”
查看 OnlyOffice 日志：
docker logs -f seafile-onlyoffice
如果日志包含类似内容：
Error: DNS lookup {local IP} (family:undefined, host:undefined) is not allowed. Because, It is a private IP address.
应检查 Seafile 与 OnlyOffice 的网络互通性、域名解析及 JWT 配置。使用内网地址时，部分 OnlyOffice 版本可能会出于安全考虑阻止访问；请优先确认 JWT 已正确启用，并参考
相关问题说明
。不要直接关闭服务端安全检查作为常规解决方式。
提示“文档安全令牌格式不正确”
OnlyOffice 使用 JWT 验证 Seafile 发送的请求。若双方使用不同的密钥，可能出现文档无法打开或保存的问题。
请确认：
-
Seafile .env 中的 ONLYOFFICE_JWT_SECRET 已设置为有效的随机字符串。
-
seahub_settings.py 中的 ONLYOFFICE_JWT_SECRET 与 .env 完全一致。
-
独立部署时，OnlyOffice 服务器本身的 JWT 密钥与 Seafile 配置一致。
-
修改密钥后，已重新启动或重新创建相应服务，使配置生效。
无法打开 OnlyOffice 页面
检查
ONLYOFFICE_APIJS_URL
是否与实际协议、域名、端口及代理路径一致。使用默认 Caddy 部署时，
ONLYOFFICE_PORT
应与 URL 中的端口保持一致。再检查 DNS、证书有效性以及主机防火墙是否允许访问该端口。
如何启用 SSL？
使用默认
onlyoffice.yml
与
caddy.yml
时，HTTPS 由 Caddy 负责。独立部署的 OnlyOffice 服务器则需要自行配置 HTTPS，具体请参阅
ONLYOFFICE Docker 部署说明
。
