243 lines
7.2 KiB
Markdown
243 lines
7.2 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
|
||
```
|
||
|
||
脚本会自动：
|
||
- 清理旧的构建产物
|
||
- 安装依赖（如果需要）
|
||
- 执行构建
|
||
- 检查构建结果
|
||
- 提示是否提交并推送
|
||
|
||
### 方式二：手动操作
|
||
|
||
```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`
|
||
|
||
### 问题：推送后 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`
|
||
|