《Chet.Admin 全栈实战》系列第 2 篇前言上一篇我们概览了 Chet.Admin 的整体设计是不是已经跃跃欲试想把它跑起来了这篇就是保姆级启动教程✅ 环境要求一表看懂✅ 后端 3 条命令跑起来✅ 前端 3 条命令跑起来✅ Vite 代理配置详解✅ 默认账号 常见问题排查目标5 分钟内浏览器看到登录页输入账号密码进系统 一、环境要求在动手之前先确认本机装了下面这些工具工具最低版本推荐版本验证命令.NET SDK10.010.0.xdotnet --versionNode.js22.1822.x LTSnode --versionpnpm11.011.7.0pnpm --versionGit2.30最新git --versionIDE可选-VS 2026 / Rider / VSCode-⚠️Node 版本很关键项目package.json里写死了engines.node: ^22.18.0 || ^24.0.0低版本会直接报错。⚠️pnpm 是必须的项目用了preinstall: npx only-allow pnpm用 npm / yarn 会被拦截。安装 pnpm如果还没装 pnpm一行命令搞定# 任选一种npminstall-gpnpm11.7.0# 或corepackenablecorepack prepare pnpm11.7.0--activate数据库不用装默认用SQLite一个文件Chet.Admin.dbEF Core 启动时会自动建库建表 灌种子数据。Redis 也默认关掉了开发环境零依赖。二、拉代码# GitHubgitclone https://github.com/qiect/Chet.Admin.git# 或 Gitee国内更快gitclone https://gitee.com/qiect/Chet.Admin.git项目结构长这样Chet.Admin/ ├── Chet.Admin.Api/ # 后端.NET 10 ├── Chet.Admin.Web/ # 前端Vue3 Vben Admin └── docs/ # 文档前后端是两个独立目录可以分别用不同的 IDE 打开。三、后端启动1. 进入后端目录cdChet.Admin/Chet.Admin.Api2. 还原依赖dotnet restore第一次跑会下载 NuGet 包大概 30 秒到 2 分钟取决于网速。3. 启动后端dotnet run--projectChet.Admin.Api看到这行日志就说明起来了[INF] Application started successfully. Listening on http://localhost:50004. 验证后端打开浏览器访问Swagger 文档http://localhost:5000/swagger根路径http://localhost:5000/会自动重定向到 Swagger后端启动配置说明后端端口在launchSettings.json里配置{profiles:{http:{commandName:Project,applicationUrl:http://localhost:5000;https://localhost:5001;,environmentVariables:{ASPNETCORE_ENVIRONMENT:Development}}}}HTTP 端口5000开发用这个HTTPS 端口5001开发环境不建议用Vite 代理会冲突环境Development数据库自动初始化启动时会自动执行应用迁移MigrateAsync()增量更新 Schema种子数据SeedDataAsync()首次启动灌入2 个部门总公司、技术部2 个角色admin 超管、user 普通用户13 个菜单含按钮权限5 个字典类型 子项2 个默认账号见下文近 7 天模拟登录审计日志让仪表盘有图可看 想重新初始化删掉Chet.Admin.Api/Chet.Admin.Api/Chet.Admin.db文件重启后端即可。四、前端启动1. 进入前端目录cdChet.Admin/Chet.Admin.Web2. 安装依赖pnpminstall⏱ 第一次会装很久Vben Admin 是 Monorepo依赖多大概 2-5 分钟。3. 启动前端pnpmdev:antddev:antd是启动apps/web-antd这个 Ant Design Vue 应用的快捷命令等价于pnpm-Fvben/web-antd run dev启动成功后控制台会显示VITE v7.x.x ready in 800 ms ➜ Local: http://localhost:5666/4. 验证前端浏览器打开http://localhost:5666看到登录页就成功了 五、Vite 代理配置详解前后端要联调靠的是Vite 开发服务器代理。配置在apps/web-antd/vite.config.tsimport{defineConfig}fromvben/vite-config;exportdefaultdefineConfig(async(){return{application:{},vite:{server:{proxy:{/api:{changeOrigin:true,// 后端 API 地址target:http://localhost:5000,ws:true,},// 静态资源上传的文件代理/uploads:{changeOrigin:true,target:http://localhost:5000,},},},},};});代理原理浏览器 Vite Dev Server 后端 │ http://localhost:5666 │ │ │ /api/v1/auth/login ──────▶│ │ │ │ http://localhost:5000 │ │ │ /api/v1/auth/login ──▶│ │ │ │ │ │ ◀── JWT Token ──────│ │ ◀── Response ──────────────│ │前端所有/api/**请求会被转发到http://localhost:5000前端所有/uploads/**请求图片、文件也会转发同源访问没有跨域问题Cookie 也能正常带前端环境变量apps/web-antd/.env.development关键配置# 前端端口VITE_PORT5666# 接口地址前缀VITE_GLOB_API_URL/api/v1# 关闭 Mock 服务VITE_NITRO_MOCKfalse 如果后端端口改了比如改成 6000记得同步改vite.config.ts里的target。六、默认账号种子数据内置了两个账号开箱即用角色邮箱密码权限超级管理员adminexample.comAdmin123所有菜单 所有按钮普通用户userexample.comUser123仅菜单查看无增删改按钮登录后效果对比用admin登录看到所有菜单按钮可点用user登录只看到菜单新增/编辑/删除按钮不会渲染这就是 Chet.Admin 的按钮级权限不是简单的前端隐藏而是后端不返回权限码 前端不渲染。七、CORS 配置可选后端appsettings.json里有 CORS 白名单Cors:{AllowedOrigins:[http://localhost:3000,http://localhost:5173]}⚠️ 注意默认白名单里没有 5666为什么还能跑因为开发环境用的是 Vite 代理同源根本走不到 CORS。如果你前端直连后端不走代理需要加上http://localhost:5666。八、Redis 配置可选默认关闭开发环境不需要Redis:{Enabled:false,ConnectionString:localhost:6379,InstanceName:ChetAdmin:}想启用三步本地装个 RedisDocker 最快docker run -d -p 6379:6379 redis把Enabled改成true重启后端启用后缓存查询走 Redis不启用自动降级到NoOp 缓存每次都查 DB功能不受影响。九、JWT 配置开发环境默认配置appsettings.jsonJwt:{Enabled:true,SecretKey:YourSecretKeyForJWTAuthentication1234567890,Issuer:Chet.Admin,Audience:Chet.Admin,AccessTokenExpirationInMinutes:30,RefreshTokenExpirationDays:7}配置项说明默认值Enabled是否启用 JWTtrueSecretKey签名密钥≥32 字节内置开发密钥Issuer发行者Chet.AdminAudience受众Chet.AdminAccessTokenExpirationInMinutesAccess Token 有效期30 分钟RefreshTokenExpirationDaysRefresh Token 有效期7 天生产环境务必修改 SecretKey这个密钥在 GitHub 上是公开的。十、常见问题排查Q1后端启动报错 “端口被占用”Failed to bind to http://localhost:5000: address already in use解决# 查 5000 端口被谁占了netstat-ano|findstr :5000# 杀掉进程替换 PIDtaskkill /PID12345/F或者改launchSettings.json里的端口同步改前端 vite.config.ts 的 target。Q2前端启动报 “pnpm not found”ERR_PNPM_NOT_FOUND原因没装 pnpm或版本太低。解决# 检查pnpm--version# 没装就装npminstall-gpnpm11.7.0Q3前端pnpm install报 “node version not satisfied”ERR_PNPM_UNSUPPORTED_ENGINE原因Node 版本不够。解决升级到 Node 22 LTS 或 24。node--version# 必须是 v22.18 或 v24推荐用 nvm 或 fnm 管理多版本。Q4前端pnpm install卡住不动原因网络问题Vben Admin 依赖很多。解决换镜像源# .npmrc 文件加上registryhttps://registry.npmmirror.com或者直接pnpmconfigsetregistry https://registry.npmmirror.compnpminstallQ5前端 pnpm workspace 链接报错ERR_PNPM_WORKSPACE_CONFIG_ERROR原因Monorepo 内部包没链接上。解决# 清掉重来pnpmrun cleanpnpminstallclean脚本会删掉所有node_modules和dist然后重新安装。Q6登录提示 “邮箱或密码错误”检查清单✅ 邮箱拼写adminexample.com不是 adminchet.com✅ 密码大小写Admin123A 大写 是 at 符号✅ 数据库有没有种子数据删掉Chet.Admin.db重启后端Q7前端页面空白控制台报 401原因Token 过期或没带。解决清浏览器 localStorage重新登录Q8登录成功但接口都报 500原因数据库没初始化成功。解决# 看后端日志# 找 Initializing database... 后面的报错# 最常见db 文件权限问题# 删掉重启del Chet.Admin.Api\Chet.Admin.Api\Chet.Admin.db dotnet run--projectChet.Admin.ApiQ9Swagger 打不开原因环境不是 Development。解决# 设置环境变量$env:ASPNETCORE_ENVIRONMENTDevelopmentdotnet run--projectChet.Admin.ApiQ10想用 HTTPS后端默认同时监听 HTTP(5000) HTTPS(5001)但开发环境不建议用HTTPSVite 代理配的是http://localhost:5000HTTPS 会触发证书信任问题生产环境用 Nginx 反代 Let’s Encrypt 即可后端不需要自己处理 HTTPS。十一、IDE 推荐配置后端.NETVisual Studio 2026WindowsJetBrains Rider跨平台推荐VSCode C# Dev Kit打开Chet.Admin.Api/Chet.Admin.slnx解决方案文件。前端Vue3VSCode VolarWebStormCursor打开Chet.Admin.Web目录即可IDE 会自动识别 Monorepo。同时开发前后端推荐用VSCode 工作区创建一个.code-workspace文件添加Chet.Admin.Api和Chet.Admin.Web两个文件夹一个窗口搞定十二、开发调试技巧后端热重载dotnetwatchrun--projectChet.Admin.Api改 C# 代码自动重启比dotnet run爽多了。前端热更新pnpm dev:antd默认就开了 HMRHot Module Replacement改 Vue 文件秒级生效。联调后端 API前端请求都带/api/v1前缀比如登录POST http://localhost:5666/api/v1/auth/login实际上经过 Vite 代理转发到POST http://localhost:5000/api/v1/auth/login你可以在后端 Swagger 直接测也可以用 Postman / Apifox 测http://localhost:5000/api/v1/...。查看后端日志日志文件在Chet.Admin.Api/Chet.Admin.Api/logs/log-2026-07-10.txt格式是Serilog Compact JSON方便结构化检索。十三、一键启动脚本可选如果你嫌每次敲两遍命令麻烦可以写个脚本Windows PowerShell# start-dev.ps1Start-Processpowershell-ArgumentList-Command,cd Chet.Admin.Api; dotnet run --project Chet.Admin.ApiStart-Processpowershell-ArgumentList-Command,cd Chet.Admin.Web; pnpm dev:antd或用 concurrently推荐根目录装个工具npminstall-gconcurrently然后concurrentlycd Chet.Admin.Api dotnet run --project Chet.Admin.Apicd Chet.Admin.Web pnpm dev:antd十四、启动检查清单启动完成后对照这张表逐项确认检查项期望结果命令/操作.NET SDK10.0.xdotnet --versionNode.jsv22.18node --versionpnpm11.7pnpm --version后端运行http://localhost:5000/swagger 可访问浏览器打开前端运行http://localhost:5666 可访问浏览器打开数据库文件Chet.Admin.db 存在看后端目录admin 登录成功进仪表盘adminexample.com / Admin123user 登录进系统但无按钮userexample.com / User123全部 ✅ 就说明环境搭好了可以开撸代码了十五、Docker 启动可选项目根目录有Dockerfile和docker-compose.yml也可以用 DockercdChet.Admin.Apidockerbuild-tchet-admin-api.dockerrun-d-p5000:5000 chet-admin-api或者用 composedocker-composeup-d Docker 启动适合演示开发调试还是用本地dotnet runpnpm dev:antd。十六、下一步环境搭好了接下来 第 3 篇项目结构全解析搞懂目录怎么组织的 第 4 篇后端分层架构理解 Clean Architecture 怎么落地 第 5 篇JWT 认证与安全看看双令牌怎么玩互动启动过程中遇到什么坑评论区贴出来我帮你排 GitHubhttps://github.com/qiect/Chet.Admin Giteehttps://gitee.com/qiect/Chet.Admin⭐ 觉得不错的话点个 Star 支持一下吧#ChetAdmin#快速上手#.NET10#Vue3#VbenAdmin#全栈开发