haoliang/docs/DEPLOYMENT.md

浩景CNC机床数据采集分析系统 - 部署指南

文档信息

项目	内容
版本	v1.0.0
日期	2026-04-13
部署环境	Windows Server + IIS + MariaDB

---

目录

1. 环境要求
2. 一、安装 .NET 8.0 Runtime
3. 二、数据库配置
4. 三、项目发布
5. 四、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，执行：

dotnet --list-runtimes

确认输出包含 Microsoft.AspNetCore.App 8.0.x

1.4 常见问题

• 安装失败：确保以管理员身份运行，关闭杀毒软件
• IIS 检测失败：先安装 IIS，再安装 Hosting Bundle

---

二、数据库配置

2.1 连接 MariaDB

mysql -u root -p

2.2 创建数据库和用户

-- 创建专用数据库用户（密码请使用强密码）
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 导入数据库结构

# 进入项目数据库脚本目录
cd C:\path\to\haoliang\database

# 导入业务库
mysql -u haoliang -p cnc_business < cnc_business.sql

# 导入日志库（使用修复版本，修正了视图定义问题）
mysql -u haoliang -p cnc_log < cnc_log_fixed.sql

# 验证表结构
mysql -u haoliang -p -e "USE cnc_business; SHOW TABLES;"
mysql -u haoliang -p -e "USE cnc_log; SHOW TABLES;"

注意：cnc_log_fixed.sql 是修正版本，修复了原 cnc_log.sql 中视图定义引用不存在表的问题。

2.4 验证数据库连接

mysql -u haoliang -p -e "SELECT 1 AS Test;"

---

三、项目发布

3.1 构建后端

# 进入项目根目录
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

# 进入 Admin 目录
cd C:\path\to\haoliang\src\frontend\admin

# 安装依赖（如已有 node_modules 可跳过）
npm install

# 构建生产版本
npm run build

构建完成后，输出在 dist 目录。

3.3 构建前端 Dashboard

# 进入 Dashboard 目录
cd C:\path\to\haoliang\src\frontend\dashboard

# 安装依赖
npm install

# 构建生产版本
npm run build

3.4 创建部署目录

# 创建部署根目录
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

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

New-WebSite -Name "HaoliangApi" -PhysicalPath "C:\inetpub\haoliang\api" -Port 5000 -ApplicationPool "HaoliangApi"

4.3 创建子应用程序

# 创建 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 version="1.0" encoding="utf-8"?>
<configuration>
  <location path="." inheritInChildApplications="false">
    <system.webServer>
      <handlers>
        <add name="aspNetCore" path="*" verb="*"
             modules="AspNetCoreModuleV2"
             resourceType="Unspecified" />
      </handlers>
      <aspNetCore processPath="dotnet"
                  arguments=".\Haoliang.Api.dll"
                  stdoutLogEnabled="true"
                  stdoutLogFile=".\logs\stdout"
                  hostingModel="inprocess">
        <environmentVariables>
          <environmentVariable name="ASPNETCORE_ENVIRONMENT"
                              value="Production" />
          <environmentVariable name="ASPNETCORE_DETAILED_ERRORS"
                              value="false" />
        </environmentVariables>
      </aspNetCore>
      <httpErrors existingResponse="PassThrough" />
      <modules runAllManagedModulesForAllRequests="false">
        <remove name="WebSockets" />
        <add name="WebSockets" module="WebSocketsModule" />
      </modules>
    </system.webServer>
  </location>
</configuration>

---

五、生产配置

5.1 创建生产配置文件

创建 C:\inetpub\haoliang\api\appsettings.Production.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 设置环境变量

# 设置环境变量
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 中修改：

services.AddCors(options =>
{
    options.AddPolicy("AllowConfiguredOrigins", builder =>
    {
        var allowedOrigins = Configuration.GetSection("AppSettings:AllowedOrigins").Get<string[]>();
        builder.WithOrigins(allowedOrigins)
               .AllowAnyMethod()
               .AllowAnyHeader()
               .AllowCredentials();
    });
});

---

六、日志配置

6.1 目录权限

# 设置日志目录权限
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）已包含：

.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 日志查看

# 查看最新日志
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 目录权限

# 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 防火墙规则

# 开放 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 端口检查

# 检查端口占用
netstat -an | findstr ":5000 :8080 :8081"

# 测试端口连通性
Test-NetConnection -ComputerName localhost -Port 5000

---

九、验证部署

9.1 启动服务

# 启动 IIS
iisreset /start

# 启动应用程序池
Start-WebAppPool -Name "HaoliangApi"

# 启动网站
Start-WebSite -HaoliangApi

9.2 健康检查

浏览器或 curl 访问：

# 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 查看实时日志

# 跟踪日志
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 日志分析方法

# 查看应用程序池错误
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 数据库连接问题

# 测试数据库连接
mysql -u haoliang -p -e "USE cnc_business; SELECT COUNT(*) FROM Devices;"

# 检查连接字符串
# 确保 Server=localhost;Port=3306;

10.4 权限问题

# 重置权限
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 命令

# 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：

# 停止
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. 备份配置

# 备份配置文件
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