mercure 是一个开放的网络协议，用于推送实时更新到 web 浏览器和其他客户端。通过与 symfony 框架集成，开发者可以轻松地为应用程序添加实时功能，如聊天、通知或仪表盘更新。本指南将详细介绍如何在 symfony 5 项目中配置和运行 mercure 服务，并解决常见的访问问题。
1. 环境准备
在开始之前，请确保您已具备以下环境：
- 一个运行中的 Symfony 5 项目。
- Windows 10 操作系统（本教程基于此环境）。
- PHP 和 Composer 已正确安装并配置。
2. Mercure Hub 的安装
Mercure Hub 是负责接收、存储和分发更新的核心服务。
- 下载 Mercure Hub： 访问 Mercure 的 GitHub 发布页面（例如：https://github.com/dunglas/mercure/releases），下载适用于您操作系统的最新版本。对于 Windows 10 ARM64 系统，您可能需要下载 mercure_0.13.0_Windows_arm64.zip 或其最新对应版本。
- 解压文件： 将下载的 zip 文件解压到您项目目录之外的一个独立文件夹中，例如 C:mercure-hub。解压后，您会得到 mercure.exe 和 Caddyfile.dev 等文件。
3. Symfony Mercure Bundle 的集成
在 Symfony 项目中，我们需要安装 Mercure Bundle 来方便地发布更新。
-
安装 Symfony Mercure Bundle：
在您的 Symfony 项目根目录中，打开终端并执行以下 Composer 命令：
composer require symfony/mercure
此命令会安装必要的依赖并自动配置 Bundle。
4. 环境变量配置
Mercure Bundle 需要通过环境变量来知道 Mercure Hub 的地址和用于签名的密钥。
-
编辑 .env 文件：
在您的 Symfony 项目根目录下的 .env 文件中，添加或修改以下 Mercure 相关的环境变量。请注意，MERCURE_URL 和 MERCURE_PUBLIC_URL 中的端口通常是 8000，这与 Mercure 默认的开发配置相符。
# 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!" ###< symfony/mercure-bundle ###
重要提示： MERCURE_JWT_SECRET 在生产环境中必须是一个强随机密钥，并且不能是默认的 !ChangeMe!。
5. 启动 Mercure 服务器
Mercure Hub 使用 Caddy 作为其 HTTP 服务器，它能够自动处理 TLS 证书。
-
启动 Mercure Hub： 打开 PowerShell 或命令提示符，导航到您解压 Mercure Hub 的目录（例如 C:mercure-hub）。然后执行以下命令来启动 Mercure 服务器：
$env:MERCURE_PUBLISHER_JWT_KEY='!ChangeMe!'; $env:MERCURE_SUBSCRIBER_JWT_KEY='!ChangeMe!'; .mercure.exe run -config Caddyfile.dev
命令解释：
- $env:MERCURE_PUBLISHER_JWT_KEY 和 $env:MERCURE_SUBSCRIBER_JWT_KEY：这是 Mercure Hub 自身用于验证发布者和订阅者 JWT 的密钥。在开发环境中，可以暂时使用 !ChangeMe!，但生产环境务必使用强密钥。
- .mercure.exe run -config Caddyfile.dev：运行 Mercure 可执行文件，并指定使用 Caddyfile.dev 配置文件。这个文件通常配置 Mercure 在 localhost:8000 上监听，并为 localhost 自动生成和信任 TLS 证书。
如果一切正常，您会看到类似以下的日志输出，表明 Caddy 服务器已成功启动并监听 HTTPS 端口：
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.111 INFO tls cleaning storage unit {"description": "FileStorage:C:\Users\toufi\AppData\Roaming\Caddy"} 2021/11/16 01:39:58.113 INFO tls finished cleaning storage units 2021/11/16 01:39:58.134 INFO pki.ca.local root certificate is already trusted by system {"path": "storage:pki/authorities/local/root.crt"} 2021/11/16 01:39:58.135 INFO http enabling automatic TLS certificate management {"domains": ["localhost"]} 2021/11/16 01:39:58.136 WARN tls stapling OCSP {"error": "no OCSP stapling for [localhost]: no OCSP server specified in certificate"} 2021/11/16 01:39:58.143 INFO autosaved config (load with --resume flag) {"file": "C:\Users\toufi\AppData\Roaming\Caddy\autosave.json"} 2021/11/16 01:39:58.143 INFO serving initial configuration这些日志表明 Mercure Hub 正在运行，并且 Caddy 已经为 localhost 启用了 HTTPS。
6. 验证 Mercure 服务器状态与故障排除
启动 Mercure Hub 后，您需要验证它是否可访问。
-
在浏览器中访问 Mercure 端点： 许多用户在尝试访问 Mercure 端点时可能会遇到“Not Found”错误，因为他们可能忘记指定端口。例如，直接访问 https://localhost/.well-known/mercure 可能会导致 Apache 或其他 Web 服务器响应，而不是 Mercure Hub。
正确的访问方式是包含端口号 8000：
https://localhost:8000/.well-known/mercure
当您在浏览器中访问 https://localhost:8000/.well-known/mercure 时，如果 Mercure Hub 运行正常，您应该会看到一个空白页面或一个简单的文本响应，表明连接成功，而不是“Not Found”错误。这是因为 Mercure Hub 的 Caddyfile.dev 配置使其在端口 8000 上监听请求，而不是默认的 HTTPS 端口 443。
总结与注意事项
- 端口一致性： 确保 .env 文件中的 MERCURE_URL 和 MERCURE_PUBLIC_URL 所指定的端口与您启动 Mercure Hub 时实际监听的端口（通常由 Caddyfile.dev 或自定义配置决定）保持一致。
- JWT 密钥安全： 在生产环境中，请务必使用强随机密钥替换所有的 !ChangeMe!，并妥善保管这些密钥。
- Caddyfile 配置： Caddyfile.dev 适用于开发环境，它会自动处理 localhost 的 TLS 证书。在生产环境中，您需要为 Mercure Hub 配置一个更健壮的 Caddyfile 或其他反向代理（如 Nginx, Apache），并正确配置 TLS 证书。
- 防火墙： 确保您的系统防火墙允许对 8000 端口的入站连接。
- 其他 Web 服务器冲突： 如果您在 8000 端口上运行了其他服务，可能会导致 Mercure Hub 无法启动。请检查并解决端口冲突。
通过遵循本教程的步骤，您应该能够成功地在 Symfony 5 项目中配置和运行 Mercure 服务，并开始构建您的实时应用程序。
