YiShaAdmin部署避坑指南：10分钟修好启动与连接问题

YiShaAdmin部署避坑指南：10分钟修好启动与连接问题

【免费下载链接】YiShaAdmin基于 .NET Core MVC 的权限管理系统，代码易读易懂、界面简洁美观项目地址: https://gitcode.com/GitHub_Trending/yi/YiShaAdmin

大多数人卡在两处：dotnet run一上来就报"找不到运行时"，或者服务起来了、页面却不停闪数据库错误。YiShaAdmin 是一个基于 .NET Core MVC 的权限管理系统，内置员工与部门管理、角色菜单权限、定时任务和代码生成，适合用来快速搭 CMS、CRM、OA 这类管理后台。下面按症状把排查路径拆开，10 分钟内能定位到问题。

📋 部署前的 5 分钟自检

1. SDK 与项目版本匹配——主项目 YiSha.Admin.Web 的目标框架是 netcoreapp3.1，只装了 .NET 6/7 编译必挂。 验证：dotnet --list-sdks（全平台）
2. 数据库服务可连通——MySQL 或 SQL Server 要在运行状态，光装好还不够。 验证：mysql -u root -p -e "SELECT 1;"（Linux/macOS）
3. Provider 与数据库一致——DBProvider 默认是 SqlServer，实际建了 MySQL 就必然连不上。 验证：打开 YiSha.Web/YiSha.Admin.Web/appsettings.json，看 SystemConfig 段
4. 端口空闲——Web 端默认占 5000，WebApi 端默认占 5001。 验证：netstat -ano | findstr :5000（Windows）
5. 依赖包已还原——克隆下来后要先还原一次 NuGet 包再编译。 验证：dotnet restore（全平台）

🔍 按症状分组排查

当 dotnet build 报"找不到运行时"时

最可能的原因是机器 SDK 与项目目标框架不匹配：YiSha.Admin.Web.csproj 里 TargetFramework 写的是 netcoreapp3.1，只装了 .NET 6/7 就必然对不上；另一种常见情况是 restore 那一步其实失败了，被直接跳到了 build，报错只是换了个说法。

快速修复：

1. dotnet --list-sdks确认当前装了哪些版本。
2. 没有 3.1 就安装 .NET Core 3.1 SDK；也可以把仓库切到 Net6 / Net7 分支，与手上已有 SDK 对齐。
3. 先让dotnet restore跑成功，再执行dotnet build。

如果还没好，查三处：NuGet 源是否可达（临时换个源再还原一次）；项目根目录有没有 global.json 锁定了没有装的版本；解决方案里各 csproj 的 TargetFramework 是否同一大版本。

当服务起来了但页面报数据库连接错误时

最可能的原因是 appsettings.json 的 SystemConfig 里 DBProvider 与 DBConnectionString 两个字段不匹配：默认配置连的是名为 YsData 的 SQL Server，实际建了 MySQL（或反过来），连接必然失败。

快速修复：

1. 打开 Web 入口项目下的 appsettings.json，把"DBProvider"改成MySql或SqlServer，与真实数据库一致。
2. 连接串跟着 Provider 一起改，MySQL 的最小配置长这样：

{ "SystemConfig": { "DBProvider": "MySql", "DBConnectionString": "Server=localhost;Port=3306;Database=YsData;Uid=root;Pwd=你的密码;" } }

3. 确认数据库初始化过：数据库初始化脚本按 Provider 分成建表脚本和数据脚本，脚本说明写得很清楚——先删表再建表，别对着已有数据的库直接跑。

连接修好后的首页：左侧是菜单树，中间展示框架介绍与技术选型

如果还没好：先用数据库客户端验证同一条连接串，连不上就是数据库侧的问题；再确认防火墙没拦 3306 或 1433；报错若是"超时"而不是"连不上"，看DBCommandTimeout（默认 180 秒）和慢查询。

当登录成功但菜单为空、列表空白、定时任务不触发时

最可能的原因是初始化数据没导全：只跑了建表脚本没跑数据脚本，菜单和角色表是空的；或者管理员账户没挂上管理员角色。定时任务则要看任务本身的开关——Quartz.NET 调度下，状态不是"启用"就不会写任何执行日志。

快速修复：

1. 用默认账户 admin / 123456 登录，进"系统管理 → 菜单管理"，确认菜单树是否完整。
2. 为空就重新导入对应 Provider 的数据脚本；数据到位后，在"单位组织 → 员工管理"里把管理员角色挂到账户上。
3. 进"系统工具 → 定时任务"，确认任务"启用"开关打开、下次执行时间已生成；任务调度实现在 定时任务模块。

员工管理界面：左侧是组织机构树，右侧是员工列表，可核对账户状态与角色归属

如果还没好：核对服务器系统时间是否正确（调度完全依赖服务器时间）；手动验一遍 Cron 表达式，Quartz 用 6~7 段，和 5 段写法不一样；打开自动任务执行日志看报错文本，判断是任务代码本身的问题。

⚙️ 把开发配置迁到生产环境

缓存换成 Redis 怎么改：SystemConfig 里只动两个字段：

{ "SystemConfig": { "CacheProvider": "Redis", "RedisConnectionString": "127.0.0.1:6379" } }

Memory 缓存在进程重启后清空，登录会话和菜单缓存会一并失效；换 Redis 之后状态可持久，多个应用实例还能共用一份缓存。

连接串加上连接池：

{ "SystemConfig": { "DBConnectionString": "Server=10.0.0.5;Database=YsData;User Id=sa;Password=xxx;Pooling=true;Min Pool Size=5;Max Pool Size=100;" } }

池化的好处是复用已有连接，而不是每个请求都重新建立连接；Min / Max 按实际并发量调，超时时间可以配合DBCommandTimeout一并设置。

多环境配置分开维护：在 appsettings.json 旁边建 appsettings.Production.json 覆盖生产参数，启动时指定环境变量：

export ASPNETCORE_ENVIRONMENT=Production # Linux / macOS set ASPNETCORE_ENVIRONMENT=Production # Windows

框架会按环境自动加载对应配置，切环境不用改主文件，也能避免生产和开发指向同一个库。

📊 一张表看懂环境选型

踩坑复盘与社区求助

• 别把默认连接串当生产配置：仓库里的 sa 密码和本机地址只是示例，部署前确认改过。
• 在跑初始化脚本之前先备份：脚本先删表再建表，对着已有数据的库直接执行，数据就没了。
• 别把端口被占用当项目问题：先用 netstat 查清 5000 / 5001 被哪个进程占着，再决定改端口还是释放端口。
• 在社区提问之前先收集证据：附上dotnet --list-sdks输出、appsettings.json 的 SystemConfig 段和完整报错，大多数"起不来"的问题看到这三样就能回答。

按上面的路径走仍卡住的话，到项目仓库提一个可复现的 Issue，或到官方文档站、社区交流群提问，信息越全响应越快。下一步建议：在仓库根目录执行一次dotnet restore，成功后启动 YiSha.Admin.Web——登录页能显示出来，环境就通了大半。

【免费下载链接】YiShaAdmin基于 .NET Core MVC 的权限管理系统，代码易读易懂、界面简洁美观项目地址: https://gitcode.com/GitHub_Trending/yi/YiShaAdmin