Platform Features and Operations

When troubleshooting a platform feature, first confirm the version and whether the module has been purchased and enabled. Then distinguish configuration, data, permissions, scheduled tasks, and third-party services. Full operating procedures remain in each module's documentation.

1. Accounts, Permissions, and Runtime Performance

1.1. How are multi-tenancy, organizations, roles, and data permissions related?

An organization is a tenant and isolates products, devices, scenes, work orders, and other data. Roles control menus, buttons, and data scope. The organization hierarchy affects which data can be managed. Terminal users normally bind devices through the App/Mini Program, while tenant users work in the web backend.

"Data is missing" and "menus are missing" are different problems; check data permissions and role-menu permissions separately. See Multi-tenant Operations and System Administration.

1.2. Why cannot a user see menus, buttons, devices, products, or scenes?

• Missing menus: check role-menu grants, menu status, and whether the user logged in again.
• Missing buttons: check button permission identifiers, role grants, and frontend/backend permission controls.
• Missing devices/products/scenes: check organization relationships, data permissions, device allocation, product privacy, and the creator's organization.

Do not bypass the issue by granting super-administrator access. Validate least privilege with a test account for the target role. See System Administration.

1.3. Where do I change the system name, organization name, logo, and passwords?

Update basic system information and logos through system parameters, the personal center, or organization configuration as appropriate. Maintain organization names in organization management, and change passwords through the personal center or administrator user-management flow; do not edit source code to change default passwords.

Menu names vary by version. After changes, validate display and permissions with a normal account. See System Administration and Multi-tenant Operations.

1.4. How should default, datasource-monitoring, and delivery accounts be handled securely?

Initial accounts are only for first deployment acceptance. Change default passwords at handover and create accounts for actual roles. Do not reuse one password for datasource monitoring, EMQX, databases, and the private repository, and never publish initial repository passwords or test-tenant credentials.

Restrict network exposure of Druid, EMQX, and other administration interfaces in production. See Docker Quick Deployment.

1.5. Which metrics should I check for slow pages, API timeouts, message backlogs, or database pressure?

Collect metrics by layer:

• Slow pages: static-asset size, Nginx caching, browser network waterfall, and API duration.
• API timeouts: Java thread pools, slow SQL, slow Redis commands, and external callbacks.
• Message backlogs: Broker throughput, rule duration, database writes, and consumer concurrency.
• Frequent JVM GC: heap size, object allocation, cached objects, and large result sets.
• High database pressure: indexes, lock waits, transaction scope, hot tables, and archival policies.

Identify the bottleneck before scaling or changing multiple parameters. See Performance Optimization.

1.6. How do I troubleshoot log paths, upload paths, low disk space, and API errors?

Inspect the earliest backend root cause, confirm that log/upload directories exist and are writable, and then check disk space, file permissions, Nginx proxying, and database connectivity. On Linux, df -h, free -h, and ss -lntup can help.

Before cleaning files, distinguish application logs, business uploads, database files, and backups; never delete business data indiscriminately. See Operations Monitoring.

2. Reports, Work Orders, and Maintenance

2.1. Why is a report not generated or empty?

For a missing report, check rule status, execution time, server time, and scheduled tasks. For an empty report, check whether devices reported during the selected period, whether historical storage is enabled for the variables, and whether the aggregation method suits the data.

A current runtime value does not prove that historical data exists for the selected period. See Data Center.

2.2. Why does a report download link fail or its email not arrive?

For download links, check the server domain, Nginx proxy, file-storage path, and URL in the notification template. For email, check notification channel, template enablement, user email, delivery logs, and provider restrictions.

First confirm that the report exists and can be downloaded from the backend, then troubleshoot notifications. See Data Center and Message Notifications.

2.3. Why are no work orders generated from alerts/maintenance, or why are duplicates generated?

For alerts, check whether "generate work order" is enabled, whether the associated scene triggered, and whether the alert-execution count limit applied. For maintenance, check start time, cycle, advance-dispatch time, and scheduled tasks.

For duplicates, check for multiple maintenance plans on the same device. In a cluster, also check whether multiple nodes are running the same scheduled task. See Work Order Management and Device Maintenance.

2.4. Why cannot a normal user see a work order or a contact receive notifications?

For visibility, check tenant, role, data permissions, device allocation, and whether the user is the work-order contact. For notifications, check the contact's email in their user profile, notification template, channel, and delivery logs.

See Work Order Management.

3. SIM Cards and Object Storage

3.1. Why does adding a SIM card fail or platform information stop synchronizing?

Check the card-platform API address, credentials, server IP whitelist, ICCID existence, and whether the carrier exposes its API. For synchronization problems, also inspect scheduled tasks, API availability, and rate limits.

See IoT SIM Card Management.

3.2. Why is a device not automatically bound to a card after reporting its ICCID?

Check iccid and cardPlatformId in the /info/post payload, confirm that the platform can synchronize the card, and verify that the device report was processed successfully. If no platform ID is supplied, the current implementation attempts to match a platform, but the card data must still be synchronizable.

See MQTT Device Information and IoT SIM Card Management.

3.3. Why is no SIM-data usage alert sent?

Check the usage threshold, notification users, templates, and channels, and confirm that usage has been synchronized successfully. If the platform has no current usage data, it cannot generate an accurate alert merely because the carrier reports overage.

See IoT SIM Card Management.

3.4. Why does OSS/S3-compatible upload fail, return 403, or not upload recordings?

• Upload failure: check AccessKey, SecretKey, Bucket, region, Endpoint, provider type, and network.
• 403 after upload: check bucket read permission, object ACL, custom domain, and hotlink protection.
• Missing recordings: check the device recording switch, recording service, ZLM Hook, and OSS configuration.

Validate storage with the platform's test upload before troubleshooting recording. See Recording OSS Configuration.

4. Visualization, SCADA, and Mobile

4.1. What is the difference between visualization dashboards and Web SCADA?

Visualization dashboards primarily display data, usually through API queries. Web SCADA binds directly to Thing Models or scene variables, refreshes through real-time messages, and can issue device commands through control components. Web SCADA is an optional paid module.

During platform upgrades, replace the main system, visualization and SCADA resources together as described in the release notes, and keep the SCADA module aligned with the main-system version. Visualization is integrated into the Commercial Edition main project starting with V2.9, so do not follow the old independent-directory upgrade process. After upgrading, validate projects, APIs, variable bindings, and control workflows. See Visualization Dashboards, SCADA Management, and Release Notes.

4.2. Why is a published dashboard blank, cross-origin, incorrectly formatted, or slow?

For a blank page, check deployment directories, Nginx location, resource 404s, and API addresses. For cross-origin errors, check frontend proxying, backend CORS, Nginx, and HTTP/HTTPS mixing. Use filters to convert API responses into the structure required by components.

For slow pages, reduce refresh rates, high-frequency charts, and simultaneous videos; compress images and limit component counts. See Visualization Dashboards.

4.3. Why do SCADA variables have no values, controls not work, or assets fail to load?

For missing values, check product/scene bindings, variable source, Thing Model identifier, device online status, and reporting. For ineffective controls, check writability, online status, device-side command handling, and user permission.

For image or 3D-model failures, check deleted assets, paths, file size, cross-origin rules, and static-resource services. See SCADA Management.

4.4. Why does a SCADA share link fail, a click do nothing, or a script/visibility rule fail?

For share links, check sharing enablement, password, deleted SCADA, access domain, and Nginx proxy. For clicks, check overlapping components, event enablement, and whether the target component or variable exists.

For scripts, check null values, field names, component IDs, and browser syntax support. For visibility problems, check groups, event order, and default states. See SCADA Quickstart and SCADA Events and Scripts.

4.5. Why is a custom mobile device panel not displayed?

The panel is defined by the product, not separately for each device. In the product's application configuration, edit and save the panel, then enable the custom panel; disabling it restores the default runtime panel.

Also check component compatibility with Thing Model data type, read-only behavior, and chart settings. See Mobile Device Panels.

4.6. How are mobile apps packaged and published, and why does a WeChat Mini Program require HTTPS and a compliant domain?

Use HBuilderX to build for native App, H5, or WeChat Mini Program. A Mini Program must use valid request domains, HTTPS, and certificates as required by WeChat; a plain HTTP/IP endpoint is not a valid production configuration.

After building, validate APIs, MQTT WebSocket, video, and third-party SDKs in the target environment. See Mobile Deployment.

4.7. Why does an App not detect an update, WGT installation fail, or iOS hot update fail?

For undetected updates, check that the target version exceeds the client version, the App uses the correct environment, and the version is enabled. For WGT failures, check base-app compatibility and whether changes require a new native installation package.

For iOS, follow App Store or enterprise-signing workflows rather than Android WGT procedures. See App Version Management.

5. AI, OAuth, and Smart Speakers

5.1. Why does AI return authentication failure or model unavailable?

Check provider status, API Base URL, authentication method, API Key, model name, model permissions, and quota. For an internal model, also verify backend-to-model network, port, and path.

Use different keys for production and testing, and never share screenshots or logs containing keys publicly. See Model Provider Configuration.

5.2. Why does AI still use old content or miss a knowledge base after successful upload and parsing?

Successful upload and parsing only makes content available for a build; it does not publish it to the runtime. Check that:

1. New documents are enabled and old documents are not also active.
2. A knowledge-base version has been built and passed quality checks.
3. The new version is published and the knowledge-base type is enabled.
4. NL2SQL and similar scenarios have rebuilt runtime caches or semantic indexes when required.
5. Content includes clear menu paths, field semantics, and relevant keywords.

See Knowledge Base and RAG.

5.3. Why is there no AI protocol-adaptation task entry, no parsing after upload, or code-package failure?

The current version starts protocol adaptation by uploading material in an AI conversation; no manual task creation is required. If parsing does not start, switch to "Protocol Parsing" mode and explicitly describe the protocol, messages, and codec objective.

Missing fields or code-package failures usually mean incomplete material. Add message directions, field tables, byte order, checksum algorithms, sample messages, and expected decoded results. See AI Protocol Adaptation.

5.4. Can AI-generated protocol code go directly into production?

No. Generated output is an aid, not a production-ready deliverable. It requires code review, compilation, unit tests, real-device integration, and business acceptance. Validate malformed messages, packet framing, checksum failures, device responses, and log boundaries.

See AI Protocol Adaptation.

5.5. How do I troubleshoot OAuth callback, token, userinfo, or single-logout problems?

• redirect_uri must exactly match the client configuration, including scheme, domain, port, path, and trailing slash.
• For token failures, check Client ID, Client Secret, authorization-code expiry, and grant mode.
• For empty userinfo, check token validity, user status, and scope.
• Before single logout, decide whether to log out of the third party, FastBee, or both, and apply one consistent policy.

See OAuth Single Sign-On.

5.6. Which mappings are required before Xiaodu can discover, query, or control devices?

Complete enterprise developer verification and configure the skill and HTTPS service address. Associate the FastBee product with a Xiaodu device type, then map Thing Models to Xiaodu properties, actions, and values.

Thing Model units must match Xiaodu property units. Configure mappings for enum values and associate object properties with corresponding child Thing Models. Refresh associations after model changes. See Smart Speaker.

5.7. How do I confirm a custom feature that is not explicitly covered in the documentation?

Define the business workflow, inputs/outputs, device protocol, and acceptance criteria, then compare them with the Platform Module Matrix. If configuration alone is insufficient, assess Rule Scripts, API integration, or secondary development instead of giving an unconditional supported/unsupported answer.