haoliang/docs/DEPLOYMENT.md

# 浩景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_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 验证数据库连接

```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
<?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`：

```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<string[]>();
        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*