夜雨聆风本文基于 onlyoffice/documentserver:9.4.0.1 镜像，Ubuntu 24.04 服务器实测
想在浏览器里在线预览、编辑 Word / Excel / PPT？ONLYOFFICE Document Server（社区版）提供开源的在线文档编辑引擎，可对接 Nextcloud、ownCloud 等网盘，也可单独部署做能力验证。
它不是完整的网盘或办公套件，而是「文档编辑后端服务」。本文带你从零完成一次完整部署：Docker 拉取与启动、欢迎页验证、内置 /example/ 测试编辑、以及通过 Nginx 反代 + sub_filter 解决非 80 端口下的白屏与 400 错误。下文命令均在 Ubuntu 24.04、约 4GB 内存环境下实测通过。
一、环境要求
启动提示：ONLYOFFICE 首次启动会生成字体、主题、插件缓存，CPU 可能长时间 100%，需 5～15 分钟。期间请不要用
Ctrl+C打断docker logs，否则可能反复初始化。Community 版内置 PostgreSQL / RabbitMQ 数据写在 Docker overlay（根分区/），不在你挂载的lib目录里——根分区满会导致ENOSPC报错。
二、安装 Docker
若尚未安装 Docker，可使用轩辕镜像一键脚本（适用于 Linux 及国内云服务器）：
bash <(wget -qO- https://xuanyuan.cloud/docker.sh)Docker 安装脚本地址（可复制）：
https://xuanyuan.cloud/docker.sh验证：
docker --version
docker compose version三、拉取 ONLYOFFICE 镜像
使用轩辕镜像加速域拉取 9.4.0.1 标签：
docker pull docker.xuanyuan.run/onlyoffice/documentserver:9.4.0.1成功时终端显示：
Status: Downloaded newer image for docker.xuanyuan.run/onlyoffice/documentserver:9.4.0.1onlyoffice/documentserver:9.4.0.1 | docker pull docker.xuanyuan.run/onlyoffice/documentserver:9.4.0.1 |
源码仓库 ONLYOFFICE/DocumentServer 与 Docker 部署仓库 ONLYOFFICE/Docker-DocumentServer 为不同项目，部署请以 Docker 仓库文档为准。
ONLYOFFICE/DocumentServer：
https://github.com/ONLYOFFICE/DocumentServerONLYOFFICE/Docker-DocumentServer：
https://github.com/ONLYOFFICE/Docker-DocumentServer四、创建目录并启动容器
4.1 准备数据卷
mkdir -p /www/wwwroot/onlyoffice/{logs,data,lib}若提示权限不足，可在路径前加 sudo，或改为 $HOME/onlyoffice/{logs,data,lib}，下文路径同步替换。
4.2 首次启动（8080 端口）
若宿主机 80 端口已被占用（如已有 Nginx / 宝塔），将容器 80 映射到 8080 即可：
docker run -i -t -d \
--name onlyoffice-documentserver \
--restart=always \
-p 8080:80 \
-v /www/wwwroot/onlyoffice/logs:/var/log/onlyoffice \
-v /www/wwwroot/onlyoffice/data:/var/www/onlyoffice/Data \
-v /www/wwwroot/onlyoffice/lib:/var/lib/onlyoffice \
docker.xuanyuan.run/onlyoffice/documentserver:9.4.0.180 端口空闲时，把 -p 8080:80 改为 -p 80:80，浏览器访问 http://YOUR_SERVER_IP 即可。
查看启动日志（耐心等待，勿中断）：
docker logs -f onlyoffice-documentserver期望依次出现：Generating AllFonts.js...Done、Generating presentation themes...Done、ds:docservice: started、Version: 9.4.0 等。
五、验证部署：打开欢迎页
核心服务就绪后，检查进程：
docker exec onlyoffice-documentserver supervisorctl status期望 ds:docservice、ds:converter 为 RUNNING（启用 example 后还需 ds:example 为 RUNNING）。
健康检查（请用容器内 8000 端口，不要用宿主机 8080 的 /info/info.json，后者常返回 403）：
docker exec onlyoffice-documentserver curl -s http://127.0.0.1:8000/info/info.json | grep buildVersion期望输出含 "buildVersion" 或版本号 9.4.0。
浏览器访问（将 YOUR_SERVER_IP 换成服务器局域网或公网 IP）：
http://YOUR_SERVER_IP:8080/welcome/若看到 ONLYOFFICE Docs Community Edition installed 欢迎页，说明 Document Server 主体已部署成功：
从 7.2 版本起 JWT 默认开启。对接 Nextcloud 等应用时需要 JWT Secret，可在容器内执行：
docker exec onlyoffice-documentserver documentserver-jwt-status.sh欢迎页也会提示通过容器内命令读取 local.json 中的 secret，请将输出中的 secret 妥善保存，下文配置 example 时用到（用 <YOUR_JWT_SECRET> 占位，勿泄露）。
六、启用测试示例 example
欢迎页底部的 Testing before integration 说明：内置 example 是简易文档管理系统，用于验证编辑器是否正常。默认未开启，需重建容器并加上环境变量：
docker exec onlyoffice-documentserver documentserver-prepare4shutdown.sh
docker stop onlyoffice-documentserver
docker rm onlyoffice-documentserver
docker run -i -t -d \
--name onlyoffice-documentserver \
--restart=always \
-p 8080:80 \
-e EXAMPLE_ENABLED=true \
-e ALLOW_PRIVATE_IP_ADDRESS=true \
-e ALLOW_META_IP_ADDRESS=true \
-v /www/wwwroot/onlyoffice/logs:/var/log/onlyoffice \
-v /www/wwwroot/onlyoffice/data:/var/www/onlyoffice/Data \
-v /www/wwwroot/onlyoffice/lib:/var/lib/onlyoffice \
docker.xuanyuan.run/onlyoffice/documentserver:9.4.0.1• EXAMPLE_ENABLED=true：启用/example/测试页• ALLOW_PRIVATE_IP_ADDRESS=true/ALLOW_META_IP_ADDRESS=true：局域网192.168.x.x场景下避免私有 IP 被安全策略拦截
等待 2～5 分钟后确认 example 进程：
docker exec onlyoffice-documentserver supervisorctl status | grep example若为 STOPPED，可手动启动：
docker exec onlyoffice-documentserver supervisorctl start ds:example欢迎页下方会出现 GO TO TEST EXAMPLE 按钮，或直接访问 http://YOUR_SERVER_IP:8080/example/：
安全提示：example 仅供测试，生产环境请勿开启。正式上线前应关闭
EXAMPLE_ENABLED并禁用 example 服务。
七、常见问题排错
7.1 磁盘满：ENOSPC / Server error
现象：访问 /example/ 报 Server error；example 日志出现：
Error: ENOSPC: no space left on device, mkdir '.../documentserver-example/files/...'原因：根分区或 Docker 存储满，example 无法创建用户文件目录；同时可能伴随 Request to meta/formats timed out。
排查：
df -h /
df -i /
docker system df解决：释放空间。实测中 docker system prune -a 可回收大量未使用镜像。执行前请确认无需要保留的停止容器与旧镜像。
docker system prune -a释放后完整重启容器，并等待初始化完成，不要中途打断日志。
7.2 宿主机 curl .../info/info.json 返回 403
现象：
curl -s http://127.0.0.1:8080/info/info.json
# 返回 403 Forbidden HTML说明：容器外层 Nginx 对 /info/ 有访问限制，不代表服务未启动。请以容器内检查为准：
docker exec onlyoffice-documentserver curl -s http://127.0.0.1:8000/info/info.json7.3 languages.forEach is not a function
现象：打开 /example/ 出现模板错误页，languages.forEach is not a function；example 日志大量 Request to meta/config timed out。
因果链：
example 请求 meta/config、meta/formats 超时
→ languages 未加载为数组
→ 渲染 index.ejs 时报 languages.forEach is not a function原因：使用 -p 8080:80 且浏览器通过 http://YOUR_SERVER_IP:8080 访问时，example 会按 Host 去请求 http://YOUR_SERVER_IP:8080/meta/config；在容器内部没有 8080 端口（仅有 80 与 docservice 的 8000），该请求常超时（Docker hairpin 问题）。
验证（在宿主机执行）：
# 容器内 8000 正常
docker exec onlyoffice-documentserver curl -s -m 5 http://127.0.0.1:8000/meta/config | head -c 200
# 容器内访问宿主机映射 IP:8080 往往超时（复现 example 问题）
docker exec onlyoffice-documentserver curl -s -m 5 http://YOUR_SERVER_IP:8080/meta/config修复：将 example 的 siteUrl 改为容器内 docservice 地址。进入容器写入配置：
docker exec -it onlyoffice-documentserver bash在容器内执行（将 <YOUR_JWT_SECRET> 替换为 documentserver-jwt-status.sh 的输出）：
cat > /etc/onlyoffice/documentserver-example/local-production-linux.json << 'EOF'
{
"server": {
"siteUrl": "http://127.0.0.1:8000/",
"exampleUrl": "http://127.0.0.1/example/",
"configUrl": "meta/config",
"formatsUrl": "meta/formats",
"preloaderUrl": "web-apps/apps/api/documents/preload.html",
"token": {
"enable": true,
"useforrequest": true,
"algorithmRequest": "HS256",
"secret": "<YOUR_JWT_SECRET>"
}
}
}
EOF
supervisorctl restart ds:example
exit重启后刷新 /example/，列表页应恢复正常。
siteUrl: http://127.0.0.1:8000/ | |
exampleUrl: http://127.0.0.1/example/ |
注意：此文件在删除/重建容器后会丢失。建议宿主机保存一份并挂载：
-v /www/wwwroot/onlyoffice/example-local.json:/etc/onlyoffice/documentserver-example/local-production-linux.json
7.4 编辑器白屏：浏览器无法加载 api.js
现象：example 列表页正常，点预览/编辑白屏；浏览器 F12 控制台：
GET http://127.0.0.1:8000/web-apps/apps/api/documents/api.js ERR_CONNECTION_REFUSED
DocsAPI is not defined原因：上一步把 siteUrl 设为 127.0.0.1:8000 后，编辑器 HTML 里的 api.js 地址也变成容器内地址；用户浏览器访问的是自己电脑上的 127.0.0.1:8000，当然连不上。
矛盾：example 只有一个 siteUrl，需同时满足「容器内拉 meta」与「浏览器加载 api.js」——在 -p 8080:80 且 hairpin 不通时，单靠改 JSON 无法两全。
解决方案：保持 siteUrl 为 http://127.0.0.1:8000/，在 Nginx 反代中对 HTML/JS 响应做 sub_filter，把 127.0.0.1:8000 替换为浏览器可访问的对外地址（见第九节）。
7.5 日志中的其他提示（可忽略或知悉）
find: '/var/www/onlyoffice/Data/certs': No such file or directory | |
converter ... embedded mode | |
ds:metrics STOPPED |
八、example 配置小结与列表页验证
完成 7.3 节 JSON 配置并重启 ds:example 后，访问：
http://YOUR_SERVER_IP:8080/example/应看到 Welcome to ONLYOFFICE Docs! 测试首页，可新建 Document / Spreadsheet / Presentation，或上传文件：
若仍报错，请再次检查 example 日志：
docker exec onlyoffice-documentserver tail -30 /var/log/onlyoffice/documentserver-example/out.log
docker exec onlyoffice-documentserver tail -30 /var/log/onlyoffice/documentserver-example/err.log九、宝塔 Nginx 反代（非 80 端口完整方案）
若希望通过 88（或其他端口）对外提供 ONLYOFFICE，而 Docker 仍监听 127.0.0.1:8080 或 8080，可在宝塔面板新建站点，反向代理到 http://127.0.0.1:8080。
9.1 架构说明
• 浏览器访问 http://YOUR_SERVER_IP:88/example/• Nginx 转发到 127.0.0.1:8080• 响应 HTML 中的 http://127.0.0.1:8000由 sub_filter 替换为http://YOUR_SERVER_IP:88
9.2 推荐 location 配置
在站点配置中，将反代 location 设为（勿重复proxy_set_header Host）：
location / {
proxy_pass http://127.0.0.1:8080;
proxy_http_version 1.1;
proxy_set_header Host $http_host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header X-Forwarded-Host $http_host;
proxy_set_header X-Forwarded-Port $server_port;
proxy_connect_timeout 60s;
proxy_send_timeout 600s;
proxy_read_timeout 600s;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection $connection_upgrade;
proxy_set_header Accept-Encoding "";
gzip off;
sub_filter 'http://127.0.0.1:8000' 'http://YOUR_SERVER_IP:88';
sub_filter 'http://127.0.0.1/example' 'http://YOUR_SERVER_IP:88/example';
sub_filter_once off;
sub_filter_types text/html application/javascript application/json;
}同时将 #include enable-php-00.conf;注释掉（纯反代站点不需要 PHP）。WebSocket 相关头建议只放在 location 内，不要重复写在 server 块外层。
保存后：
nginx -t && nginx -s reload验证：
curl -s -o /dev/null -w "HTTP:%{http_code}\n" http://YOUR_SERVER_IP:88/example/期望 HTTP:200。
9.3 Nginx 返回 400 Bad Request
现象：curl http://127.0.0.1:8080/example/ 为 200，经 :88 反代为 400；错误页为 nginx 默认 400 HTML。
实测根因：location 内 重复写了两段 proxy 头，尤其是 proxy_set_header Host 出现两次，清理重复块后恢复 200。
排查对比：
# 直连 Docker 正常
curl -sI http://127.0.0.1:8080/example/
# 经反代异常
curl -s -o /dev/null -w "HTTP:%{http_code}\n" http://YOUR_SERVER_IP:88/example/建议：每个 proxy_set_header 在 location 内只写一次；先使用最小反代配置确认 200，再逐步加回 sub_filter。
9.4 进阶：CSV 预览 CORS（可选）
docx 预览正常后，若 CSV 预览报 CORS，因转换后的 cache URL 为 http://YOUR_SERVER_IP/cache/...（缺 :88）。可在 sub_filter 中追加：
sub_filter 'http://YOUR_SERVER_IP/cache' 'http://YOUR_SERVER_IP:88/cache';
sub_filter 'https://YOUR_SERVER_IP/cache' 'http://YOUR_SERVER_IP:88/cache';或在 80 端口单独反代 /cache/ 并加 CORS 头。本文实测以 docx 上传编辑为主，CSV 作可选优化。
9.5 生产建议：Docker 只绑本机
避免外网绕过 Nginx 直连 8080，可将端口映射改为：
-p 127.0.0.1:8080:80对外仅通过 Nginx 域名或端口访问。
十、验证在线编辑
浏览器访问（反代后）：
http://YOUR_SERVER_IP:88/example/上传 docx 或新建文档，应出现 Loading the file、Conversion 均成功，可点击 EDIT / VIEW：
上传成功后，example 首页会切换到 Your documents 文档列表，已传文件出现在表格中，可对每个文件进行编辑、预览或删除：
点击 EDIT 进入 Word 在线编辑器，文档内容正常加载，可修改文字、使用左侧评论/聊天等协作功能（界面为深色主题）：
除 docx 外，Presentation 同样可在线编辑。新建或上传 .pptx 后，幻灯片、表格等内容在浏览器中正常渲染：
在 Your documents 列表中，还可对已有文档一键转换格式。点击文件行的转换按钮，在 Converting file 对话框中选择目标格式（如 PDF、TXT、EPUB、MD、ODT、RTF、PNG 等），转换完成后可 DOWNLOAD 下载、VIEW 预览或 EDIT 继续编辑：
命令行验证编辑器页是否已替换 api.js 地址（反代 + sub_filter 生效后）：
curl -s "http://YOUR_SERVER_IP:88/example/editor?mode=view&fileName=test.docx&userid=uid-1" \
| grep -o 'src="[^"]*api.js"'期望类似 src="http://YOUR_SERVER_IP:88/web-apps/.../api.js"，而非 127.0.0.1:8000。
十一、对接 Nextcloud 与生产环境
11.1 对接 Nextcloud / ownCloud
1. 在 ONLYOFFICE 侧确认 JWT Secret： documentserver-jwt-status.sh2. 在网盘 ONLYOFFICE 应用设置中填写： • Document Server 地址： http://YOUR_SERVER_IP:88（或你的域名）• JWT Secret：与 ONLYOFFICE 一致
11.2 生产环境 checklist
关闭EXAMPLE_ENABLED/example/ | |
127.0.0.1:8080，外网走 Nginx 443 | |
十二、常见问题 FAQ
Q1：首次启动要等多久？
通常 5～15 分钟，视 CPU/内存而定。看到 ds:docservice: started 且 buildVersion: 9.4.0 即可认为主体就绪。
Q2：4GB 内存够吗？
可以跑通测试，但首次初始化慢，converter 可能 WARN embedded mode。生产建议 8GB+。
Q3：为什么不能用 localhost 访问 example？
example 与 docservice 回调依赖 Host / IP，局域网测试请用 服务器 IP（如 http://YOUR_SERVER_IP:8080/example/）。
Q4：重建容器后 example 配置没了？local-production-linux.json 在容器内，需重新写入或挂载宿主机文件。
Q5：supervisorctl restart ds:example 后仍超时？
说明 URL 配置未改对，按 7.3 节设置 siteUrl: http://127.0.0.1:8000/。
Q6：列表正常但编辑白屏？
按 7.4 节配置 Nginx sub_filter，或检查浏览器 F12 是否仍请求 127.0.0.1:8000。
Q7：88 反代 400 但 8080 正常？
检查 Nginx 是否重复 proxy_set_header Host、是否误开 PHP、extension 目录是否有冲突规则（见 9.3 节）。
Q8：如何更新镜像？
docker pull docker.xuanyuan.run/onlyoffice/documentserver:9.4.0.1
docker exec onlyoffice-documentserver documentserver-prepare4shutdown.sh
docker stop onlyoffice-documentserver && docker rm onlyoffice-documentserver
# 再执行第四节/第六节的 docker run（volume 数据保留）总结
本文完成了 ONLYOFFICE Document Server 9.4.0.1 从镜像拉取到在线编辑验证的完整流程：
• 使用轩辕镜像加速拉取 onlyoffice/documentserver:9.4.0.1• Docker 映射 8080 端口并挂载 logs / data / lib • 启用 EXAMPLE_ENABLED与私有 IP 相关环境变量• 通过 siteUrl: http://127.0.0.1:8000/解决 meta 超时与languages.forEach报错• 通过 Nginx sub_filter 解决编辑器 api.js 白屏 • 清理重复 proxy 头解决 Nginx 400 Bad Request • 实测 docx 在线编辑、pptx 幻灯片编辑均可正常使用
延伸阅读：
ONLYOFFICE Docker-DocumentServer：
https://github.com/ONLYOFFICE/Docker-DocumentServeronlyoffice/documentserver 镜像页：
https://xuanyuan.cloud/zh/r/onlyoffice/documentserver轩辕镜像首页：
https://xuanyuan.cloudDocker 一键安装脚本：
https://xuanyuan.cloud/docker.sh
