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*