From 2d2182e77536a899cbe2d1f2d399d53a3fcef7a8 Mon Sep 17 00:00:00 2001 From: "821644@qq.com" <821644@qq.com> Date: Mon, 13 Apr 2026 14:06:41 +0800 Subject: [PATCH] =?UTF-8?q?=E6=B7=BB=E5=8A=A0=E5=B1=80=E5=9F=9F=E7=BD=91II?= =?UTF-8?q?S=E9=83=A8=E7=BD=B2=E6=8C=87=E5=8D=97=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/DEPLOYMENT.md | 775 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 775 insertions(+) create mode 100644 docs/DEPLOYMENT.md diff --git a/docs/DEPLOYMENT.md b/docs/DEPLOYMENT.md new file mode 100644 index 0000000..8481cb4 --- /dev/null +++ b/docs/DEPLOYMENT.md @@ -0,0 +1,775 @@ +# 浩景CNC机床数据采集分析系统 - 部署指南 + +## 文档信息 + +| 项目 | 内容 | +|------|------| +| 版本 | v1.0.0 | +| 日期 | 2026-04-13 | +| 部署环境 | Windows Server + IIS + MariaDB | + +--- + +## 目录 + +1. [环境要求](#1-环境要求) +2. [一、安装 .NET 8.0 Runtime](#一安装-net-80-runtime) +3. [二、数据库配置](#二数据库配置) +4. [三、项目发布](#三项目发布) +5. [四、IIS 配置](#四iis-配置) +6. [五、生产配置](#五生产配置) +7. [六、日志配置](#六日志配置) +8. [七、权限配置](#七权限配置) +9. [八、防火墙配置](#八防火墙配置) +10. [九、验证部署](#九验证部署) +11. [十、故障排查](#十故障排查) +12. [部署清单](#部署清单) + +--- + +## 1. 环境要求 + +### 1.1 服务器配置 + +| 项目 | 最低要求 | 推荐配置 | +|------|----------|----------| +| 操作系统 | Windows Server 2016 | Windows Server 2019/2022 | +| CPU | 2 核心 | 4 核心及以上 | +| 内存 | 4 GB | 8 GB 及以上 | +| 磁盘空间 | 50 GB | 100 GB 及以上 | +| .NET Runtime | .NET 8.0 | .NET 8.0 LTS | + +### 1.2 依赖软件 + +| 软件 | 版本 | 用途 | +|------|------|------| +| MariaDB | 10.6+ | 业务库 + 日志库 | +| .NET Runtime | 8.0 | 运行后端 API | +| IIS | 10.0+ | Web 服务 | +| Web Deploy | 3.6+ | 可选,发布工具 | + +### 1.3 网络要求 + +- 服务器固定 IP 地址 +- 端口 5000(API)、8080(Admin)、8081(Dashboard)可用 +- 数据库端口 3306 可访问 + +--- + +## 一、安装 .NET 8.0 Runtime + +### 1.1 下载 .NET 8.0 Hosting Bundle + +访问 Microsoft 官方下载页面: + +``` +https://dotnet.microsoft.com/download/dotnet/8.0 +``` + +下载文件:`dotnet-hosting-8.0.0-win.exe`(或当前最新版本) + +### 1.2 安装步骤 + +1. 以**管理员身份**运行下载的安装程序 +2. 如果提示关闭 IIS,先停止 IIS:`iisreset /stop` +3. 接受许可协议 +4. 等待安装完成 +5. 重启 IIS:`iisreset /start` + +### 1.3 验证安装 + +打开 PowerShell,执行: + +```powershell +dotnet --list-runtimes +``` + +确认输出包含 `Microsoft.AspNetCore.App 8.0.x` + +### 1.4 常见问题 + +- **安装失败**:确保以管理员身份运行,关闭杀毒软件 +- **IIS 检测失败**:先安装 IIS,再安装 Hosting Bundle + +--- + +## 二、数据库配置 + +### 2.1 连接 MariaDB + +```powershell +mysql -u root -p +``` + +### 2.2 创建数据库和用户 + +```sql +-- 创建专用数据库用户(密码请使用强密码) +CREATE USER 'haoliang'@'localhost' IDENTIFIED BY 'YourStrongPassword123!'; +CREATE USER 'haoliang'@'127.0.0.1' IDENTIFIED BY 'YourStrongPassword123!'; + +-- 创建业务库 +CREATE DATABASE cnc_business CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci; + +-- 创建日志库 +CREATE DATABASE cnc_log CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci; + +-- 授权 +GRANT ALL PRIVILEGES ON cnc_business.* TO 'haoliang'@'localhost'; +GRANT ALL PRIVILEGES ON cnc_log.* TO 'haoliang'@'localhost'; + +FLUSH PRIVILEGES; + +-- 验证 +SHOW GRANTS FOR 'haoliang'@'localhost'; +``` + +### 2.3 导入数据库结构 + +```powershell +# 进入项目数据库脚本目录 +cd C:\path\to\haoliang\database + +# 导入业务库 +mysql -u haoliang -p cnc_business < cnc_business.sql + +# 导入日志库 +mysql -u haoliang -p cnc_log < cnc_log.sql + +# 验证表结构 +mysql -u haoliang -p -e "USE cnc_business; SHOW TABLES;" +``` + +### 2.4 验证数据库连接 + +```powershell +mysql -u haoliang -p -e "SELECT 1 AS Test;" +``` + +--- + +## 三、项目发布 + +### 3.1 构建后端 + +```powershell +# 进入项目根目录 +cd C:\path\to\haoliang + +# 清理并发布后端(Release 模式) +dotnet clean Haoliang.sln -c Release +dotnet publish Haoliang.Api/Haoliang.Api.csproj -c Release -o .\publish\api --self-contained false + +# 发布后目录结构 +# C:\path\to\haoliang\publish\api\ +``` + +### 3.2 构建前端 Admin + +```powershell +# 进入 Admin 目录 +cd C:\path\to\haoliang\src\frontend\admin + +# 安装依赖(如已有 node_modules 可跳过) +npm install + +# 构建生产版本 +npm run build +``` + +构建完成后,输出在 `dist` 目录。 + +### 3.3 构建前端 Dashboard + +```powershell +# 进入 Dashboard 目录 +cd C:\path\to\haoliang\src\frontend\dashboard + +# 安装依赖 +npm install + +# 构建生产版本 +npm run build +``` + +### 3.4 创建部署目录 + +```powershell +# 创建部署根目录 +New-Item -ItemType Directory -Path "C:\inetpub\haoliang\api" -Force +New-Item -ItemType Directory -Path "C:\inetpub\haoliang\admin" -Force +New-Item -ItemType Directory -Path "C:\inetpub\haoliang\dashboard" -Force +New-Item -ItemType Directory -Path "C:\inetpub\haoliang\api\logs" -Force +New-Item -ItemType Directory -Path "C:\inetpub\haoliang\api\data" -Force + +# 复制文件 +Copy-Item -Path "C:\path\to\haoliang\publish\api\*" -Destination "C:\inetpub\haoliang\api\" -Recurse +Copy-Item -Path "C:\path\to\haoliang\src\frontend\admin\dist\*" -Destination "C:\inetpub\haoliang\admin\" -Recurse +Copy-Item -Path "C:\path\to\haoliang\src\frontend\dashboard\dist\*" -Destination "C:\inetpub\haoliang\dashboard\" -Recurse +``` + +### 3.5 最终目录结构 + +``` +C:\inetpub\haoliang\ +├── api\ +│ ├── wwwroot\ +│ ├── appsettings.json +│ ├── Haoliang.Api.dll +│ ├── Haoliang.Api.exe +│ ├── logs\ # 日志目录 +│ ├── data\ # 数据目录 +│ └── web.config +├── admin\ +│ ├── index.html +│ ├── assets\ +│ └── ... +└── dashboard\ + ├── index.html + ├── assets\ + └── ... +``` + +--- + +## 四、IIS 配置 + +### 4.1 创建应用程序池 + +**方式一:IIS 管理器** + +1. 打开 **Internet Information Services (IIS) 管理器** +2. 右键 **应用程序池** → **添加应用程序池** +3. 配置: + +| 配置项 | 值 | +|--------|-----| +| 名称 | `HaoliangApi` | +| .NET CLR 版本 | **无托管代码** | +| 托管管道模式 | **集成** | +| 立即启动应用程序池 | ✓ | + +**方式二:PowerShell** + +```powershell +New-WebAppPool -Name "HaoliangApi" +Set-ItemProperty -Path "IIS:\AppPools\HaoliangApi" -Name "managedRuntimeVersion" -Value "" +Set-ItemProperty -Path "IIS:\AppPools\HaoliangApi" -Name "managedPipelineMode" -Value "Integrated" +``` + +### 4.2 创建网站 + +**方式一:IIS 管理器** + +1. 右键 **网站** → **添加网站** +2. 配置: + +| 配置项 | 值 | +|--------|-----| +| 网站名称 | `HaoliangApi` | +| 物理路径 | `C:\inetpub\haoliang\api` | +| 绑定类型 | HTTP | +| 端口 | `5000` | +| 应用程序池 | `HaoliangApi` | + +**方式二:PowerShell** + +```powershell +New-WebSite -Name "HaoliangApi" -PhysicalPath "C:\inetpub\haoliang\api" -Port 5000 -ApplicationPool "HaoliangApi" +``` + +### 4.3 创建子应用程序 + +```powershell +# 创建 Admin 子应用 +New-WebApplication -Name "admin" -Site "HaoliangApi" -PhysicalPath "C:\inetpub\haoliang\admin" -ApplicationPool "HaoliangApi" + +# 创建 Dashboard 子应用 +New-WebApplication -Name "dashboard" -Site "HaoliangApi" -PhysicalPath "C:\inetpub\haoliang\dashboard" -ApplicationPool "HaoliangApi" + +# 验证 +Get-WebApplication -Site "HaoliangApi" +``` + +### 4.4 应用程序池高级设置 + +1. 选择 **HaoliangApi** 应用程序池 +2. 右键 → **高级设置** +3. 配置: + +| 配置项 | 推荐值 | 说明 | +|--------|--------|------| +| 回收间隔(分钟) | `1740` | 每天凌晨回收一次 | +| 虚拟内存限制(MB) | `0` | 无限制 | +| 专用内存限制(KB) | `0` | 无限制 | +| 启动模式 | `OnDemand` | 按需启动 | +| 最小工作进程数 | `1` | - | + +### 4.5 创建 web.config + +在 `C:\inetpub\haoliang\api\web.config`(如不存在): + +```xml + + + + + + + + + + + + + + + + + + + + + +``` + +--- + +## 五、生产配置 + +### 5.1 创建生产配置文件 + +创建 `C:\inetpub\haoliang\api\appsettings.Production.json`: + +```json +{ + "ConnectionStrings": { + "CNCBusinessDB": "Server=localhost;Database=cnc_business;User=haoliang;Password=YourStrongPassword123!;CharSet=utf8mb4;", + "CNCLLogDB": "Server=localhost;Database=cnc_log;User=haoliang;Password=YourStrongPassword123!;CharSet=utf8mb4;" + }, + "Logging": { + "LogLevel": { + "Default": "Information", + "Microsoft.AspNetCore": "Warning", + "Microsoft.EntityFrameworkCore": "Warning" + } + }, + "AppSettings": { + "ApiVersion": "v1", + "EnableSwagger": false, + "EnableCors": true, + "AllowedOrigins": [ + "http://localhost:5000", + "http://localhost:8080", + "http://localhost:8081", + "http://192.168.1.100:5000", + "http://192.168.1.100:8080", + "http://192.168.1.100:8081" + ], + "DefaultCacheDuration": 300, + "MaxConcurrentCollections": 100 + }, + "CollectionSettings": { + "DefaultInterval": 30, + "MaxRetryCount": 3, + "RetryInterval": 30, + "PingTimeout": 5000, + "CollectionTimeout": 10000 + } +} +``` + +### 5.2 设置环境变量 + +```powershell +# 设置环境变量 +Set-ItemProperty -Path "IIS:\AppPools\HaoliangApi" -Name "environmentVariables" -Value @( + @{ name="ASPNETCORE_ENVIRONMENT"; value="Production" } +) + +# 验证 +Get-ItemProperty -Path "IIS:\AppPools\HaoliangApi" -Name "environmentVariables" + +# 重启应用程序池 +Restart-WebAppPool -Name "HaoliangApi" +``` + +### 5.3 修改 CORS 配置(可选) + +如果需要更严格的 CORS,在 `Startup.cs` 中修改: + +```csharp +services.AddCors(options => +{ + options.AddPolicy("AllowConfiguredOrigins", builder => + { + var allowedOrigins = Configuration.GetSection("AppSettings:AllowedOrigins").Get(); + builder.WithOrigins(allowedOrigins) + .AllowAnyMethod() + .AllowAnyHeader() + .AllowCredentials(); + }); +}); +``` + +--- + +## 六、日志配置 + +### 6.1 目录权限 + +```powershell +# 设置日志目录权限 +icacls "C:\inetpub\haoliang\api\logs" /grant "IIS AppPool\HaoliangApi:(OI)(CI)M" +icacls "C:\inetpub\haoliang\api\data" /grant "IIS AppPool\HaoliangApi:(OI)(CI)M" + +# 验证权限 +icacls "C:\inetpub\haoliang\api\logs" +``` + +### 6.2 Serilog 配置说明 + +当前配置(Program.cs)已包含: + +```csharp +.WriteTo.File("logs/app.log", + rollingInterval: RollingInterval.Day, + retainedFileCountLimit: 30, + fileSizeLimitBytes: 104857600) // 100MB +``` + +- 日志路径:`C:\inetpub\haoliang\api\logs\app-{Date}.log` +- 保留天数:30 天 +- 单文件大小限制:100MB + +### 6.3 日志查看 + +```powershell +# 查看最新日志 +Get-Content "C:\inetpub\haoliang\api\logs\app-20260413.log" -Tail 50 + +# 实时跟踪日志 +Get-Content "C:\inetpub\haoliang\api\logs\app-20260413.log" -Wait -Tail 10 +``` + +--- + +## 七、权限配置 + +### 7.1 目录权限 + +```powershell +# API 目录 - 完全控制 +icacls "C:\inetpub\haoliang\api" /grant "IIS AppPool\HaoliangApi:(OI)(CI)M" +icacls "C:\inetpub\haoliang\api" /grant "IIS_IUSRS:(OI)(CI)RX" + +# 前端目录 - 只读 +icacls "C:\inetpub\haoliang\admin" /grant "IIS_IUSRS:(OI)(CI)RX" +icacls "C:\inetpub\haoliang\dashboard" /grant "IIS_IUSRS:(OI)(CI)RX" +``` + +### 7.2 IIS 管理器权限配置 + +1. 右键网站 **HaoliangApi** → **编辑权限** +2. 安全标签页 → 编辑 → 添加: + +| 用户/组 | 权限 | +|---------|------| +| `IIS_IUSRS` | 读取 | +| `IUSR` | 读取 | +| `IIS AppPool\HaoliangApi` | 读取/写入 | + +--- + +## 八、防火墙配置 + +### 8.1 Windows 防火墙规则 + +```powershell +# 开放 API 端口 (5000) +New-NetFirewallRule -DisplayName "Haoliang API" ` + -Direction Inbound -Protocol TCP ` + -LocalPort 5000 -Action Allow ` + -Profile Any + +# 开放 Admin 端口 (8080) +New-NetFirewallRule -DisplayName "Haoliang Admin" ` + -Direction Inbound -Protocol TCP ` + -LocalPort 8080 -Action Allow ` + -Profile Any + +# 开放 Dashboard 端口 (8081) +New-NetFirewallRule -DisplayName "Haoliang Dashboard" ` + -Direction Inbound -Protocol TCP ` + -LocalPort 8081 -Action Allow ` + -Profile Any + +# 验证规则 +Get-NetFirewallRule | Where-Object {$_.DisplayName -like "Haoliang*"} +``` + +### 8.2 端口检查 + +```powershell +# 检查端口占用 +netstat -an | findstr ":5000 :8080 :8081" + +# 测试端口连通性 +Test-NetConnection -ComputerName localhost -Port 5000 +``` + +--- + +## 九、验证部署 + +### 9.1 启动服务 + +```powershell +# 启动 IIS +iisreset /start + +# 启动应用程序池 +Start-WebAppPool -Name "HaoliangApi" + +# 启动网站 +Start-WebSite -HaoliangApi +``` + +### 9.2 健康检查 + +浏览器或 curl 访问: + +```powershell +# API 健康检查 +curl http://localhost:5000/api/v1/health + +# 预期返回示例 +# {"status":"healthy","timestamp":"2026-04-13T00:00:00Z"} +``` + +### 9.3 验证目录访问 + +| URL | 预期结果 | +|-----|----------| +| `http://localhost:5000/` | 返回 API 根信息或 404 | +| `http://localhost:5000/api/v1/devices` | 返回设备列表 JSON | +| `http://localhost:5000/admin/` | 返回 Admin 管理后台首页 | +| `http://localhost:5000/dashboard/` | 返回 Dashboard 大屏首页 | +| `http://localhost:5000/swagger` | 生产环境返回 404(正常) | + +### 9.4 查看实时日志 + +```powershell +# 跟踪日志 +Get-Content "C:\inetpub\haoliang\api\logs\stdout_*" -Wait -Tail 20 +``` + +--- + +## 十、故障排查 + +### 10.1 常见错误及解决方案 + +| 错误代码 | 可能原因 | 解决方案 | +|----------|----------|----------| +| `500.19` | web.config 语法错误 | 检查 web.config 文件 | +| `500.21` | 模块未正确安装 | 重新安装 .NET Hosting Bundle | +| `502.5` | 应用程序启动失败 | 检查 .NET Runtime、查看 stdout 日志 | +| `502.3` | 应用程序池错误 | 检查环境变量配置 | +| `503.0` | 应用程序池未启动 | 启动应用程序池 | +| `404.0` | 文件不存在 | 检查物理路径配置 | + +### 10.2 日志分析方法 + +```powershell +# 查看应用程序池错误 +Get-Content "C:\inetpub\haoliang\api\logs\stdout_*.log" | Select-String "Error" + +# 查看最近 100 行 +Get-Content "C:\inetpub\haoliang\api\logs\app-20260413.log" -Tail 100 +``` + +### 10.3 数据库连接问题 + +```powershell +# 测试数据库连接 +mysql -u haoliang -p -e "USE cnc_business; SELECT COUNT(*) FROM Devices;" + +# 检查连接字符串 +# 确保 Server=localhost;Port=3306; +``` + +### 10.4 权限问题 + +```powershell +# 重置权限 +icacls "C:\inetpub\haoliang\api" /reset + +# 重新设置 +icacls "C:\inetpub\haoliang\api" /grant "IIS AppPool\HaoliangApi:(OI)(CI)M" /T +``` + +--- + +## 部署清单 + +### 部署前检查 + +``` +[ ] Windows Server 已安装并激活 +[ ] 服务器 IP 地址已固定 +[ ] 所有依赖软件版本确认 +[ ] 部署脚本和文件已准备 +``` + +### 环境安装 + +``` +[ ] .NET 8.0 Hosting Bundle 已安装 +[ ] IIS 已安装并启动 +[ ] MariaDB 已安装并启动 +[ ] 所有端口(3306/5000/8080/8081)可用 +``` + +### 数据库配置 + +``` +[ ] 数据库用户 haoliang 已创建 +[ ] 业务库 cnc_business 已创建 +[ ] 日志库 cnc_log 已创建 +[ ] 数据库脚本已导入 +[ ] 数据库连接测试通过 +``` + +### 文件部署 + +``` +[ ] API 文件已复制到 C:\inetpub\haoliang\api +[ ] Admin 文件已复制到 C:\inetpub\haoliang\admin +[ ] Dashboard 文件已复制到 C:\inetpub\haoliang\dashboard +[ ] 日志目录已创建 +[ ] web.config 已配置 +``` + +### IIS 配置 + +``` +[ ] 应用程序池 HaoliangApi 已创建 +[ ] 网站 HaoliangApi 已创建并绑定端口 5000 +[ ] Admin 子应用已创建 +[ ] Dashboard 子应用已创建 +[ ] 应用程序池高级设置已配置 +``` + +### 权限配置 + +``` +[ ] API 目录权限已设置 +[ ] 前端目录权限已设置 +[ ] 日志目录写入权限已设置 +[ ] IIS_IUSRS 读取权限已设置 +``` + +### 生产配置 + +``` +[ ] appsettings.Production.json 已创建 +[ ] 数据库连接字符串已配置 +[ ] CORS 源已配置 +[ ] 环境变量 ASPNETCORE_ENVIRONMENT=Production 已设置 +``` + +### 防火墙配置 + +``` +[ ] 端口 5000 防火墙规则已创建 +[ ] 端口 8080 防火墙规则已创建 +[ ] 端口 8081 防火墙规则已创建 +``` + +### 验证测试 + +``` +[ ] IIS 服务已启动 +[ ] 应用程序池已启动 +[ ] API 健康检查通过 +[ ] Admin 页面可访问 +[ ] Dashboard 页面可访问 +[ ] 日志正常写入 +``` + +--- + +## 附录 + +### A. 常用 PowerShell 命令 + +```powershell +# IIS 管理 +iisreset /start # 启动 IIS +iisreset /stop # 停止 IIS +iisreset /restart # 重启 IIS + +# 应用程序池 +Start-WebAppPool -Name "HaoliangApi" +Stop-WebAppPool -Name "HaoliangApi" +Restart-WebAppPool -Name "HaoliangApi" + +# 网站 +Start-WebSite -Name "HaoliangApi" +Stop-WebSite -Name "HaoliangApi" + +# 查看配置 +Get-WebBinding -Name "HaoliangApi" +Get-WebApplication -Site "HaoliangApi" +``` + +### B. 快速重启脚本 + +创建 `restart.ps1`: + +```powershell +# 停止 +Stop-WebSite -Name "HaoliangApi" +Stop-WebAppPool -Name "HaoliangApi" + +Start-Sleep -Seconds 2 + +# 启动 +Start-WebAppPool -Name "HaoliangApi" +Start-WebSite -Name "HaoliangApi" + +Write-Host "Haoliang API restarted successfully." +``` + +### C. 备份配置 + +```powershell +# 备份配置文件 +Copy-Item "C:\inetpub\haoliang\api\appsettings.Production.json" ` + "C:\Backup\appsettings.Production.json.$(Get-Date -Format 'yyyyMMdd')" -Force + +# 备份网站配置 +%windir%\system32\inetsrv\appcmd list site "HaoliangApi" > "C:\Backup\site_config.txt" +``` + +--- + +## 联系方式 + +如有问题,请检查: +1. 日志文件:`C:\inetpub\haoliang\api\logs\` +2. Windows 事件查看器 +3. IIS 管理器连接测试 + +--- + +*文档最后更新:2026-04-13*