ABP vNext 多租户系统实现登录页自定义 Logo 的最佳实践

🚀 ABP vNext 多租户系统实现登录页自定义 Logo 的最佳实践

🧭 版本信息与运行环境

• ABP Framework：v8.1.5
• .NET SDK：8.0
• 数据库：PostgreSQL（支持 SQLServer、MySQL 等）
• BLOB 存储：本地/OSS/Azure Blob（推荐启用 CDN）
• 部署建议：支持单库/多库多租户结构，推荐搭配 CI/CD 自动迁移

🔍 实现背景

ABP vNext 提供完备的多租户能力，支持根据请求自动切换上下文。在实际项目中，为每个租户提供个性化登录 Logo 是增强品牌感、提升用户体验的重要方式。

📦 总体思路与流程图

使用 ABP 的实体扩展和 Blob 模块，结合租户解析机制，动态加载 Logo：

🧱 步骤一：扩展租户实体添加 Logo 字段

🔧 实体扩展配置流程

💡 推荐位置：*.Domain.Shared + *.Domain

// MyTenantConsts.cs
public static class MyTenantConsts
{
    public const string LogoUrlPropertyName = "LogoUrl";
}

// MyTenantEntityExtension.cs
public static class MyTenantEntityExtension
{
    public static void Configure()
    {
        ObjectExtensionManager.Instance
            .Modules()
            .ConfigureSaas(sa =>
            {
                sa.ConfigureTenant(t =>
                {
                    t.AddOrUpdateProperty<string>(MyTenantConsts.LogoUrlPropertyName);
                });
            });
    }
}

在模块类中 PreConfigureServices 阶段调用：

public override void PreConfigureServices(ServiceConfigurationContext context)
{
    MyTenantEntityExtension.Configure();
}

✅ 确保迁移脚本包含新字段

🖼 步骤二：上传并持久化租户 Logo

📥 Logo 上传与持久化流程

💡 建议封装至 Application Service：

public class TenantUiAppService : ApplicationService
{
    private readonly IBlobContainer _blobContainer;
    private readonly ITenantRepository _tenantRepository;

    public TenantUiAppService(IBlobContainer blobContainer, ITenantRepository tenantRepository)
    {
        _blobContainer = blobContainer;
        _tenantRepository = tenantRepository;
    }

    public async Task<string> UploadLogoAsync(Guid tenantId, IFormFile file)
    {
        if (file.Length > 1024 * 1024)
            throw new UserFriendlyException("文件不能超过 1MB");
        
        if (!file.ContentType.StartsWith("image/"))
            throw new UserFriendlyException("请上传 PNG 或 JPG 图片");

        var blobPath = $"{tenantId}/logo.png";

        using var stream = file.OpenReadStream();
        await _blobContainer.SaveAsync(blobPath, stream, overrideExisting: true);

        var tenant = await _tenantRepository.GetAsync(tenantId);
        tenant.SetProperty(MyTenantConsts.LogoUrlPropertyName, blobPath);
        await _tenantRepository.UpdateAsync(tenant); // 持久化

        return await _blobContainer.GetDownloadUrlAsync(blobPath); // 带签名 URL
    }
}

🌐 步骤三：登录页动态加载租户 Logo

⚙️ 登录页 Logo 加载流程

封装服务接口：

public class TenantUiQueryService : ApplicationService
{
    private readonly ITenantRepository _tenantRepository;
    private readonly IBlobContainer _blobContainer;

    public TenantUiQueryService(ITenantRepository tenantRepository, IBlobContainer blobContainer)
    {
        _tenantRepository = tenantRepository;
        _blobContainer = blobContainer;
    }

    public async Task<string> GetLogoUrlAsync()
    {
        var tenantId = CurrentTenant.Id;
        if (tenantId == null)
            return "/images/default-logo.png";

        var tenant = await _tenantRepository.GetAsync(tenantId.Value);

        if (!tenant.ExtraProperties.TryGetValue(MyTenantConsts.LogoUrlPropertyName, out var rawPath) ||
            rawPath == null)
        {
            return "/images/default-logo.png";
        }

        return await _blobContainer.GetDownloadUrlAsync(rawPath.ToString());
    }
}

前端渲染：

<img src="@logoUrl" onerror="this.src='/images/default-logo.png'" class="login-logo" />

🏗️ CI/CD 自动迁移流程

🧠 最佳实践建议