From 3c6a92b1d42ac175509d418a007e702566fb39a6 Mon Sep 17 00:00:00 2001 From: lzh Date: Thu, 18 Dec 2025 15:45:59 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20cicd=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/DEPLOY.md | 73 ++++++++++++++++++++++++++++---------------------- 1 file changed, 41 insertions(+), 32 deletions(-) diff --git a/docs/DEPLOY.md b/docs/DEPLOY.md index 91d927723..f73419d75 100644 --- a/docs/DEPLOY.md +++ b/docs/DEPLOY.md @@ -6,33 +6,40 @@ 项目采用 **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` 网络，端口映射到宿主机。 +- **构建方式**：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. **创建网络 (可选)**: - ```bash - docker network create aiot-net - ``` +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 | **8080** | 前端 Web 服务，请在 1Panel 中反代此端口 | +| :-- | :-- | :-- | :-- | +| **aiot-web-antd** | 80 | **9090** | 前端 Web 服务，请在 1Panel 中反代此端口 | | aiot-server | 48080 | 48080 | 后端 API 服务 (参考) | -> **注意**：如果 8080 端口已被占用，请修改 `.gitea/workflows/deploy-web.yaml` 中的 `HOST_PORT` 变量。 +> **注意**：如果 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 配置指南 @@ -41,32 +48,34 @@ 1. **进入 1Panel** -> **网站** -> **创建网站**。 2. **域名**: 填写你的域名 (e.g., `admin.example.com`)。 3. **类型**: `反向代理`。 -4. **代理地址**: `http://127.0.0.1:8080`。 +4. **代理地址**: `http://127.0.0.1:9090`。 5. **提交**。 ## 5. 常见问题排查 ### 构建失败：`pnpm install` 很慢或超时 -* **原因**：网络问题。 -* **解法**：Dockerfile 中已配置 npm 淘宝源。如果依然慢，考虑在 Runner 机器上配置透明代理。 + +- **原因**：网络问题。 +- **解法**：Dockerfile 中已配置 npm 淘宝源。如果依然慢，考虑在 Runner 机器上配置透明代理。 ### 部署失败：`Permission denied` 访问 Docker -* **原因**：Gitea Runner 用户没有 Docker 组权限。 -* **解法**： - 1. 在服务器执行：`sudo usermod -aG docker `。 - 2. 或者在 workflow yaml 中开启 `privileged: true` (不推荐)。 + +- **原因**：Gitea Runner 用户没有 Docker 组权限。 +- **解法**： + 1. 在服务器执行：`sudo usermod -aG docker `。 + 2. 或者在 workflow yaml 中开启 `privileged: true` (不推荐)。 ### 页面刷新 404 -* **原因**：Nginx 未配置 SPA 重定向。 -* **解法**：检查 `apps/web-antd/nginx.conf` 是否包含 `try_files $uri $uri/ /index.html;`。 + +- **原因**：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** 查看构建进度。 - +- 修改代码后，推送到 `master` 分支： + ```bash + git add . + git commit -m "feat: 更新功能" + git push origin master + ``` +- 前往 Gitea 仓库页面 -> **Actions** 查看构建进度。