# 脑晴测 H5 部署说明（自有服务器 + Node.js）

更新时间：2026-07-28

## 一、项目简介

- 中文、免登录的认知能力测评 H5
- 含四项游戏 + AI 生成报告（DeepSeek）
- 前端 React 19 + Vite，已构建为静态文件
- 服务端是零依赖单文件 Node.js（`server.mjs`）

## 二、仓库结构

```
.
├── brain-h5/
│   ├── dist/client/        # 预构建前端（已含，无需再 build）
│   ├── server.mjs          # Node.js 服务器入口（零依赖）
│   ├── src/                # 前端源码（仅二次开发时需要）
│   ├── worker/index.js     # Cloudflare Worker 版本（本方案不用）
│   └── ...
├── 交接文档.md
└── DEPLOY.md               # 本文件
```

## 三、部署步骤（自有服务器 + Node.js）

### 1. 系统要求

- Node.js v18 或更高（推荐 v20+）
- 任何能跑 Node.js 的操作系统（Linux/Windows/macOS）

不需要 npm install，不需要 pnpm，不需要 React 开发环境。

### 2. 克隆仓库

```bash
git clone <仓库地址>
cd Brain
```

### 3. 配置 API Key

`DEEPSEEK_API_KEY` 通过环境变量传入，**不要写入任何文件**。

Linux/macOS:
```bash
export DEEPSEEK_API_KEY=sk-你的key
```

Windows PowerShell:
```powershell
$env:DEEPSEEK_API_KEY = "sk-你的key"
```

或者用 systemd / pm2 / docker 等进程管理工具注入环境变量。

### 4. 启动服务

```bash
cd brain-h5
node server.mjs
```

默认监听 `0.0.0.0:4173`。可通过环境变量改：

```bash
PORT=8080 HOST=127.0.0.1 node server.mjs
```

### 5. 反向代理（推荐）

如果服务器有 Nginx，建议反代到 Node 服务：

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

    location / {
        proxy_pass http://127.0.0.1:4173;
        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;
    }
}
```

### 6. 进程守护（生产环境）

推荐用 pm2:

```bash
npm install -g pm2
cd brain-h5
DEEPSEEK_API_KEY=sk-你的key pm2 start server.mjs --name brain-h5
pm2 save
pm2 startup
```

## 四、健康检查

部署完成后应能通过：

| 检查项 | 期望结果 |
|---|---|
| `GET /` | 返回 HTML（200） |
| `GET /assets/index-*.js` | 返回 JS bundle（200） |
| `POST /api/analyze`（带 JSON body） | 返回 JSON 报告（200） |
| 未配置 Key 时 `POST /api/analyze` | 返回 503 `{"error":"AI service is not configured..."}` |

## 五、关键安全约束

- `DEEPSEEK_API_KEY` **必须**通过环境变量传入，**不要**写入仓库、commit、或前端 bundle。
- `.env` 文件已在 `.gitignore` 中排除，不会进入仓库。
- Key 由项目负责人通过私密渠道单独发送。

## 六、本地开发（可选，技术总监无需操作）

如需修改源码并重新构建：

```bash
cd brain-h5
pnpm install      # 或 npm install
pnpm run dev      # 本地开发服务器
pnpm run build    # 重新构建到 dist/client/
```

## 七、联系人

- 项目负责人：MingNian
- 项目根目录：`D:\GMS project`