常见问题

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

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

后台入口是 /admin/{AdminRouteSecret}。默认配置下访问：

http://localhost:端口/admin/i4ByMAX4

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

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

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

3. 打开 /Admin 返回 404？

说明没带 AdminRouteSecret 对应的安全 Cookie。请先访问 /admin/{AdminRouteSecret}（带安全码的地址），而不是直接访问 /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 用于加密 Cookie 等数据，更换后所有已登录用户需要重新登录，属正常现象。AdminRouteSecret 更换后，后台入口变为 /admin/{新安全码}。

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 包升级到最新版，方法见升级指南。

---

上线安全自查

正式上线前，至少确认：

• 修改了 AdminRouteSecret、AesKey 和默认管理员密码
• UseAutoSyncStructure 已关闭
• HTTPS 已配置
• 上传目录写权限正确
• 数据库已备份