OnlyOffice HTTPS 代理配置总结

项目背景

将 OnlyOffice API 从 HTTP IP 地址访问（http://20.51.117.204）改为通过 Nginx 的 HTTPS 代理访问（https://chat.xutongbao.top/onlyoffice/），以解决混合内容（Mixed Content）安全问题。

问题演进与解决过程

1. 初始问题：混合内容错误

错误信息：

复制代码

Mixed Content: The page at 'https://...' was loaded over HTTPS,
but requested an insecure XMLHttpRequest endpoint 'http://chat.xutongbao.top/cache/...'.
This request has been blocked; the content must be served over HTTPS.

原因分析：

Next.js 页面通过 HTTPS 加载
OnlyOffice API 脚本使用 HTTP IP 地址
OnlyOffice 内部生成的资源链接也是 HTTP

解决方案：

修改 Next.js 中的 API 脚本地址为 HTTPS 代理地址
配置 Nginx 代理转发请求到后端 OnlyOffice 服务器
使用 sub_filter 替换响应中的 HTTP 链接为 HTTPS

2. 第二个问题：404 错误

错误信息：

复制代码

GET https://chat.xutongbao.top/cache/files/data/.../Editor.bin 404 (Not Found)

原因分析：

OnlyOffice 除了 /onlyoffice/ 路径，还需要访问 /cache/ 路径
最初只配置了 /onlyoffice/ 代理，没有配置 /cache/ 代理

解决方案：

单独为 /cache/ 路径添加代理配置

3. 第三个问题：502 Bad Gateway 错误（核心问题）

错误信息：

复制代码

GET https://chat.xutongbao.top/cache/.../Editor.bin 502 (Bad Gateway)

Nginx 错误日志：

复制代码

WSARecv() failed (10054: An existing connection was forcibly closed by the remote host)

原因分析：

通过 curl 命令测试发现：

✅ OnlyOffice 服务器本身可以正常访问
✅ cache 文件可以直接通过 HTTP 获取
❌ 通过 Nginx 代理时连接被远程主机强制关闭

深入分析：

二进制文件（Editor.bin）传输时的缓冲问题
gzip 压缩导致的连接中断
Connection 头设置不当导致过早关闭连接

最终解决方案：

优化 /cache/ 代理配置：

nginx 复制代码

location /cache/ {
    # 禁用 gzip 压缩
    proxy_set_header Accept-Encoding "";

    # 关闭代理缓冲（适合二进制文件流式传输）
    proxy_buffering off;
    proxy_cache off;
    proxy_request_buffering off;

    # 保持持久连接
    proxy_set_header Connection "";

    # 增大缓冲区
    proxy_buffer_size 128k;
    proxy_buffers 8 128k;
    proxy_busy_buffers_size 256k;
}

核心配置文件修改

1. Next.js 文件修改

文件路径： E:\source\m-yuying-nextjs\app\light\onlyOffice0120\page.tsx

第 440 行修改：

typescript 复制代码

// 修改前
src='http://20.51.117.204/web-apps/apps/api/documents/api.js'

// 修改后
src='https://chat.xutongbao.top/onlyoffice/web-apps/apps/api/documents/api.js'

2. Nginx 配置修改

文件路径： C:\tools\nginx-1.21.3\conf\nginx.conf

关键配置（第 204-293 行）：

A. /cache/ 路径代理（用于二进制文件）

nginx 复制代码

# OnlyOffice cache 路径代理
location /cache/ {
    # 设置允许跨域
    add_header 'Access-Control-Allow-Origin' '*' always;
    add_header 'Access-Control-Allow-Methods' 'GET, POST, OPTIONS' always;
    add_header 'Access-Control-Allow-Headers' 'User-Agent,Keep-Alive,Content-Type,Authorization' always;
    add_header 'Access-Control-Max-Age' 1728000 always;

    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header REMOTE-HOST $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-NginX-Proxy true;
    proxy_set_header Host $host;

    # 告诉后端服务这是 HTTPS 请求
    proxy_set_header X-Forwarded-Proto https;
    proxy_set_header X-Forwarded-Ssl on;

    # 禁用 gzip 压缩（关键！）
    proxy_set_header Accept-Encoding "";

    proxy_http_version 1.1;
    proxy_set_header Connection "";

    # 对于二进制文件，关闭缓冲（关键！）
    proxy_buffering off;
    proxy_cache off;
    proxy_request_buffering off;

    # 代理到 OnlyOffice 服务器
    proxy_pass http://20.51.117.204/cache/;

    # 增加超时时间
    proxy_connect_timeout 300s;
    proxy_send_timeout 300s;
    proxy_read_timeout 300s;

    # 缓冲区设置
    proxy_buffer_size 128k;
    proxy_buffers 8 128k;
    proxy_busy_buffers_size 256k;
}

B. /onlyoffice/ 路径代理（用于静态资源和 WebSocket）

nginx 复制代码

# OnlyOffice 代理配置
location /onlyoffice/ {
    # 设置允许跨域
    add_header 'Access-Control-Allow-Origin' '*' always;
    add_header 'Access-Control-Allow-Methods' 'GET, POST, OPTIONS' always;
    add_header 'Access-Control-Allow-Headers' 'User-Agent,Keep-Alive,Content-Type,Authorization' always;
    add_header 'Access-Control-Max-Age' 1728000 always;

    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header REMOTE-HOST $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-NginX-Proxy true;
    proxy_set_header Host $host;

    # 告诉后端服务这是 HTTPS 请求
    proxy_set_header X-Forwarded-Proto https;
    proxy_set_header X-Forwarded-Ssl on;

    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";

    # 将响应中的 HTTP 链接替换为 HTTPS（关键！）
    sub_filter 'http://chat.xutongbao.top' 'https://chat.xutongbao.top';
    sub_filter 'http://${host}' 'https://${host}';
    sub_filter_once off;
    sub_filter_types *;

    chunked_transfer_encoding off;
    # sub_filter 需要开启 buffering
    proxy_buffering on;
    proxy_cache off;

    # 代理到 OnlyOffice 服务器
    proxy_pass http://20.51.117.204/;

    # 增加超时时间
    proxy_connect_timeout 300s;
    proxy_send_timeout 300s;
    proxy_read_timeout 300s;

    # 缓冲区设置
    proxy_buffer_size 16k;
    proxy_buffers 4 64k;
    proxy_busy_buffers_size 128k;
}

配置位置说明：

这两个 location 配置必须放在 location / 之前，否则会被根路径匹配拦截。

curl 命令调试经验（重点）

为什么使用 curl 调试

在遇到 502 错误时，需要确定问题出在：

后端服务器本身不可用？
文件不存在？
Nginx 代理配置问题？

使用 curl 可以跳过 Nginx 直接测试后端服务器，快速定位问题。

curl 基础用法

1. 测试 URL 是否可访问（只看响应头）

bash 复制代码

curl -I http://20.51.117.204/web-apps/apps/api/documents/api.js

参数说明：

-I：只获取 HTTP 响应头，不下载内容（HEAD 请求）
适用场景：快速检查资源是否存在、服务器是否响应

成功的响应示例：

复制代码

HTTP/1.1 200 OK
Server: nginx
Content-Type: application/javascript
Content-Length: 64310

2. 测试带查询参数的 URL（需要用引号）

bash 复制代码

curl -I "http://20.51.117.204/cache/files/data/1768789600204-3qud71/Editor.bin/Editor.bin?md5=dyqUgG7uxOthzNEimCZ4qA&expires=1771642019"

注意事项：

URL 包含 & 等特殊字符时，必须用引号包裹
否则 & 会被解释为后台运行符号

3. 查看详细请求过程

bash 复制代码

curl -v http://20.51.117.204/cache/test.bin

参数说明：

-v：显示详细的请求和响应过程
可以看到：请求头、响应头、重定向、SSL 握手等

4. 测试 HTTPS 代理后的 URL

bash 复制代码

curl -I https://chat.xutongbao.top/onlyoffice/web-apps/apps/api/documents/api.js

用途：

验证 Nginx 代理配置是否生效
对比直接访问和代理访问的响应差异

Windows 11 系统使用 curl

方法一：使用 Git Bash（推荐）

如果安装了 Git for Windows，会自带 Git Bash。

打开方式：

开始菜单搜索 "Git Bash"
或右键文件夹选择 "Git Bash Here"

优势：

完整的 Linux 命令行环境
支持所有标准 curl 参数
兼容性好

示例：

bash 复制代码

# 在 Git Bash 中执行
curl -I http://20.51.117.204/web-apps/apps/api/documents/api.js

方法二：使用 PowerShell

Windows 11 自带 PowerShell，已内置 curl（实际是 Invoke-WebRequest 的别名）。

打开方式：

Win + X，选择 "Windows PowerShell (管理员)"
或开始菜单搜索 "PowerShell"

注意事项：

PowerShell 的 curl 是别名，不是真正的 curl，部分参数不兼容。

解决方法：使用原生 curl

powershell 复制代码

# 使用 curl.exe 而不是 curl 别名
curl.exe -I http://20.51.117.204/web-apps/apps/api/documents/api.js

方法三：使用 CMD

Windows 10 1803 及以后版本，CMD 也内置了 curl。

打开方式：

Win + R，输入 cmd
或开始菜单搜索 "命令提示符"

示例：

cmd 复制代码

curl -I http://20.51.117.204/web-apps/apps/api/documents/api.js

三种方法对比

方法	优点	缺点	推荐度
Git Bash	完整 Linux 环境，兼容性好	需要安装 Git	⭐⭐⭐⭐⭐
PowerShell	系统自带，功能强大	需要使用 `curl.exe`	⭐⭐⭐⭐
CMD	系统自带，简单直接	功能相对简单	⭐⭐⭐

本次调试中的实际应用

步骤 1：测试 OnlyOffice API 是否可访问

bash 复制代码

curl -I http://20.51.117.204/web-apps/apps/api/documents/api.js 2>&1 | head -20

参数说明：

2>&1：将错误输出重定向到标准输出
| head -20：只显示前 20 行（避免输出过多）

结果：

复制代码

HTTP/1.1 200 OK
Server: nginx
Content-Type: application/javascript
Content-Length: 64310

结论： ✅ OnlyOffice 服务器正常运行

步骤 2：测试问题文件是否存在

bash 复制代码

curl -I "http://20.51.117.204/cache/files/data/1768789600204-3qud71/Editor.bin/Editor.bin?md5=dyqUgG7uxOthzNEimCZ4qA&expires=1771642019&shardkey=1768789600204-3qud71&filename=Editor.bin" 2>&1 | head -20

结果：

复制代码

HTTP/1.1 200 OK
Server: nginx
Content-Type: application/octet-stream
Content-Length: 23844

结论： ✅ 文件存在且可以直接访问

步骤 3：对比分析

测试项	直接访问	通过 Nginx 代理	结论
OnlyOffice API	✅ 200 OK	✅ 200 OK	正常
cache 文件	✅ 200 OK	❌ 502 Bad Gateway	问题在 Nginx 代理

确定问题根源：

后端服务器正常
文件存在
问题出在 Nginx 代理配置

通过这个对比，我们快速定位到问题是 Nginx 在代理二进制文件时的配置不当（缓冲、压缩等）。

重启 Nginx 的方法

Windows 系统

方法 1：命令行重启（推荐）

bash 复制代码

# 进入 Nginx 目录
cd C:\tools\nginx-1.21.3

# 停止 Nginx
nginx.exe -s quit

# 等待 2 秒
timeout /t 2

# 启动 Nginx
nginx.exe

方法 2：任务管理器重启

Ctrl + Shift + Esc 打开任务管理器
找到 nginx.exe 进程
右键选择"结束任务"
命令行执行 nginx.exe 启动

方法 3：使用 reload（推荐用于配置更新）

bash 复制代码

nginx.exe -s reload

注意： 如果遇到权限错误，需要以管理员身份运行命令提示符。

测试配置是否正确

bash 复制代码

# 进入 Nginx 目录
cd C:\tools\nginx-1.21.3

# 测试配置文件语法
nginx.exe -t

成功输出：

复制代码

nginx: the configuration file C:\tools\nginx-1.21.3/conf/nginx.conf syntax is ok
nginx: configuration file C:\tools\nginx-1.21.3/conf/nginx.conf test is successful

关键技术点总结

1. 混合内容问题

问题根源：

HTTPS 页面加载 HTTP 资源会被浏览器阻止

解决要点：

所有资源必须通过 HTTPS 加载
使用 Nginx 代理将 HTTP 后端转换为 HTTPS 前端

2. 代理配置的位置顺序

关键原则：

Nginx location 匹配遵循"最长前缀匹配"和"配置顺序"原则。

正确顺序：

nginx 复制代码

location /cache/ { }      # 具体路径在前
location /onlyoffice/ { } # 具体路径在前
location / { }            # 根路径在最后

错误顺序：

nginx 复制代码

location / { }            # ❌ 根路径会拦截所有请求
location /cache/ { }      # ❌ 永远不会被匹配

3. 二进制文件代理优化

关键配置：

nginx 复制代码

# 禁用 gzip
proxy_set_header Accept-Encoding "";

# 关闭缓冲（适合大文件流式传输）
proxy_buffering off;
proxy_cache off;
proxy_request_buffering off;

# 保持持久连接
proxy_set_header Connection "";

4. HTTP 到 HTTPS 的链接替换

问题：

OnlyOffice 后端返回的响应中包含 HTTP 链接

解决：

nginx 复制代码

sub_filter 'http://chat.xutongbao.top' 'https://chat.xutongbao.top';
sub_filter_once off;  # 替换所有出现的地方
sub_filter_types *;   # 对所有类型的响应生效

注意：
sub_filter 需要 proxy_buffering on

5. 告知后端使用 HTTPS

作用：

让后端服务知道请求来自 HTTPS，从而生成正确的 HTTPS 链接

配置：

nginx 复制代码

proxy_set_header X-Forwarded-Proto https;
proxy_set_header X-Forwarded-Ssl on;

常见问题排查

Q1: 配置修改后不生效？

原因： 未重启 Nginx

解决：

bash 复制代码

cd C:\tools\nginx-1.21.3
nginx.exe -s quit
nginx.exe

Q2: 502 错误如何排查？

步骤：

查看 Nginx 错误日志

bash 复制代码

tail -50 C:\tools\nginx-1.21.3\logs\error.log

使用 curl 测试后端
bash 复制代码
```
curl -I http://后端地址
```
对比直接访问和代理访问的差异

Q3: curl 命令提示找不到？

解决方法：

Windows 11：使用 Git Bash 或 curl.exe
Windows 10：更新到最新版本

Q4: 权限不足无法重启 Nginx？

解决：

以管理员身份运行命令提示符

右键"命令提示符" → "以管理员身份运行"

完整配置检查清单

配置前检查

确认 OnlyOffice 后端服务器正常运行
确认 SSL 证书已配置
备份原始 nginx.conf 文件

配置修改

修改 Next.js 文件，使用 HTTPS 代理地址
在 Nginx 中添加 /onlyoffice/ 代理
在 Nginx 中添加 /cache/ 代理
配置 sub_filter 替换 HTTP 链接
配置跨域 CORS 头
设置 X-Forwarded-Proto 和 X-Forwarded-Ssl

配置后测试

执行 nginx -t 验证配置语法
重启 Nginx
使用 curl 测试代理路径
浏览器中测试 OnlyOffice 加载
检查浏览器控制台无错误
验证文档编辑功能正常

最终效果

✅ OnlyOffice 通过 HTTPS 正常加载

✅ 无混合内容警告

✅ 文档可以正常编辑

✅ cache 文件正常传输

✅ WebSocket 连接正常

经验教训

问题定位要分层：先确定是前端、代理还是后端的问题
善用 curl 工具：快速测试 HTTP 服务，绕过代理直接测试后端
查看错误日志：Nginx 错误日志提供了关键的调试信息
二进制文件代理：需要关闭缓冲和压缩
配置顺序很重要：具体路径要放在通配路径之前

文档编写日期： 2026-01-22
适用环境： Windows 11, Nginx 1.21.3, Next.js
作者备注： 本文档记录了完整的调试过程，重点介绍了 curl 工具在 Windows 上的使用方法。

OnlyOffice HTTPS 代理配置总结