OnlyOffice Docker 部署说明
重要声明： OnlyOffice 采用 AGPL 协议，默认不允许商业化使用。LangChat Pro 仅提供接入支持，用户需自行处理版权和许可证问题，LangChat 团队不承担任何相关责任。在使用前请仔细阅读相关许可证条款。
快速开始
启动服务
cd docs/docker/onlyoffice
docker compose up -d
首次启动需要 1-2 分钟初始化，请耐心等待。
验证服务
# 健康检查（返回 true 表示就绪）
curl http://localhost:80/healthcheck
# 访问 Example 编辑器页面（应看到文档管理界面）
# 浏览器打开 http://localhost:80/example
访问地址
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_ENABLED | false | 启用内置 Example 编辑器服务。必须设为 true，否则需要手动进入容器执行 supervisorctl start ds:example |
JWT_ENABLED | true | 是否启用 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" # 内外端口必须一致
# 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 服务仅用于演示和集成用途，任何人均可访问。生产环境中请注意：
- 网络隔离：确保 OnlyOffice 仅在内网可访问，不要直接暴露到公网
- 启用 JWT：生产环境建议开启
JWT_ENABLED=true 并配置密钥
- 防火墙规则：通过防火墙限制访问来源 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 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
