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

本地构建+自动部署方案

📋 快速参考

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

快速部署命令：

./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 镜像打包，不进行构建

使用方法

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

# 在项目根目录执行
./scripts/deploy/build-and-push.sh

脚本会自动：

• 清理旧的构建产物
• 安装依赖（如果需要）
• 执行构建
• 检查构建结果
• 提示是否提交并推送

方式二：手动操作

# 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: 本地构建和推送脚本
• .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 无法检测到变化。

检查方法：

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

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

解决方法：

• 如果 dist 在 .gitignore 中，需要临时移除或使用强制添加：

  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. 工作流程建议

推荐流程：

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

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

# 3. 构建阶段：生成构建产物
pnpm build:antd

# 4. 部署阶段：推送构建产物（触发 CI/CD）
./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 跟踪：

   # 检查 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. 推送构建产物：

   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