# IoT Platform 部署文档

## 概述

本项目使用 Podman 容器化部署，通过 `deploy.sh` 脚本实现一键构建、上传、构建镜像、健康检查。

## 服务器环境

- **服务器**: online180 (47.104.204.180)
- **OS**: Alibaba Cloud Linux 3
- **容器运行时**: Podman 4.9.4 (docker 兼容)
- **Java**: OpenJDK 1.8 (容器内)
- **安装目录**: `/mnt/iot-platform/`（兼容软链接 `/opt/iot-platform`）
- **容器名称**: `iot-platform`

## 目录结构

```
/mnt/iot-platform/
├── iot-platform.jar          # 当前运行版本
├── Dockerfile                # 容器镜像构建定义
├── start-container.sh        # 容器启动脚本（加载 .env）
├── .env                      # 环境变量（密码、凭据）
├── backup/                   # 版本备份（自动创建）
├── bin/
│   ├── deploy.sh             # 一键部署脚本（本地运行）
│   └── health-check.sh       # 健康检查脚本
├── config/                   # 线上专属配置
└── logs/                     # 日志输出（宿主机挂载）
```

## 容器架构

| 容器 | 网络模式 | 端口 | 数据持久化 |
|------|---------|------|-----------|
| `tdengine-operator` | host | 6031 (taosd), 6041 (taosadapter) | `/mnt/tdengine-operator/data` |
| `taos-explorer` | bridge | `127.0.0.1:6060->6060` | `/mnt/taos-explorer-data` |
| `iot-platform` | bridge | `0.0.0.0:8887->8887` | `/mnt/iot-platform/logs` |

## 快速开始

### 首次部署（服务器初始化）

确保服务器上已有 `/mnt/iot-platform/` 目录，并包含 `Dockerfile`、`.env`、`start-container.sh`：

```bash
# 从本地同步必要文件到服务器
scp deploy/setup-server.sh root@47.104.204.180:/mnt/iot-platform/
scp .env root@47.104.204.180:/mnt/iot-platform/
scp deploy/Dockerfile root@47.104.204.180:/mnt/iot-platform/
scp deploy/start-container.sh root@47.104.204.180:/mnt/iot-platform/
ssh root@47.104.204.180 "chmod +x /mnt/iot-platform/start-container.sh"
```

然后执行首次部署：

```bash
cd deploy
./deploy.sh --build
```

### 日常部署

#### 方式一：本地构建后部署

```bash
cd deploy
./deploy.sh --build
```

流程：
1. 本地执行 `mvn clean package`
2. 上传 jar 到服务器 `/mnt/iot-platform/`
3. 备份当前版本（带时间戳）
4. 停止并删除旧容器
5. 替换 jar 并构建新镜像
6. 启动容器（bridge 网络模式，端口映射 `8887:8887`）
7. 健康检查（`/actuator/health`）
8. 失败时保留容器用于排查（不再自动回滚）

#### 方式二：指定 jar 部署

```bash
cd deploy
./deploy.sh --jar ../iot-platform/target/iot-platform.jar
```

#### 方式三：CI/CD 构建后部署

```bash
cd deploy
./deploy.sh --jar /path/to/ci/artifacts/iot-platform.jar
```

## 环境变量

`.env` 文件位于项目根目录和服务器 `/mnt/iot-platform/.env`，包含所有环境变量：

```bash
# MySQL
MYSQL_USERNAME=root
MYSQL_PASSWORD="..."

# Redis
REDIS_PASSWORD=
REDIS_HOST=172.21.185.173

# MQTT
MQTT_USERNAME=...
MQTT_PASSWORD=...

# TDengine
TDENGINE_USERNAME=root
TDENGINE_PASSWORD=taosdata

# Druid 监控
DRUID_STAT_ENABLED=false
DRUID_USERNAME=ruoyi
DRUID_PASSWORD=...
```

## 服务器管理

```bash
# 查看容器状态
podman ps

# 查看实时日志
podman logs -f iot-platform

# 查看最后 100 行日志
podman logs --tail 100 iot-platform

# 查看宿主机上的日志文件（和容器内同步）
tail -f /mnt/iot-platform/logs/iot-platform.$(date +%Y-%m-%d).*.log

# 停止容器
podman stop iot-platform

# 删除容器
podman rm iot-platform

# 重启容器
podman restart iot-platform
```

## 健康检查

```bash
# 在服务器上执行
bash /mnt/iot-platform/bin/health-check.sh localhost 8887 30

# 或从本地检查
curl -s http://47.104.204.180:8887/actuator/health
```

健康检查策略：
1. 优先检查 `/actuator/health`（Spring Boot Actuator）
2. 如果 Actuator 未启用，降级为 TCP 端口监听检查

## 回滚

部署失败时容器会保留用于排查，需手动回滚：

```bash
ssh root@47.104.204.180

# 停止并删除当前容器
podman stop iot-platform && podman rm iot-platform

# 恢复旧版本 jar
ls /mnt/iot-platform/backup/          # 查看可用备份
cp /mnt/iot-platform/backup/iot-platform-XXXX.jar /mnt/iot-platform/iot-platform.jar

# 重新构建镜像并启动
cd /mnt/iot-platform && podman build -t iot-platform:latest .
podman run -d \
    --name iot-platform \
    --network bridge \
    --restart unless-stopped \
    -p 8887:8887 \
    -v /mnt/iot-platform/logs:/opt/iot-platform/logs \
    localhost/iot-platform:latest
```

## TDengine 容器管理

```bash
# 查看所有 TDengine 相关容器
podman ps | grep -E 'tdengine|taos'

# 重启 tdengine-operator（taosd + taosadapter）
podman restart tdengine-operator

# 重启 taos-explorer
podman restart taos-explorer

# 查看 tdengine-operator 日志
podman logs -f tdengine-operator

# 查看 taos-explorer 日志
podman logs -f taos-explorer

# 验证 taosadapter REST API
curl -s -u root:taosdata http://127.0.0.1:6041/rest/sql -X POST -d "SHOW DATABASES"
```

### 启动脚本位置

| 脚本 | 用途 |
|------|------|
| `scripts/start-tdengine-operator.sh` | 启动 tdengine-operator（host 网络，taosd + taosadapter） |
| `scripts/start-taos-explorer.sh` | 启动 taos-explorer（bridge 网络，REST API） |

## 架构说明

```
┌─────────────────────────────────────────────┐
│                    宿主机                     │
│  ┌─────────────┐      ┌─────────────────┐   │
│  │ nginx :6060 │─────▶│ taos-explorer   │   │
│  └─────────────┘      │ (REST API)      │   │
│                       └────────┬────────┘   │
│                                │            │
│  ┌─────────────────────────────┼────────┐   │
│  │         iot-platform        │        │   │
│  │         (bridge)            │        │   │
│  └─────────────────────────────┘        │   │
│                                         │   │
│  ┌──────────────────────────────────────┘   │
│  │  tdengine-operator (host网络)            │
│  │  taosd :6031  +  taosadapter :6041       │
│  └──────────────────────────────────────────┘
└─────────────────────────────────────────────┘
```

- `tdengine-operator` 使用 **host 网络**，内部同时运行 `taosd`（6031）和 `taosadapter`（6041）
- `taos-explorer` 通过 `host.containers.internal:6041` 使用 **REST API** 连接
- `iot-platform` 通过 `host.containers.internal:6031` 使用 **native 协议** 连接
- `taosadapter` 配置通过覆盖镜像 `entrypoint.sh` 读取 `/etc/taos/taosadapter.toml`

## 配置文件说明

| 文件 | 说明 |
|------|------|
| `deploy.sh` | 一键部署脚本（本地执行） |
| `setup-server.sh` | 服务器初始化脚本 |
| `health-check.sh` | 健康检查脚本 |
| `Dockerfile` | 容器镜像构建定义 |
| `start-container.sh` | 容器内启动脚本（加载 .env） |
| `iot-platform.service` | systemd 服务定义（已废弃，保留备用） |
| `config/taos.cfg` | TDengine 服务端配置 |
| `config/entrypoint.sh` | 覆盖容器默认 entrypoint，使 taosadapter 读取配置文件 |
| `config/explorer.toml` | taos-explorer 配置（REST API） |
| `config/taosadapter.toml` | taosadapter 配置（禁用未使用插件） |
| `config/tdengine-explorer.conf` | nginx 代理配置 |