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` 分支：
  ```bash
  git add .
  git commit -m "feat: 更新功能"
  git push origin master
  ```
- 前往 Gitea 仓库页面 -> **Actions** 查看构建进度。