RabbitMQ: 快速開始

如何使用 Stackhero 連接 RabbitMQ

使用 Python 連接 RabbitMQ

以下將說明如何使用 Aio Pika 函式庫，讓您的 Python 應用程式連接到 RabbitMQ。在大多數情況下，您只需要提供 AMQPS URL，即可建立安全連線：

connection = await aio_pika.connect_robust(
  "amqps://admin:<PASSWORD>@<XXXXXX>.stackhero-network.com:<AMQP_PORT_TLS>",
)

以下是一個完整範例，展示如何建立與 RabbitMQ 的安全連線、建立 channel 並宣告一個基本佇列。這是驗證您的設定是否正確的好方法：

import asyncio
import logging
import aio_pika

async def main() -> None:
    # 若您想查看除錯日誌，可取消註解下一行
    # logging.basicConfig(level=logging.DEBUG)

    connection = await aio_pika.connect_robust(
        "amqps://admin:<PASSWORD>@<XXXXXX>.stackhero-network.com:<AMQP_PORT_TLS>"
    )

    async with connection:
        print("The connection worked!")
        channel = await connection.channel()
        await channel.set_qos(prefetch_count=10)
        queue = await channel.declare_queue("test_queue", auto_delete=True)

if __name__ == "__main__":
    asyncio.run(main())

處理 `unable to get local issuer certificate` 錯誤

如果您在 Python 連線時遇到如下錯誤：

aiormq.exceptions.AMQPConnectionError: [Errno 5] [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: unable to get local issuer certificate (_ssl.c:1006)

這通常表示您的系統缺少 Let's Encrypt 的 CA 憑證。請依照您的作業系統安裝常用的 CA 憑證套件來解決：

在 Ubuntu/Debian 上，請執行：
```
sudo apt install ca-certificates
```
在 Alpine Linux 上，請執行：
```
apk add ca-certificates
```

如果您無法使用上述指令，也可以手動安裝 CA 憑證：

從 https://letsencrypt.org/certs/isrgrootx1.pem 下載 Let's Encrypt CA 憑證。

然後在 Python 程式碼中指定 CA 憑證檔案來連接 RabbitMQ：

import ssl

ssl_context = ssl.create_default_context()
ssl_context.load_verify_locations(cafile='isrgrootx1.pem')

connection = await aio_pika.connect_robust(
  "amqps://admin:<PASSWORD>@<XXXXXX>.stackhero-network.com:<AMQP_PORT_TLS>",
  ssl_context=ssl_context
)

以下是一個完整範例，使用 Let's Encrypt CA 憑證進行安全連線：

import asyncio
import logging
import ssl
import aio_pika

async def main() -> None:
    # 若要啟用除錯日誌，可取消註解這一行
    # logging.basicConfig(level=logging.DEBUG)

    ssl_context = ssl.create_default_context()
    # 載入您剛下載的 Let's Encrypt CA 憑證
    # 例如：wget https://letsencrypt.org/certs/isrgrootx1.pem
    ssl_context.load_verify_locations(cafile='isrgrootx1.pem')

    connection = await aio_pika.connect_robust(
        "amqps://admin:<PASSWORD>@<XXXXXX>.stackhero-network.com:<AMQP_PORT_TLS>",
        ssl_context=ssl_context
    )

    async with connection:
        print("The connection worked!")
        channel = await connection.channel()
        await channel.set_qos(prefetch_count=10)
        queue = await channel.declare_queue("test_queue", auto_delete=True)

if __name__ == "__main__":
    asyncio.run(main())

使用 GoLang 連接 RabbitMQ

若您想從 Go 應用程式連接 RabbitMQ，官方的 Go RabbitMQ Client Library 提供了簡單的方式。以下是開始的步驟：

go mod init rabbitmq-example

接著，將 RabbitMQ 函式庫加入您的專案：

go get github.com/rabbitmq/amqp091-go

現在，建立一個名為 main.go 的檔案並加入以下程式碼：

package main

import (
  "fmt"
  amqp "github.com/rabbitmq/amqp091-go"
)

func main() {
  connection, err := amqp.Dial("amqps://<PASSWORD>@<XXXXXX>.stackhero-network.com:<AMQP_PORT_TLS>")
  if err != nil {
    panic(err)
  }
  defer connection.Close()

  fmt.Println("Successfully connected to RabbitMQ instance")
}

使用以下指令執行您的程式：

go run main.go

若連線成功，您會看到訊息 "Successfully connected to RabbitMQ instance"。這表示您已透過驗證與 TLS 加密安全連線。

如需更進階的範例，建議參考 RabbitMQ 官方 repository 的 Go 範例：https://github.com/rabbitmq/rabbitmq-tutorials/tree/main/go。

使用 PHP 連接 RabbitMQ

若您使用 PHP，可以透過 php-amqplib 函式庫連接 RabbitMQ。由於 Stackhero 採用 TLS 加密（SSL），建議使用 AMQPSSLConnection：

use PhpAmqpLib\Connection\AMQPSSLConnection;

$connection = new AMQPSSLConnection(
  '<XXXXXX>.stackhero-network.com',
  <AMQP_PORT_TLS>,
  'admin',
  '<PASSWORD>',
  '/',
  array()
);

/**
 * @param \PhpAmqpLib\Connection\AbstractConnection $connection
 */
function shutdown($connection)
{
  $connection->close();
}

register_shutdown_function('shutdown', $connection);

手動下載 CA 憑證

有時候，您的 TLS 連線可能需要憑證授權中心（CA）憑證。多數系統已內建，但如有需要，您也可以手動下載。操作方式如下：

從 https://letsencrypt.org/certs/isrgrootx1.pem 下載憑證並儲存於您的伺服器。
然後，於 PHP 連線時指定下載的憑證：

$sslOptions = array(
  'cafile' => realpath(__DIR__ . '/isrgrootx1.pem'),
);

$connection = new AMQPSSLConnection(
  '<XXXXXX>.stackhero-network.com',
  <AMQP_PORT_TLS>,
  'admin',
  '<PASSWORD>',
  '/',
  $sslOptions
);

使用 PHP/Symfony 連接 RabbitMQ

若您使用 Symfony，可透過設定 MESSENGER_TRANSPORT_DSN 環境變數，將 RabbitMQ 作為訊息代理。只需更新您的 .env 檔案：

MESSENGER_TRANSPORT_DSN=amqps://<USER>:<PASSWORD>@<HOST>:<PORT>/%2f/messages?cacert=%2Fetc%2Fssl%2Fcerts%2Fca-certificates.crt

請將 <USER>、<PASSWORD>、<HOST> 及 <PORT> 替換為您自己的 RabbitMQ 資訊。

接著，請確認您的 config/packages/messenger.yaml 檔案有使用 MESSENGER_TRANSPORT_DSN 變數。內容應如下：

framework:
    messenger:
        transports:
            async: '%env(MESSENGER_TRANSPORT_DSN)%'

使用 Spring Boot 連接 RabbitMQ

對於 Spring Boot 應用程式，您可以透過更新 application properties，設定與 Stackhero RabbitMQ 的安全連線：

spring.rabbitmq.host=<XXXXXX>.stackhero-network.com
spring.rabbitmq.port=<AMQP_PORT_TLS>
spring.rabbitmq.username=admin
spring.rabbitmq.password=<PASSWORD>
spring.rabbitmq.ssl.enabled=true
spring.rabbitmq.ssl.algorithm=TLSv1.2

使用 .NET 與 MassTransit 連接 RabbitMQ

若您使用 .NET 與 MassTransit，以下為設定專案以 TLS 加密安全連接 Stackhero RabbitMQ 的方式：

using MassTransit;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
using System;

public class Program
{
  public static void Main(string[] args)
  {
    var host = Host.CreateDefaultBuilder(args)
      .ConfigureServices((context, services) =>
      {
        services.AddMassTransit(x =>
        {
          x.UsingRabbitMq((context, cfg) =>
          {
            cfg.Host(new Uri("amqps://admin:<PASSWORD>@<XXXXXX>.stackhero-network.com:<AMQP_PORT_TLS>"), h =>
            {
              h.UseSsl(s =>
              {
                s.Protocol = System.Security.Authentication.SslProtocols.Tls12;
              });
            });
          });
        });

        services.AddMassTransitHostedService(true);
      })
      .Build();

    host.Run();
  }
}

使用 Elixir 處理 `CLIENT ALERT: Fatal - Handshake Failure` 錯誤

若您從 Elixir 連線時看到如下錯誤訊息：

CLIENT ALERT: Fatal - Handshake Failure

這通常是 AMQP 函式庫對 TLS 1.3 支援的 bug。建議的解決方式是強制使用 TLS 1.2，於開啟連線時加入以下選項：

AMQP.Connection.open("amqps://admin:<PASSWORD>@<XXXXXX>.stackhero-network.com:<AMQP_PORT_TLS>", :undefined, ssl_options: [ versions: [ :"tlsv1.2" ] ])

使用 Node.js 處理 `Error: Socket closed abruptly during opening handshake` 錯誤

若您在 Node.js 使用時遇到 Error: Socket closed abruptly during opening handshake，很可能是因為您使用的 amqplib 函式庫版本低於 0.10.7，且 RabbitMQ 版本為 4.1.0 或以上。這與 RabbitMQ 4.1.0 引入的 frame_max 設定有關。

請將您的 amqplib 函式庫升級至 0.10.7 或更新版本，即可解決此問題。