部署上线

本文介绍 EasyAdminBlazor 项目发布到生产环境的完整流程，重点覆盖 Nginx 反向代理（Blazor Server 必须配置 WebSocket）、HTTPS、Windows 部署和上线检查清单。

1. 发布项目

在项目根目录执行：

dotnet publish -c Release -o publish

把 publish 目录整体拷贝到服务器即可。发布物包含运行时文件，服务器不需要再装 .NET SDK，但需要安装对应的 .NET 10 Runtime（Windows 上 IIS 部署还要装 ASP.NET Core Hosting Bundle）。

2. 生产环境配置

环境变量

设置 ASPNETCORE_ENVIRONMENT=Production，框架会读取 appsettings.Production.json 覆盖开发配置。

数据库与自动建表

开发时 UseAutoSyncStructure(true) 会自动同步表结构，生产环境建议改为 false，避免程序启动时意外改动生产库结构
首次上线可以先在开发库把结构同步好，再发布；确需自动建表时，临时开启、跑通后关闭
MySQL 连接串建议带 Charset=utf8mb4，避免中文乱码
数据库密码不要写进仓库，用环境变量或密钥管理服务覆盖

密钥与安全

修改 AdminRouteSecret：这是后台入口的安全码，上线前必须换成自己的值
修改 AesKey：用于 Cookie 等加密，上线前必须更换（更换后已登录用户会失效，属正常现象）
修改默认管理员密码：模板默认 admin / 123yyq，上线后第一时间改掉

3. Nginx 反向代理（推荐）

Blazor Server 依赖 WebSocket 长连接，Nginx 必须配置 Upgrade 请求头，否则页面会频繁断线重连：

server {
    listen 80;
    server_name admin.example.com;

    location / {
        proxy_pass http://127.0.0.1:5207;   # 端口换成项目实际监听端口
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_read_timeout 3600s;            # Blazor Server 长连接，避免空闲断开
    }
}

要点：

Program.cs 里已经内置了 app.UseForwardedHeaders，Nginx 把 X-Forwarded-Proto 转发过来后，HTTPS 下的回调地址、登录跳转才正确
证书建议用 Let's Encrypt（certbot）或云厂商证书，把 80 端口 301 重定向到 443
多租户按域名识别租户，反向代理必须透传原始 Host，否则所有请求都会被当成同一个租户

4. Windows 上部署

IIS

安装 ASP.NET Core Hosting Bundle
启用 IIS 的 WebSocket 协议（Blazor Server 依赖 WebSocket 长连接，不启用会导致后台页面反复重连/刷新）：
- Windows Server：服务器管理器 → 添加角色和功能 → Web 服务器(IIS) → 应用程序开发 → 勾选“WebSocket 协议”；或在管理员 PowerShell 中执行 Install-WindowsFeature Web-WebSockets
- Windows 客户端/独立 IIS：控制面板 → 启用或关闭 Windows 功能 → IIS → 万维网服务 → 应用程序开发功能 → 勾选“WebSocket 协议”
- 安装完成后执行 iisreset，并重启应用程序池
站点物理路径指向 publish 目录
应用程序池选择“无托管代码”
给 wwwroot/uploads 目录配置写权限

Windows 服务

用 NSSM 或 winsw 把 dotnet YourApp.dll 注册成 Windows 服务，开机自启、崩溃自动拉起。给服务账号配置上传目录的写权限。

5. 上线检查清单

6. 常见坑

页面反复断线重连：基本是 Nginx 没配 Upgrade/Connection 头，或 proxy_read_timeout 太短
IIS 下后台页面反复刷新/重连：IIS 未启用 WebSocket 协议（见上文 IIS 安装步骤）
登录后跳转变成 http：反向代理没转发 X-Forwarded-Proto，或 UseForwardedHeaders 没生效
上传文件失败：检查 wwwroot/uploads 写权限和 FileSettings 配置
启动报数据库错误：生产连接串没生效，确认环境变量名与 appsettings.Production.json 对应
后台 404：AdminRouteSecret 改了，要访问 /admin/{新安全码}