---
name: cloud-public-deploy
description: edge_collector 云平台公网部署流程规范。用于整理、审查或执行云平台公网部署方案时参考 deploy_cloud.sh，覆盖 package.sh --cloud-only、runtime/cloud_server 同步、远端配置保护、Mosquitto Dynamic Security、systemd/nginx 初始化、cloud-server 重启和公网接口验证。
---

# 云平台公网部署

## 固定约定

- 部署脚本：`./deploy_cloud.sh`
- 默认目标：`ubuntu@119.45.4.75`
- 远端目录：`~/cloud_server`
- systemd 服务：`cloud-server`
- 公网入口：`http://119.45.4.75`
- 本地构建输出：`runtime/cloud_server/`

## 使用边界

- 常规部署使用 `./deploy_cloud.sh`。
- 只看流程或生成文档时可以参考本 skill，不直接执行。
- 只有用户明确要求“初始化、清库、重置云端状态”时才允许加 `--init`。
- 不要手写 rsync、scp、systemctl 流程替代 `deploy_cloud.sh`。

## deploy_cloud.sh 实际流程

```text
1. bash ./package.sh --cloud-only
2. 校验 runtime/cloud_server 和 cloud_server/config/server_config.json
3. 读取 MQTT dynsec、PostgreSQL、TDengine 配置
4. 检查 SSH 连通性
5. 备份远端 server_config.json 和 ai_config.json
6. rsync runtime/cloud_server/ 到 ~/cloud_server/
7. 恢复/生成远端运行密钥，保留远端 AI 配置
8. 迁移并校验 Mosquitto Dynamic Security
9. --init 模式下安装 systemd 服务和 nginx
10. 重启 cloud-server 并输出公网 URL
```

## 运行配置保护

部署脚本会保护：

- `~/cloud_server/config/server_config.json` 中的 `jwt_secret`。
- `custom_config.terminal.credential_key`。
- `~/cloud_server/config/ai_config.json`。

审查或修改部署逻辑时，必须确认这些运行态配置不会被打包产物覆盖。

## MQTT Dynamic Security

脚本会根据 `server_config.json` 配置：

- 禁用旧的 Mosquitto 静态账号/ACL 配置。
- 初始化或更新 `/var/lib/mosquitto/dynamic-security.json`。
- 创建 gateway/cloud 角色和 cloud MQTT client。
- 设置 `/data/#`、`/status/#`、`/ack/#`、`/cmd/#` 相关权限。

如果部署失败，先查 `mosquitto_ctrl`、`mosquitto_dynamic_security.so` 和 Mosquitto 服务状态。

## 初始化模式

`--init` 会执行高风险动作：

- 停止 `cloud-server` 和 `mosquitto`。
- 重置 PostgreSQL 数据库。
- 重置 TDengine 数据库。
- 清理 MQTT dynsec 状态。
- 安装/覆盖 systemd service。
- 配置 nginx 80 端口反代到 8081，443 自签名证书重定向到 HTTP。

未获用户明确确认时禁止使用 `--init`。

## 验证步骤

部署完成后至少验证：

```bash
ssh ubuntu@119.45.4.75 'sudo systemctl is-active cloud-server'
ssh ubuntu@119.45.4.75 'sudo systemctl is-active mosquitto'
curl -s http://119.45.4.75/api/health
```

按改动范围补充：

- 登录接口：`POST /api/auth/login`
- AI 配置/分析接口。
- OTA 包列表接口。
- MQTT 网关连接和设备在线状态。
- 前端页面静态资源是否刷新。

## 故障排查

服务启动失败：

```bash
ssh ubuntu@119.45.4.75 'sudo journalctl -u cloud-server --since "10 min ago" --no-pager'
```

nginx 异常：

```bash
ssh ubuntu@119.45.4.75 'sudo nginx -t && sudo systemctl status nginx --no-pager'
```

MQTT dynsec 异常：

```bash
ssh ubuntu@119.45.4.75 'sudo systemctl status mosquitto --no-pager'
```

## 文档输出

整理公网部署文档时必须写清：

- 目标主机和远端目录。
- 是否使用 `--init`。
- 会保留哪些远端配置。
- 会重启哪些服务。
- 公网访问入口和验证接口。
- 回滚方式和日志位置。