# 宝塔部署 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 服务地址。