Uptime-Kuma 反向代理配置问题解析与解决方案

在使用 Uptime-Kuma 监控工具时，许多用户会遇到反向代理配置不当导致无法访问的问题。本文将深入分析常见配置错误，并提供专业可靠的解决方案。

常见配置问题分析

大多数用户在配置 Nginx 反向代理时容易犯以下几个错误：

1. 子目录路径问题：尝试将 Uptime-Kuma 部署在子目录下（如 example.com/uptimekuma），这是目前版本不支持的配置方式

2. 代理头设置不完整：缺少必要的 HTTP 头信息，特别是 WebSocket 升级头

3. 端口映射错误：容器端口与主机端口映射不一致

正确的 Nginx 配置方案

以下是经过验证的标准 Nginx 反向代理配置（带 SSL）：

server {
    listen 443 ssl;
    server_name status.example.com;
    
    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;
    
    location / {
        proxy_pass http://localhost:3001;
        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 X-Forwarded-Proto $scheme;
        
        # WebSocket 支持
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

关键配置说明

1. 域名配置：必须使用独立域名或子域名，不能使用子目录路径

2. WebSocket 支持：必须包含 Upgrade 和 Connection 头，否则实时监控功能将无法正常工作

3. 安全头设置：X-Forwarded-* 系列头确保应用能正确识别客户端信息

Docker 部署注意事项

使用 Docker 部署时，需要确保：

1. 端口映射正确：- "3001:3001" 表示将容器内 3001 端口映射到主机 3001 端口

2. 数据卷配置：持久化存储监控数据，避免容器重启后数据丢失

3. 网络配置：确保容器网络与主机网络能够正常通信

故障排查步骤

当反向代理不工作时，建议按以下步骤排查：

1. 检查 Nginx 错误日志：通常位于 /var/log/nginx/error.log

2. 直接访问后端服务：尝试直接访问 http://localhost:3001 确认 Uptime-Kuma 是否正常运行

3. 检查端口监听状态：使用 netstat -tulnp 或 ss -tulnp 确认 3001 端口是否被监听

4. 验证 SSL 证书：确保证书路径正确且权限设置合理

通过以上专业配置和排查方法，可以解决绝大多数 Uptime-Kuma 反向代理相关的问题，确保监控服务稳定可靠地运行。