常见问题

汇总新手最容易遇到的一批问题。如果这里没有你要的答案,可以看看文档索引里的对应模块文档,或更新日志确认版本行为。

1. 项目跑起来了,后台登录入口在哪?

后台入口是 /admin/{AdminRouteSecret}:

  • 用模板新建的项目:安全码是首次启动时随机生成的 8 位字符,会打印在控制台启动日志里(同时保存在 .aspnet/admin-route-secret.txt,重启不变)。
  • 自己接入框架的项目:用 AddEasyAdminBlazor 里配置的 AdminRouteSecret(不配置则后台没有路由保护,直接访问 /Admin/ 即可)。

访问该地址后系统会种下安全 Cookie 并跳转到 /Admin/。端口以控制台启动日志里的监听地址为准。

2. 默认账号密码是什么?忘记密码怎么办?

模板默认管理员:admin / 123yyq。忘记密码时,用另一个管理员账号登录,在「系统管理 → 用户管理」里对目标用户点「编辑」,输入新密码保存即可。如果所有管理员都进不去了,只能找技术人员直接处理数据库,或从备份恢复。

3. 打开 /Admin 返回 404?

说明没带 AdminRouteSecret 对应的安全 Cookie。请先访问 /admin/{AdminRouteSecret}(带安全码的地址,安全码见启动日志或 AddEasyAdminBlazor 的配置),而不是直接访问 /Admin。如果安全码改过,用新安全码。

4. 数据库连接失败 / 首次启动报错?

  • 检查 appsettings.json(或 appsettings.Development.json)里的连接串
  • MySQL 连接串建议带 Charset=utf8mb4
  • 确认数据库服务已启动、账号密码正确、目标库已创建
  • 首次运行需要开启 UseAutoSyncStructure(true) 自动建表;生产环境建议先在开发库同步结构

5. 表结构/新字段没有自动同步?

开发阶段 UseAutoSyncStructure(true) 会自动同步;生产环境一般设为 false。如果开发环境也没同步,确认实体类在 EasyAdminBlazorOptions.Assemblies 注册的程序集里,重启项目即可。

6. 中文乱码?

  • MySQL 连接串加 Charset=utf8mb4,数据库和表也建议用 utf8mb4
  • 页面乱码检查 App.razor 里的 <meta charset="utf-8" />

7. 聊天、在线状态不生效?

聊天扩展依赖 Redis。检查:

  • Program.cs 里调用了 AddEasyAdminBlazorChat() 和 app.UseChat()
  • Redis:ConnectionString 配置正确,Redis 服务已启动
  • 没配置 Redis 时聊天功能不会启用(这是设计行为)

8. 发布后上传文件/图片失败?

检查 wwwroot/uploads 目录是否有写权限(IIS、Windows 服务、Linux 都要给运行账号授权)。上传限制和图片处理参数在 FileSettings 里配置。

9. Blazor Server 页面频繁断线重连?

生产环境通过反向代理访问时,必须转发 WebSocket 的 Upgrade/Connection 请求头,并适当调大 proxy_read_timeout。详见部署上线。开发环境偶尔掉线是正常的(重新编译、页面长时间无操作等)。

10. 改了 AesKey 或 AdminRouteSecret 后出问题?

AesKey 会派生 Data Protection 的应用名,参与 Cookie / 登录票据的加密密钥隔离;更换后所有已登录用户需要重新登录,属正常现象。AdminRouteSecret 更换后,后台入口变为 /admin/{新安全码}。

登录票据还会绑定签发租户并带服务端有效期(TicketLifetime,默认 7 天)。升级到 v2.3.2 后,旧版 v1 票据会被当作未登录处理,需要重新登录一次。多租户部署建议同时配置 Security:AllowedHosts 白名单,避免 Host 头被伪造后切到其他租户。

11. 登录验证码不显示 / 登录失败次数限制不生效?

验证码功能由 EasyAdminBlazor.Captcha 扩展提供:

builder.AddEasyAdminBlazor(new EasyAdminBlazorOptions
{
    EnableLoginCaptcha = true,
    ...
})
    .AddEasyAdminBlazorCaptcha(options =>
    {
        options.Chars = "0123456789";
    });

确认扩展包已安装、EnableLoginCaptcha = true、AddEasyAdminBlazorCaptcha 已调用。

12. 发送邮件失败?

邮件扩展支持两种通道:

  • SMTP:配置 SmtpSettings(Server、Port、Username、Password、FromEmail、EnableSsl)。常见问题:邮箱服务商要求授权码而不是登录密码;587 端口需启用 SSL/TLS
  • SendCloud:配置 SendCloud 节点(ApiUser、ApiKey、SenderEmail、SenderName),配置后优先走 SendCloud

详见扩展集成。

13. 代码生成器里找不到我的实体?

实体类需要满足以下条件:

  • 继承了 EntityFull,或实现了 IEntity<> / 带 [Table] 特性
  • 所在程序集加入了 EasyAdminBlazorOptions.Assemblies

改完代码需要重新编译运行才会被扫描到。

14. 界面语言切换不生效?

在 Program.cs 设置 EnableLocalization = true,并取消注释:

var option = app.Services.GetService<IOptions<RequestLocalizationOptions>>();
if (option != null)
{
    app.UseRequestLocalization(option.Value);
}

15. 页面上的按钮/菜单看不见或没权限?

按钮级权限由「菜单管理」里的按钮配置和「角色管理」里的角色分配共同决定。给角色勾选对应菜单和按钮权限后,刷新页面再看。

16. 模板创建的项目版本比较旧?

模板包和核心包版本可能不同步。用模板建项目后,建议把 NuGet 包升级到最新版,方法见升级指南。


17. 在线升级会不会丢数据、要不要重新登录?

不会。升级只替换程序文件,上传文件、日志、密钥、配置和数据库都不会被写入或删除;某一步失败只回滚该步骤,并保证应用重新拉起,升级完成后用户不需要重新登录(前提是 AesKey 不变,且 Data Protection 密钥目录不被替换——升级默认保护 .aspnet/DataProtection-Keys 与配置的 DataProtectionKeyPath,框架默认把密钥放在内容根目录的 .aspnet/DataProtection-Keys)。IIS 进程内托管(in-process)不支持在线升级,会自动禁用该能力。

18. 生产环境为什么看不到代码生成器?

代码生成器仅在本地开发环境启用,生产环境不暴露生成入口,避免误操作直接改动生产代码或数据库结构。

上线安全自查

正式上线前,至少确认:

  • 确认了后台入口安全码(模板生成的项目是随机码,记录启动日志里的地址即可;自行接入框架的项目已改成自己的随机值)、AesKey 和默认管理员密码
  • UseAutoSyncStructure 已关闭
  • HTTPS 已配置
  • 上传目录写权限正确
  • 数据库已备份