Skip to main content

​
OnlyOffice Docker 部署说明

​
简介

OnlyOffice Document Server 是一个在线文档编辑套件，支持 Word（.docx）、Excel（.xlsx）、PPT（.pptx）等 Office 格式的在线编辑和预览。 LangChat 通过 OnlyOffice 内置的 Example 编辑器服务实现文档的新建和预览功能。

​
快速开始

​
启动服务

cd docs/docker/onlyoffice
docker compose up -d
首次启动需要 1-2 分钟初始化，请耐心等待。

​
验证服务

# 健康检查（返回 true 表示就绪）
curl http://localhost:80/healthcheck

# 访问 Example 编辑器页面（应看到文档管理界面）
# 浏览器打开 http://localhost:80/example

​
访问地址

地址说明
http://localhost:80/healthcheck健康检查接口
http://localhost:80/exampleExample 编辑器管理页
http://localhost:80/example/editor?fileName=new.docx&lang=zh新建 Word 文档
http://localhost:80/example/editor?fileName=new.xlsx&lang=zh新建 Excel 表格
http://localhost:80/example/editor?fileName=new.pptx&lang=zh新建 PPT 演示文稿

​
LangChat 后端配置

在 application-dev.yml 或 application-prd.yml 中配置： 
langchat:
  onlyoffice:
    # Document Server 服务地址（用于健康检查）
    url: http://127.0.0.1:80
    # Example 编辑器基础地址（包含前缀路径，前端通过此地址拼接 /editor?fileName=xxx&lang=zh 打开编辑器）
    editor-url: http://127.0.0.1:80/example

​
关于 editor-url

editor-url 必须包含 Example 服务的路径前缀。默认路径为 /example，即完整地址为 http://your-host:port/example。 前端不会拼接任何前缀，直接使用 editor-url + /editor?fileName=new.docx&lang=zh 构建 iframe 地址。

​
配置说明

​
环境变量

变量默认值说明
EXAMPLE_ENABLEDfalse启用内置 Example 编辑器服务。必须设为 true，否则需要手动进入容器执行 supervisorctl start ds:example
JWT_ENABLEDtrue是否启用 JWT 签名验证。内网部署可设为 false 简化配置
JWT_SECRET-JWT 密钥，开启 JWT 时需配置

​
数据持久化

目录说明
./data/onlyoffice/data文档数据存储
./data/onlyoffice/logs服务运行日志

​
端口说明（重要）

默认使用 80 端口，请勿随意修改端口映射。 为什么不能随意改端口？ OnlyOffice Document Server 内部的 Document Service 与 Example 服务通过 localhost 相互回调。当浏览器通过 localhost:8200 访问时，Example 服务会将 localhost:8200 作为回调地址传给 Document Service。但容器内部 nginx 只监听 80 端口，Document Service 在容器内请求 localhost:8200 会因端口不存在而报 ECONNREFUSED 错误，导致文档无法打开。 使用 80:80 映射时，浏览器和容器内部都通过 localhost:80 访问，回调地址一致，不会出现端口不通的问题。 如果 80 端口被占用，如何修改？ 需要在容器内同步修改 nginx 监听端口，使内外端口一致： 
# docker-compose.yml
ports:
  - "8200:8200"  # 内外端口必须一致
同时在 docker-compose.yml 中添加自定义 nginx 配置，覆盖默认的 80 端口监听： 
# 1. 启动容器后，导出默认 nginx 配置
docker exec langchat-onlyoffice cat /etc/nginx/conf.d/ds.conf > ds.conf

# 2. 修改 ds.conf 中 listen 80 为 listen 8200

# 3. 在 docker-compose.yml 中挂载修改后的配置
# volumes:
#   - ./ds.conf:/etc/nginx/conf.d/ds.conf
修改端口后，还需同步更新后端配置中的 url 和 editor-url： 
langchat:
  onlyoffice:
    url: http://127.0.0.1:8200
    editor-url: http://127.0.0.1:8200/example

​
安全提示

OnlyOffice 的 Example 服务仅用于演示和集成用途，任何人均可访问。生产环境中请注意：
  1. 网络隔离：确保 OnlyOffice 仅在内网可访问，不要直接暴露到公网
  2. 启用 JWT：生产环境建议开启 JWT_ENABLED=true 并配置密钥
  3. 防火墙规则：通过防火墙限制访问来源 IP

​
开源协议声明

OnlyOffice Document Server 采用 AGPL v3 开源协议。请注意以下事项：
  • LangChat 仅提供 Docker Compose 部署脚本和 iframe 集成方案，不包含、不修改、不分发 OnlyOffice 的任何源码或二进制文件
  • 镜像由使用方自行从 Docker Hub 拉取，AGPL v3 的合规义务由实际部署和运行该软件的主体承担
  • 如果您需要修改 OnlyOffice 源码，根据 AGPL v3 协议，您必须向通过网络访问该服务的用户提供修改后的完整源码
  • 如果您希望在商业产品中深度集成 OnlyOffice 且不公开源码，请考虑购买 OnlyOffice 商业许可
  • 更多协议详情请参阅 AGPL v3 原文

​
常见问题

​
1. 启动后访问 /example 返回 404

检查 EXAMPLE_ENABLED 环境变量是否设置为 true。如果容器已在运行但未设置该变量，可以手动启用： 
# 手动启动 Example 服务
docker exec langchat-onlyoffice supervisorctl start ds:example

# 设置为自动启动（容器重启后生效）
docker exec langchat-onlyoffice sed -i 's/autostart=false/autostart=true/' /etc/supervisor/conf.d/ds-example.conf

​
2. 健康检查一直返回 false

OnlyOffice 首次启动需要初始化数据库和编译字体，通常需要 1-2 分钟。可查看日志确认进度： 
docker compose logs -f onlyoffice

​
3. 中文字体显示异常

可挂载自定义字体目录，然后重建字体缓存： 
# 取消 docker-compose.yml 中字体挂载的注释，将字体文件放入 ./data/onlyoffice/fonts/

# 重建字体缓存
docker exec langchat-onlyoffice documentserver-generate-allfonts.sh

​
停止服务

docker compose down

​
查看日志

docker compose logs -f onlyoffice

​
docker-compose.yml

version: '3.8'

services:
  onlyoffice:
    container_name: langchat-onlyoffice
    image: onlyoffice/documentserver:latest
    ports:
      - "80:80"
    environment:
      # 启用内置 Example 编辑器服务
      - EXAMPLE_ENABLED=true
      # 禁用 JWT 签名验证（内网部署可关闭，生产环境建议开启）
      - JWT_ENABLED=false
      # 允许回调私有 IP（Docker 内部 localhost 回调必须开启）
      - ALLOW_PRIVATE_IP_ADDRESS=true
      - ALLOW_META_IP_ADDRESS=true
      # JWT 密钥（开启 JWT 时需配置，前后端需保持一致）
      # - JWT_SECRET=your_jwt_secret_here
    volumes:
      # 文档数据持久化
      - ./cache/onlyoffice/data:/var/www/onlyoffice/Data
      # 日志持久化
      - ./cache/onlyoffice/logs:/var/log/onlyoffice
      # 字体（可选，挂载自定义中文字体）
      # - ./data/onlyoffice/fonts:/usr/share/fonts/custom
    restart: always
    networks:
      - langchat-network

networks:
  langchat-network:
    driver: bridge
    name: langchat-network