# Upgrade Guide

## Page Guide

- **Use Cases**: For upgrading from an old version to a new version, or replacing the backend, frontend, and database scripts during professional-edition delivery.
- **Prerequisites**: You have confirmed the current version, target version, upgrade SQL, deployment method, and rollback window.
- **Upgrade Scope**: Database, backend jar, frontend static assets, mobile app, visualization, cache, time-series database, and license configuration.
- **Acceptance Criteria**: Services start normally, core business links are available, no data is lost, and version features take effect as expected.

## 1. Pre-Upgrade Preparation

| Preparation Item | Notes |
| --- | --- |
| Confirm versions | Record the current version and target version |
| Back up databases | MySQL, time-series database, OSS files, configuration files |
| Back up deployment packages | Backend jar, frontend directory, docker-compose, Nginx configuration |
| Read the changes | Check the release notes and SQL upgrade scripts |
| Test rehearsal | Rehearse the complete upgrade in a test environment first |
| Rollback plan | Define the rollback package, database backup, and downtime window |

## 2. Upgrade Order

```mermaid
%%{init: {"flowchart": {"htmlLabels": false}}}%%
flowchart LR
  A["Stop writes or enter maintenance window"] --> B["Back up data and deployment packages"]
  B --> C["Execute upgrade SQL"]
  C --> D["Replace backend jar"]
  D --> E["Replace frontend assets"]
  E --> F["Clear necessary caches"]
  F --> G["Start services"]
  G --> H["Business acceptance"]
  H --> I["Observe logs"]
```

## 3. SQL Scripts

SQL is located in the source repository:

```text
springboot/sql
```

Common script types:

| Type | Notes |
| --- | --- |
| Major-version initialization script | Used for new deployments, such as `fastbee-v2.9.0.sql` |
| Version upgrade script | Used to upgrade from an old version to a new version, such as `fastbee2.8.0-upgrade-v2.9.0.sql` |
| Multi-database scripts | Dameng, KingbaseES, Oracle, Postgres, SQL Server |
| Time-series database scripts | IoTDB, TDengine initialization |
| AI initialization script | AI tables and initialization data |

::: warning
Upgrade SQL must be executed in version order; do not skip scripts across versions. Back up the database before execution.
:::

## 4. Docker Deployment Upgrade

Common paths:

| File | Location |
| --- | --- |
| Backend jar | `/var/data/java/` |
| Frontend assets | `/var/data/nginx/vue/` |
| Visualization assets | `/var/data/nginx/view/` |
| Nginx configuration | `/var/data/nginx/` or the deployment package configuration directory |

Restart the services after replacement:

```shell
cd /var/data
docker-compose restart java
docker-compose restart nginx
```

## 5. Cache And Time-Series Database

Some version upgrades involve cache structures, device data permissions, or time-series database super-table changes. Handle them according to the release notes:

| Scenario | Recommendation |
| --- | --- |
| Device message cache changes | Clear the corresponding business keys in Redis |
| Modbus configuration changes | Clear Modbus-related caches |
| Thing model structure changes | Restart the service and verify device models |
| TDengine table structure changes | Handle super tables and historical data according to the release notes |
| IoTDB initialization | Confirm the scripts and connection configuration |

## 6. Post-Upgrade Acceptance

| Acceptance Item | Normal Behavior |
| --- | --- |
| Login | Administrators can log in and menus are normal |
| Products and devices | Products, devices, and thing models can be queried |
| Device access | MQTTX can go online, report, and receive commands |
| Data center | Historical data and reports can be queried |
| Rules and alerts | Rules, scenes, and alerts can be triggered |
| Notifications and work orders | Notification delivery and work order generation are normal |
| Video | Live streaming, channels, and recording are available as needed |
| AI | Models, knowledge base, and conversations are available as needed |

## 7. Rollback Strategy

If the upgrade fails:

1. Stop the new-version services.
2. Restore the old jar and frontend directory.
3. Restore the database backup.
4. Restore the Nginx and configuration files.
5. Start the old-version services.
6. Re-analyze the upgrade problem.

## 8. Related Docs

* [Operations And Monitoring](https://www.fastbee.cn/doc/en/business/v2/install/operation-maintenance.html)
* [Quick Deployment With Docker](https://www.fastbee.cn/doc/en/business/v2/install/docker.html)
* [Data Model And API Map](https://www.fastbee.cn/doc/en/business/v2/dev/data-model-map.html)
* [Version History](https://www.fastbee.cn/doc/en/business.md)
