Deployment and Upgrades

Before deployment or upgrade, confirm the product version and deployment model. Validate in this order: containers/processes → configuration → database/cache → MQTT → web pages → business workflows. A reachable home page alone does not prove a successful deployment.

1. FAQ

1.1. Which deployment method is recommended, and what must be prepared?

Docker Compose is recommended for quick evaluation and small-scale validation. Secondary-development environments can also start dependencies with Docker and then replace the backend JAR and frontend assets.

Prepare at least:

1. A Linux server with Docker and Docker Compose.
2. A domain or IP, security-group/firewall rules, and required business ports.
3. Installation packages, database scripts, and configuration matching the target version.
4. The Commercial Edition license certificate and installation details.
5. Data backups, log directories, and an upgrade/rollback plan.

See Docker Quick Deployment.

1.2. How do I use the one-click script, docker-compose, or an existing Docker image?

• One-click script: install Docker first, then run the command published on the official page rather than copying a same-named script elsewhere.
• docker-compose: place the deployment files in the documented directory, review configuration, and run docker-compose up -d under /var/data/.
• Existing images: import with docker load -i <image-file>, then start using the compose configuration supplied with the deployment package. Images do not eliminate business configuration or acceptance checks.

After startup, use docker-compose ps and container logs to verify core services. See Docker Quick Deployment.

1.3. How do I troubleshoot page 404s, unusable menus, or a missing verification code after deployment?

Separate static assets, backend APIs, and login dependencies, and change only one area at a time:

1. Check Nginx, the frontend directory, and the browser console for static-resource 404s.
2. Check the /prod-api/ proxy, backend port, and API prefix.
3. Check whether the backend and MySQL initialization have completed and whether the Redis password matches.
4. Review backend logs for verification-code, token, database, or licensing errors.
5. When multiple instances share a server, check for conflicting ports, directories, and proxy rules.

See Demo Environment Troubleshooting and Nginx Deployment.

1.4. What if the backend container keeps restarting or a port is already in use?

Inspect the earliest root cause in the container log rather than only the latest restart:

• Check connectivity to MySQL, Redis, the time-series database, and EMQX.
• Check the license name, paths, and configuration syntax.
• Use commands such as ss -lntup to identify port conflicts before changing host mappings or stopping a conflicting service.
• Check memory, writable mount directories, and YAML validity.

See Operations Monitoring.

1.5. How do I view Java, MySQL, EMQX, and other container logs?

Run the following in the deployment directory:

docker-compose ps
docker logs -n 300 java
docker logs -n 200 mysql
docker logs -n 200 redis
docker logs -n 200 emqx
docker logs -n 200 nginx

Keep the timestamp, complete stack trace, and earliest root cause. Use -f instead of -n for continuous viewing when needed, but do not retain only the final error line. See Docker Quick Deployment.

1.6. What if deployed frontend/backend features do not match the current code?

A one-click deployment package may not contain the latest source. After secondary development or an upgrade, verify that the backend JAR, frontend assets, visualization assets, and database scripts all belong to the target version.

For Docker deployments, normally replace the backend JAR under /var/data/java/ and frontend content under /var/data/nginx/vue/, restart the corresponding services, and run business acceptance checks. Do not update only one side. See Upgrade Guide.

1.7. How do I troubleshoot missing tables, Mapper/SQL errors, or startup failure after an upgrade?

Follow the database initialization and upgrade chain:

1. Compare the code version with the actual database schema.
2. For a new deployment, check initialization SQL; for an upgrade, verify that every upgrade script ran in version order.
3. Check for failed, duplicate, or partial script execution instead of rerunning scripts repeatedly.
4. Check the MySQL version, table-name case behavior, datasource, and account permissions.
5. Preserve logs and database state before restoring a backup or rolling back.

See Upgrade Guide.

1.8. How do I troubleshoot "internal client not started" or EMQX/Redis startup errors?

First confirm whether the deployment uses the built-in Netty Broker or external EMQX; do not mix the two:

• Check the Redis address, port, password, and network.
• With EMQX, check listeners, HTTP authentication, Webhook, backend connection address, and credentials.
• When the backend runs locally on Windows while EMQX runs elsewhere, use a backend address reachable from EMQX rather than an unusable java or localhost value.
• Check whether online/offline and subscription events reach the backend log.

See EMQX Installation and Configuration.

1.9. How do I switch between the built-in Netty Broker and EMQX?

Select one MQTT service in the current-version configuration, then update the backend, frontend WebSocket, authentication callbacks, and deployment ports consistently. After switching, validate not only client connection but also device online status, property reporting, command delivery, and result reporting.

See the deployment FAQ in the platform introduction and Technology Stack and Modules.

1.10. Where is the Commercial Edition certificate installed, and how do I check subject and certificate paths?

The license certificate must be installed after deployment. New versions normally open the certificate installation page when no certificate is installed. Local and Docker/production paths differ.

Check that:

1. The matching certificate and public-key files have been uploaded.
2. license.subject is set in the relevant application-dev.yml or application-prod.yml.
3. licensePath and publicKeysStorePath match the actual files.
4. Docker deployments mount the certificate directory and use production configuration.
5. After restart, the licensing prompt disappears and commercial features are accessible.

See License Configuration.

1.11. What if the certificate reports an unauthorized region or certificate validation fails?

The certificate may not match the authorized server or project environment. Do not bypass validation:

• Check the certificate name, subject, paths, and dependency versions.
• If the server region, IP, MAC, or deployment project changes, provide the before/after details to support for authorization review.
• Keep backend and dependencies such as fastbee-common aligned with the source version, clear failed dependency caches, and fetch them again.
• Preserve the complete stack trace and distinguish certificate reading, dependency mismatch, and business API authentication failures.

See License Configuration.

1.12. How should server specifications be selected?

A basic evaluation can start with the currently documented 4 cores, 8 GB RAM, and 100 GB or more disk. Production sizing must account for connections, reporting frequency, historical data, and video.

The existing stress-test report uses 8 cores, 16 GB RAM, and 10 Mbps as its recommended single-node configuration and reports results for specific scenarios. It is neither a universal minimum nor a capacity guarantee for every workload. See Technology Stack and Runtime and the stress-test report.

1.13. What is required when switching the primary database?

Confirm that the current version supports the target database, then prepare its initialization/upgrade SQL, driver, connection account, and character-set configuration. Commercial Edition database support includes MySQL, PostgreSQL, Oracle, SQL Server, DM, and Kingbase, each with its own tested versions and scripts. Open Source Edition support follows its own overview and must not assume this Commercial Edition list.

Copy the target datasource example from application-sql into the active environment configuration, then validate startup, core pages, and device workflows. Changing only the connection string is not enough. See Multiple Datasource Support.

1.14. What if TDengine times out or is not needed?

When TDengine is required, check the service, datasource address, client driver, FQDN/DNS, and ports. Server, client, and driver versions must also match. If it is not needed, disable the optional time-series store as documented and use MySQL for smaller historical datasets.

Do not switch or delete a historical database without confirming migration and retention requirements. See Time-series Database Installation and Activation.

1.15. What is the correct order for upgrade SQL, frontend/backend replacement, and rollback?

Use this order: identify current/target versions → enter a maintenance window → back up databases and deployment packages → read release notes → run upgrade SQL in order → replace backend JAR → replace frontend assets → clear only the caches required by the version notes → start and validate.

Validate at least login, products/devices, MQTT reporting/control, historical data, rules/alerts, notifications/work orders, video, and any enabled AI features. On failure, restore the old deployment and database backup instead of continuing over a broken state. See Upgrade Guide.

1.16. How do I upgrade after secondary development?

Merge the target version in an isolated branch or test environment, distinguish upstream fixes from local business changes, and resolve code conflicts, database scripts, configuration, and frontend dependency changes.

Record local modifications and API contracts before upgrading, then regression-test custom protocols, permissions, pages, and workflows. Do not overwrite production directly or skip intermediate SQL versions. See Upgrade Guide.

1.17. What if a cluster node says localAddress is not bindable or other nodes are missing?

Check each FMQ node's application.yml:

1. localAddress must be the current node's own bindable internal IP.
2. static-ip-addresses must list all cluster nodes consistently.
3. Internal ports, routing, and firewalls must allow node-to-node communication.
4. Restart the relevant node and verify the FMQ node page.

In containers or VMs, use the address from the actual network namespace rather than copying the host IP. See FMQ Cluster Deployment.

1.18. Where can I find current and upcoming version information?

Use the Release Notes, which maintain features, upgrade notices, and release status. Upcoming dates may remain undetermined; chat predictions such as "coming soon" are not an upgrade basis.