Windows Server Nginx 代理企业内网 API 偶发超时处理与保活 SOP(20260608))

文章目录

[1. 文档目的](#1. 文档目的)
[2. 系统链路说明](#2. 系统链路说明)
[3. 问题现象](#3. 问题现象)
[4. 初步原因判断](#4. 初步原因判断)
[5. 当前稳定方案](#5. 当前稳定方案)
[6. 保活脚本配置](#6. 保活脚本配置)
- [6.1 PowerShell 保活脚本](#6.1 PowerShell 保活脚本)
- [6.2 创建 Windows 定时任务](#6.2 创建 Windows 定时任务)
- [6.3 手动运行定时任务](#6.3 手动运行定时任务)
- [6.4 查看定时任务状态](#6.4 查看定时任务状态)
- [6.5 查看保活日志](#6.5 查看保活日志)
结尾提醒

1. 文档目的

本文用于说明 Windows Server 上通过 Nginx 代理企业内网 API 时，偶发出现上游连接超时的问题现象、初步原因判断以及当前采用的轻量保活方案。

2. 系统链路说明

当前系统通过 Windows Server 上的 Nginx，将前端请求代理到企业内网上游 API Gateway。

整体访问链路如下：

text 复制代码

前端浏览器
    ↓
http://<NGINX_SERVER_IP>:<NGINX_LISTEN_PORT>/<LOCAL_API_PATH>
    ↓
Windows Server Nginx
    ↓
https://<UPSTREAM_API_GATEWAY_DOMAIN>/<UPSTREAM_API_PATH>
    ↓
企业内网上游 API Gateway / 后端服务

占位符说明：

text 复制代码

<NGINX_SERVER_IP>              Nginx 所在 Windows Server IP
<NGINX_LISTEN_PORT>            Nginx 对外监听端口
<LOCAL_API_PATH>               Nginx 本地代理接口路径
<UPSTREAM_API_GATEWAY_DOMAIN>  上游 API Gateway 域名
<UPSTREAM_API_PATH>            上游后端 API 路径
<NGINX_INSTALL_DIR>            Nginx 安装目录

3. 问题现象

系统运行过程中，前端访问 Nginx 代理接口时，偶发出现请求失败或接口无响应的情况。

Nginx 错误日志中可能出现类似信息：

text 复制代码

connect() failed (10060) while connecting to upstream
upstream: "https://<UPSTREAM_API_GATEWAY_IP>:443/<UPSTREAM_API_PATH>"

该错误含义是：

text 复制代码

Nginx 尝试连接上游 API Gateway 的 443 端口时发生 TCP 连接超时。

该类问题通常不是以下原因导致：

text 复制代码

1. 前端 CORS 问题
2. API Key 错误
3. Nginx location 路由匹配错误
4. OPTIONS / POST 请求方法问题

如果是认证或权限问题，通常会返回：

text 复制代码

401
403

而不是：

text 复制代码

connect() failed (10060)

4. 初步原因判断

根据现场观察，该问题更符合企业内网环境中的链路冷启动或会话老化现象。

可能涉及：

text 复制代码

防火墙会话老化
NAT 映射失效
跨网段访问策略偶发丢包
安全网关连接状态刷新
API Gateway 前置网络设备空闲超时

典型表现为：

text 复制代码

长时间空闲后或者刚配置完成以后，Nginx 到上游 API Gateway 的连接一直失败。
手动执行一次端口连通性测试后，Nginx 代理恢复正常。

手动测试命令如下：

powershell 复制代码

Test-NetConnection <UPSTREAM_API_GATEWAY_DOMAIN> -Port 443

该命令只测试：

text 复制代码

Windows Server -> 上游 API Gateway:443

它不会调用真实业务 API，也不需要 API Key。

5. 当前稳定方案

当前采用轻量端口保活方式：

text 复制代码

Windows 任务计划程序
    ↓
定时执行 Test-NetConnection
    ↓
保持 Windows Server 到上游 API Gateway 443 端口链路活跃

推荐频率：

text 复制代码

每 5 分钟一次，或者根据实际情况进行设置

不建议设置过于频繁，例如：

text 复制代码

每 10 秒一次
每 30 秒一次

原因：

text 复制代码

1. 没有必要
2. 可能触发安全设备审计
3. 可能被误判为异常探测行为

6. 保活脚本配置

6.1 PowerShell 保活脚本

建议脚本路径：

text 复制代码

<NGINX_INSTALL_DIR>\upstream_port_keepalive.ps1

示例：

text 复制代码

D:\nginx\upstream_port_keepalive.ps1

脚本内容如下：

powershell 复制代码

$LogFile = "<NGINX_INSTALL_DIR>\logs\upstream_port_keepalive.log"
$Time = Get-Date -Format "yyyy-MM-dd HH:mm:ss"

$result = Test-NetConnection <UPSTREAM_API_GATEWAY_DOMAIN> -Port 443

"$Time TcpTestSucceeded=$($result.TcpTestSucceeded) RemoteAddress=$($result.RemoteAddress) SourceAddress=$($result.SourceAddress)" |
    Out-File -FilePath $LogFile -Append -Encoding utf8

需要替换以下内容：

text 复制代码

<NGINX_INSTALL_DIR>
<UPSTREAM_API_GATEWAY_DOMAIN>

6.2 创建 Windows 定时任务

使用管理员 CMD 执行：

bat 复制代码

schtasks /Create /TN "Enterprise_API_Port_KeepAlive" /TR "powershell.exe -WindowStyle Hidden -ExecutionPolicy Bypass -File <NGINX_INSTALL_DIR>\upstream_port_keepalive.ps1" /SC MINUTE /MO 5 /RL HIGHEST /F

参数说明：

text 复制代码

/TN              任务名称
/TR              执行内容
/SC MINUTE       按分钟执行
/MO 5            每 5 分钟执行一次
/RL HIGHEST      使用最高权限运行
/F               覆盖已有同名任务

创建任务时，建议在任务计划程序中同时确认以下选项：

text 复制代码

✅ 不論使用者登入與否均執行
✅ 以最高權限執行
❌ 不要儲存密碼

说明：

text 复制代码

1. 「不論使用者登入與否均執行」
   可确保用户注销、远程桌面断开后，保活任务仍会继续后台执行。

2. 「以最高權限執行」
   可避免 PowerShell、网络探测或日志写入权限不足。

3. 不勾选「不要儲存密碼」
   部分环境下可能导致任务无法正常访问网络资源。

6.3 手动运行定时任务

bat 复制代码

schtasks /Run /TN "Enterprise_API_Port_KeepAlive"

6.4 查看定时任务状态

bat 复制代码

schtasks /Query /TN "Enterprise_API_Port_KeepAlive" /V /FO LIST

重点关注：

text 复制代码

Last Run Time
Last Result
Next Run Time
Task To Run

如果：

text 复制代码

Last Result: 0

通常表示任务执行成功。

6.5 查看保活日志

PowerShell 执行：

powershell 复制代码

Get-Content <NGINX_INSTALL_DIR>\logs\upstream_port_keepalive.log -Tail 20

正常日志示例：

text 复制代码

2026-06-01 19:40:12 TcpTestSucceeded=True RemoteAddress=<UPSTREAM_API_GATEWAY_IP> SourceAddress=<NGINX_SERVER_IP>

如果看到：

text 复制代码

TcpTestSucceeded=True

说明 Windows Server 到上游 API Gateway 的 443 端口当前连通，保活任务正常。

如果看到：

text 复制代码

TcpTestSucceeded=False

说明当前 Windows Server 到上游 API Gateway 的 443 端口不可达，需要由网络、运维或相关系统负责人进一步确认链路、防火墙、路由或上游服务状态。

结尾提醒

该保活方式仅测试上游 443 端口连通性：

text 复制代码

Test-NetConnection <UPSTREAM_API_GATEWAY_DOMAIN> -Port 443

它不会调用真实业务 API，因此：

text 复制代码

不需要 API Key
不会触发真实业务请求
不会产生业务数据变更