aiot-platform-ui/docs/DEPLOY.md

Gitea CI/CD 部署指南

本文档描述了 aiot-platform-ui (Web Antd 端) 的自动化构建与部署流程。

1. 架构说明

项目采用 Gitea Actions + Docker 进行部署。

• 构建方式：Docker 多阶段构建 (Multi-stage Build)。
  • Stage 1: node:20-alpine -> 安装依赖 -> pnpm build:web-antd -> 生成 dist。
  • Stage 2: nginx:alpine -> 复制 dist -> 启动 Web 服务。
• 运行环境：目标服务器 (安装了 Gitea Runner 和 Docker)。
• 网络模式：容器加入 aiot-net 网络，端口映射到宿主机。

2. 前置准备

在使用 CI/CD 前，请确保目标服务器满足以下条件：

1. 安装 Docker: docker -v 可用。
2. 配置 Gitea Runner:
   • Runner 已注册到 Gitea。
   • Runner 有权限访问 Docker Socket (/var/run/docker.sock)。
3. Docker 网络:
   • 项目使用 1Panel 的默认网络 1panel-network
   • CI/CD 会自动检查网络是否存在，如果不存在则创建
   • 确保前端和后端容器都在同一个网络中

3. 端口规划

服务名称	容器端口	宿主机端口 (Host Port)	说明
aiot-web-antd	80	9090	前端 Web 服务，请在 1Panel 中反代此端口
aiot-server	48080	48080	后端 API 服务 (参考)

注意：如果 9090 端口已被占用，请修改 .gitea/workflows/deploy-web.yaml 中的 HOST_PORT 变量。

部署失败：端口已被占用 (port is already allocated)

• 原因：宿主机端口被其他容器或服务占用。
• 解法：
  1. 修改 workflow 中的 HOST_PORT 为其他端口（如 8082、8083）。
  2. 或者手动停止占用端口的容器：docker ps | grep <端口号> 然后 docker stop <容器名>。

4. 1Panel 配置指南

由于容器运行在 127.0.0.1:8080，需要在 1Panel (或 Nginx) 中配置反向代理以通过域名访问。

1. 进入 1Panel -> 网站 -> 创建网站。
2. 域名: 填写你的域名 (e.g., admin.example.com)。
3. 类型: 反向代理。
4. 代理地址: http://127.0.0.1:9090。
5. 提交。

5. 常见问题排查

构建失败：pnpm install 很慢或超时

• 原因：网络问题。
• 解法：Dockerfile 中已配置 npm 淘宝源。如果依然慢，考虑在 Runner 机器上配置透明代理。

部署失败：Permission denied 访问 Docker

• 原因：Gitea Runner 用户没有 Docker 组权限。
• 解法：
  1. 在服务器执行：sudo usermod -aG docker <runner-user>。
  2. 或者在 workflow yaml 中开启 privileged: true (不推荐)。

页面刷新 404

• 原因：Nginx 未配置 SPA 重定向。
• 解法：检查 apps/web-antd/nginx.conf 是否包含 try_files $uri $uri/ /index.html;。

6. 如何触发部署

• 修改代码后，推送到 master 分支：

  git add .
  git commit -m "feat: 更新功能"
  git push origin master
  

• 前往 Gitea 仓库页面 -> Actions 查看构建进度。