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

脚本会自动：

- 清理旧的构建产物
- 安装依赖（如果需要）
- 执行构建
- 检查构建结果
- 使用 `--no-verify` 跳过 pre-commit hooks（避免检查大量构建产物文件）
- 提示是否提交并推送

### 方式二：手动操作

```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` 目录在 `.gitignore` 中被忽略，但我们需要将其提交到 Git 才能触发 CI/CD。

**脚本会自动处理**：

- 构建脚本（`build-and-push.sh` 和 `build-and-push.ps1`）会自动使用 `git add -f` 强制添加 dist 目录
- 你不需要手动修改 `.gitignore` 文件

**手动添加方法**（如果使用脚本）：

```bash
# 强制添加被忽略的 dist 目录
git add -f apps/web-antd/dist
```

**检查方法**：

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

# 如果输出为空，说明 dist 未被跟踪，需要使用 -f 强制添加
```

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

### 问题：构建后使用了开发环境配置（如 localhost:5666）

**可能原因**：
1. 构建时环境变量被开发环境配置覆盖
2. 浏览器缓存了旧的配置
3. Service Worker 缓存了旧版本

**解决方案**：

1. **确保使用生产环境构建**：
   - 脚本已自动设置 `NODE_ENV=production`
   - 构建命令使用 `--mode production`
   - 检查 `.env.production` 文件中的 `VITE_GLOB_API_URL` 配置

2. **清除浏览器缓存**：
   - 硬刷新：`Ctrl+Shift+R` (Windows) 或 `Cmd+Shift+R` (Mac)
   - 清除浏览器缓存和 Cookie
   - 使用无痕模式测试

3. **检查构建产物**：
   ```bash
   # 检查构建后的配置文件
   cat apps/web-antd/dist/_app.config.js
   # 应该显示：VITE_GLOB_API_URL 为 "/admin-api" 或正确的生产环境地址
   ```

4. **如果仍有问题**：
   - 删除 `apps/web-antd/dist` 目录
   - 重新构建：`pnpm build:antd`
   - 检查是否有 `.env.local` 文件覆盖了配置

### 问题：推送后 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 会被跳过
   - **重要**：构建脚本已更新，不再使用 `[skip ci]` 标记
   - 如果之前使用了 `[skip ci]`，需要重新提交：
     ```bash
     git commit --amend -m "chore: build and deploy web-antd"
     git push origin master --force
     ```

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`

### 问题：构建成功但服务没有运行

**可能原因和解决方案**：

1. **容器启动失败**：
   ```bash
   # 在服务器上检查容器状态
   docker ps -a | grep aiot-web-antd
   
   # 查看容器日志
   docker logs aiot-web-antd
   
   # 如果容器不存在，检查 CI/CD 日志
   ```

2. **端口被占用**：
   ```bash
   # 检查端口 9090 是否被占用
   netstat -tuln | grep 9090
   # 或
   lsof -i :9090
   
   # 检查是否有其他容器占用端口
   docker ps --filter "publish=9090"
   ```

3. **Nginx 配置错误**：
   ```bash
   # 进入容器检查 nginx 配置
   docker exec -it aiot-web-antd sh
   nginx -t  # 测试配置
   cat /etc/nginx/conf.d/default.conf  # 查看配置
   ```

4. **构建产物问题**：
   ```bash
   # 检查容器内的文件
   docker exec -it aiot-web-antd ls -la /usr/share/nginx/html
   
   # 检查 index.html 是否存在
   docker exec -it aiot-web-antd cat /usr/share/nginx/html/index.html
   ```

5. **网络问题**：
   ```bash
   # 检查容器网络
   docker network inspect 1panel-network
   
   # 检查容器是否在正确的网络中
   docker inspect aiot-web-antd | grep NetworkMode
   ```

6. **手动启动容器测试**：
   ```bash
   # 停止现有容器
   docker stop aiot-web-antd || true
   docker rm aiot-web-antd || true
   
   # 手动启动容器（前台运行，查看输出）
   docker run --rm \
     --name aiot-web-antd-test \
     --network 1panel-network \
     -p 9090:80 \
     aiot-web-antd:latest
   ```

7. **检查 CI/CD 日志**：
   - 查看 Gitea Actions 的完整日志
   - 检查是否有错误信息
   - 确认容器是否成功启动

**快速诊断命令**（在服务器上执行）：
```bash
# 一键诊断脚本
echo "=== Container Status ==="
docker ps -a | grep aiot-web-antd

echo "=== Container Logs (last 50 lines) ==="
docker logs aiot-web-antd --tail 50

echo "=== Port Status ==="
netstat -tuln | grep 9090

echo "=== Container Files ==="
docker exec aiot-web-antd ls -la /usr/share/nginx/html | head -10
```