文章目录
- 一、关于 Svix
- Client Library Overview
- 与 Svix 托管服务的区别
- 二、运行服务器
- 1、部署
- 1.1 Docker
- 1) 使用 Docker Compose
- 2) 独立容器
- 1.2 预编译的二进制文件
- 1.3 从源代码构建
- 2、运行时依赖项
- 3、Redis/Valkey 注意事项
- 持久性
- Eviction 政策
- 4、服务器配置
- 4.1 配置文件
- 4.2 环境（变量或`.env`）
- 4.3 OpenTelemetry
- 4.4 连接池大小
- 4.5 SSRF 攻击和内部 IP 地址
- 4.6 Webhook 签名方案（对称与非对称）
- 5、验证
- 使用不同的签名算法
- 6、操作（传入）webhook
- 7、非对称签名
- 配置按键
- 签名方案
- 8、关闭服务器
一、关于 Svix
- github : https://github.com/svix/svix-webhooks/
- 官网：https://svix.com/
- 文档 : https://docs.svix.com/
- API : https://api.svix.com
- 社区 Slack : https://svix.com/slack | 论坛：https://github.com/svix/svix-webhooks/discussions
Svix 让开发人员可以轻松发送 webhook。开发人员只需进行一次 API 调用，Svix 便会负责交付能力、重试、安全性等。有关更多信息，请参阅Svix 主页。
要及时了解新功能和改进，请务必关注 repo : https://github.com/svix/svix-webhooks/
Client Library Overview
| ⚡️ Feature Breakdown ⚡️ | ||||
|---|---|---|---|---|
| Language | Officially Supported | API Support | Webhook Verification | Other Notes |
| Go | ✅ | ✅ | ✅ | |
| Python | ✅ | ✅ | ✅ | |
| Typescript/Javascript | ✅ | ✅ | ✅ | |
| Java | ✅ | ✅ | ✅ | Async support planned. (If you use kotlin, checkout our kotlin library for coroutine support.) |
| Kotlin | ✅ | ✅ | ✅ | |
| Ruby | ✅ | ✅ | ✅ | |
| C# (dotnet) | ✅ | ✅ | ✅ | |
| Rust | ✅ | ✅ | ✅ | |
| PHP | ✅ | 🔜 | ✅ |
与 Svix 托管服务的区别
我们开源 Svix 调度程序的主要目标之一是易于使用。然而，由于我们的规模和所需的基础设施，托管的 Svix 服务相当复杂。这种复杂性对绝大多数人来说没有用处，会使这个项目更难使用，限制也更多。这就是为什么在发布之前调整了此代码，并且托管调度程序支持的一些功能、优化和行为尚未在此存储库中提供。话虽如此，除了一些已知的不兼容性之外，内部 Svix 测试套件已通过。这意味着它们已经基本兼容，我们正在努力使它们达到完全功能对等。
二、运行服务器
有多种方法可以启动 Svix 服务器。Docker 可能是最常见的方法，但你可以选择最适合你的方法。
Svix 服务器是用 Rust 🦀 编写的，这意味着您可以将其编译为各种目标的静态库。有关更多信息，请参阅下面的从源代码构建部分。
有关可用设置的更多信息，请参阅下面的服务器配置部分。
1、部署
1.1 Docker
您可以使用Docker Hub中的官方 Svix Docker 镜像：https://hub.docker.com/r/svix/svix-server
您也可以使用 latest 标签，或者使用 the versioned tags 之一。
您可以使用 docker compose 示例docker-compose.yml文件（最简单）、docker swarm（高级），或者独立运行容器。
1) 使用 Docker Compose
这个替代方案是最简单的，因为它也将启动和redis配置postgresql。
假设您已经安装了 Docker Compose v2。
cd server
docker compose up
2) 独立容器
运行独立容器稍微高级一些，因为它需要您设置一些环境变量并让它们指向您的redis和postgres实例。
您可以使用标志将各个环境变量传递给 docker -e，或者只需创建一个文件（如development.env） 并像以下示例一样使用 --env-file 标志：
docker run \--name svix-server \-p 8071:8071 \--env-file development.env \svix/svix-server
1.2 预编译的二进制文件
已发布版本的预编译二进制文件可在发布部分中找到。
https://github.com/svix/svix-webhooks/releases
1.3 从源代码构建
Svix 服务器用 Rust 🦀 编写，需要 Rust 构建环境。
如果您已经有一个，那么您只需要运行cargo build，否则，请参阅Svix 服务器 README以获取有关从源代码构建服务器的更多信息。
2、运行时依赖项
服务器需要以下运行时依赖项才能正常工作：
- PostgreSQL 服务器 - 用于存储事件。
- 可选的 Redis 服务器 6.2.0 版本 或更高 - 用于任务队列和缓存。
3、Redis/Valkey 注意事项
持久性
请注意，建议在 Redis 中启用持久性，以便在 Redis 服务器重启和升级后保留任务。
Eviction 政策
请确保您的 Redis 实例配置为 不逐出 未明确设置 expire 策略的密钥。这意味着maxmemory-policy应设置为noeviction或任何可用volatile-策略。有关更多信息，请参阅 Redis/Valkey 文档。
4、服务器配置
有三种配置方式svix-server：环境变量，.env文件和配置文件。
4.1 配置文件
您可以将一个名为的文件config.toml放在当前工作目录中，svix-server它会自动选择该文件。您可以查看示例文件以获取更多信息和受支持设置的完整列表：config.toml。
以下是最重要的配置的简单示例：
# The JWT secret for authentication - should be secret and securely generated
jwt_secret = "8KjzRXrKkd9YFcNyqLSIY8JwiaCeRc6WK4UkMnSW"# The DSN for the database. Only postgres is currently supported.
db_dsn = "postgresql://postgres:postgres@pgbouncer/postgres"# The DSN for redis (can be left empty if not using redis)
redis_dsn = "redis://redis:6379"# What kind of message queue to use.
queue_type = "redis"
4.2 环境（变量或.env）
或者，您可以svix-server通过为每个支持的设置设置等效的环境变量来进行配置。环境变量可以直接传递，也可以通过在文件中设置它们来传递.env。
环境变量的名称 name 与配置名称相同，但都是大写，并以 为前缀SVIX_。
例如，如果在环境中传递上述示例配置，它将如下所示：
# The JWT secret for authentication - should be secret and securely generated
SVIX_JWT_SECRET = "8KjzRXrKkd9YFcNyqLSIY8JwiaCeRc6WK4UkMnSW"# The DSN for the database. Only postgres is currently supported.
SVIX_DB_DSN = "postgresql://postgres:postgres@pgbouncer/postgres"# The DSN for redis (can be left empty if not using redis)
SVIX_REDIS_DSN = "redis://redis:6379"# What kind of message queue to use.
SVIX_QUEUE_TYPE = "redis"
4.3 OpenTelemetry
您可以将跟踪信息发送到 OpenTelemetry Collector，它允许将跟踪事件转发到许多外部应用程序/服务，例如 DataDog、Jaeger、NewRelic、Prometheus、Sentry、Signoz 和 Zipkin。
您可以在这些说明中看到更多内容。
4.4 连接池大小
有两个配置变量db_pool_max_size和redis_pool_max_size分别控制 PostgreSQL 和 Redis 的连接池允许的最大大小。
它们默认的最大大小为 20，但如果您的数据库可以处理，则更高的值可以显著提高性能。
4.5 SSRF 攻击和内部 IP 地址
为了防止 SSRF 攻击，默认情况下会阻止向内部 IP 地址发送消息。
但是，我们知道这不能满足每个用户的需求，例如，服务只能在内部访问。要绕过这些限制，请参阅配置选项whitelist_subnets，它接受 CIDR 符号子网数组以允许向其发送消息。
4.6 Webhook 签名方案（对称与非对称）
为了确保消息的安全性和完整性，Svix 在发送之前会对所有 webhook 消息进行签名。Svix 支持两种类型的签名方案：对称（预共享密钥）和非对称（公钥）。
对称签名的速度明显更快（签名速度快约 50 倍，验证速度快约 160 倍），而且更简单（这让您的客户更容易验证），但它们需要每个端点使用预共享密钥（端点机密）才能工作。另一方面，非对称签名只需要与您的客户共享公钥（不是机密）。
鉴于上述情况，建议使用对称密钥，这也是 Svix 的默认设置。它们的使用已记录在文档的验证签名部分中。
但是，在某些情况下，使用非对称签名可能会有所帮助，这就是为什么它们也受到支持的原因。有关更多信息，请参阅下面的非对称签名部分。
5、验证
使用正确的机密生成的有效 JWT 作为Bearer。
例如：
Authorization: Bearer <JWT_TOKEN_HERE>
使用以下方式生成一个
svix-server jwt generate
或者如果您正在生成自己的，请确保用作org_23rb8YdGqMT0qIzpgGwdXfHirMu字段sub并H256用作算法。
机密的有效 JWT 示例x（以便您可以看到结构）：
// JWT: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE2NTUxNDA2MzksImV4cCI6MTk3MDUwMDYzOSwibmJmIjoxNjU1MTQwNjM5LCJpc3MiOiJzdml4LXNlcnZlciIsInN1YiI6Im9yZ18yM3JiOFlkR3FNVDBxSXpwZ0d3ZFhmSGlyTXUifQ.USMuIPrqsZTSj3kyWupCzJO9eyQioBzh5alGlvRbrbA
// Structure (when decoded):
{"iat": 1655140639,"exp": 1970500639,"nbf": 1655140639,"iss": "svix-server","sub": "org_23rb8YdGqMT0qIzpgGwdXfHirMu"
}
使用不同的签名算法
如上所述，签署 JWT 的默认算法是。您可以通过将配置设置为以下支持的值之一来HS256选择其他算法： 、、、、或。jwt_algorithm``HS384``HS512``RS256``RS384``RS512``EdDSA
6、操作（传入）webhook
操作性 webhook 是您可以订阅的 webhook，以便收到 svix-server 上发生的重要事件的通知。支持的事件列表可在API 参考的 webhook 部分中找到。
操作 webhook 使用 Svix，并由具有以下 ID 的特殊帐户服务帐户控制：org_00000000000SvixManagement00。
第一步是通过设置配置operational_webhook_address以指向您的 Svix 服务器来启用它。此设置的最常见值是http://127.0.0.1:8071，但根据您的具体设置，它可能有所不同。
上述步骤在此实例上启用了操作 webhook，下一步是为您的特定组织启用它。如上所述，操作 webhook 在后台使用普通的 Svix 帐户，因此我们首先需要获取此帐户的身份验证令牌。为此，您应该运行：
svix-server jwt generate org_00000000000SvixManagement00
这将为您提供一个特殊的 JWT 来访问操作 webhook 帐户，这与您与 Svix 交互时使用的普通 JWT 不同。例如，我们假设它返回的 JWT 是op_webhook_token_123。
要为特定帐户启用操作 webhook，我们需要首先在服务帐户中为其创建一个应用程序（请记住：操作 webhook 只是在后台使用 Svix）。我们将使用默认的 Svix 帐户作为示例：org_23rb8YdGqMT0qIzpgGwdXfHirMu。
curl -X 'POST' \'http://localhost:8071/api/v1/app/' \-H 'Authorization: Bearer op_webhook_token_123' \-H 'Accept: application/json' \-H 'Content-Type: application/json' \-d '{"name": "Operational webhook for default org","uid": "org_23rb8YdGqMT0qIzpgGwdXfHirMu"}'
就是这样，我们现在已为默认帐户启用了操作 webhook。剩下唯一要做的就是添加将操作 webhook 发送到的端点。例如：
curl -X 'POST' \'https://api.eu.svix.com/api/v1/app/org_23rb8YdGqMT0qIzpgGwdXfHirMu/endpoint/' \-H 'Authorization: Bearer AUTH_TOKEN' \-H 'Accept: application/json' \-H 'Content-Type: application/json' \-d '{"url": "https://operational-webhook-destination.com/webhook/","filterTypes": [“endpoint.updated”,“endpoint.deleted”],}'
请注意，在创建端点时，我们如何使用默认帐户的组织 ID 作为app_id（或者更确切地说，在这种情况下）。uid
就是这样。您现在应该有可用的操作 webhook。如果您想创建新端点或修改现有端点，只需为服务帐户生成 JWT，然后像使用任何其他 Svix 帐户一样使用该 JWT。
7、非对称签名
如上所述，建议使用对称签名。但是，如果您确定需要非对称签名，请阅读以下有关设置非对称签名的说明。
配置按键
默认情况下，Svix 服务器会为端点生成对称密钥，这意味着消息将使用对称密钥进行签名。要更改此默认设置，请将配置设置default_signature_type为ed25519如下：
default_signature_type = "ed25519"
此外，无论默认值设置为多少，您仍然可以通过在端点上明确设置密钥来覆盖它。
要设置对称密钥，请将端点密钥设置为以 为前缀的密钥whsec_，例如whsec_51TKyHBy5KFY1Ab98GQ8V60BkWnejkWy。
要设置非对称密钥，请将端点密钥设置为以 为前缀的有效ed25519 base64 编码私钥，whsk_例如 ： whsk_6Xb/dCcHpPea21PS1N9VY/NZW723CEc77N4rJCubMbfVKIDij2HKpMKkioLlX0dRqSKJp4AJ6p9lMicMFs6Kvg==。
请注意，预期的私钥结构是：whsk_${base64(private_key + public_key)}。
为了测试目的，可以使用以下命令生成新的非对称密钥对：
$ svix-server asymmetric-key generateSecret key: whsk_6Xb/dCcHpPea21PS1N9VY/NZW723CEc77N4rJCubMbfVKIDij2HKpMKkioLlX0dRqSKJp4AJ6p9lMicMFs6Kvg==
Public key: whpk_1SiA4o9hyqTCpIqC5V9HUakiiaeACeqfZTInDBbOir4=
签名方案
Svix 用于ed25519(m)签署 webhook 消息，其构造m方式与对称签名相同。
当验证消息时，您还应确保时间戳足够新，以限制重放攻击的可能性，如对称验证文档中所述。
8、关闭服务器
为了支持服务器的正常关机，所有正在运行的任务都会在 SIGINT/SIGTERM 信号关闭之前完成。这通常需要不到十秒钟的时间。
2024-05-24（五）
