Symfony 5 项目中的 Mercure 集成指南
mercure 是一个基于服务器发送事件（sse）的实时通信协议，它允许服务器向连接的客户端推送更新。在 symfony 5 项目中集成 mercure，可以轻松构建聊天、通知、实时仪表盘等功能。本教程将详细介绍其配置、启动过程，并解决一个常见的访问问题。
1. Mercure Hub 环境搭建
首先，您需要下载并运行 Mercure Hub 服务器。Mercure Hub 是一个独立的二进制文件，不依赖于 Symfony 应用。
下载 Mercure Hub: 访问 Mercure 的 GitHub 发布页面（例如：https://github.com/dunglas/mercure/releases），下载适用于您操作系统的最新版本。对于 Windows 系统，通常是 mercure_X.Y.Z_Windows_amd64.zip 或 mercure_X.Y.Z_Windows_arm64.zip。 下载后，将其解压到一个方便的位置，例如您的项目根目录或一个独立的工具目录。
-
启动 Mercure Hub: Mercure Hub 需要通过命令行启动。在启动前，您需要设置 JWT 密钥，用于发布者和订阅者的认证。在 Windows PowerShell 中，可以按如下方式设置环境变量并启动：
$env:MERCURE_PUBLISHER_JWT_KEY='!ChangeMe!'; $env:MERCURE_SUBSCRIBER_JWT_KEY='!ChangeMe!'; .\mercure.exe run -config Caddyfile.dev
- !ChangeMe! 应替换为生产环境中的强密码。
- .\mercure.exe 是您解压后的 Mercure 可执行文件。
- -config Caddyfile.dev 参数指示 Mercure 使用 Caddyfile.dev 文件进行配置，该文件通常包含开发环境下的 Caddy 服务器配置，负责处理 HTTPS 和 Mercure 端点。
成功启动后，您会在命令行中看到类似以下的日志输出，表明 Mercure Hub 正在监听并已启用 TLS：
2021/11/16 01:39:58.029 INFO http server is listening only on the HTTPS port but has no TLS connection policies; adding one to enable TLS {"server_name": "srv0", "https_port": 443} 2021/11/16 01:39:58.029 INFO http enabling automatic HTTP->HTTPS redirects {"server_name": "srv0"} ... 2021/11/16 01:39:58.143 INFO serving initial configuration请注意，这些日志表明 Caddy 服务器正在运行，并处理 HTTPS 请求。Mercure Hub 实际上作为 Caddy 的一个反向代理目标。
2. Symfony Mercure Bundle 配置
在 Symfony 项目中，您需要安装 symfony/mercure 组件包来与 Mercure Hub 交互。
-
安装 Mercure Bundle: 在您的 Symfony 项目根目录中，通过 Composer 安装 Mercure Bundle：
composer require symfony/mercure
-
配置 .env 文件: 安装完成后，Symfony 会自动在您的 .env 文件中添加 Mercure 相关的配置项。您需要根据您的 Mercure Hub 实际运行情况进行调整。
# See https://symfony.com/doc/current/mercure.html#configuration # The URL of the Mercure hub, used by the app to publish updates (can be a local URL) MERCURE_URL=https://127.0.0.1:8000/.well-known/mercure # The public URL of the Mercure hub, used by the browser to connect MERCURE_PUBLIC_URL=https://127.0.0.1:8000/.well-known/mercure # The secret used to sign the JWTs MERCURE_JWT_SECRET="!ChangeMe!"
- MERCURE_URL: 这是您的 Symfony 应用用于向 Mercure Hub 发布更新的 URL。
- MERCURE_PUBLIC_URL: 这是浏览器或其他客户端用于连接 Mercure Hub 以订阅更新的公共 URL。
- MERCURE_JWT_SECRET: 必须与您在启动 Mercure Hub 时设置的 MERCURE_PUBLISHER_JWT_KEY 和 MERCURE_SUBSCRIBER_JWT_KEY 保持一致。
重要提示: 请确保 MERCURE_URL 和 MERCURE_PUBLIC_URL 中的端口（例如 :8000）与您的 Mercure Hub 实际监听的端口一致。Caddyfile.dev 默认通常会将 Mercure 代理到 8000 端口。
3. 解决 Mercure Hub 访问异常问题
在上述配置和启动步骤完成后，一个常见的困惑是无法通过浏览器直接访问 Mercure Hub 的 .well-known/mercure 端点。
问题现象: 当您在浏览器中尝试访问 https://localhost/.well-known/mercure 时，可能会收到 "Not Found" 错误，并显示类似 "Apache/2.4.46 (Win64) OpenSSL/1.1.1h PHP/7.4.25 Server at localhost Port 443" 的信息。
原因分析: 这个错误表明您的请求被 Apache 服务器（或任何监听 443 端口的 Web 服务器）拦截了，而不是 Mercure Hub。尽管 Mercure Hub 已经启动并在日志中显示处理 HTTPS，但它通常不会监听标准的 443 端口，除非您在 Caddyfile.dev 中明确配置了。默认情况下，或者在 Caddyfile.dev 的特定配置下，Mercure Hub 可能通过 Caddy 在一个非标准端口（如 8000）提供服务。
解决方案: 您需要使用 Mercure Hub 实际监听的端口来访问它。根据 .env 中的配置以及 Caddyfile.dev 的常见设置，这个端口通常是 8000。
因此，在浏览器中，您应该访问：
https://localhost:8000/.well-known/mercure
当您使用正确的端口访问时，如果一切配置正确，您应该会看到一个空的响应，或者一个包含 Mercure Hub 版本信息、CORS 头部等内容的响应，而不是 "Not Found" 错误。这表明您的浏览器已成功连接到 Mercure Hub。
4. 最佳实践与注意事项
- JWT 密钥安全: 在生产环境中，切勿使用 !ChangeMe! 作为 JWT 密钥。请生成一个复杂且足够长的随机字符串，并妥善保管。
- 端口一致性: 始终确保 Symfony 应用的 .env 配置（MERCURE_URL 和 MERCURE_PUBLIC_URL）与 Mercure Hub 实际监听的端口保持一致。如果修改了 Caddyfile.dev 中的端口，也需要相应更新 .env。
- 防火墙: 确保您的操作系统防火墙没有阻止对 Mercure Hub 监听端口（例如 8000）的访问。
- Caddyfile.dev: 了解 Caddyfile.dev 的内容有助于您更好地理解 Mercure Hub 的网络配置。它通常会配置 Caddy 作为反向代理，将请求路由到 Mercure 服务的内部端口。
- 生产环境部署: 在生产环境中，您可能需要将 Mercure Hub 部署为一个长期运行的服务（例如使用 systemd 或 Docker），并配置一个专业的 Web 服务器（如 Nginx 或 Caddy）作为反向代理，处理 TLS 终止和域名映射。
总结
通过遵循上述步骤，您可以在 Symfony 5 项目中成功配置、启动 Mercure 实时通信服务，并解决常见的访问问题。关键在于理解 Mercure Hub 的独立运行机制及其端口配置，并确保 Symfony 应用和客户端使用正确的 URL 来发布和订阅更新。一旦 Mercure Hub 能够正确访问，您就可以开始在 Symfony 应用中构建强大的实时功能了。
