Konfiguracja pulpitu nawigacyjnego

Artykuł
12/13/2024

Pulpit nawigacyjny jest konfigurowany podczas uruchamiania. Konfiguracja obejmuje adresy frontonu i protokołu OpenTelemetry (OTLP), punkt końcowy usługi zasobów, uwierzytelnianie, limity telemetrii i inne.

Po uruchomieniu pulpitu nawigacyjnego przy użyciu projektu hosta aplikacji .NET.NET Aspire jest on automatycznie skonfigurowany do wyświetlania zasobów i telemetrii aplikacji. Konfiguracja jest udostępniana podczas uruchamiania pulpitu nawigacyjnego w trybie autonomicznym .

Istnieje wiele sposobów zapewnienia konfiguracji:

Argumenty wiersza polecenia.
Zmienne środowiskowe. Ogranicznik : należy zastąpić podwójnym podkreśleniem (__) w nazwach zmiennych środowiskowych.
Opcjonalny plik konfiguracji JSON. Ustawienie DOTNET_DASHBOARD_CONFIG_FILE_PATH może służyć do określania pliku konfiguracji JSON.

Rozważmy poniższy przykład pokazujący sposób konfigurowania pulpitu nawigacyjnego podczas uruchamiania z kontenera Docker:

powłoki Bash
programu PowerShell

docker run --rm -it -p 18888:18888 -p 4317:18889 -d --name aspire-dashboard \
    -e DASHBOARD__TELEMETRYLIMITS__MAXLOGCOUNT='1000' \
    -e DASHBOARD__TELEMETRYLIMITS__MAXTRACECOUNT='1000' \
    -e DASHBOARD__TELEMETRYLIMITS__MAXMETRICSCOUNT='1000' \
    mcr.microsoft.com/dotnet/aspire-dashboard:9.0

docker run --rm -it -p 18888:18888 -p 4317:18889 -d --name aspire-dashboard `
    -e DASHBOARD__TELEMETRYLIMITS__MAXLOGCOUNT='1000' `
    -e DASHBOARD__TELEMETRYLIMITS__MAXTRACECOUNT='1000' `
    -e DASHBOARD__TELEMETRYLIMITS__MAXMETRICSCOUNT='1000' `
    mcr.microsoft.com/dotnet/aspire-dashboard:9.0

Alternatywnie można skonfigurować te same wartości przy użyciu pliku konfiguracji JSON określonego przy użyciu DOTNET_DASHBOARD_CONFIG_FILE_PATH:

{
  "Dashboard": {
    "TelemetryLimits": {
      "MaxLogCount": 1000,
      "MaxTraceCount": 1000,
      "MaxMetricsCount": 1000
    }
  }
}

Ważny

Na pulpicie nawigacyjnym są wyświetlane informacje o zasobach, w tym ich konfiguracja, dzienniki konsoli i szczegółowe dane telemetryczne.

Dane wyświetlane na pulpicie nawigacyjnym mogą być poufne. Na przykład wpisy tajne w zmiennych środowiskowych i poufne dane środowiska uruchomieniowego w telemetrii. Należy zadbać o skonfigurowanie pulpitu nawigacyjnego w celu zabezpieczenia dostępu.

Aby uzyskać więcej informacji, zobacz zabezpieczenia pulpitu nawigacyjnego .

Nuta

Konfiguracja opisana na tej stronie dotyczy autonomicznego pulpitu nawigacyjnego. Aby skonfigurować projekt hosta aplikacji .NET.NET Aspire, zobacz Konfiguracja hosta aplikacji.

Typowa konfiguracja

Opcja	Wartość domyślna	Opis
`ASPNETCORE_URLS`	`http://localhost:18888`	Co najmniej jeden punkt końcowy HTTP, za pośrednictwem którego jest obsługiwany fronton pulpitu nawigacyjnego. Punkt końcowy frontonu służy do wyświetlania pulpitu nawigacyjnego w przeglądarce. Po uruchomieniu pulpitu nawigacyjnego przez host aplikacji .NET.NET Aspire ten adres jest zabezpieczony przy użyciu protokołu HTTPS. Zalecane jest zabezpieczanie pulpitu nawigacyjnego przy użyciu protokołu HTTPS.
`DOTNET_DASHBOARD_OTLP_ENDPOINT_URL`	`http://localhost:18889`	Punkt końcowy OTLP/gRPC. Ten punkt końcowy hostuje usługę OTLP i odbiera dane telemetryczne przy użyciu funkcji gRPC. Po uruchomieniu pulpitu nawigacyjnego przez host aplikacji .NET.NET Aspire ten adres jest zabezpieczony przy użyciu protokołu HTTPS. Zalecane jest zabezpieczanie pulpitu nawigacyjnego przy użyciu protokołu HTTPS.
`DOTNET_DASHBOARD_OTLP_HTTP_ENDPOINT_URL`	`http://localhost:18890`	Punkt końcowy OTLP/HTTP. Ten punkt końcowy hostuje usługę OTLP i odbiera dane telemetryczne przy użyciu protokołu Protobuf za pośrednictwem protokołu HTTP. Po uruchomieniu pulpitu nawigacyjnego przez aplikację .NET.NET Aspire hostem punktu końcowego OTLP/HTTP nie jest domyślnie skonfigurowany. Aby skonfigurować punkt końcowy OTLP/HTTP przy użyciu hosta aplikacji, ustaw `DOTNET_DASHBOARD_OTLP_HTTP_ENDPOINT_URL` env var wartość w launchSettings.json. Zalecane jest zabezpieczanie pulpitu nawigacyjnego przy użyciu protokołu HTTPS.
`DOTNET_DASHBOARD_UNSECURED_ALLOW_ANONYMOUS`	`false`	Konfiguruje pulpit nawigacyjny tak, aby nie używał uwierzytelniania i akceptuje dostęp anonimowy. To ustawienie jest skrótem do konfigurowania `Dashboard:Frontend:AuthMode` i `Dashboard:Otlp:AuthMode` w celu `Unsecured`.
`DOTNET_DASHBOARD_CONFIG_FILE_PATH`	`null`	Ścieżka pliku konfiguracji JSON. Jeśli pulpit nawigacyjny jest uruchamiany w kontenerze Docker, jest to ścieżka do pliku konfiguracji w zainstalowanym woluminie. Ta wartość jest opcjonalna.
`DOTNET_RESOURCE_SERVICE_ENDPOINT_URL`	`null`	Punkt końcowy gRPC, z którym pulpit nawigacyjny łączy się ze swoimi danymi. Jeśli ta wartość jest nieokreślona, na pulpicie nawigacyjnym są wyświetlane dane telemetryczne, ale nie ma listy zasobów ani dzienników konsoli. To ustawienie jest skrótem do `Dashboard:ResourceServiceClient:Url`.

Uwierzytelnianie frontonu

Uwierzytelnianie punktu końcowego frontonu pulpitu nawigacyjnego jest konfigurowane przy użyciu Dashboard:Frontend:AuthMode. Fronton można zabezpieczyć za pomocą uwierzytelniania tokenu OpenID Connect (OIDC) lub przeglądarki.

Uwierzytelnianie tokenu przeglądarki działa przez fronton z prośbą o token. Token można wprowadzić w interfejsie użytkownika lub podać jako wartość ciągu zapytania na stronie logowania. Na przykład https://localhost:1234/login?t=TheToken. Gdy token zostanie pomyślnie uwierzytelniony, cookie uwierzytelniania zostanie utrwalone w przeglądarce, a przeglądarka zostanie przekierowana do aplikacji.

Opcja	Wartość domyślna	Opis
`Dashboard:Frontend:AuthMode`	`BrowserToken`	Można ustawić na `BrowserToken`, `OpenIdConnect` lub `Unsecured`. `Unsecured` należy używać tylko podczas programowania lokalnego. Nie zaleca się hostowania pulpitu nawigacyjnego publicznie lub w innych ustawieniach.
`Dashboard:Frontend:BrowserToken`	`null`	Określa token przeglądarki. Jeśli token przeglądarki nie zostanie określony, zostanie wygenerowany przez pulpit nawigacyjny. Narzędzia, które chcą zautomatyzować logowanie za pomocą uwierzytelniania tokenu przeglądarki, mogą określić token i otworzyć przeglądarkę przy użyciu tokenu w ciągu zapytania. Przy każdym uruchomieniu pulpitu nawigacyjnego należy wygenerować nowy token.
`Dashboard:Frontend:OpenIdConnect:NameClaimType`	`name`	Określa jeden lub więcej typów oświadczeń, które powinny być używane do wyświetlania pełnej nazwy uwierzytelnionego użytkownika. Może być pojedynczym typem oświadczenia lub rozdzielaną przecinkami listą typów oświadczeń.
`Dashboard:Frontend:OpenIdConnect:UsernameClaimType`	`preferred_username`	Określa jeden lub więcej typów oświadczeń, które powinny być używane do wyświetlania nazwy użytkownika uwierzytelnionego użytkownika. Może być pojedynczym typem oświadczenia lub rozdzielaną przecinkami listą typów oświadczeń.
`Dashboard:Frontend:OpenIdConnect:RequiredClaimType`	`null`	Określa oświadczenie, które musi być obecne dla autoryzowanych użytkowników. Autoryzacja kończy się niepowodzeniem bez tego oświadczenia. Ta wartość jest opcjonalna.
`Dashboard:Frontend:OpenIdConnect:RequiredClaimValue`	`null`	Określa wartość wymaganego oświadczenia. Używane tylko wtedy, gdy określono `Dashboard:Frontend:OpenIdConnect:RequireClaimType`. Ta wartość jest opcjonalna.
`Authentication:Schemes:OpenIdConnect:Authority`	`null`	Adres URL dostawcy tożsamości (IdP).
`Authentication:Schemes:OpenIdConnect:ClientId`	`null`	Tożsamość jednostki uzależnionej (RP).
`Authentication:Schemes:OpenIdConnect:ClientSecret`	`null`	Sekret, który wiedziałby tylko prawdziwy RP.
Inne właściwości OpenIdConnectOptions	`null`	Wartości w sekcji konfiguracji `Authentication:Schemes:OpenIdConnect:*` są powiązane z `OpenIdConnectOptions`, takimi jak `Scope`.

Nuta

Dodatkowa konfiguracja może być wymagana w przypadku korzystania z OpenIdConnect jako trybu uwierzytelniania za zwrotnym serwerem proxy, który przerywa protokół SSL. Sprawdź, czy chcesz ustawić ASPNETCORE_FORWARDEDHEADERS_ENABLED na true.

Aby uzyskać więcej informacji, zobacz Konfigurowanie ASP.NET Core do pracy z serwerami proxy i modułami równoważenia obciążenia.

Uwierzytelnianie OTLP

Uwierzytelnianie punktu końcowego OTLP jest konfigurowane przy użyciu Dashboard:Otlp:AuthMode. Punkt końcowy OTLP można zabezpieczyć za pomocą klucza interfejsu API lub certyfikatu klienta uwierzytelniania.

Uwierzytelnianie klucza interfejsu API działa, wymagając, aby każde żądanie OTLP miało prawidłową wartość nagłówka x-otlp-api-key. Musi być zgodny z kluczem podstawowym lub pomocniczym.

Opcja	Wartość domyślna	Opis
`Dashboard:Otlp:AuthMode`	`Unsecured`	Można ustawić na `ApiKey`, `Certificate` lub `Unsecured`. `Unsecured` należy używać tylko podczas programowania lokalnego. Nie zaleca się hostowania pulpitu nawigacyjnego publicznie lub w innych ustawieniach.
`Dashboard:Otlp:PrimaryApiKey`	`null`	Określa podstawowy klucz interfejsu API. Klucz interfejsu API może być dowolnym tekstem, ale zalecana jest wartość z co najmniej 128 bitami entropii. Ta wartość jest wymagana, jeśli tryb uwierzytelniania jest kluczem interfejsu API.
`Dashboard:Otlp:SecondaryApiKey`	`null`	Określa pomocniczy klucz interfejsu API. Klucz interfejsu API może być dowolnym tekstem, ale zalecana jest wartość z co najmniej 128 bitami entropii. Ta wartość jest opcjonalna. Jeśli określono drugi klucz interfejsu API, wartość nagłówka przychodzącego `x-otlp-api-key` może być zgodna z kluczem podstawowym lub pomocniczym.

OTLP CORS

Współużytkowanie zasobów między źródłami (CORS) można skonfigurować tak, aby umożliwić aplikacjom przeglądarki wysyłanie danych telemetrycznych do pulpitu nawigacyjnego.

Domyślnie aplikacje przeglądarki są ograniczone do wykonywania wywołań interfejsu API między domenami. Ma to wpływ na wysyłanie danych telemetrycznych do pulpitu nawigacyjnego, ponieważ pulpit nawigacyjny i aplikacja przeglądarki są zawsze w różnych domenach. Aby skonfigurować mechanizm CORS, użyj sekcji Dashboard:Otlp:Cors i określ dozwolone źródła i nagłówki:

{
  "Dashboard": {
    "Otlp": {
      "Cors": {
        "AllowedOrigins": "http://localhost:5000,https://localhost:5001"
      }
    }
  }
}

Rozważ następujące opcje konfiguracji:

Opcja	Wartość domyślna	Opis
`Dashboard:Otlp:Cors:AllowedOrigins`	`null`	Określa dozwolone źródła mechanizmu CORS. Jest to ciąg rozdzielany przecinkami i może zawierać symbol wieloznaczny `*`, aby zezwolić na dowolną domenę. Ta opcja jest opcjonalna i można ustawić przy użyciu zmiennej środowiskowej `DASHBOARD__OTLP__CORS__ALLOWEDORIGINS`.
`Dashboard:Otlp:Cors:AllowedHeaders`	`null`	Ciąg rozdzielany przecinkami reprezentujący dozwolone nagłówki dla mechanizmu CORS. To ustawienie jest opcjonalne i można je ustawić przy użyciu zmiennej środowiskowej `DASHBOARD__OTLP__CORS__ALLOWEDHEADERS`.

Nuta

Pulpit nawigacyjny obsługuje tylko metodę POST wysyłania danych telemetrycznych i nie zezwala na konfigurację dozwolonych metod (Access-Control-Allow-Methods) dla mechanizmu CORS.

Zasoby

Pulpit nawigacyjny łączy się z usługą zasobów w celu załadowania i wyświetlenia informacji o zasobach. Klient jest skonfigurowany na pulpicie nawigacyjnym w celu nawiązania połączenia z usługą.

Uwierzytelnianie klienta usługi zasobów jest konfigurowane przy użyciu Dashboard:ResourceServiceClient:AuthMode. Klienta można skonfigurować do obsługi klucza interfejsu API lub uwierzytelniania certyfikatu klienta.

Opcja	Wartość domyślna	Opis
`Dashboard:ResourceServiceClient:Url`	`null`	Punkt końcowy gRPC, z którym pulpit nawigacyjny łączy się ze swoimi danymi. Jeśli ta wartość jest nieokreślona, na pulpicie nawigacyjnym są wyświetlane dane telemetryczne, ale nie ma listy zasobów ani dzienników konsoli.
`Dashboard:ResourceServiceClient:AuthMode`	`null`	Można ustawić na `ApiKey`, `Certificate` lub `Unsecured`. `Unsecured` należy używać tylko podczas programowania lokalnego. Nie zaleca się hostowania pulpitu nawigacyjnego publicznie lub w innych ustawieniach. Ta wartość jest wymagana, jeśli określono adres URL usługi zasobów.
`Dashboard:ResourceServiceClient:ApiKey`	`null`	Interfejs API do wysłania do usługi zasobów w nagłówku `x-resource-service-api-key`. Ta wartość jest wymagana, jeśli tryb uwierzytelniania jest kluczem interfejsu API.
`Dashboard:ResourceServiceClient:ClientCertificate:Source`	`null`	Można ustawić na `File` lub `KeyStore`. Ta wartość jest wymagana, jeśli tryb uwierzytelniania to certyfikat klienta.
`Dashboard:ResourceServiceClient:ClientCertificate:FilePath`	`null`	Ścieżka pliku certyfikatu. Ta wartość jest wymagana, jeśli źródło jest `File`.
`Dashboard:ResourceServiceClient:ClientCertificate:Password`	`null`	Hasło do pliku certyfikatu. Ta wartość jest opcjonalna.
`Dashboard:ResourceServiceClient:ClientCertificate:Subject`	`null`	Podmiot certyfikatu. Ta wartość jest wymagana, jeśli źródło jest `KeyStore`.
`Dashboard:ResourceServiceClient:ClientCertificate:Store`	`My`	Certyfikat StoreName.
`Dashboard:ResourceServiceClient:ClientCertificate:Location`	`CurrentUser`	Certyfikat StoreLocation.

Limity telemetrii

Dane telemetryczne są przechowywane w pamięci. Aby uniknąć nadmiernego użycia pamięci, pulpit nawigacyjny ma limity liczby i rozmiaru przechowywanych danych telemetrycznych. Po osiągnięciu limitu liczby zostanie dodana nowa telemetria, a najstarsza telemetria zostanie usunięta. Po osiągnięciu limitu rozmiaru dane są obcinane do limitu.

Limity telemetrii mają różne zakresy w zależności od typu telemetrii:

MaxLogCount i MaxTraceCount są współużytkowane między zasobami. Na przykład wartość MaxLogCount 5000 konfiguruje pulpit nawigacyjny do przechowywania maksymalnie 5000 wpisów dziennika dla wszystkich zasobów.
MaxMetricsCount to zasób. Na przykład wartość MaxMetricsCount 10 000 konfiguruje pulpit nawigacyjny do przechowywania maksymalnie 10 000 punktów danych metryk na zasób.

Opcja	Wartość domyślna	Opis
`Dashboard:TelemetryLimits:MaxLogCount`	10,000	Maksymalna liczba wpisów dziennika. Limit jest współużytkowany między zasobami.
`Dashboard:TelemetryLimits:MaxTraceCount`	10,000	Maksymalna liczba śladów dziennika. Limit jest współużytkowany między zasobami.
`Dashboard:TelemetryLimits:MaxMetricsCount`	50,000	Maksymalna liczba punktów danych metryk. Limit to zasób.
`Dashboard:TelemetryLimits:MaxAttributeCount`	128	Maksymalna liczba atrybutów telemetrii.
`Dashboard:TelemetryLimits:MaxAttributeLength`	`null`	Maksymalna długość atrybutów.
`Dashboard:TelemetryLimits:MaxSpanEventCount`	`null`	Maksymalna liczba zdarzeń dla atrybutów span.

Inny

Opcja	Wartość domyślna	Opis
`Dashboard:ApplicationName`	`Aspire`	Nazwa aplikacji, która ma być wyświetlana w interfejsie użytkownika. Ma to zastosowanie tylko wtedy, gdy nie określono żadnego adresu URL usługi zasobów. Gdy usługa zasobów istnieje, usługa określa nazwę aplikacji.

Następne kroki

Zagadnienia dotyczące zabezpieczeń dotyczące uruchamiania pulpitu nawigacyjnego .NET.NET Aspire

Udostępnij za pośrednictwem

Konfiguracja pulpitu nawigacyjnego

Typowa konfiguracja

Uwierzytelnianie frontonu

Uwierzytelnianie OTLP

OTLP CORS

Zasoby

Limity telemetrii

Inny

Następne kroki

Dodatkowe zasoby