# 部署与启动说明

本文档说明「故障预测波形工作台」前后端的部署与启动方式。

## 一、环境要求

| 组件 | 版本要求 |
| --- | --- |
| Python | 3.10+（建议 3.11 / 3.12 / 3.13） |
| Node.js | 18+（建议 20+） |
| npm | 随 Node.js 自带 |
| MySQL | 5.7+ / 8.x（已建好 `compressorsensor` 库，含 `wave_file`、`wave_sample` 表） |

## 二、目录结构

```
Compressor/
├── backend/
│   ├── requirements.txt      # Python 依赖
│   └── app/
│       ├── main.py           # FastAPI 入口与全部接口
│       ├── config.py         # 配置（读环境变量 / 数据库.md）
│       ├── db.py             # 数据库连接 + wave_annotation 建表语句
│       ├── auth.py           # 登录 token（进程内存存储）
│       ├── services/         # 数据查询与标注服务
│       └── algorithms/       # 周期识别等算法
├── frontend/
│   ├── package.json
│   ├── vite.config.ts        # 开发端口 5173，/api 代理到后端
│   └── src/                  # Vue3 + ElementPlus + ECharts
├── 数据库.md                 # 数据库连接信息（不入库、不提交敏感信息）
└── README.md
```

## 三、数据库准备

1. 确认 MySQL 中已有 `compressorsensor` 数据库及 `wave_file`、`wave_sample` 表。
2. 数据库连接信息放在项目根目录 `数据库.md`，格式如下（键名支持 `host` / `port` / `user` / `password` / `db_name`）：

   ```
   host : 127.0.0.1
   port : 3306
   user : root
   password : 你的密码
   db_name : compressorsensor
   ```

3. 标注索引表 `wave_annotation` 无需手动创建：后端启动时会自动执行 `CREATE TABLE IF NOT EXISTS`（见 `backend/app/db.py`）。

## 四、后端部署

### 4.1 安装依赖

```bash
cd Compressor
python3 -m pip install -r backend/requirements.txt
```

### 4.2 开发模式启动

```bash
cd Compressor
uvicorn app.main:app --app-dir backend --reload --port 8000
```

- `--reload` 修改代码自动重启（仅开发用）。
- 后端默认监听 `127.0.0.1:8000`。

### 4.3 生产模式启动

```bash
cd Compressor
uvicorn app.main:app --app-dir backend --host 0.0.0.0 --port 8000
```

> **注意**：登录 token 保存在进程内存中（`backend/app/auth.py`）。因此生产环境**请使用单进程启动**（不要加 `--workers N`，或显式 `--workers 1`），否则多进程各自持有独立 token 表，登录后请求可能被其他进程判定为未登录。若需要多进程/多实例，请改用 Redis 等共享存储（当前未实现）。

### 4.4 用环境变量覆盖数据库连接

不修改 `数据库.md` 也可以直接用环境变量覆盖：

```bash
DB_HOST=127.0.0.1 DB_PORT=3306 DB_USER=root DB_PASSWORD='...' \
DB_NAME=compressorsensor \
uvicorn app.main:app --app-dir backend --host 0.0.0.0 --port 8000
```

## 五、前端部署

### 5.1 安装依赖

```bash
cd Compressor/frontend
npm install
```

### 5.2 开发模式启动

```bash
cd Compressor/frontend
npm run dev
```

浏览器访问 `http://localhost:5173`。开发服务器把 `/api` 代理到 `http://127.0.0.1:8000`（见 `vite.config.ts`），因此本地开发无需额外配置。

### 5.3 生产构建

```bash
cd Compressor/frontend
npm run build
```

产物在 `frontend/dist/`，是纯静态文件。

### 5.4 生产部署（推荐：nginx 托管 + 反向代理）

把 `dist/` 部署到 nginx，并将 `/api` 反向代理到后端，前后端同源、无需处理 CORS：

```nginx
server {
    listen 80;
    server_name your-domain.com;

    root /path/to/Compressor/frontend/dist;
    index index.html;

    # SPA 路由回退（当前为单页应用，一般可省略）
    location / {
        try_files $uri $uri/ /index.html;
    }

    # 后端接口反向代理
    location /api/ {
        proxy_pass http://127.0.0.1:8000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}
```

### 5.5 生产部署（备选：前端独立域名直连后端）

前端构建时可指定后端地址（跨域直连）：

```bash
VITE_API_BASE=http://backend-host:8000 npm run build
```

此时后端需放行该来源，启动后端时设置：

```bash
CORS_ORIGIN=http://your-frontend-domain \
uvicorn app.main:app --app-dir backend --host 0.0.0.0 --port 8000
```

## 六、环境变量一览

后端相关：

| 环境变量 | 默认值 | 说明 |
| --- | --- | --- |
| `DB_HOST` | `数据库.md` 的 `host`，否则 `127.0.0.1` | MySQL 地址 |
| `DB_PORT` | `数据库.md` 的 `port`，否则 `3306` | MySQL 端口 |
| `DB_USER` | `数据库.md` 的 `user`，否则 `root` | MySQL 用户 |
| `DB_PASSWORD` | `数据库.md` 的 `password` | MySQL 密码 |
| `DB_NAME` | `数据库.md` 的 `db_name`，否则 `compressorsensor` | 数据库名 |
| `DB_CONNECT_TIMEOUT` | `3` | 连接超时（秒） |
| `DEMO_MODE` | `never` | `never` 数据库失败即报错；`always` 强制演示数据；`auto` 数据库失败时回退演示数据 |
| `CORS_ORIGIN` | `http://localhost:5173` | 允许的跨域来源 |
| `ANNOTATION_WIDTH` | `10` | 标注宽度（几个周期为一段） |
| `AUTH_USER` | `aaabbb` | 登录账号 |
| `AUTH_PASSWORD` | `Aa*147258&cd` | 登录密码 |
| `AUTH_TOKEN_TTL_SECONDS` | `43200` | token 有效期（秒，默认 12 小时） |

前端相关：

| 环境变量 | 默认值 | 说明 |
| --- | --- | --- |
| `VITE_API_BASE` | 空（走相对路径，配合 nginx 反代） | 前端请求后端的基础地址，如 `http://backend-host:8000` |

## 七、登录账号

内置账号（可用 `AUTH_USER` / `AUTH_PASSWORD` 环境变量覆盖）：

- 账号：`aaabbb`
- 密码：`Aa*147258&cd`

除 `POST /api/login` 外，所有接口都需要在请求头携带 `Authorization: Bearer <token>`。token 默认 12 小时有效，服务重启后失效，需重新登录。

## 八、注意事项

1. **敏感信息**：`数据库.md` 含数据库密码，已被 `.gitignore` 忽略，请勿提交到版本库。
2. **自动建表**：`wave_annotation` 标注表由后端启动时自动创建，无需手动建表。
3. **token 存储**：token 存于进程内存，生产请单进程运行（见 4.3）。
4. **演示模式**：无数据库时可用 `DEMO_MODE=always` 启动，前端与标注功能均可体验（标注走内存，不落库）。
5. **验证部署**：登录后访问 `GET /api/health`（需带 token）返回 `{"status": "ok"}` 即表示后端正常。