平台功能与运维
平台功能排错应先确认版本和模块是否已购买/启用，再区分配置、数据、权限、定时任务和第三方服务问题。完整操作步骤以各模块文档为准。
1. 账号、权限与运行性能
1.1. 多租户、机构、角色和数据权限有什么关系？
机构即租户，用于隔离产品、设备、场景、工单等数据；角色决定菜单、按钮和数据范围；上下级机构影响可管理的数据边界。终端用户通常用于 App/小程序绑定设备，租户用户用于 Web 后台管理。
“看不到数据”与“看不到菜单”是不同问题，应分别检查数据权限和角色菜单权限。详见 多租户操作 和 系统管理总览。
1.2. 用户看不到菜单、按钮、设备、产品或场景怎么办？
- 菜单不可见：检查角色菜单授权、菜单状态和用户是否重新登录。
- 按钮不可见：检查按钮权限标识、角色授权和前后端权限控制。
- 设备/产品/场景不可见：检查机构关系、数据权限、设备分配、产品私有状态和创建人所属机构。
不要通过直接授予超级管理员来绕过问题，应使用目标角色的测试账号验证最小权限。详见 系统管理总览。
1.3. 系统名称、机构名称、Logo 和密码在哪里修改？
系统基础信息和 Logo 优先在系统参数、个人中心或对应机构配置中修改；机构名称在机构管理中维护；用户密码通过个人中心或管理员的用户管理流程修改，不需要搜索源码修改默认密码。
不同版本菜单可能略有差异，修改后使用普通账号验证显示和权限。参考 系统管理总览 和 多租户操作。
1.4. 默认账号、数据源监控账号和交付账号如何安全处理？
初始账号只用于首次部署验收，交付后应立即修改默认密码，并按角色创建实际使用账号。数据源监控、EMQX、数据库和私有仓库账号不要共用同一密码，也不要把私有仓库初始密码或测试租户凭据发布到公开文档和群组。
生产环境还应限制 Druid、EMQX 等管理入口的网络暴露。部署账号说明见 Docker 快速部署。
1.5. 页面慢、接口超时、消息积压或数据库压力高先看哪些指标？
按链路收集指标：
- 页面慢：静态资源体积、Nginx 缓存、浏览器网络瀑布和接口耗时。
- 接口超时：Java 线程池、慢 SQL、Redis 慢命令和外部服务回调。
- 消息积压：Broker 吞吐、规则耗时、数据库写入和消费者并发。
- JVM 频繁 GC：堆大小、对象分配、缓存对象和大结果集。
- 数据库压力高：索引、锁等待、事务范围、热点表和归档策略。
先确认瓶颈再扩容，不要同时调整所有参数。详见 性能优化。
1.6. 日志路径、上传路径、磁盘不足和接口异常如何排查？
先查看后端最早根因，确认日志/上传目录是否存在且可写，再检查磁盘空间、文件权限、Nginx 代理和数据库连接。Linux 可使用 df -h、free -h、ss -lntup 辅助检查。
清理文件前先区分应用日志、业务上传、数据库文件和备份，不要直接删除业务数据。巡检命令见 运维监控。
2. 报表、工单与维保
2.1. 报表没有生成或报表为空怎么办？
没有生成时检查报表规则状态、执行时间、服务器时间和定时任务；报表为空时检查所选时间范围内是否有设备上报、变量是否开启历史存储，以及统计方式是否适合当前数据。
“运行状态有实时值”不代表所选历史时间段内一定有可聚合数据。详见 数据中心。
2.2. 报表下载链接打不开或邮件没有收到怎么办？
下载链接检查服务器域名、Nginx 转发、文件存储路径和通知模板中的地址；邮件检查通知渠道、模板启用状态、用户邮箱、发送日志和邮件服务商限制。
先确认报表文件本身已生成并可从后台下载，再排查通知链路。详见 数据中心 和 消息通知。
2.3. 告警或维保没有自动生成工单，或生成重复工单怎么办？
告警未生成工单时，检查告警配置是否启用“生成工单”、关联场景是否触发，以及告警执行次数限制。维保未生成时，检查维保开始时间、周期、提前派工时间和定时任务。
重复工单要检查同一设备是否有多个维保计划；集群环境还要确认定时任务是否被多个节点重复调度。详见 工单管理 和 设备维保。
2.4. 普通用户看不到工单或联系人收不到通知怎么办？
看不到工单时，检查租户、角色、数据权限、设备分配关系，以及用户是否为工单联系人。联系人收不到通知时，检查其用户资料中的邮箱、通知模板、渠道和发送日志。
详见 工单管理。
3. 物联网卡与对象存储
3.1. 新增 SIM 卡失败或卡平台信息不同步怎么办？
检查卡平台 API 地址、账号密钥、服务器 IP 白名单、ICCID 是否存在，以及运营商平台是否开放接口。信息不同步时，再检查定时任务、平台接口可用性和限流。
详见 物联网卡管理。
3.2. 设备上报 ICCID 后没有自动绑卡怎么办？
检查 /info/post 报文中的 iccid 和 cardPlatformId，确认平台能否同步到该卡以及设备上报是否被成功处理。未提供平台编号时，系统会按当前实现尝试匹配卡平台，但仍以卡数据可同步为前提。
3.3. 物联网卡流量告警没有发送怎么办？
检查流量阈值、通知用户、通知模板和渠道，并确认卡用量已成功同步。平台没有获取到最新用量时，不会仅因运营商侧超量而自动产生准确告警。
详见 物联网卡管理。
3.4. OSS/S3 兼容存储上传失败、访问 403 或录像未上传怎么办？
- 上传失败：检查 AccessKey、SecretKey、Bucket、地域、Endpoint、服务商类型和网络。
- 上传后 403：检查存储桶读权限、对象 ACL、自定义域名和防盗链。
- 录像未上传：检查监控设备录像开关、录像服务、ZLM Hook 和 OSS 配置。
先用平台测试上传验证存储，再排查录像链路。详见 录像 OSS 配置。
4. 可视化、组态与移动端
4.1. 可视化大屏与 Web 组态有什么区别？
可视化大屏主要用于数据展示，动态数据通常通过接口查询；Web 组态可直接绑定物模型或场景变量，通过实时消息刷新，并可配置控制组件向设备下发指令。Web 组态属于单独选购模块。
升级平台时，应按发布说明同步替换主系统、可视化与组态资源，并保持组态模块与主系统版本匹配。V2.9 起可视化已整合到商业版主项目，不要继续照搬旧独立目录的升级方式；升级后验证项目、接口、变量绑定和控制链路。详见 可视化大屏、组态管理 和 发布说明。
4.2. 大屏发布后空白、跨域、数据格式不匹配或页面卡顿怎么办？
空白页检查部署目录、Nginx location、资源 404 和接口地址；跨域检查前端代理、后端 CORS、Nginx 以及 HTTP/HTTPS 混用；数据格式问题使用过滤器转换为组件需要的结构。
卡顿时降低刷新频率、减少高频图表和同时播放的视频、压缩图片并控制组件数量。详见 可视化大屏。
4.3. 组态变量没有值、控制按钮无效或素材加载失败怎么办？
变量无值时检查产品/场景绑定、变量来源、物模型标识符、设备在线和上报；控制无效时检查物模型可写性、设备在线、设备端处理逻辑和用户权限。
图片或 3D 模型加载失败时，检查素材是否删除、路径、文件大小、跨域和静态资源服务。详见 组态管理。
4.4. 组态分享链接打不开、点击无反应或脚本/显隐异常怎么办？
分享链接检查分享是否启用、密码、组态是否删除、访问域名和 Nginx 转发。点击事件检查组件遮挡、事件启用状态、目标组件或变量是否存在。
脚本报错检查空值、字段名、组件 ID 和浏览器语法兼容性；显隐错乱检查分组、事件顺序和默认状态。详见 组态快速搭建 和 组态事件与脚本。
4.5. 移动端自定义设备面板为什么不显示？
设备面板由产品决定，不是逐台设备独立配置。进入产品详情的应用配置，完成面板编辑并保存后，还要启用自定义面板；停用时会显示系统默认状态面板。
同时检查组件类型是否与物模型数据类型、只读和图表属性匹配。详见 手机设备面板。
4.6. 移动端如何打包发布，微信小程序为什么需要 HTTPS 和合规域名？
使用 HBuilderX 按目标选择原生 App、H5 或微信小程序发行。微信小程序需要按微信要求配置合法域名、HTTPS 和相应证书，不能直接把普通 HTTP/IP 地址当作正式发布环境。
打包后还需在对应环境验证接口、MQTT WebSocket、视频和第三方 SDK。详见 移动端发布。
4.7. App 检测不到新版本、WGT 安装失败或 iOS 无法热更新怎么办？
检测不到新版本时，检查目标版本号是否大于客户端当前版本、App 请求环境和版本启用状态。WGT 安装失败时，检查其与当前 App 基座是否兼容，以及是否修改了必须重新打包安装包的原生能力。
iOS 应遵循 App Store 或企业签名流程，不按 Android WGT 的方式处理。详见 App 版本管理。
5. AI、OAuth 与智能音箱
5.1. AI 返回鉴权失败或模型不可用怎么办？
检查厂商状态、API Base URL、鉴权方式、API Key、模型名称、模型权限和额度。内网模型还要确认后端到模型服务的网络、端口和访问路径。
生产与测试环境建议使用不同密钥，不要把包含密钥的截图或日志发送到公开群组。详见 模型厂商配置。
5.2. 知识库上传解析成功后，为什么 AI 仍使用旧内容或没有命中知识？
上传并解析成功只表示资料可用于构建，不代表已经发布到运行态。继续检查：
- 新文档是否启用，旧文档是否仍同时启用。
- 是否已构建知识库版本并通过质量检查。
- 新版本是否已发布，知识库类型是否启用。
- NL2SQL 等场景是否需要重建运行态缓存或语义索引。
- 资料是否包含足够明确的菜单路径、字段语义和关键词。
详见 知识库与 RAG。
5.3. AI 协议适配没有任务入口、上传后未解析或代码包失败怎么办？
当前版本由 AI 会话上传资料触发协议适配，不需要手动创建任务。上传后未进入解析时，切换到“协议解析”模式，并在需求中明确协议、报文和编解码目标。
字段缺失或代码包失败通常意味着资料不完整，应补充报文方向、字段表、字节序、校验算法、样例报文和预期解析结果。详见 AI 协议适配。
5.4. AI 生成的协议代码可以直接上线吗？
不能。生成内容是辅助产物，上线前必须完成代码审查、编译、单元测试、真实设备联调和业务验收。尤其要验证异常报文、拆包粘包、校验失败、设备应答和日志边界。
详见 AI 协议适配。
5.5. OAuth 回调、Token、用户信息或单点退出异常怎么办？
redirect_uri必须与客户端配置完全一致，包括协议、域名、端口、路径和末尾斜杠。- Token 获取失败时，检查 Client ID、Client Secret、授权码有效期和授权模式。
- 用户信息为空时，检查 Token、用户状态和 scope。
- 单点退出前明确只退出第三方、只退出 FastBee，还是两边都退出，并统一策略。
详见 OAuth 单点登录。
5.6. 小度音箱发现、查询或控制设备前需要哪些映射？
需要完成企业开发者认证、技能与 HTTPS 服务地址配置，并将 FastBee 产品关联到小度设备类型。物模型还要分别映射小度属性、动作和值。
物模型单位应与小度属性一致；枚举值要配置映射，对象属性要关联对应的子物模型。修改物模型后按文档刷新关联。详见 智能音箱。
5.7. 文档没有明确覆盖的个性化功能如何确认？
先整理具体业务流程、输入输出、设备协议和验收标准，再对照 平台模块总览 判断现有能力。无法通过配置实现的部分，再评估规则脚本、接口集成或二次开发，不把个别需求直接回答为必然支持或必然不支持。