Vector 中 NATS 集成测试凭据生成指南NKey、TLS 与 JWT 配置实战【免费下载链接】vectorA high-performance observability data pipeline.项目地址: https://gitcode.com/GitHub_Trending/vect/vector本指南以 Vector 仓库的 NATS 集成测试数据说明文档 为骨架完整讲解如何为 Vector 的 NATS source/sink 集成测试生成三类安全凭据——基于 NKey 的认证配置、基于 TLS 的证书与密钥以及基于 JWT 的 credentials 文件。读完本文你将掌握mkcert签发服务器/客户端证书的完整命令序列、NKey 与 JWT 凭据的生成与归档流程并能对照仓库中的集成测试配置compose、test.yaml 与各类.conf文件理解这些凭据在真实 CI 环境中如何被消费。背景这些凭据服务于哪套测试Vector 仓库中的 NATS 集成测试由 tests/integration/nats/config/test.yaml 驱动它声明了 feature 标志nats-integration-tests、测试过滤器::nats::并注入了多达 8 个 NATS 服务地址环境变量env: NATS_ADDRESS: nats://nats:4222 NATS_JWT_ADDRESS: nats://nats-jwt:4222 NATS_NKEY_ADDRESS: nats://nats-nkey:4222 NATS_TLS_ADDRESS: nats://nats-tls:4222 NATS_TLS_CLIENT_CERT_ADDRESS: nats://nats-tls-client-cert:4222 NATS_TOKEN_ADDRESS: nats://nats-token:4222 NATS_USERPASS_ADDRESS: nats://nats-userpass:4222 NATS_JETSTREAM_ADDRESS: nats://nats-jetstream-test:4222对应的服务编排定义在 tests/integration/nats/config/compose.yaml 中无认证的nats、用户名/密码的nats-userpass--user natsuser --pass natspass、token 的nats-token--auth secret以及通过挂载../data目录读取配置的nats-nkey、nats-tls、nats-tls-client-cert、nats-jwt、nats-jetstream-test五个服务。其中后四个基于配置的服务其配置文件与凭据文件全部存放在 tests/integration/nats/data 目录下——这正是本文要生成的nats-server.pem、nats-server.key、rootCA.pem、nats-client.pem、nats-client.key、nats.creds、nats-bad.creds等文件的归宿。这些凭据被哪些测试使用凭据的消费方是 src/sinks/nats/integration_tests.rs 与 src/sources/nats/integration_tests.rs。它们通过NATS_ADDRESS、NATS_TLS_ADDRESS、NATS_TLS_CLIENT_CERT_ADDRESS、NATS_NKEY_ADDRESS、NATS_JWT_ADDRESS等环境变量读取地址配合authuser_password、token、credentials_file、nkey四种策略与tls配置段完成连接认证。共享的认证配置解析逻辑位于 src/nats.rs其中NatsAuthConfig枚举清晰列出了 Vector 支持的四种 NATS 认证策略UserPassword用户名/密码TokentokenCredentialsFile基于 JWT 的 credentials 文件NkeyNKey 用户认证nkey seed。无论 source 还是 sink最终都通过from_tls_auth_configsrc/nats.rs把auth与tls配置统一转换成async_nats::ConnectOptions。生成前的准备工作安装 mkcert文档明确指出根 CA、客户端与服务器证书/密钥均使用mkcert工具生成。mkcert 的作用是自动生成本地信任的根 CA并用它快速签发任意主机名的证书特别适合本地开发与集成测试场景。# macOS (Homebrew) $ brew install mkcert # 或使用任意平台对应的包管理器安装安装后首次使用前通常需要初始化本地 CA$ mkcert -installmkcert -CAROOT命令会输出本地根 CA 所在目录后续复制rootCA.pem时会用到。切换到正确的输出目录文档特别强调所有生成输出文件的命令如 TLS 与 JWT 两节都必须在正确的测试数据目录tests/data/nats下执行或者将生成的文件移动到该目录。注意这里的tests/data/nats是文档写作时使用的旧路径在当前仓库中对应的实际位置是 tests/integration/nats/data。因此执行前先$ cd tests/integration/nats/data生成基于 NKey 的配置与凭据NKey 是 NATS 的 Ed25519 密钥体系用于在无中心化证书机构的情况下验证用户身份。文档明确建议以 NATS 官方 NKey 认证指南 为最佳参考该指南包含配置所需的全部命令与配置片段。NKey 认证的核心步骤是使用nsc工具NATS 的凭据管理 CLI创建 operator、account、user导出用户的 NKey 公钥用户标识与 seed私钥种子需妥善保管在 NATS 服务端配置中将该公钥注册为受信任用户。仓库中已生成的 NKey 服务端配置 tests/integration/nats/data/nats-nkey.conf 展示了最终形态authorization: { users: [ { nkey: UD345ZYSUJQD7PNCTWQPINYSO3VH4JBSADBSYUZOBT666DRASFRAWAWT } ] }而在 Vector 侧NKey 认证通过auth配置段声明nkey字段对应公钥、seed字段对应私钥种子auth: strategy: nkey nkey: nkey: UC435ZYS52HF72E2VMQF4GO6CUJOCHDUUPEBU7XDXW5AQLIC6JZ46PO5 seed: SUAAEZYNLTEA2MDTG7L5X7QODZXYHPOI2LT2KH5I4GD6YVP24SE766EGPA该格式在 src/nats.rs 中被定义为NatsAuthNKey结构体其注释将nkey明确定义为概念上等价于公钥、seed为概念上等价于私钥。解析时若二者缺一配置校验都会失败见 src/nats.rs 中的auth_nkey_missing_nkey、auth_nkey_missing_seed等测试用例。生成基于 TLS 的配置与凭据TLS 凭据是整篇文章的核心也是 JWT 一节的前提JWT 服务同样需要 TLS 传输加密。文档给出的命令设计得很巧妙证书同时覆盖localhost/::1与集成测试使用的主机名保证同一套证书在本地与 CI 容器两种场景下都能使用。第一步生成服务器证书与密钥# 先生成服务器证书/密钥同时会生成一个根 CA稍后需要一并复制 $ mkcert -cert-file nats-server.pem -key-file nats-server.key localhost ::1 nats-tls nats-tls-client-cert nats-jwt这条命令一次性为 5 个主机名签发证书localhost、::1IPv6 回环、nats-tls、nats-tls-client-cert、nats-jwt。对照 tests/integration/nats/config/compose.yaml 可以看到后三个主机名正是nats-tls、nats-tls-client-cert、nats-jwt三个 Docker 服务的名称——容器间通过 Docker 网络以服务名互相访问因此证书必须包含这些服务名否则 TLS 握手会因主机名不匹配而失败。第二步移动根 CA# 将 mkcert 根 CA 移动到正确位置 $ mv $(mkcert -CAROOT)/rootCA.pem tests/data/nats/rootCA.pem$(mkcert -CAROOT)会展开为 mkcert 根 CA 所在目录例如 macOS 上的~/Library/Application Support/mkcert。生成的根 CA 被用于TLS 配置中让客户端信任服务端证书ca_file双向 TLSmTLS配置中让服务端验证客户端证书verify_and_map。第三步生成客户端证书与密钥# 生成客户端证书/密钥最后一个参数是客户端证书的用户标识 $ mkcert -client -cert-file nats-client.pem -key-file nats-client.key localhost ::1 nats-tls nats-tls-client-cert nats-jwt emaillocalhost与服务器证书命令的差异在于-client标志签发 EKU 为 clientAuth 的客户端证书以及末尾的emaillocalhost——这是客户端证书的身份标识SAN/主体用于服务端的verify_and_map映射。这些凭据如何被消费服务器证书的消费方式见 tests/integration/nats/data/nats-tls.conftls: { cert_file: /usr/share/nats/config/nats-server.pem key_file: /usr/share/nats/config/nats-server.key }该配置文件被挂载到nats-tls服务容器内的/usr/share/nats/config路径对应 compose.yaml 中的volumes: - ../data:/usr/share/nats/configNATS 服务启动时即启用 TLS。注意这套纯服务端 TLS 场景不验证客户端证书客户端只需信任根 CA 即可。而客户端证书 根 CA 组合使用在双向 TLS 场景见 tests/integration/nats/data/nats-tls-client-cert.conftls: { cert_file: /usr/share/nats/config/nats-server.pem key_file: /usr/share/nats/config/nats-server.key ca_file: /usr/share/nats/config/rootCA.pem verify_and_map: true } authorization { users [ {user: emaillocalhost} ] }关键点在于verify_and_map: true——它要求客户端必须出示由受信任 CA 签发的客户端证书并将证书中的用户标识此处为emaillocalhost映射为 NATS 用户与authorization中声明的用户比对。这解释了为什么客户端证书生成命令要额外携带emaillocalhost参数。在 Vector 侧客户端如何配置这些凭据由 src/nats.rs 中的from_tls_auth_config决定tls.enabled为true时调用require_tls(true)强制加密连接配置了ca_file时调用add_root_certificates用于验证服务端证书同时配置了crt_file与key_file时调用add_client_certificate用于 mTLS 客户端身份认证若只配置了crt_file或key_file二者其一校验函数validate_tls_cert_key_pairsrc/nats.rs会直接拒绝配置。相应的 Vector 配置示例tls: enabled: true ca_file: /path/to/rootCA.pem crt_file: /path/to/nats-client.pem key_file: /path/to/nats-client.keyTLS 配置校验的行为在 src/sinks/nats/config.rs 中有专门的单元测试覆盖证书无密钥、密钥无证书均校验失败而完整的证书/密钥对通过校验tls.enabled: false时即便只配置了孤立的证书也不会报错。生成基于 JWT 的配置与凭据JWTJSON Web Token认证是 NATS 最完整的身份管理方案由 operator → account → user 三级体系构成。文档强调必须先完成上面的 TLS 一节因为 JWT 认证的 NATS 服务nats-jwt同样依赖 TLS 加密传输其配置 tests/integration/nats/data/nats-jwt.conf 中同时包含tls段和 JWT 解析器段// Operator memory operator: eyJ0eXAiOiJKV1QiLCJhbGciOiJlZDI1NTE5LW5rZXkifQ.eyJqdGkiOiI1RFVZWUUzVFlQQU1WVU9MRU9TSUJCRVlKQzdDNDRJT1EzQ0Y3NzZNTkNVTU9BVENCV0pRIiwiaWF0IjoxNjQxMjYxMDYxLCJpc3MiOiJPQlpZWVBDU04yVUw3R01MRU9GWFVLU1JQRjc0SlNKSzJOUUVJRkpIR1BNQVo0T1BQMzZXWlVZNiIsIm5hbWUiOiJtZW1vcnkiLCJzdWIiOiJPQlpZWVBDU04yVUw3R01MRU9GWFVLU1JQRjc0SlNKSzJOUUVJRkpIR1BNQVo0T1BQMzZXWlVZNiIsIm5hdHMiOnsidHlwZSI6Im9wZXJhdG9yIiwidmVyc2lvbiI6Mn19.Su5lbisERxV0Wth8tAn57Nqr20gaATqRemo-9_gufGbuPG4QG9sLX60xTwOqDAayZWMuMDcXgJMzDxovrFciCQ resolver: MEMORY resolver_preload: { // Account A ADU2HWIBX4HJ3WFAIQFCH5AI3KW7N55TBRLOENM2SDVPVBELC3XNSH4R: eyJ0eXAiOiJKV1QiLCJhbGciOiJlZDI1NTE5LW5rZXkifQ.eyJqdGkiOiJFR0lSUU9YS0lSVDRLRkdMSVNPWUxRR0tONkdPT0FUN0ZTVUdVQUM0VTNNN1VEUVdSNktBIiwiaWF0IjoxNjQxMjYxMTAwLCJpc3MiOiJPQlpZWVBDU04yVUw3R01MRU9GWFVLU1JQRjc0SlNKSzJOUUVJRkpIR1BNQVo0T1BQMzZXWlVZNiIsIm5hbWUiOiJBIiwic3ViIjoiQURVMkhXSUJYNEhKM1dGQUlRRkNINUFJM0tXN041NVRCUkxPRU5NMlNEVlBWQkVMQzNYTlNINFIiLCJuYXRzIjp7ImxpbWl0cyI6eyJzdWJzIjotMSwiZGF0YSI6LTEsInBheWxvYWQiOi0xLCJpbXBvcnRzIjotMSwiZXhwb3J0cyI6LTEsIndpbGRjYXJkcyI6dHJ1ZSwiY29ubiI6LTEsImxlYWYiOi0xfSwiZGVmYXVsdF9wZXJtaXNzaW9ucyI6eyJwdWIiOnt9LCJzdWIiOnt9fSwidHlwZSI6ImFjY291bnQiLCJ2ZXJzaW9uIjoyfX0.PrX_C9-Txq3N8Ea23fLjocK0V_WTac1BTIF58-qNl98YK9Ga36ussyeT7dljC1zUHI-mSEcIVoWgCTDlT-vAAg } tls: { cert_file: /usr/share/nats/config/nats-server.pem key_file: /usr/share/nats/config/nats-server.key }该配置使用内存解析器resolver: MEMORY通过resolver_preload将 operator 与 account 的 JWT 直接内嵌在配置文件中。官方指南与凭据归档文档要求先完整执行 NATS JWT 内存解析器认证指南 中的步骤nsc工具创建 operator/account/user、生成用户 credentials然后把生成的凭据移动到正确位置# 将这些凭据移动到正确位置因为它们不会直接生成在当前目录 $ mv ~/.nkeys/creds/memory/A/TA.creds tests/data/nats/nats.credsnsc生成的用户 credentials 文件默认存放在~/.nkeys/creds/下路径结构为operator/account/user.creds。此处的memory对应 operator 名A对应 account 名TA对应 user 名与nats-jwt.conf中 operator memory、Account A 的注释完全对应。文件内容为 base64 编码的 JWT 与 NKey seed 的组合。制造坏凭据nats-bad.creds# 之后复制一份作为坏凭据。 # # 你需要打开这份坏版本修改 seed 值中的某个字符才能真正让它们失效。 $ cp tests/data/nats/nats.creds tests/data/nats/nats-bad.credsnats-bad.creds用于测试认证失败路径集成测试会验证使用被篡改凭据时Vector 的 NATS sink/source 能否正确报错而非静默成功。因此复制后必须手动修改其中 seedNKey 私钥种子的任意一个字符使其与 JWT 中签名的密钥不再匹配。从 src/nats.rs 的CredentialsFile实现可以看到Vector 通过with_credentials读取该文件内容进行认证一旦 seed 被篡改NATS 服务端校验签名必然失败。Vector 侧对应的 credentials 文件认证配置如下auth: strategy: credentials_file credentials_file: path: /path/to/nats.creds四种认证策略在 Vector 配置中的完整对照综合 src/nats.rs 的枚举定义与 src/nats.rs 的to_nats_options实现将本文涉及的认证方式汇总为如下对照表策略Vectorauth配置结构对应 NATS 服务端配置底层async_nats选项用户名/密码strategy: user_passworduser/password--user/--pass或authorization.userswith_user_and_passwordTokenstrategy: tokenvalue--authwith_tokenCredentials 文件JWTstrategy: credentials_filepathoperator/resolver/resolver_preloadwith_credentialsNKeystrategy: nkeynkey/seedauthorization.users[].nkeywith_nkey其中 JWT 与 NKey 都基于 NATS 的 Ed25519 NKey 体系区别在于NKey 只是公钥/私钥对由服务端静态配置公钥而 JWT 将用户身份与权限封装进经签名的 token由 operator/account 逐级授权支持更细粒度的权限控制与动态撤销。这些解析行为均有 src/nats.rs 中的单元测试逐一验证如auth_user_password_ok、auth_token_missing、auth_nkey_missing_seed等。证书过期后如何重新生成文档指出如果只是证书过期等原因需要重新生成可以跳过阅读链接直接按上述命令执行——上面的命令序列就是为仓库现有测试配置量身定制的。完整的重新生成流程为# 1. 进入测试数据目录当前仓库为 tests/integration/nats/data $ cd tests/integration/nats/data # 2. 重新生成服务器证书/密钥覆盖 localhost、::1 与三个服务主机名 $ mkcert -cert-file nats-server.pem -key-file nats-server.key localhost ::1 nats-tls nats-tls-client-cert nats-jwt # 3. 重新复制根 CA $ mv $(mkcert -CAROOT)/rootCA.pem rootCA.pem # 4. 重新生成客户端证书/密钥 $ mkcert -client -cert-file nats-client.pem -key-file nats-client.key localhost ::1 nats-tls nats-tls-client-cert nats-jwt emaillocalhost执行后请核对 tests/integration/nats/data 目录中的全部凭据文件是否就位。若同时需要更新 JWT 凭据还需参照上文用nsc重新生成nats.creds并同步刷新nats-bad.creds。重新生成过程中如遇到服务名或端口变化记得同步更新 tests/integration/nats/config/compose.yaml 与 tests/integration/nats/config/test.yaml因为 test.yaml 中明确声明了触发 CI 集成测试的路径变更范围tests/integration/nats/**等。小结Vector 的 NATS 集成测试覆盖了 NATS 几乎全部的主流安全机制无认证、用户名/密码、token、NKey、服务端 TLS、双向 TLS客户端证书与 JWT credentials。本文从 tests/integration/nats/data/README.md 出发给出了这三类凭据从生成、归档到被 compose.yaml 与 test.yaml 消费的完整链路并结合 src/nats.rs 中的NatsAuthConfig与from_tls_auth_config实现、src/sinks/nats/config.rs 与 src/sources/nats/config.rs 中的配置校验逻辑说明了 Vector 侧各凭据字段的语义与校验规则。当你需要为 NATS 场景重新签发证书或新增认证方式时直接复用上文命令即可同时建议将 Vector 侧auth/tls配置与 src/nats.rs 的实现对照阅读以准确理解每一项配置对连接建立过程的实际影响。【免费下载链接】vectorA high-performance observability data pipeline.项目地址: https://gitcode.com/GitHub_Trending/vect/vector创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考