ZR.Admin.NET + Vue3实战：从本地开发到Nginx部署的完整避坑指南
ZR.Admin.NET + Vue3实战：从本地开发到Nginx部署的完整避坑指南
当你成功在本地运行了ZR.Admin.NET后台管理系统后，下一步就是将其部署到生产环境。本文将带你从本地开发环境出发，一步步完成前端Vue3项目打包、后端.NET WebApi发布、Nginx配置等关键步骤，并解决部署过程中可能遇到的各种"坑"。
1. 前端Vue3项目打包配置
前端项目的打包配置直接影响最终部署的效果。ZR.Admin.NET的前端基于Vue3，我们需要针对不同环境进行差异化配置。
1.1 环境变量配置
在项目根目录下创建或修改以下文件：
.env.development # 开发环境 .env.test # 测试环境 .env.production # 生产环境每个文件应包含类似以下内容：
# .env.production NODE_ENV=production VUE_APP_BASE_API=/prod-api/ VUE_APP_WS_API=/msgHub1.2 多环境打包脚本
在package.json中添加或修改scripts部分：
{ "scripts": { "dev": "vue-cli-service serve", "build:test": "vue-cli-service build --mode test", "build:prod": "vue-cli-service build --mode production", "preview": "serve -s dist" } }1.3 常见打包问题解决
- 静态资源路径错误：在vue.config.js中配置publicPath
module.exports = { publicPath: process.env.NODE_ENV === 'production' ? '/' : '/', assetsDir: 'static', indexPath: 'index.html' }- 路由History模式问题：确保router配置正确
const router = createRouter({ history: createWebHistory(process.env.BASE_URL), routes })2. 后端.NET WebApi发布
2.1 Windows服务器发布
- 在Visual Studio中右键项目 → 发布
- 选择"文件夹"作为发布目标
- 配置发布设置：
- 配置：Release
- 目标框架：net7.0或更高
- 部署模式：框架依赖
- 目标运行时：win-x64
2.2 Linux服务器发布
对于Linux环境，建议使用以下命令发布：
dotnet publish -c Release -r linux-x64 --self-contained false发布完成后，将publish文件夹上传到服务器。
2.3 守护进程配置
在Linux上，使用Supervisor守护进程：
[program:zradmin] command=dotnet ZR.Admin.WebApi.dll --urls "http://*:8888" directory=/var/www/zradmin autostart=true autorestart=true stderr_logfile=/var/log/zradmin.err.log stdout_logfile=/var/log/zradmin.out.log environment=ASPNETCORE_ENVIRONMENT=Production user=www-data stopsignal=INT3. Nginx配置详解
3.1 基础反向代理配置
server { listen 80; server_name yourdomain.com; # 前端静态文件 location / { root /var/www/zradmin/dist; index index.html; try_files $uri $uri/ /index.html; } # 后端API代理 location /prod-api/ { proxy_pass http://localhost:8888/; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; } }3.2 WebSocket(SignalR)代理
location ~* ^/msgHub { proxy_pass http://localhost:8888; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "upgrade"; }3.3 HTTPS配置
server { listen 443 ssl; server_name yourdomain.com; ssl_certificate /path/to/cert.pem; ssl_certificate_key /path/to/key.pem; # 其他配置同上... # 强制HTTPS if ($scheme = http) { return 301 https://$server_name$request_uri; } }4. 部署常见问题解决方案
4.1 跨域问题
虽然Nginx反向代理可以解决大部分跨域问题，但有时仍需要在后端配置：
// Startup.cs services.AddCors(options => { options.AddPolicy("AllowAll", builder => { builder.AllowAnyOrigin() .AllowAnyMethod() .AllowAnyHeader(); }); }); // 在Configure方法中 app.UseCors("AllowAll");4.2 静态资源404
检查以下配置：
- Nginx的root路径是否正确
- Vue打包后的dist文件夹权限
- 确保vue.config.js中的publicPath配置正确
4.3 数据库连接问题
生产环境数据库连接字符串通常需要修改：
{ "dbConfigs": [ { "Conn": "Server=prod-db.example.com;Database=ZrAdmin;User Id=admin;Password=yourStrongPassword;", "DbType": 1, "ConfigId": "0", "IsAutoCloseConnection": true } ] }4.4 性能优化建议
前端优化：
- 启用gzip压缩
- 使用CDN分发静态资源
- 开启HTTP/2
后端优化：
- 使用JIT编译
- 配置响应缓存
- 优化数据库查询
# 启用gzip gzip on; gzip_types text/plain text/css application/json application/javascript text/xml application/xml application/xml+rss text/javascript;5. 监控与维护
5.1 日志配置
在appsettings.Production.json中配置日志：
{ "Logging": { "LogLevel": { "Default": "Information", "Microsoft": "Warning", "Microsoft.Hosting.Lifetime": "Information" }, "File": { "Path": "logs/log.txt", "FileSizeLimitBytes": 10485760, "RetainedFileCountLimit": 5 } } }5.2 健康检查
添加健康检查端点：
services.AddHealthChecks() .AddSqlServer(Configuration["dbConfigs:0:Conn"]) .AddDbContextCheck<YourDbContext>(); app.UseEndpoints(endpoints => { endpoints.MapHealthChecks("/health"); });5.3 备份策略
建议设置以下备份计划：
- 数据库每日全量备份
- 应用程序每周备份
- 配置文件变更即时备份
对于Linux服务器，可以使用crontab设置自动备份：
# 每天凌晨2点备份数据库 0 2 * * * /usr/bin/mysqldump -u admin -p'password' ZrAdmin > /backups/ZrAdmin_$(date +\%Y\%m\%d).sql