aiot-platform-ui/scripts/deploy/README.md

# 本地构建+自动部署方案

## 📋 快速参考

| 操作 | 是否触发 CI/CD | 说明 |
|------|---------------|------|
| 修改源码 | ❌ 否 | 需要先本地构建，再推送 dist |
| 推送 dist 目录 | ✅ 是 | 自动触发部署 |
| 修改 nginx.conf | ✅ 是 | 自动触发部署 |
| 修改 Dockerfile.deploy | ✅ 是 | 自动触发部署 |

**快速部署命令**：
```bash
./scripts/deploy/build-and-push.sh
```

## 方案说明

本方案采用**本地构建 + 服务器部署**的方式，避免在服务器上进行资源密集的构建过程，从而解决服务器资源占用问题。

**重要提示**：
- ✅ **修改源码不会触发 CI/CD**：只有推送 `dist` 目录时才会触发部署
- ✅ **必须先本地构建**：在推送前需要在本地执行构建命令
- ✅ **服务器零构建压力**：服务器只负责轻量级的 Docker 镜像打包，不进行构建

## 工作流程

```
本地开发 → 本地构建 → 推送 dist → CI/CD 自动部署 → 服务器运行
   ↓          ↓          ↓            ↓              ↓
修改源码   pnpm build   git push   检测 dist 变化    Docker 打包
(不触发)   (生成 dist)  (触发)     (自动部署)      (不构建)
```

详细步骤：
1. **本地开发**：修改源码（`apps/web-antd/src/**`），此时不会触发 CI/CD
2. **本地构建**：在本地执行构建命令，生成 `apps/web-antd/dist` 目录
3. **推送构建产物**：将 `dist` 目录提交并推送到 Git 仓库
4. **自动部署**：CI/CD 检测到 `dist` 目录变化，自动部署到服务器
5. **服务器部署**：服务器只进行 Docker 镜像打包，不进行构建

## 使用方法

### 方式一：使用自动化脚本（推荐）

**Windows PowerShell 用户**：
```powershell
# 在项目根目录执行
.\scripts\deploy\build-and-push.ps1
```

**Linux/Mac 用户**：
```bash
# 在项目根目录执行
./scripts/deploy/build-and-push.sh
```

**或者使用 Git Bash（Windows）**：
```bash
bash scripts/deploy/build-and-push.sh
```

脚本会自动：
- 清理旧的构建产物
- 安装依赖（如果需要）
- 执行构建
- 检查构建结果
- 提示是否提交并推送

### 方式二：手动操作

```bash
# 1. 本地构建
pnpm build:antd

# 2. 检查构建结果
ls -la apps/web-antd/dist

# 3. 提交并推送
git add apps/web-antd/dist
git commit -m "chore: build and deploy web-antd"
git push origin master
```

## 文件说明

- `Dockerfile.deploy`: 仅用于部署的 Dockerfile，不进行构建，只复制构建产物
- `build-and-push.sh`: 本地构建和推送脚本（Linux/Mac/Git Bash）
- `build-and-push.ps1`: 本地构建和推送脚本（Windows PowerShell）
- `.gitea/workflows/deploy-web.yaml`: CI/CD 工作流配置（已修改为仅部署模式）

## CI/CD 触发条件

### ✅ 会触发部署的情况

当以下文件变化时会触发自动部署：
- `apps/web-antd/dist/**` - **构建产物目录（主要触发条件）**
- `apps/web-antd/nginx.conf` - Nginx 配置
- `Dockerfile.deploy` - 部署用 Dockerfile
- `.gitea/workflows/deploy-web.yaml` - CI/CD 配置

### ❌ 不会触发部署的情况

以下情况**不会**触发 CI/CD：
- 修改源码（`apps/web-antd/src/**`）
- 修改依赖包（`packages/**`）
- 修改 `package.json` 或 `pnpm-lock.yaml`
- 修改原 `Dockerfile`（根目录）
- 修改其他配置文件

**注意**：如果只修改了源码，需要先本地构建生成 `dist` 目录，然后推送 `dist` 才会触发部署。

## 重要注意事项

### 1. 构建产物必须提交到 Git

**必须确保** `apps/web-antd/dist` 目录被 Git 跟踪，否则 CI/CD 无法检测到变化。

**检查方法**：
```bash
# 检查 dist 是否被 Git 跟踪
git ls-files apps/web-antd/dist

# 如果输出为空，说明 dist 未被跟踪
```

**解决方法**：
- 如果 `dist` 在 `.gitignore` 中，需要临时移除或使用强制添加：
  ```bash
  git add -f apps/web-antd/dist
  ```

### 2. 修改源码后必须重新构建

**重要**：修改源码后，CI/CD **不会自动触发**，需要：
1. 本地执行构建：`pnpm build:antd`
2. 推送构建产物：`git add apps/web-antd/dist && git push`

### 3. 构建环境要求

- **Node.js**: >= 20.12.0
- **pnpm**: >= 10.14.0
- **网络**: 本地构建需要能够访问 npm/pnpm 仓库

### 4. 工作流程建议

**推荐流程**：

**Windows PowerShell**：
```powershell
# 1. 开发阶段：修改源码（不会触发 CI/CD）
# 使用你喜欢的编辑器修改 apps/web-antd/src/xxx.vue

# 2. 测试阶段：本地预览
pnpm dev:antd

# 3. 构建和部署：一键完成
.\scripts\deploy\build-and-push.ps1
```

**Linux/Mac/Git Bash**：
```bash
# 1. 开发阶段：修改源码（不会触发 CI/CD）
vim apps/web-antd/src/xxx.vue

# 2. 测试阶段：本地预览
pnpm dev:antd

# 3. 构建和部署：一键完成
./scripts/deploy/build-and-push.sh
```

## 优势

✅ **服务器零构建压力**：不占用服务器 CPU/内存/带宽  
✅ **构建速度快**：本地资源充足，构建更快  
✅ **可离线构建**：不依赖服务器网络  
✅ **便于调试**：本地可预览构建结果  
✅ **资源友好**：服务器只负责轻量级的 Docker 镜像打包

## 故障排查

### 问题：CI/CD 提示构建产物不存在

**解决方案**：
1. 检查本地是否成功构建：`ls -la apps/web-antd/dist`
2. 检查 dist 目录是否被 Git 跟踪：`git ls-files apps/web-antd/dist`
3. 如果 dist 在 .gitignore 中，使用强制添加：`git add -f apps/web-antd/dist`

### 问题：构建失败

**解决方案**：
1. 检查 Node.js 版本：`node --version`（需要 >= 20.12.0）
2. 检查 pnpm 版本：`pnpm --version`（需要 >= 10.14.0）
3. 清理并重新安装依赖：`pnpm clean && pnpm install`
4. 查看详细错误信息：`pnpm build:antd --verbose`

### 问题：推送后 CI/CD 未触发

**可能原因**：
1. **只推送了源码，没有推送 dist**：修改源码不会触发 CI/CD
   - 解决：先执行 `pnpm build:antd`，然后推送 `dist` 目录

2. **dist 目录未被 Git 跟踪**：
   ```bash
   # 检查 dist 是否被跟踪
   git ls-files apps/web-antd/dist
   
   # 如果为空，强制添加
   git add -f apps/web-antd/dist
   git commit -m "chore: add build artifacts"
   git push
   ```

3. **推送的文件路径不匹配触发条件**：
   - 确保推送了 `apps/web-antd/dist/**` 目录
   - 检查 `.gitignore` 是否忽略了 dist

4. **Git 提交信息包含 `[skip ci]`**：
   - 如果提交信息包含 `[skip ci]`，CI/CD 会被跳过
   - 解决：使用其他提交信息

5. **Gitea Actions 未启用**：
   - 检查 Gitea 仓库设置中 Actions 是否启用

### 问题：修改源码后如何部署

**解决方案**：
1. 本地构建：`pnpm build:antd`
2. 检查构建结果：`ls -la apps/web-antd/dist`
3. 推送构建产物：
   ```bash
   git add apps/web-antd/dist
   git commit -m "chore: build and deploy web-antd"
   git push origin master
   ```
4. 或者使用自动化脚本：`./scripts/deploy/build-and-push.sh`