操作	是否触发 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)  (触发)     (自动部署)      (不构建)

详细步骤：

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

使用方法

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

Windows PowerShell 用户：

# 在项目根目录执行
.\scripts\deploy\build-and-push.ps1

Linux/Mac 用户：

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

或者使用 Git Bash（Windows）：

bash scripts/deploy/build-and-push.sh

脚本会自动：

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

方式二：手动操作

# 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 文件

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

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

检查方法：

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

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

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

重要：修改源码后，CI/CD 不会自动触发，需要：

本地执行构建：pnpm build:antd
推送构建产物：git add apps/web-antd/dist && git push

3. 构建环境要求

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

4. 工作流程建议

推荐流程：

Windows 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：

# 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 提示构建产物不存在

解决方案：

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

问题：构建失败

解决方案：

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

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

可能原因：

构建时环境变量被开发环境配置覆盖
浏览器缓存了旧的配置
Service Worker 缓存了旧版本

解决方案：

确保使用生产环境构建：
- 脚本已自动设置 NODE_ENV=production
- 构建命令使用 --mode production
- 检查 .env.production 文件中的 VITE_GLOB_API_URL 配置
清除浏览器缓存：
- 硬刷新：Ctrl+Shift+R (Windows) 或 Cmd+Shift+R (Mac)
- 清除浏览器缓存和 Cookie
- 使用无痕模式测试

检查构建产物：

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

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

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

可能原因：

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

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

推送的文件路径不匹配触发条件：
- 确保推送了 apps/web-antd/dist/** 目录
- 检查 .gitignore 是否忽略了 dist
Git 提交信息包含 [skip ci]：
- 如果提交信息包含 [skip ci]，CI/CD 会被跳过
- 重要：构建脚本已更新，不再使用 [skip ci] 标记
- 如果之前使用了 [skip ci]，需要重新提交：
```
git commit --amend -m "chore: build and deploy web-antd"
git push origin master --force
```
Gitea Actions 未启用：
- 检查 Gitea 仓库设置中 Actions 是否启用

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

解决方案：

本地构建：pnpm build:antd
检查构建结果：ls -la apps/web-antd/dist

推送构建产物：

git add apps/web-antd/dist
git commit -m "chore: build and deploy web-antd"
git push origin master

或者使用自动化脚本：./scripts/deploy/build-and-push.sh

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

可能原因和解决方案：

容器启动失败：

# 在服务器上检查容器状态
docker ps -a | grep aiot-web-antd

# 查看容器日志
docker logs aiot-web-antd

# 如果容器不存在，检查 CI/CD 日志

端口被占用：

# 检查端口 9090 是否被占用
netstat -tuln | grep 9090
# 或
lsof -i :9090

# 检查是否有其他容器占用端口
docker ps --filter "publish=9090"

Nginx 配置错误：

# 进入容器检查 nginx 配置
docker exec -it aiot-web-antd sh
nginx -t  # 测试配置
cat /etc/nginx/conf.d/default.conf  # 查看配置

构建产物问题：

# 检查容器内的文件
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

网络问题：

# 检查容器网络
docker network inspect 1panel-network

# 检查容器是否在正确的网络中
docker inspect aiot-web-antd | grep NetworkMode

手动启动容器测试：

# 停止现有容器
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

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

快速诊断命令（在服务器上执行）：

# 一键诊断脚本
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

README.md Unescape Escape

本地构建+自动部署方案

📋 快速参考

方案说明

工作流程

使用方法

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

方式二：手动操作

文件说明

CI/CD 触发条件

✅ 会触发部署的情况

❌ 不会触发部署的情况

重要注意事项

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

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

3. 构建环境要求

4. 工作流程建议

优势

故障排查

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

问题：构建失败

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

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

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

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

README.md