# 机器人智慧服务系统 Alpha · 国内云部署说明

> 适用：将本项目（前端 SPA + Alpha 三服务 + nodevideo 视频服务）部署到国内云服务器
> （阿里云 ECS / 腾讯云 CVM / 华为云 ECS，推荐 Ubuntu 22.04 LTS）。
> 配套代码文档见 `docs/` 下设备数据字典、命令字典、状态机、联调报告等。

---

## 一、系统组成与端口

| 组件 | 目录 / 说明 | 端口 | 数据 / 依赖 |
|------|------------|:---:|------------|
| 前端 SPA（React 19 + Vite） | 仓库根目录 `npm run build` → `dist/` | 开发 3001；生产由 Nginx 托管 80/443 | 通过 `env.js` 的 `baseURL` 指向后端 |
| 设备接入服务 Alpha | `services/device-access` | **3010** | `data/devices.json` |
| 状态服务 Alpha | `services/status` | **3020** | `data/status.json` |
| 命令服务 Alpha | `services/command` | **3030** | `data/commands.json` |
| 主后端（已有，非 Alpha） | 由 `env.js` 指向 | API **8081** / WS **9002** / MQTT **8083** / GeoServer **59018** | 需与前端在同一云环境且可达 |
| 视频服务 nodevideo | 独立项目，视频管理页直连 | **9528** | SRS 录制目录 `BASE_DIR=/hdd/data/media/record/video/srs/` |

技术栈：Node.js + Express + 本地 JSON 文件（三服务均**不使用数据库**，数据落 `data/*.json`）。
Alpha 三服务均 `app.use(cors())` 全开；nodevideo 亦 `app.use(cors())` 全开（跨域直连可行，但生产建议走反代同源）。

---

## 二、云服务器准备

1. 选购：2 vCPU / 4 GB 起（含 Cesium 三维前端，建议 4 vCPU / 8 GB）；系统盘 40 GB+，数据盘按需（录像/JSON 备份）。
2. 系统：Ubuntu 22.04 LTS（或腾讯云 TencentOS Server 3/4）。
3. 安全组（推荐**仅暴露 22/80/443**，其它端口走 Nginx 反代）：
   - 入站：22（SSH）、80（HTTP）、443（HTTPS）。
   - 出站：全通。
   - 若采用「直连各端口」方案，需额外开放 3010/3020/3030/9528/8081 等，并依赖 CORS——**不推荐生产使用**。
4. 域名（可选但建议）：国内云需 ICP 备案后才能用 80/443 绑定域名；备案期间可先用 IP + 自签/免费证书测试。

---

## 三、基础环境（Ubuntu）

```bash
# 1. 系统更新
sudo apt update && sudo apt -y upgrade

# 2. Node.js 20 LTS（项目用 React19+Vite6，需 Node 18+）
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt -y install nodejs
node -v && npm -v          # 期望 v20.x / v10.x

# 3. 进程守护 PM2（全局）
sudo npm i -g pm2

# 4. 反向代理 + HTTPS
sudo apt -y install nginx
sudo snap install --classic certbot && sudo ln -s /snap/bin/certbot /usr/bin/certbot
```

> 国内云若访问 npm 慢，可切换镜像：`npm config set registry https://registry.npmmirror.com`

---

## 四、获取代码

```bash
cd /opt
sudo git clone <你的仓库地址> robot-system
sudo chown -R $USER:$USER /opt/robot-system
cd /opt/robot-system
```

> 若不用 git，可用 `scp` / 对象存储 将本地仓库打包上传解压。

---

## 五、部署 Alpha 三服务

三个服务结构一致，分别安装依赖并启动。下面以 `device-access` 为例，其余两目录同理。

```bash
# 设备接入服务
cd /opt/robot-system/services/device-access
npm install
pm2 start server.js --name device-access --watch

# 状态服务
cd /opt/robot-system/services/status
npm install
pm2 start server.js --name status --watch

# 命令服务
cd /opt/robot-system/services/command
npm install
pm2 start server.js --name command --watch

# 保存进程列表并实现开机自启（Linux 上 pm2 startup 可用）
pm2 save
pm2 startup          # 按提示执行它打印的 sudo 命令（写 systemd 单元）
```

验证：

```bash
pm2 ls                         # 三个服务 online
curl -s http://127.0.0.1:3010/api/devices/online/ROBOT-001   # 返回 JSON
curl -s http://127.0.0.1:3020/health ; curl -s http://127.0.0.1:3030/health
```

> 端口固定写死在 `server.js`（`PORT = 3010/3020/3030`），如需变更改文件即可。
> 数据文件 `data/*.json` 首次启动自动创建（空数组）。部署升级时**务必备份该目录**，避免覆盖业务数据。

---

## 六、部署前端（SPA）

### 6.1 配置生产后端地址

编辑仓库根目录 `env.js`，将 `PROD` 段改为云上实际地址（默认 `MODE=production` 时生效）：

```js
[ENV.PROD]: {
  baseURL:      'https://你的域名或http://云服务器IP:8081',   // 主后端 API
  WS_URL:       'wss://你的域名/ws/' 或 'ws://云服务器IP:9002/ws/',
  mqtt_url:     'wss://你的域名/mqtt' 或 'ws://云服务器IP:8083/mqtt',
  geoserver_url:'https://你的域名/geoserver' 或 'http://云服务器IP:59018/geoserver'
},
```

### 6.2 构建

```bash
cd /opt/robot-system
npm install
npm run build          # 产出 dist/（MODE=production，使用 env.js 的 PROD 配置）
```

### 6.3 视频管理页地址（重要）

`src/components/SystemSetting/VideoManagement.tsx` 顶部硬编码了：

```ts
const NODEVIDEO_BASE = 'http://localhost:9528';
```

部署到云后，浏览器里的 `localhost:9528` 指向**用户本机**而非服务器，视频无法访问。二选一：

- **方案A（反代同源，推荐）**：改为 `const NODEVIDEO_BASE = '/nodevideo'`，并在 Nginx 配置 `location /nodevideo/ { proxy_pass http://127.0.0.1:9528/; }`。
- **方案B（跨域直连）**：改为 `const NODEVIDEO_BASE = 'http://<云服务器IP或域名>:9528'`（nodevideo 已开 CORS，可用；但需安全组开放 9528）。

改完需重新 `npm run build`。

### 6.4 Nginx 托管 + 反代

```nginx
# /etc/nginx/sites-available/robot-system
server {
    listen 80; server_name 你的域名或IP;
    root /opt/robot-system/dist; index index.html;
    location / { try_files $uri $uri/ /index.html; }   # SPA 路由回退

    # ---- Alpha 三服务（按前端实际 API 前缀分流）----
    location /api/devices/  { proxy_pass http://127.0.0.1:3010; }
    location /api/status/   { proxy_pass http://127.0.0.1:3020; }
    location /api/commands/ { proxy_pass http://127.0.0.1:3030; }

    # ---- nodevideo 视频（对应方案A的 /nodevideo）----
    location /nodevideo/ { proxy_pass http://127.0.0.1:9528/; }

    # ---- 主后端（若与 Alpha 共用 /api 前缀需区分，建议独立子域或前缀）----
    location /backend/ { proxy_pass http://127.0.0.1:8081/; }

    # WebSocket / MQTT 透传（如前端直连）
    location /ws/  { proxy_pass http://127.0.0.1:9002; proxy_http_version 1.1;
                     proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "upgrade"; }
}
```

> 注意：前端 `env.js` 的 `baseURL` 必须与实际访问方式一致——若走 Nginx 同源，填 `https://你的域名`（或 `/backend` 之类前缀）；若主后端与 Alpha 都用 `/api` 前缀会冲突，请为二者分配不同前缀或子域。

启用并重载：

```bash
sudo ln -s /etc/nginx/sites-available/robot-system /etc/nginx/sites-enabled/
sudo nginx -t && sudo systemctl reload nginx
```

---

## 七、部署 nodevideo 视频服务（9528）

视频管理页依赖此服务，需与前端同一云环境可达。

```bash
cd /opt/nodevideo
npm install
pm2 start server.js --name nodevideo
pm2 save
```

**关键路径说明**：`server.js` 中 `BASE_DIR = "/hdd/data/media/record/video/srs/"` 为 Linux 绝对路径（SRS 录制存储）。
- 云服务器需存在该目录并挂载好录像盘；否则 `/list` 返回 `code:500 / directories:[]`，视频管理页显示为空。
- 如路径不同，直接修改 `server.js` 的 `BASE_DIR` 后 `pm2 restart nodevideo`。
- `PORT` 在代码里写 `30003`，但实际按你指定以 **9528** 对外（用 `PORT=9528 pm2 start server.js --name nodevideo` 或反代时统一即可）。

---

## 八、域名与 HTTPS（国内云）

1. **备案**：国内云使用 80/443 + 域名必须完成 ICP 备案（阿里云/腾讯云控制台申请，约 1–2 周）。
2. **证书**：备案后用免费证书
   ```bash
   sudo certbot --nginx -d 你的域名.cn
   ```
   或在云控制台申请免费 DV 证书后下载，Nginx 配置 `ssl_certificate / ssl_certificate_key`。
3. 证书自动续期：`sudo certbot renew --dry-run` 验证，certbot 默认建好 timer。

---

## 九、开机自启（推荐 systemd）

PM2 在 Linux 可用 `pm2 startup`（写 systemd 单元）实现开机拉起全部 `pm2 save` 的进程，最省事。
若偏好纯 systemd，可为每个服务写一个 unit（示例 `device-access.service`）：

```ini
[Unit]
Description=Device Access Service Alpha
After=network.target

[Service]
WorkingDirectory=/opt/robot-system/services/device-access
ExecStart=/usr/bin/node server.js
Restart=always
User=www-data
Environment=NODE_ENV=production

[Install]
WantedBy=multi-user.target
```

```bash
sudo systemctl enable --now device-access
```

---

## 十、运维与备份

- **日志**：`pm2 logs <name>`；或 journald `journalctl -u device-access -f`。
- **数据备份**：三服务的 `data/*.json` 是业务数据，定时备份：
  ```bash
  tar czf /backup/alpha-data-$(date +%F).tgz /opt/robot-system/services/*/data/
  ```
- **录像备份**：nodevideo 的 `/hdd/.../srs` 目录按磁盘策略归档。
- **升级流程**：拉新代码 → `npm install` → `npm run build`（前端）→ `pm2 restart <name>`；升级前先备份 `data/`。
- **回滚**：保留上一版 `dist/` 与 `services`，出问题时 `pm2 restart` 旧版本或 git checkout。

---

## 十一、快速检查清单

- [ ] 云服务器 Ubuntu 22.04，安全组仅开 22/80/443（反代方案）
- [ ] Node 20 LTS + npm + pm2 + nginx 已装
- [ ] Alpha 三服务 `pm2 ls` 均 online，端口 3010/3020/3030 监听 127.0.0.1
- [ ] 前端 `npm run build` 成功，`dist/` 由 Nginx 托管
- [ ] `env.js` 的 `PROD` 段 baseURL/WS/MQTT/GeoServer 已改为云地址
- [ ] 视频管理页 `NODEVIDEO_BASE` 已改为 `/nodevideo` 或云地址并重新 build
- [ ] nodevideo :9528 已起，`BASE_DIR` 存在且有录像；`/list` 能返回通道
- [ ] Nginx 反代规则就位，`nginx -t` 通过
- [ ] 域名已备案，HTTPS 证书已配置并自动续期
- [ ] `pm2 save` + `pm2 startup` 完成，重启服务器后服务自动拉起
- [ ] `data/*.json` 备份任务已配置