在实际的企业运维、Web 架构设计以及多系统整合场景中将应用部署到Nginx 子目录Subdirectory是一种非常常见且实用的方式。本文将从原理、典型应用场景、注意事项入手系统讲解Nginx 子目录部署的常见模式并重点讨论ONLYOFFICE Document Server 是否能部署到子目录如何实现需要注意什么一、为什么将应用部署到 Nginx 子目录将应用部署到子目录例如https://example.com/app/https://example.com/office/https://example.com/admin/相比独立子域名如 office.example.com 有以下优势1. 单域名管理多个应用同一个域名下运行多个系统无需额外开子域名或端口降低 DNS、证书、网关管理复杂度。2. 更友好的网络拓扑减少端口暴露后端真实端口如 3000/8082隐藏在内网。用户访问 → Nginx → 内网应用提升系统安全性。3. 兼容性好适用于旧系统或第三方组件一些程序不支持自定义端口或必须使用固定目录通过 Nginx Subdirectory 可轻松适配。4. 前后端独立部署多应用共存多个 SPA、后端服务、脚本工具可通过不同路径共存于一个域名下。二、Nginx 子目录常见部署模式1. 子目录反向代理后端服务最典型场景访问 /app/ → 转发到内网 3000 端口。location /app/ { proxy_pass http://127.0.0.1:3000/; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; }✔ proxy_pass 末尾 / 不能漏否则路径拼接错误。2. 子目录部署静态前端Vue/React/Angularlocation /app/ { alias /var/www/app/; try_files $uri $uri/ /app/index.html; }注意区别root 会自动拼接子目录alias 适合子目录映射前端框架必须配置base pathVue Routerbase: /app/ReactPUBLIC_URL/app/3. 多应用复合部署示例server { listen 80; server_name example.com; location /admin/ { proxy_pass http://127.0.0.1:8080/; } location /app/ { alias /var/www/app/; try_files $uri $uri/ /app/index.html; } location /api/ { proxy_pass http://127.0.0.1:9000/; } }三、子目录部署需要特别注意的问题1. 路径斜杠细节/app 与 /app/ 在 Nginx 中完全不同会影响 proxy_pass 拼接规则。2. alias vs root子目录使用 alias 更自然否则路径容易错误。3. SPA 路由需要 try_files 重写 index.html否则刷新页面会 404。4. 资源路径必须带前缀如果前端或后端写死根路径 / 放在子目录下会立即失效。这点对于 ONLYOFFICE 非常关键。四、ONLYOFFICE 能否部署到子目录官方明确ONLYOFFICE Document Server 不支持子目录部署8以前版本ONLYOFFICE 默认所有路径都写死为根路径 / /web-apps/ /doc/... /sdkjs/ /fonts/ /cache/直接代理到 /office/ 会导致静态资源加载失败WebSocket 无法连接编辑器界面打不开“Document Server is not available”但实际生产中企业确实有必须将 OnlyOffice 放到子目录的需求例如https://example.com/office/因此虽然官方宣称不支持但翻阅9.1版本代码可以通过 Nginx 路径重写 sub_filter 的方式实现子目录部署。接下来讲如何实现。五、ONLYOFFICE 子目录部署可行方案实战验证可用1. 部署架构外部访问路径https://example.com/office/Document Server 内部服务http://127.0.0.1:8082/六、Nginx 子目录代理 ONLYOFFICE 配置可用示例子目录部署需要你在前一层的代理服务器上配置转发规则并携带关键头部信息。只需增加proxy_set_header X-Forwarded-Prefix/myeditor根据实际配置,以下三处myeditor保持一致;具体如下location /myeditor/ { proxy_pass http://127.0.0.1:9000/; # 代理头设置 proxy_set_header X-Forwarded-Prefix /myeditor; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header REMOTE-HOST $remote_addr; proxy_set_header X-Forwarded-Proto $scheme; proxy_set_header X-Forwarded-Port $server_port; proxy_set_header X-Forwarded-Host $host; # Websocket 支持 proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection upgrade; proxy_http_version 1.1; # 超时设置 proxy_read_timeout 3600s; proxy_send_timeout 3600s; proxy_connect_timeout 60s; # 缓冲和重定向 proxy_buffering off; proxy_redirect off; # Cookie 路径处理 - 如果后端应用需要 # proxy_cookie_path / /myeditor/; # 缓存头 add_header X-Cache $upstream_cache_status; add_header Cache-Control no-cache; # SSL 相关 proxy_ssl_server_name on; proxy_ssl_verify off; }七、子目录部署的潜在问题与风险1. 官方不支持 → 升级可能破坏 rewrite9以上版本没有明确若升级 OnlyOffice 版本可能需要重新测试 sub_filter 规则。2. 原生写死的绝对路径太多rewrite 成本高尤其是 /web-apps/ 与 /doc/ 的资源引用。总结推荐优先使用子域名部署 https://office.example.com若企业受限才使用子目录方案。虽然 ONLYOFFICE 子目录部署可行但需要清晰认识到其兼容性问题和维护成本。因此生产环境更建议使用子域名若必须使用子目录部署务必充分测试静态资源、WebSocket、协作文档保存等关键功能。相关资源OnlyOffice 中国版最新版本镜像安装部署 | onlyoffice 文档服务中文增强版中文办公专家中国版本介绍文档服务中文增强版 | onlyoffice 文档服务中文增强版中文办公专家技术交流183026419QQ群