openziti/ziti-sdk-csharp

 # OpenZiti.NET SDK OpenZiti.NET SDK 是一个使开发者能够利用 OpenZiti overlay 网络创建客户端和应用程序的项目。OpenZiti 是一个现代的、可编程的 overlay 网络及其关联的 edge 组件，用于应用内嵌的零信任网络连接，由开发者为开发者编写。该 SDK 通过 API 利用这种能力，允许开发者想象并开发超越 OpenZiti 默认处理范围的解决方案。 在应用程序的通信需求中使用 OpenZiti SDK，可以通过将零信任原则**直接纳入**应用程序本身，使您的应用程序默认安全。在 OpenZiti overlay 网络上的所有通信都是通过 [双向 TLS (mtls)](https://en.wikipedia.org/wiki/Mutual_authentication) 安全连接执行的。默认情况下，OpenZiti 还实现了真正的 [端到端加密](https://openziti.io/docs/learn/introduction/features/#e2e-encryption)（通过 [libsodium](https://libsodium.gitbook.io/)）。开发者只需将 OpenZiti SDK 纳入应用程序即可获得这些直接的好处。OpenZiti overlay 网络提供了许多其他安全特性，这些特性结合在一起，为任何应用程序提供了一个引人注目的安全解决方案。 如果您是 OpenZiti 或 overlay 网络的新手，查看 [官方文档](https://openziti.io) 或浏览 [https://github.com/openziti/ziti](the main repo) 并全面了解 OpenZiti 和零信任可能会很有帮助。 ## 入门指南 要开始使用，您需要拥有一个 OpenZiti overlay 网络。可以通过运行 [OpenZiti 网络快速入门之一](https://openziti.io/docs/category/network) 来部署一个。 有了对 OpenZiti overlay 网络的访问权限后，有一些重要的概念有助于理解，虽然它们对于执行示例并不是必需的： * 什么是 [Identity](https://openziti.io/docs/learn/core-concepts/identities/overview/) * 身份是如何创建的 * 什么是 [enrollment](https://openziti.io/docs/learn/core-concepts/security/enrollment/) 以及身份是如何注册的 * 使用并加载 [Identity](https://openziti.io/docs/learn/core-concepts/identities/overview/) 以创建 [ZitiContext](OpenZiti.NET/src/OpenZiti/ZitiContext.cs) * Dialing 和 Binding 示例没有引用 [OpenZiti.NET NuGet 包](https://www.nuget.org/packages/OpenZiti.NET/)。相反，它们引用了本仓库中的 [OpenZiti.NET](./OpenZiti.NET/OpenZiti.NET.csproj) 项目。当您想将 OpenZiti 添加到您的 dotnet 项目中时，您应该选择引用并使用 [OpenZiti.NET NuGet 包](https://www.nuget.org/packages/OpenZiti.NET/)。 ## 运行示例 本仓库中包含的示例旨在让您探索此 SDK 并探索 OpenZiti，而无需完全理解这些概念。当然，您最终需要理解这些术语才能充分利用 SDK，但一开始您并不需要。有关更多信息，请参阅 [官方文档](https://openziti.io)，并 [在 Discourse 上](https://openziti.discourse.group/) 与我们的社区互动。 运行示例被设计为自引导的。它们将使用 [OpenZiti Management API](https://openziti.io/docs/reference/developer/api/#edge-management-api) 在 OpenZiti overlay 网络内创建所有必要的配置。这意味着可以反复运行这些示例而无需担心失败，但这同时意味着它们每次都会重新设置示例。随着您在 OpenZiti 旅程中的进展并尝试重用由示例创建的配置，这一点将变得很重要。 目前您可以运行四个不同的示例，每个示例都概述了 OpenZiti 的不同原则。找一个看起来有趣的示例，并按照该示例的 readme 了解如何运行它。 | 示例 | 描述 | |-------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------| | [OpenAPI PetStore](https://github.com/openziti/ziti-sdk-csharp/blob/main/OpenZiti.NET.Samples/src/PetStore/README.md) | 说明如何安全地调用基于 HTTP 的 API | | [Weather](https://github.com/openziti/ziti-sdk-csharp/blob/main/OpenZiti.NET.Samples/src/Weather/README.md) | 说明如何使用 wttr.in 发出基于 http 的请求并将内容输出到屏幕 | | [Sample](https://github.com/openziti/ziti-sdk-csharp/blob/main/OpenZiti.NET.Samples/src/Server/README.md) | 说明如何将 OpenZiti 同时用作服务器**和**客户端。演示真正的应用内嵌零信任！ | | [Enrollment](https://github.com/openziti/ziti-sdk-csharp/blob/main/OpenZiti.NET.Samples/src/Enrollment/README.md) | 一个简单的示例，演示如何注册 OpenZiti Identity | ## 用于测试的 Overlay 最新版本的 `ziti` CLI 包含一个名为 `ziti edge quickstart` 的命令。此命令可与所有示例一起使用，以轻松设置测试环境。您也可以使用通过 [遵循其中一个快速入门](https://openziti.io/docs/category/network) 生成的 overlay 来运行示例，并且在向示例提供 "noint" 参数时，它也适用于 CloudZiti。 ### 获取 `ziti` CLI `ziti` CLI 工具是一种通过命令行（而不是通过 API）访问 OpenZiti overlay 网络的便捷方式。您可能时常需要用到 `ziti` CLI，因为它非常适合用于探索 OpenZiti 配置。如果您没有 `ziti` CLI 但希望安装它，您可以通过运行单个 powershell 命令快速安装（与往常一样，请在执行前阅读脚本）： ``` iex(iwr -Uri https://get.openziti.io/quick/getZiti.ps1) ``` ### 惯用的 dotnet SDK - OpenZiti.NET 此 NuGet 包提供了惯用的 SDK 实现。它 [使用此 GitHub 工作流](.github/workflows/dotnet-sdk-publish.yml) 构建并发布到 NuGet。该工作流非常直接，主要是在 [OpenZiti.NET](./OpenZiti.NET/OpenZiti.NET.csproj) 上调用 `dotnet build`，并执行 "NugetPush" target。您会在项目文件中找到该 target 的声明，并推送到您通过 `/p:NUGET_SOURCE=` 传递给 `dotnet build` 的任何源。使用此过程构建此包应该非常简单。 该任务将使用 [OpenZiti.NET.nuspec](./OpenZiti.NET/OpenZiti.NET.nuspec) 来构建包。这意味着对引用的更新**必须**反映在该文件中。当 OpenZiti.NET 项目成功完成构建时，会执行一个自动化流程，该流程将在该文件夹中生成更新后的 .nuspec 文件。如果此文件发生更改，您**必须**提交它。 #### 测试更改 要测试代码更改，最简单的方法通常是创建一个新示例来执行您想要更改/更新的功能并运行该示例。这也将为我们试图向包使用者说明/记录该示例时取得成功奠定基础。 #### 原生日志 为原生 C SDK（由 [OpenZiti.NET.native 包](https://www.nuget.org/packages/OpenZiti.NET.native/) 提供）启用更深的日志级别通常是**至关重要**的。您可以通过调用 `SetLogLevel` 来执行此操作： ``` API.SetLogLevel(ZitiLogLevel.INFO); ``` #### HTTP 日志记录 一些示例是围绕 HTTP 构建的。存在一个便利的 handler，可以轻松记录 HTTP 请求/响应。请参阅 `OpenZiti.Debugging.LoggingHandler` 以及它在示例中的使用方式。您需要通过设置以下内容来启用日志记录，然后它才会产生输出： ``` loggingHttpHandler.LogHttpRequestResponse = true; ``` ### 原生 NuGet 包 - OpenZiti.NET.native 原生 NuGet 包由 GitHub Actions 构建和发布。目前它支持以下架构： * Windows - x64 (64位) * Windows - x86 (32位) * MacOS - x86_64 * MacOS - arm64 * linux - x64 * linux - arm64 * linux - arm 到目前为止，处理 dotnet SDK 最复杂的部分是构建原生库。原生库提供了一些用 C 编写的辅助函数，这些函数对 dotnet SDK 至关重要。构建原生库有些复杂。如果您不熟悉 [cmake](https://cmake.org/)，您将需要学习大量关于 `cmake` 是什么以及它是如何工作的知识。此外，C SDK 现在使用 [vcpkg](https://github.com/microsoft/vcpkg)，这对于新学习者来说也有些复杂。我们利用了一个 [CMakePresets.json](./native/ZitiNativeApiForDotnetCore/CMakePresets.json)，您需要对此有所了解。`cmake` 的 [CMakeLists.txt](./native/ZitiNativeApiForDotnetCore/CMakeLists.txt) 位于 `native/ZitiNativeApiForDotnetCore` 中。 如果您对了解原生库是如何构建的感兴趣，请参阅 GitHub Action 文件](.github/workflows/native-nuget-publish.yml)。有关 `native/ZitiNativeApiForDotnetCore` 的更多信息，请转到 [项目文件夹中的 readme](./native/ZitiNativeApiForDotnetCore/README.md)。 原生库发布到 NuGet 后，惯用的 SDK 将引用该 NuGet 包，以提供单一、跨平台且惯用的 dotnet NuGet 包，从而便于在项目中被下游轻松引入。 ## 轮换 NuGet API Key 以下是一组关于如何轮换 NuGet API Key 以推送更新的简短说明 * 转到 https://www.nuget.org/account/ApiKeys Key Name: Expires In: 365 days Package Owner: OpenZiti Select Scopes: Push (checked) Push new packages and package versions (selected) Push only new package versions (unselected) Unlist package (unchecked) Glob Pattern: OpenZiti.* Select Packages: Available Packages: OpenZiti.NET OpenZiti.NET.native * 转到 https://github.com/organizations/openziti/settings/secrets/actions * 查找/更新：使用上面生成的密钥更新 NUGET_API_KEY

标签：Bash脚本, 多人体追踪, 端到端加密, 网络通信, 覆盖网络, 零信任网络