Excalidraw反向代理配置（Nginx/Apache）

Excalidraw反向代理配置（Nginx/Apache）

在现代远程协作日益频繁的背景下，可视化工具已成为技术团队不可或缺的一部分。Excalidraw 作为一款轻量、开源且支持实时协作的手绘风格白板应用，正被越来越多企业用于架构设计、流程梳理和原型草图绘制。其最大优势之一是支持私有化部署——这意味着你可以将它运行在内网环境中，确保敏感信息不外泄。

但直接暴露服务端口显然不是一种安全的做法。更合理的方案是通过反向代理服务器来统一入口、隐藏后端细节，并集中处理 HTTPS 加密与访问控制。Nginx 和 Apache 是两种最常用的反向代理选择，它们各有特点，适用于不同场景。

那么问题来了：如何正确地为 Excalidraw 配置 Nginx 或 Apache 的反向代理？尤其是当涉及到 WebSocket 实时同步、路径路由和 HTTPS 终止时，稍有不慎就会导致“协作功能失效”或“资源加载失败”这类令人头疼的问题。

我们不妨从实际需求出发，深入剖析这两种方案的关键配置点。

Nginx：高性能代理的首选

如果你追求高并发下的稳定表现，Nginx 几乎是默认选项。它的事件驱动模型让它能轻松应对成千上万的同时连接，非常适合团队高频使用的协作场景。

假设你的 Excalidraw 正在本地3000端口运行（比如通过npm run start启动），而你希望外部用户通过https://your-domain.com/excalidraw访问它。这时，Nginx 就扮演了中间桥梁的角色——接收公网请求，转发给内部服务，并把响应结果送回客户端。

核心配置如下：

server { listen 80; server_name your-domain.com; return 301 https://$server_name$request_uri; } server { listen 443 ssl http2; server_name your-domain.com; ssl_certificate /path/to/fullchain.pem; ssl_certificate_key /path/to/privkey.pem; ssl_protocols TLSv1.2 TLSv1.3; ssl_ciphers HIGH:!aNULL:!MD5; location /excalidraw/ { proxy_pass http://127.0.0.1:3000/; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "upgrade"; 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; proxy_set_header X-Forwarded-Host $host; proxy_cache_bypass $http_upgrade; proxy_buffering off; } location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg)$ { root /var/www/excalidraw/build; expires 1y; add_header Cache-Control "public, immutable"; } }

这里面有几个关键点值得特别注意：

• proxy_set_header Upgrade和Connection "upgrade"：这是实现 WebSocket 协议升级的核心。如果没有这两行，前端虽然能打开页面，但会提示“无法连接到协作服务器”，因为升级请求被当作普通 HTTP 处理了。

• 路径末尾的斜杠必须一致：location /excalidraw/和proxy_pass http://127.0.0.1:3000/都带斜杠，表示前缀替换。如果少了一个斜杠，可能导致静态资源路径错乱，出现 404。

• 关闭缓冲proxy_buffering off：对于实时消息传输来说，延迟越低越好。开启缓冲可能会累积数据包，影响协作体验。

• X-Forwarded-* 头部字段：这些头能让后端准确识别原始客户端 IP、协议类型等信息，在日志分析和权限判断中非常有用。

另外，建议始终启用 HTTPS 并配置 HSTS，避免中间人攻击。证书可以用 Let’s Encrypt 免费获取，配合 Certbot 自动续期。

Apache：稳重老将的优雅接入

对于已经使用 Apache 作为 Web 服务器的企业环境，比如 LAMP 架构，再额外引入 Nginx 反而增加了运维复杂度。这时候，用 Apache 自身的模块完成反向代理是个更自然的选择。

Apache 虽然基于多进程/线程模型，性能略逊于 Nginx，但在稳定性与兼容性方面久经考验。只要合理配置，完全能满足中小型团队的需求。

要实现类似功能，需要启用三个关键模块：
-mod_proxy
-mod_proxy_http
-mod_proxy_wstunnel

然后在虚拟主机中添加如下配置：

<VirtualHost *:80> ServerName your-domain.com Redirect permanent / https://your-domain.com/ </VirtualHost> <VirtualHost *:443> ServerName your-domain.com SSLEngine on SSLCertificateFile /path/to/fullchain.pem SSLCertificateKeyFile /path/to/privkey.pem ProxyPreserveHost On ProxyRequests Off ProxyPass /excalidraw/ http://127.0.0.1:3000/ ProxyPassReverse /excalidraw/ http://127.0.0.1:3000/ ProxyPassMatch ^/excalidraw/(.*)/websocket$ ws://127.0.0.1:3000/$1/websocket RequestHeader set X-Forwarded-Proto "https" RequestHeader set X-Forwarded-Port "443" LogLevel proxy:debug ErrorLog ${APACHE_LOG_DIR}/excalidraw_error.log CustomLog ${APACHE_LOG_DIR}/excalidraw_access.log combined </VirtualHost>

这里最关键的其实是ProxyPassMatch这一行。为什么不能只用ProxyPass？

因为普通的ProxyPass不会自动处理 WebSocket 升级请求。你需要显式告诉 Apache：“凡是匹配/excalidraw/*/websocket的路径，请走 WebSocket 隧道”。否则，即使 HTTP 请求能通，实时通信也会失败。

此外，ProxyPreserveHost On很重要。它保留了原始 Host 头，防止后端生成错误的重定向 URL。例如，某些框架可能根据 Host 动态拼接回调地址，若 Host 被替换成127.0.0.1，就会跳转失败。

调试时可以打开LogLevel proxy:debug查看详细的代理日志。你会发现，每次 WebSocket 建立过程中都会记录升级过程，这对排查问题非常有帮助。

架构落地：从理论到实践

典型的部署结构通常是这样的：

[Client Browser] ↓ (HTTPS) [Nginx/Apache 反向代理] ↓ (HTTP/ws) [Excalidraw 后端 (Node.js)] ↓ [可选数据库 + 文件存储]

这种分层架构带来了几个明显好处：

• 安全隔离：真实服务监听在127.0.0.1:3000，仅限本机访问，外部无法直接扫描端口。
• 统一入口：多个内部系统（如 Jenkins、Wiki、CI/CD）可以通过/jenkins、/wiki、/excalidraw共享同一个域名，简化 DNS 和防火墙策略。
• 集中管理 SSL：无需每个服务都维护证书，反向代理统一做 TLS 终止即可。
• 便于监控与审计：所有访问流量都经过代理层，日志集中收集，方便做行为分析或异常检测。

举个例子，某公司已有 Apache 服务器托管官网，现在想加入 Excalidraw 供研发画图使用。只需新增一个ProxyPass规则，重启服务，就能立即上线，无需改动现有架构。

常见问题与避坑指南

1. 协作功能无法使用？

检查是否正确代理了 WebSocket。Nginx 看Upgrade头，Apache 看ProxyPassMatch是否命中。浏览器开发者工具里查看网络请求，确认是否有101 Switching Protocols响应。

2. 页面打开但样式丢失？

多半是路径配置不一致。比如location /excalidraw没有结尾斜杠，但proxy_pass有，会导致路径拼接出错。建议统一加斜杠。

3. 如何提升性能？

对 JS、CSS、图片等静态资源设置长期缓存：

location ~* \.(js|css|png|svg)$ { expires 1y; add_header Cache-Control "public, immutable"; }

这样浏览器第二次访问就不会重复下载，大幅提升加载速度。

4. 安全加固怎么做？

除了 HTTPS，还可以：
- 使用 WAF 插件（如 ModSecurity）防御 SQL 注入、XSS；
- 添加 CSP 头限制脚本来源；
- 禁用不必要的 HTTP 方法（PUT、DELETE）；
- 设置速率限制防暴力探测。

甚至可以在代理层增加基础认证，实现简单的登录保护：

location /excalidraw/ { auth_basic "Restricted Access"; auth_basic_user_file /etc/nginx/.htpasswd; ... }

结语

无论是选用 Nginx 还是 Apache，反向代理的本质目标是一致的：让 Excalidraw 更安全、更易用、更容易融入现有 IT 体系。

Nginx 更适合对性能敏感、需要承载大量并发协作的场景；而 Apache 则胜在生态成熟、集成简单，尤其适合已有 Apache 基础设施的组织。

最终选择哪个，取决于你的技术栈偏好和运维习惯。但无论哪种方式，只要掌握了核心原理——路径映射、头部传递、WebSocket 支持——配置起来都会得心应手。

当你看到团队成员顺利进入https://your-domain.com/excalidraw开始流畅协作时，就知道这一番配置是值得的。