docs: cicd文档

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 <runner-user>`。
-    2.  或者在 workflow yaml 中开启 `privileged: true` (不推荐)。
+
+- **原因**：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;`。
+
+- **原因**：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** 查看构建进度。