Excalidraw反向代理Nginx配置样例

Excalidraw 反向代理 Nginx 配置实践指南

在现代远程协作日益频繁的背景下，团队对轻量级、高自由度的在线白板工具需求持续增长。Excalidraw 凭借其手绘风格的视觉表达和出色的实时协作能力，逐渐成为技术设计、架构讨论和教学演示中的热门选择。然而，将其直接暴露于公网不仅存在安全风险，还难以满足企业级部署中对域名访问、HTTPS 加密和统一入口管理的要求。

此时，Nginx 作为反向代理层的价值便凸显出来——它不仅能将 Excalidraw 安全地“封装”起来，还能通过灵活的配置实现性能优化与访问控制。本文不提供泛泛而谈的理论讲解，而是从一个运维工程师的实际视角出发，分享一套经过生产验证的 Nginx 配置方案，并深入剖析其中的关键细节与常见陷阱。

核心组件协同机制解析

要让 Excalidraw 在反向代理环境下稳定运行，首先要理解它的运行模式与网络依赖。Excalidraw 前端基于 React 构建，静态资源由内置服务器提供，同时依赖 WebSocket 实现多用户实时同步。这意味着代理配置不仅要能正确转发 HTTP 请求，还必须支持协议升级（Upgrade），否则协作功能将无法建立连接。

Nginx 的proxy_pass模块正是为此类场景设计。当客户端发起 WebSocket 握手时，会携带Upgrade: websocket和Connection: Upgrade头部。若 Nginx 未显式传递这些头部，后端服务将收不到升级指令，导致连接回落为普通 HTTP，最终表现为“别人看不到我的笔迹”或“画布不同步”。

因此，以下配置片段不是可选项，而是协作功能可用的前提：

proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "upgrade";

同时，必须启用 HTTP/1.1 协议版本，因为 HTTP/1.0 不支持持久连接与协议升级：

proxy_http_version 1.1;

这一点常被忽略，尤其是在复制粘贴配置模板时。许多人在配置完成后发现页面可以打开，但协作失效，问题根源往往就在这里。

完整 Nginx 配置示例与逐行解读

以下是适用于生产环境的完整 Nginx server 块配置，已包含 HTTPS 支持、静态资源缓存、安全加固等关键要素：

server { listen 80; server_name whiteboard.example.com; # 强制跳转至 HTTPS return 301 https://$host$request_uri; } server { listen 443 ssl http2; server_name whiteboard.example.com; # SSL 证书（Let's Encrypt 示例） ssl_certificate /etc/letsencrypt/live/whiteboard.example.com/fullchain.pem; ssl_certificate_key /etc/letsencrypt/live/whiteboard.example.com/privkey.pem; # 推荐的安全加密套件 ssl_protocols TLSv1.2 TLSv1.3; ssl_ciphers ECDHE-RSA-AES256-GCM-SHA512:DHE-RSA-AES256-GCM-SHA512; ssl_prefer_server_ciphers off; add_header Strict-Transport-Security "max-age=63072000" always; # 静态资源缓存：提升加载速度，减少带宽消耗 location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|woff|woff2)$ { root /var/www/excalidraw; expires 1y; add_header Cache-Control "public, immutable"; access_log off; log_not_found off; } # 主应用代理 location / { proxy_pass http://127.0.0.1:8000; proxy_http_version 1.1; 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 Upgrade $http_upgrade; proxy_set_header Connection "upgrade"; proxy_redirect off; proxy_read_timeout 90s; proxy_send_timeout 90s; # 可选：开启代理缓冲以提升大响应处理效率 proxy_buffering on; proxy_buffer_size 128k; proxy_buffers 4 256k; } # 健康检查接口（可用于负载均衡探测） location = /healthz { access_log off; return 200 "healthy\n"; add_header Content-Type text/plain; } }

关键参数说明

• X-Forwarded-*头部：确保后端服务能获取真实客户端 IP 和协议类型。某些日志记录或审计功能依赖这些信息。
• 超时设置：90 秒是合理值，过短可能导致长连接中断，过长则占用资源。根据实际网络状况微调。
• HSTS 头：强制浏览器后续请求使用 HTTPS，防止中间人攻击。
• 静态资源缓存策略：一年有效期 +immutable标志，意味着浏览器永远不会重新验证，极大提升二次访问体验。前提是资源文件名含哈希指纹（Excalidraw 默认构建方式即如此）。

部署架构与工作流程

典型的部署拓扑如下：

[用户浏览器] ↓ HTTPS (443) [Nginx 反向代理] ↓ HTTP (localhost:8000) [Docker 容器: Excalidraw] ↑ [Redis/Firebase] ← 可选：用于状态同步

整个流程如下：

1. 用户访问https://whiteboard.example.com
2. Nginx 终止 SSL，解密请求
3. 若为静态资源（如main.js），直接返回本地缓存
4. 若为主路径/或 API 路径，则转发至本地 8000 端口的容器
5. WebSocket 连接到来时，Nginx 正确代理协议升级，保持长连接
6. 所有流量均不直接暴露容器端口，后端仅监听内网接口

这种分层结构符合最小权限原则：Excalidraw 容器无需处理 SSL，也不必绑定公网 IP，降低了攻击面。

子路径部署的特殊处理

有时需要在同一台服务器上托管多个服务，例如将 Excalidraw 部署在/whiteboard路径下。这时仅修改 Nginx 配置是不够的，还需调整应用本身的路径感知逻辑。

Nginx 配置调整

location /whiteboard/ { proxy_pass http://127.0.0.1:8000/; proxy_http_version 1.1; 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 Upgrade $http_upgrade; proxy_set_header Connection "upgrade"; proxy_redirect off; }

注意proxy_pass结尾的/，它表示将/whiteboard/xxx映射为/xxx转发给后端。

应用层环境变量设置

Excalidraw 提供了PUBLIC_URL环境变量来指定基础路径。启动容器时需添加：

docker run -d \ --name excalidraw \ -p 8000:8000 \ -e PUBLIC_URL=/whiteboard \ excalidraw/excalidraw

否则前端资源仍会尝试从/路径加载，导致 404 错误。

安全与运维最佳实践

1. 访问控制增强

虽然 Excalidraw 本身无认证机制，但可在 Nginx 层添加 Basic Auth：

location / { auth_basic "Restricted Access"; auth_basic_user_file /etc/nginx/.htpasswd; # 其余代理配置... }

生成密码文件：

printf "admin:$(openssl passwd -apr1 yourpassword)\n" > /etc/nginx/.htpasswd

更高级的场景可集成 OAuth 中间件（如 oauth2-proxy）实现单点登录。

2. 自动化证书续签

使用 Certbot 自动管理 Let’s Encrypt 证书：

certbot --nginx -d whiteboard.example.com

并设置定时任务自动续期：

0 12 * * * /usr/bin/certbot renew --quiet

3. 日志与监控

开启访问日志有助于排查问题：

access_log /var/log/nginx/excalidraw.access.log combined; error_log /var/log/nginx/excalidraw.error.log warn;

结合 Prometheus + Grafana 可监控请求延迟、错误率等指标。

4. 防火墙策略

限制仅开放 80 和 443 端口：

ufw allow 80/tcp ufw allow 443/tcp ufw enable

避免意外暴露 Docker 默认端口（如 2375）或调试接口。

常见问题与排错思路

建议使用浏览器开发者工具查看 Network 面板，重点关注：

• 请求是否被重定向到 HTTPS
• 静态资源是否命中缓存（Status Code 304）
• WebSocket 连接是否成功建立（ws:// 或 wss://）

总结与延伸思考

这套 Nginx 反向代理配置不仅仅是“让 Excalidraw 能上网”，更是构建一个可持续演进的企业级协作平台的基础。它解决了最基本的可用性、安全性与性能问题，也为后续扩展留出了空间：

• 可接入统一身份认证系统；
• 可集成审计日志记录用户操作；
• 可结合对象存储实现画布持久化备份；
• 可前置 CDN 实现全球加速。

更重要的是，该模式具有高度通用性。无论是部署 Draw.io、TiddlyWiki 还是其他基于 Web 的开源工具，都可以沿用类似的反向代理架构。掌握这一套方法论，意味着你已经具备了将任何内部工具快速、安全地推向团队的能力。

最终，技术的价值不在于复杂度，而在于能否真正服务于协作效率的提升。一个配置得当的 Nginx，就是那座看不见却至关重要的桥梁。