Українська
Експлуатація
Крок 1. Фонове прибирання
Навіщо. Дані двох видів накопичуються самі собою: завантаження, що їх ніколи не надіслано (тема 11), і токени оновлення, строк дії яких давно сплив або які відкликано (тема 8). Сервіси вже вміють їх видаляти; хтось має викликати їх регулярно. ASP.NET Core запускає фонові служби (hosted services) поруч із вебсервером – довготривалі фонові завдання, що стартують і зупиняються разом із застосунком.
Що зробити. Створіть папку Maintenance:
cs
using System.ComponentModel.DataAnnotations;
using Chatex.Core.Attachments;
using Chatex.Core.Auth;
using Microsoft.Extensions.Options;
namespace Chatex.Api.Maintenance;
internal sealed class MaintenanceOptions
{
public const string Section = "Maintenance";
public bool Enabled { get; set; } = true;
/// <summary>How often the cleanup runs; the first run is right after startup.</summary>
[Range(typeof(TimeSpan), "00:01:00", "1.00:00:00")]
public TimeSpan Interval { get; set; } = TimeSpan.FromHours(1);
/// <summary>Uploads that were never sent with a message are deleted after this long.</summary>
[Range(typeof(TimeSpan), "00:10:00", "30.00:00:00")]
public TimeSpan StaleUploadAge { get; set; } = TimeSpan.FromHours(24);
}
/// <summary>
/// Deletes uploads that were never sent and refresh tokens that can no longer be used. Each pass runs in its own DI
/// scope, like a request; a failed pass is logged and the next one runs on schedule.
/// </summary>
internal sealed partial class MaintenanceService(
IServiceScopeFactory scopes,
IOptions<MaintenanceOptions> options,
TimeProvider timeProvider,
ILogger<MaintenanceService> logger) : BackgroundService
{
protected override async Task ExecuteAsync(CancellationToken stoppingToken)
{
var settings = options.Value;
if (!settings.Enabled)
{
return;
}
using var timer = new PeriodicTimer(settings.Interval, timeProvider);
do
{
await RunOnceAsync(settings, stoppingToken);
}
while (await timer.WaitForNextTickAsync(stoppingToken));
}
private async Task RunOnceAsync(MaintenanceOptions settings, CancellationToken cancellationToken)
{
try
{
await using var scope = scopes.CreateAsyncScope();
var attachments = scope.ServiceProvider.GetRequiredService<IAttachmentService>();
var auth = scope.ServiceProvider.GetRequiredService<IAuthService>();
var uploads = 0;
int batch;
do
{
batch = await attachments.CleanupStaleAsync(settings.StaleUploadAge, cancellationToken);
uploads += batch;
}
while (batch > 0);
var tokens = await auth.DeleteStaleRefreshTokensAsync(cancellationToken);
if (uploads > 0 || tokens > 0)
{
LogCleaned(uploads, tokens);
}
}
catch (Exception ex) when (ex is not OperationCanceledException)
{
LogFailed(ex);
}
}
[LoggerMessage(Level = LogLevel.Information, Message = "Maintenance deleted {Uploads} stale uploads and {Tokens} stale refresh tokens")]
private partial void LogCleaned(int uploads, int tokens);
[LoggerMessage(Level = LogLevel.Error, Message = "Maintenance pass failed; the next one runs on schedule")]
private partial void LogFailed(Exception exception);
}BackgroundService– базовий клас фонової служби: перевизначтеExecuteAsync, що працює, доки застосунок не зупиниться (stoppingToken).PeriodicTimerз упровадженимTimeProviderспрацьовує щогодини; перший прохід виконується одразу після запуску (do … while).- Нова область на кожен прохід: сервіси мають область дії (scoped; один
DbContextна одиницю роботи), а в фонової служби немає області запиту.IServiceScopeFactoryстворює її так само, як це зробив би запит. - Завантаження прибираються пакетами по 500, доки пакет не повернеться порожнім.
- Невдалий прохід записується в журнал, але не є фатальним: база даних може бути ненадовго недоступна, а наступний прохід відбудеться за розкладом.
OperationCanceledExceptionвиключено, тож завершення роботи не потрапляє до журналу як помилка. [LoggerMessage]наpartial-методах дає змогу компілятору згенерувати швидкі структуровані методи журналювання; заповнювачі{Uploads}і{Tokens}стають іменованими властивостями в журналі.
Крок 2. Зареєструйте решту веб-рівня
Навіщо. AddApi отримує все, що запровадила ця тема, плюс дві речі, потрібні серверові за проксі.
- Переспрямовані заголовки (forwarded headers). За Nginx Kestrel бачить кожен запит від
127.0.0.1через звичайний HTTP. Nginx додаєX-Forwarded-For(IP-адресу клієнта) іX-Forwarded-Proto(https); проміжне програмне забезпечення переспрямованих заголовків повертає їх уHttpContext.Connection.RemoteIpAddressіRequest.Scheme. Від цього залежать обмеження частоти запитів і IP-адреса, що зберігається з токенами оновлення. - Data Protection – це в’язка ключів ASP.NET Core для шифрування короткочасних даних (наприклад, токенів скидання пароля в Identity). Її ключі мають пережити перезапуск, тому на сервері їх записують у папку (
DataProtection:KeysPath); без цього налаштування вони лишаються в пам’яті.
Що зробити. Розширте AddApi (нові рядки позначено зеленим):
cs
using System.Text.Json;
using System.Text.Json.Serialization;
using Chatex.Api.Infrastructure;
using Chatex.Api.Maintenance;
using Chatex.Core.Auth;
using Microsoft.AspNetCore.Authentication.JwtBearer;
using Microsoft.AspNetCore.DataProtection;
using Microsoft.AspNetCore.HttpOverrides;
using Microsoft.AspNetCore.Server.Kestrel.Core;
using Microsoft.Extensions.Options;
using Microsoft.IdentityModel.JsonWebTokens;
using Microsoft.IdentityModel.Tokens;
namespace Chatex.Api;
public static class DependencyInjection
{
/// <summary>The request body limit for everything except file uploads.</summary>
public const long MaxRequestBodyBytes = 1024 * 1024;
public static IServiceCollection AddApi(this IServiceCollection services, IConfiguration configuration)
{
// Without a key folder the keys live in memory and change on every restart. Nothing persistent depends on
// them yet, but Identity tokens (password reset, email confirmation) will.
var dataProtection = services.AddDataProtection().SetApplicationName("Chatex");
if (configuration["DataProtection:KeysPath"] is { Length: > 0 } keysPath)
{
dataProtection.PersistKeysToFileSystem(new DirectoryInfo(keysPath));
}
services.AddOptions<MaintenanceOptions>()
.BindConfiguration(MaintenanceOptions.Section)
.ValidateDataAnnotations()
.ValidateOnStart();
services.AddHostedService<MaintenanceService>();
// JSON bodies are small; the upload endpoints raise this per request (FileUploadExtensions.AcceptsFileUpTo).
services.Configure<KestrelServerOptions>(o => o.Limits.MaxRequestBodySize = MaxRequestBodyBytes);
services.ConfigureHttpJsonOptions(o =>
o.SerializerOptions.Converters.Add(new JsonStringEnumConverter(JsonNamingPolicy.CamelCase)));
services.AddProblemDetails();
services.AddChatexRateLimiting();
// Malformed bodies answer 400 (turned into problem details by UseStatusCodePages) in every environment,
// instead of throwing to the exception handler in Development.
services.Configure<RouteHandlerOptions>(o => o.ThrowOnBadRequest = false);
services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme).AddJwtBearer();
services.AddOptions<JwtBearerOptions>(JwtBearerDefaults.AuthenticationScheme)
.Configure<IOptions<JwtOptions>>((bearer, jwtOptions) =>
{
var jwt = jwtOptions.Value;
bearer.MapInboundClaims = false;
bearer.TokenValidationParameters = new TokenValidationParameters
{
ValidIssuer = jwt.Issuer,
ValidAudience = jwt.Audience,
IssuerSigningKey = jwt.CreateSigningKey(),
ValidAlgorithms = [SecurityAlgorithms.HmacSha256],
NameClaimType = JwtRegisteredClaimNames.UniqueName,
ClockSkew = TimeSpan.FromSeconds(30),
};
});
services.AddAuthorization();
services.Configure<ForwardedHeadersOptions>(o =>
o.ForwardedHeaders = ForwardedHeaders.XForwardedFor | ForwardedHeaders.XForwardedProto);
services.AddOpenApi(o =>
{
o.AddDocumentTransformer<BearerSecuritySchemeTransformer>();
o.AddOperationTransformer<BearerSecuritySchemeTransformer>();
});
return services;
}
}MaxRequestBodyBytesпублічне, тож кожен бачить глобальне обмеження в 1 МБ;Configure<KestrelServerOptions>задає його, аAcceptsFileUpToпіднімає для кінцевих точок завантаження.AddHostedService<MaintenanceService>()запускає прибирання разом із застосунком; його параметри (Enabled,Interval,StaleUploadAge) перевіряються під час запуску.BindConfiguration– коротша формаBind(configuration.GetSection(...)).AddChatexRateLimiting()– метод розширення з попереднього розділу.
Крок 3. Фінальний конвеєр
Що зробити. Розширте Program.cs (нові рядки позначено зеленим):
cs
using Chatex.Api;
using Chatex.Api.Endpoints;
using Chatex.Api.Infrastructure;
using Chatex.Core;
using Scalar.AspNetCore;
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddApi(builder.Configuration);
builder.Services.AddCore(builder.Configuration);
var app = builder.Build();
app.UseForwardedHeaders();
app.UseExceptionHandler();
app.UseStatusCodePages();
app.UseAuthentication();
app.UseAuthorization();
app.UseRateLimiter();
if (app.Environment.IsDevelopment())
{
app.MapOpenApi();
app.MapScalarApiReference(o => o.AddPreferredSecuritySchemes(BearerSecuritySchemeTransformer.SchemeName));
}
// Readiness: 200 when the API can reach the database, 503 otherwise (the deploy rolls back on 503).
app.MapHealthChecks("/health").AllowAnonymous();
var api = app.MapGroup("/api").RequireAuthorization();
api.MapAuthEndpoints();
api.MapProfileEndpoints();
api.MapUserEndpoints();
api.MapChatEndpoints();
api.MapMessageEndpoints();
api.MapAttachmentEndpoints();
app.Run();
/// <summary>Visible to <c>WebApplicationFactory</c> in the Api tests.</summary>
public partial class Program;UseForwardedHeadersіде першим, щоб кожне наступне проміжне програмне забезпечення бачило справжнього клієнта.UseRateLimiterіде після автентифікації: тоді політика могла б розділяти за користувачем; Chatex розділяє за IP.MapHealthChecks("/health").AllowAnonymous()відповідає200 Healthy, коли перевірка бази даних із теми 5 проходить, і503 Unhealthyв іншому разі – без токена, бо її викликають скрипт розгортання (тема 24) та засоби моніторингу.MapAttachmentEndpointsзіставляє кінцеві точки завантаження й отримання.
Крок 4. Налаштування для робочого сервера
Навіщо. На сервері API працює як служба systemd (тема 23); його вивід у консоль іде до системного журналу. Консольний форматувальник systemd пише один рядок на запис із префіксом важливості, який розуміє journalctl, замість кольорового багаторядкового формату розробки.
Що зробити.
json
{
"Logging": {
"Console": {
"FormatterName": "systemd"
}
}
}Усе інше для робочого сервера – рядок підключення, ключ підпису, папки завантажень і ключів – надходить зі змінних середовища на сервері (Jwt__SigningKey, із подвійним підкресленням замість : розділу), ніколи не з файлу в репозиторії.
Перевірка
dotnet build проходить успішно. Запустіть API (./Run.ps1 api) і відкрийте http://localhost:5214/health: сторінка показує Healthy. Зупиніть базу даних командою ./Run.ps1 db-stop і перезавантажте сторінку: за кілька секунд відповідь буде 503 з Unhealthy. Запустіть базу знову командою ./Run.ps1 db.