使用 Apache 反向代理部署 WeKan：SSL、WebSocket 与子路径配置实战指南

使用 Apache 反向代理部署 WeKanSSL、WebSocket 与子路径配置实战指南【免费下载链接】wekanThe Open Source kanban, built with Meteor. GitHub issues/PRs are only for FLOSS Developers, not for support, support is at https://wekan.fi/commercial-support/ . PR source translation to imports/i18n/data/en.i18n.json, other translations at https://app.transifex.com/wekan/wekan项目地址: https://gitcode.com/GitHub_Trending/we/wekanWeKan 是一款基于 Meteor 构建的开源看板Kanban应用。在生产环境中通常不会让 Node.js 应用直接暴露公网端口而是由一个 Web 服务器如 Apache在前端终结 TLS、转发请求并代理实时 WebSocket 连接。本文以仓库中的 Apache 反向代理文档 为主体完整讲解从启用 mod_proxy 模块、配置 SSL 虚拟主机、处理 SockJS WebSocket 长连接到通过 Snap 设置ROOT_URL与端口的主 URL / 子 URL 两种部署形态并结合仓库源码解释每一处配置背后的原理与常见坑点。一、整体架构WeKan 只需要“反向代理”WeKan 的 Meteor 应用本身自带 HTTP 服务start-wekan.sh 中通过export PORT2000示例或export ROOT_URL...指定监听端口与对外地址Apache 只需要把流量反向转发给这个本机端口即可。有两个必须牢牢记住的安全前提永远不要启用ProxyRequests On这会把 Apache 变成一个“正向代理”任何互联网客户端都能借你的服务器去请求任意第三方主机形成开放代理漏洞。ProxyMaxForwards只能限制转发链的长度并不能关闭开放代理。因此文档中的每个虚拟主机示例都显式写了ProxyRequests Off防止全局配置中的不安全设置“泄漏”到 WeKan 主机上。二、启用 Mod_Proxy 相关模块在 Debian/Ubuntu 的 Apache 上用a2enmod一次性启用全部所需模块sudo a2enmod ssl proxy proxy_http proxy_wstunnel proxy_balancer各模块的作用模块用途ssl提供 HTTPSTLS能力proxymod_proxy 核心反向代理的基础proxy_http转发普通 HTTP 请求proxy_wstunnel转发 WebSocketws:///wss://升级请求proxy_balancer负载均衡相关为多后端扩展预留其中proxy_wstunnel至关重要WeKan 的前端与服务器之间的实时同步依赖 WebSocket。从源码看WeKan 的实时传输走的是 SockJS 协议——start-wekan.sh 中有明确注释sockjs is the only transport WeKan shipsWeKan 只内置 SockJS 传输并在启动时强制DDP_TRANSPORTsockjs。因此 WebSocket 升级路径/(sockjs/.../websocket)必须被 Apache 正确识别并隧道转发否则会退化为慢速长轮询。三、重启 Apache启用模块后立即重启使配置生效。按你的系统选择其一# Systemd 系统 sudo systemctl restart apache2 # 传统 Init.d 系统 sudo service apache2 restart四、启用 SSL 监听在 Apache 主配置如/etc/apache2/apache2.conf或ports.conf中加入Listen 443 NameVirtualHost *:443这告诉 Apache 在 443 端口监听 HTTPS 流量并允许基于主机名的虚拟主机在该端口上共存。五、配置反向代理虚拟主机在写虚拟主机之前先记住文档中反复强调的一条铁律必须把ROOT_URL设置为反向代理对外暴露的完整 URL或与ServerName一致。这条要求可以在仓库源码中找到证据。server/00checkStartup.js 中的启动检查代码显示WeKan 发出的每一封邮件看板邀请、密码重置、地址验证中的链接都由ROOT_URL拼接生成。如果ROOT_URL还是http://127.0.0.1/...收件人拿到的就是发件人自己机器上的地址邮件能发出、没有报错但链接谁也无法访问。同样start-wekan.sh 注释也强调ROOT_URL不对会导致翻译、附件上传等功能失效。因此反向代理与ROOT_URL必须成对配置、保持一致。场景 A主域名部署Main URL使用 Certbot 申请 Lets Encrypt 证书后配置/etc/apache2/sites-available/example.com.confVirtualHost *:443 ServerName example.com SSLEngine On SSLCertificateFile /etc/letsencrypt/live/example.com/fullchain.pem SSLCertificateKeyFile /etc/letsencrypt/live/example.com/privkey.pem Include /etc/letsencrypt/options-ssl-apache.conf ServerSignature Off ProxyRequests Off Location / require all granted /Location ProxyPassMatch ^/(sockjs\/.*\/websocket)$ ws://127.0.0.1:3001/$1 ProxyPass / http://127.0.0.1:3001/ ProxyPassReverse / http://127.0.0.1:3001/ /VirtualHost逐条拆解关键指令SSLCertificateFile/SSLCertificateKeyFileCertbot 生成的证书链与私钥路径Include /etc/letsencrypt/options-ssl-apache.conf引入 Certbot 推荐的安全 TLS 参数ServerSignature Off隐藏 Apache 版本信息降低信息泄露风险ProxyRequests Off显式关闭正向代理见第一节的安全说明ProxyPassMatch ^/(sockjs\/.*\/websocket)$ ws://127.0.0.1:3001/$1最关键的一行。用正则精确匹配 SockJS 的 WebSocket 升级请求路径以/sockjs/开头、以/websocket结尾并原样透传给 WeKan 的ws://端口。$1是正则捕获组把sockjs/.../websocket整段路径原样带回ProxyPass / http://127.0.0.1:3001/其余所有请求走普通 HTTP 反向代理ProxyPassReverse改写上游响应中的Location等头避免重定向把用户带到127.0.0.1。端口 3001 是文档示例中 WeKan 的监听端口。实际部署时它必须与你的 WeKan 实例端口一致——例如源码默认的 start-wekan.sh 中export PORT2000Snap 安装则用sudo snap set wekan port3001指定。请务必核对不要照抄数字。场景 B子路径部署Sub URL如果想把 WeKan 挂在https://example.com/wekan下配置如下VirtualHost *:443 ServerName example.com/wekan SSLEngine On SSLCertificateFile /etc/letsencrypt/live/example.com/fullchain.pem SSLCertificateKeyFile /etc/letsencrypt/live/example.com/privkey.pem Include /etc/letsencrypt/options-ssl-apache.conf ServerSignature Off ProxyRequests Off ProxyPassMatch ^/(sockjs\/.*\/websocket)$ ws://127.0.0.1:3001/wekan/$1 ProxyPass /wekan http://127.0.0.1:3001/wekan ProxyPassReverse /wekan http://127.0.0.1:3001/wekan /VirtualHost与主 URL 版本的三处差异WebSocket 匹配规则在转发目标后多了/wekan/前缀ws://127.0.0.1:3001/wekan/$1ProxyPass/ProxyPassReverse的路径前缀从/变为/wekan相应地ROOT_URL必须设为https://example.com/wekan见文末 Snap 配置。已知限制子路径部署下 favicon 加载目前存在问题详见 WeKan issue #1692 的讨论子路径用户可能看不到站点图标。如果希望该虚拟主机成为 443 端口的默认站点不依赖ServerName匹配把第一行改为VirtualHost _default_:443六、启用站点并重载 Apache启用站点首选a2ensite命令sudo a2ensite example.com也可以手动创建软链接sites-available中的配置只有被链接到sites-enabled才会生效sudo su cd /etc/apache2/sites-enabled ln -s ../sites-available/example.com.conf example.com.conf路径差异说明部分发行版如 RHEL/CentOS 系的 Apache httpd配置目录不同cd /etc/httpd/conf.d如果你的系统是这一类路径请把上述sites-available/sites-enabled的路径相应替换并使用httpd而非apache2作为服务名。重载配置# Systemd 系统 sudo systemctl restart apache2 # 传统 Init.d 系统 sudo service apache2 restart七、Snap 安装的配套设置如果 WeKan 是通过 Snap 安装的sudo snap install wekan反向代理就绪后还需要用snap set同步两件事监听端口与对外根地址。这里再次呼应第一节的规则——Snap 下的root-url就是ROOT_URL必须与 Apache 虚拟主机的ServerName完全一致。主 URL 形态sudo snap set wekan port3001 sudo snap set wekan root-urlhttps://example.com子 URL 形态snap set wekan port3001 snap set wekan root-urlhttps://example.com/wekan注意子 URL 形态下root-url带了/wekan路径这与上文场景 B 的 Apache 配置一一对应。设置完成后建议重启 Snap 服务使配置生效sudo systemctl restart snap.wekan.mongodb sudo systemctl restart snap.wekan.wekan该重启命令同样出现在仓库的 Nginx 反向代理文档 的 Snap 安装小节中属于 Snap 部署的标准流程。八、部署核对清单与故障排查思路完成上述步骤后按以下清单逐项自检模块是否齐全apache2ctl -M | grep proxy或httpd -M应能看到proxy_module、proxy_http_module、proxy_wstunnel_module端口是否一致Apache 转发的端口示例 3001与 WeKan 实际监听端口PORT或snap set wekan port必须相同ROOT_URL 是否匹配ROOT_URL必须等于浏览器访问的完整地址含路径与 https可参考 start-wekan.sh 中关于端口与 URL 一一对应的注释启动日志中的警告见 server/00checkStartup.js会在ROOT_URL缺失或仍指向 localhost 时明确提示WebSocket 是否升级打开浏览器开发者工具如果控制台出现WebSocket connection to wss://.../sockjs/.../websocket failed说明ProxyPassMatch的正则未命中或proxy_wstunnel未启用实时同步会退化为慢速长轮询应重点检查第一节与场景 A/B 中的 WebSocket 透传配置防火墙与监听确保 443 端口对外开放且 Apache 能访问本机 WeKan 端口如遇 SELinux 拦截可参考 Nginx 文档 中的setsebool -P httpd_can_network_connect 1思路不要直接关闭 SELinux。按以上顺序完成“启用模块 → 配置 SSL 虚拟主机 → 代理 HTTP 与 WebSocket → 同步 Snap 端口与 root-url → 重载并验证”即可在 Apache 之后稳定运行 WeKan同时获得 TLS 加密、域名访问与实时看板同步的完整体验。【免费下载链接】wekanThe Open Source kanban, built with Meteor. GitHub issues/PRs are only for FLOSS Developers, not for support, support is at https://wekan.fi/commercial-support/ . PR source translation to imports/i18n/data/en.i18n.json, other translations at https://app.transifex.com/wekan/wekan项目地址: https://gitcode.com/GitHub_Trending/we/wekan创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考