386 lines
11 KiB
Markdown
386 lines
11 KiB
Markdown
# 本地构建+自动部署方案
|
||
|
||
## 📋 快速参考
|
||
|
||
| 操作 | 是否触发 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
|
||
```
|