更新

docs/BAOTA_DEPLOY.md

@@ -0,0 +1,226 @@
+# 宝塔部署 Web 端说明
+
+## 一、构建前配置
+
+### 1. 配置后端 API 地址
+
+编辑 `config/prod.env.js`，将 `BASE_API` 改为实际的后端接口地址：
+
+```javascript
+module.exports = {
+  NODE_ENV: '"production"',
+  BASE_API: '"https://your-api-domain.com/api"',  // 改为实际后端地址
+  VUE_APP_SOCKET_API: '"ws://127.0.0.1:10010"'   // WebSocket 默认地址（用户可在登录页修改）
+}
+```
+
+**注意：**
+- `BASE_API` 是 HTTP 接口地址（登录、数据请求等）
+- `VUE_APP_SOCKET_API` 是 WebSocket 默认地址，用户可在登录页修改，所以这里可以保持默认或设为公网地址
+
+### 2. 执行构建
+
+在项目根目录执行：
+
+```bash
+npm run build:web
+```
+
+构建完成后，产物在 `dist/web/` 目录下，包含：
+- `index.html`（入口文件）
+- `web.js`（主 JS 文件，包含所有代码和样式）
+- `1.js` ~ `7.js`（代码分割的 chunk 文件）
+- `fonts/`（字体文件）
+- `imgs/`（图片资源）
+
+**注意**：CSS 样式被打包进 `web.js` 中，运行时动态注入，无需单独引用 CSS 文件。
+
+---
+
+## 二、宝塔部署步骤
+
+### 1. 创建网站
+
+1. 登录宝塔面板
+2. 点击「网站」→「添加站点」
+3. 填写：
+   - **域名**：例如 `your-domain.com` 或 `192.168.1.100`（内网 IP）
+   - **根目录**：例如 `/www/wwwroot/your-domain.com`
+   - **PHP 版本**：选择「纯静态」或任意版本（前端不需要 PHP）
+
+### 2. 上传文件
+
+将 `dist/web/` 目录下的**所有文件**上传到网站根目录：
+
+```
+/www/wwwroot/your-domain.com/
+├── index.html
+├── web.js
+├── styles.css
+└── static/
+    ├── imgs/
+    └── fonts/
+```
+
+**上传方式：**
+- 方式一：在宝塔「文件」中直接上传压缩包并解压
+- 方式二：使用 FTP/SFTP 工具上传
+- 方式三：使用宝塔「终端」执行 `scp` 或 `rsync` 命令
+
+### 3. 配置 Nginx（重要）
+
+由于是 Vue Router 的 hash 模式（`#/login`、`#/manage`），通常不需要特殊配置。但建议添加以下配置以确保正常访问：
+
+在宝塔「网站」→ 选择站点 →「设置」→「配置文件」中，在 `server` 块内添加：
+
+```nginx
+server {
+    listen 80;
+    server_name your-domain.com;
+    root /www/wwwroot/your-domain.com;
+    index index.html;
+
+    # 前端路由支持（hash 模式通常不需要，但加上更稳妥）
+    location / {
+        try_files $uri $uri/ /index.html;
+    }
+
+    # 静态资源缓存
+    location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|woff|woff2|ttf|eot)$ {
+        expires 1y;
+        add_header Cache-Control "public, immutable";
+    }
+
+    # 禁止访问隐藏文件
+    location ~ /\. {
+        deny all;
+    }
+}
+```
+
+### 4. 配置 HTTPS（可选但推荐）
+
+如果使用域名且需要 HTTPS：
+
+1. 在宝塔「网站」→ 选择站点 →「SSL」→「Let's Encrypt」申请免费证书
+2. 开启「强制 HTTPS」
+3. **注意**：如果后端 API 或 WebSocket 使用 HTTPS/WSS，确保：
+   - `BASE_API` 使用 `https://`
+   - WebSocket 地址使用 `wss://`（或在登录页填写 `wss://` 地址）
+
+### 5. 配置跨域（如需要）
+
+如果后端 API 与前端不在同一域名，后端需要配置 CORS：
+
+- 允许的源：`https://your-domain.com`（或 `*` 用于开发）
+- 允许的请求头：`Content-Type, X-Token`（根据实际后端要求）
+- 允许的方法：`GET, POST, PUT, DELETE` 等
+
+---
+
+## 三、WebSocket 配置
+
+### 情况 1：WebSocket 服务在服务器本机
+
+如果 WebSocket 服务运行在**宝塔服务器本机**（例如 `ws://127.0.0.1:10010`）：
+
+- 用户访问网页时，浏览器会尝试连接**用户电脑**的 `127.0.0.1`，**无法连接**
+- **解决方案**：
+  1. 在登录页填写 `ws://服务器公网IP:10010` 或 `ws://服务器域名:10010`
+  2. 或配置 Nginx 反向代理 WebSocket（见下方）
+
+### 情况 2：使用 Nginx 反向代理 WebSocket（推荐）
+
+在宝塔「网站」→ 选择站点 →「设置」→「配置文件」中添加：
+
+```nginx
+# WebSocket 代理（假设后端 WebSocket 在 127.0.0.1:10010）
+location /ws {
+    proxy_pass http://127.0.0.1:10010;
+    proxy_http_version 1.1;
+    proxy_set_header Upgrade $http_upgrade;
+    proxy_set_header Connection "upgrade";
+    proxy_set_header Host $host;
+    proxy_set_header X-Real-IP $remote_addr;
+    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+    proxy_set_header X-Forwarded-Proto $scheme;
+}
+```
+
+然后在登录页填写：`wss://your-domain.com/ws`（HTTPS 用 `wss://`，HTTP 用 `ws://`）
+
+### 情况 3：WebSocket 服务在公网服务器
+
+如果 WebSocket 服务部署在**公网服务器**（例如 `wss://ws-api.xxx.com`）：
+
+- 在登录页填写该地址即可
+- 或在构建时设置 `VUE_APP_SOCKET_API` 为 `wss://ws-api.xxx.com`
+
+---
+
+## 四、访问测试
+
+1. 打开浏览器访问：`http://your-domain.com` 或 `https://your-domain.com`
+2. 应能看到登录页
+3. 点击「设置 WebSocket 服务地址」，填写实际可访问的 WebSocket 地址
+4. 输入账号密码登录
+5. 检查：
+   - 登录是否成功
+   - WebSocket 是否连接成功（查看浏览器控制台 Network → WS）
+   - 各功能页面是否正常加载
+
+---
+
+## 五、常见问题
+
+### 1. 页面空白
+
+- **检查**：浏览器控制台是否有 JS 错误
+- **解决**：确认 `index.html` 中引用的 `web.js`、`styles.css` 路径正确；检查 Nginx 配置是否正确
+
+### 2. 接口请求失败（404 或 CORS）
+
+- **检查**：`BASE_API` 是否正确；后端是否允许跨域
+- **解决**：修改 `config/prod.env.js` 中的 `BASE_API` 后重新构建；后端配置 CORS
+
+### 3. WebSocket 连接失败
+
+- **检查**：浏览器控制台 Network → WS，查看连接地址和错误信息
+- **解决**：
+  - 确认 WebSocket 服务已启动
+  - 在登录页填写正确的地址（本机用 `ws://127.0.0.1:10010`，服务器用 `ws://服务器IP:10010`，HTTPS 用 `wss://`）
+  - 如使用 Nginx 代理，确认代理配置正确
+
+### 4. 静态资源 404
+
+- **检查**：`static/` 目录是否上传完整
+- **解决**：重新上传 `dist/web/static/` 目录
+
+### 5. 路由跳转异常
+
+- **检查**：Nginx 配置中是否有 `try_files $uri $uri/ /index.html;`
+- **解决**：添加该配置后重启 Nginx
+
+---
+
+## 六、更新部署
+
+当代码更新后：
+
+1. 修改 `config/prod.env.js`（如需要）
+2. 执行 `npm run build:web`
+3. 将 `dist/web/` 下的文件**覆盖上传**到宝塔网站根目录
+4. 清除浏览器缓存或强制刷新（Ctrl+F5）
+
+---
+
+## 七、总结
+
+- **构建产物**：`dist/web/` 目录
+- **上传位置**：宝塔网站根目录
+- **配置要点**：
+  - `BASE_API`：后端 HTTP 接口地址
+  - WebSocket：用户可在登录页配置，或通过 Nginx 反向代理
+- **访问方式**：`http(s)://your-domain.com`
+
+部署完成后，用户访问网站即可使用，首次登录时记得在登录页配置 WebSocket 服务地址。