司空2私有化与一体机常见问题及排障指南

2026 Q1

01. 私有化部署核心问题 Pure Software

核心挑战：服务器环境 · 资源调度 · 授权与多用户管理

部署环境与系统兼容性

服务器环境配置不当是私有化部署失败的首要原因，需严格遵循硬件与系统要求。

容器启动失败 (es-management / tas-service Unhealthy)

根因：机械硬盘IO性能不足导致容器启动超时。
解决方案：核心服务必须部署在SSD上，严禁使用机械硬盘。建议采用NVMe SSD以获得最佳IO性能。

依赖缺失报错 (缺少 gdm3)

现象：安装时提示缺少 gdm3 或无法读取 /etc/gdm/custom.conf。

解决方案：补全依赖组件。

sudo apt update && sudo apt install gdm3 -y

K8s/环境冲突

现象：与现有 K3s/OpenShift 环境冲突，导致安装中断。
解决方案：若已有K3s环境，使用 --skip_serverless 参数跳过内置K3s安装；严格核对env文件中的IP、端口及存储路径。

最佳实践：可以先使用试用版本进行部署，验证司空与服务器的适配性。

资源调度与高性能场景

大规模设备接入与建模任务对服务器资源提出严峻挑战。

设备规模	CPU	内存	GPU推荐
50台设备 (基础)	16C	64GB	RTX 3060
100台设备 (推荐)	32C	128GB	RTX 4090
500+台 (企业级)	集群部署 · 负载均衡 · 分布式存储

建模任务失败 (OOM / 进度卡住)

解决方案：

参考官方配置表，按设备数量线性增加资源。

重启建模容器释放显存：

cd terracloud-privatization-deployment
docker compose restart

RabbitMQ连接堆积

解决方案：清理连接并重启服务。

docker logs file-storage | grep ERROR
docker restart rabbitmq

License授权管理

License读取失败 (错误码101/200)

解决方案：进入容器内部启动 codemeter 服务或重启授权服务。

docker exec -it [容器ID] /bin/bash
./run_server.sh
# 或宿主机执行
systemctl restart codemeter

"设备已达上限"误报

解决方案：执行SQL命令重置设备在线状态（清除僵尸记录）。

UPDATE devices SET online_status = 0;
UPDATE ThingAccessService.devices SET online_status = 0;

02. 一体机硬件与系统 AIO Hardware

核心挑战：硬件稳定性 · 网络配置 · 系统维护

硬件系统与底层稳定性

系统无法启动 / 黑屏

根因：运输震动导致显卡/网卡接触不良。
解决方案：重新插拔显卡/网卡确保接触良好；联系联想售后修复。

IP地址丢失 / 还原为DHCP

解决方案：修改NetworkManager配置以固化静态IP。

# 1. 编辑配置文件
vim /etc/NetworkManager/conf.d/unmanaged.conf
# 2. 删除第2行后面的所有内容，保存
# 3. 重启服务
sudo systemctl restart NetworkManager
# 4. 验证状态
systemctl status NetworkManager

注意：重装系统后务必升级Linux内核以匹配硬件驱动（特别是WiFi模块）。

网络配置与接口管理

网络配置不同步、端口拦截、NAT规则错误是一体机网络问题的三大根源。

LAN/WAN口不通 / 机场无法上云

解决方案：

修改内网IP后，必须更新ENV文件并执行重启命令：

vi /opt/fhaio/.env  # 修改IP配置
./setuptools update  # 更新服务使配置生效

确保核心端口全程畅通：TCP 30812 (信令), UDP 8000 (媒体流)。

网络拓扑建议：一体机LAN口下接独立交换机，连接机场/遥控器，避免与办公网络混用。

内置服务与维护操作

升级失败 / 版本回退

规范升级：严格在指定目录下执行脚本。

cd /fhaio-install/upgrade/
./setuptools update

时间/时区设置无效

解决方案：执行环境初始化命令。

locale-gen en_US.UTF-8
dpkg-reconfigure locales

严重警告：恢复出厂设置会清空所有数据卷（包括媒体文件、航线数据）。操作前务必备份 /data 目录！

tar -czvf backup.tar.gz /data/

授权扩容与设备管理

扩容激活失败 / 断电后授权丢失

解决方案：导入新License或异常断电后，必须重启一体机或执行重启命令使仲裁服务生效。

./setuptools restart
# 或
reboot

03. 通用场景专项排查 Common Scenarios

适用场景：私有化部署 & 一体机

直播推流专项排查

核心结论：90%的直播黑屏/超时问题源于 UDP 8000 端口被防火墙拦截。

排查步骤

端口测试：使用 nc 命令验证UDP连通性。

# 服务器端监听
nc -u -l 8000
# 客户端发送测试包
echo "test" | nc -u [服务器IP] 8000

配置清理：检查MySQL/Redis，删除重复的RTMP推流配置记录。
协议确认：确认直播源是SRS(接收)还是ZLM(转推)，检查对应容器日志。
临时方案：若WebRTC持续失败，可修改env文件关闭WebRTC，强制使用RTMP：
```
WEBRTC_ENABLE=false
```

媒体存储与上传专项

删除文件后空间未释放

机制说明：司空2采用软删除机制，删除文件仅标记状态，实际数据仍保留。

解决方案：执行官方底层清理脚本释放空间。

./cleanup.sh

桥接状态检查

检查命令：

docker exec -it [redis容器ID] redis-cli
GET bridge_enabled

发布高程与地图专项

高程导入成功但地图不显示红框

根因：公有云环境下，INTERNAL_IP 误配为公网IP，导致内部服务超时。
解决方案：
1. 获取服务器内网IP (ip a | more)。
2. 修改 env 文件中的 INTERNAL_IP 为内网IP。
3. 执行 ./setuptools update 重启服务。

地图加载提示"跨域访问被拒绝"

解决方案：修改 Nginx 配置添加 CORS 头。

# 编辑 asset-map-nginx.conf
add_header 'Access-Control-Allow-Origin' '*';
add_header 'Access-Control-Allow-Methods' 'GET, POST, OPTIONS, PUT, DELETE, PATCH, HEAD, TRACE';
add_header 'Access-Control-Max-Age' '100';
# 重启服务
docker restart

04. 运维最佳实践

运维核心原则

硬件红线：私有化必须用SSD；一体机严禁强制断电。
网络优先：遇到直播/接入问题，第一动作检查 TCP 30812 和 UDP 8000。
变更管理：改IP → 改ENV → 重启服务；导License → 重启生效。
数据安全：删除文件≠释放空间（需脚本）；恢复出厂=数据清零（需备份）。

常用命令速查

# 重置设备在线状态 (解决上限误报)
UPDATE ThingAccessService.devices SET online_status = 0;

# 重启服务
./setuptools restart

# 清理存储空间
./cleanup.sh

# 网络测试
nc -u -l 8000
telnet [IP] 30812

# 查看容器状态
docker compose ls
docker ps -a | grep -v Up

# 下载日志
./setuptools log download --type=all --last-days=1

排障工具与资源

AI小助手：访问开发者网站。
FAQ知识库：https://fh2-faq.apifox.cn/
ENV查看：cat .env (在安装包目录下)