82 lines
3.0 KiB
Markdown
82 lines
3.0 KiB
Markdown
# 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** 查看构建进度。
|