卸载与清理#
卸载（保留数据）与清理（删除数据）#
彻底卸载会清理安装目录下的 depends / libs / models / videos / font.ttf / mysql_data / minio_data 及运行期生成的 socket/pid 等非包登记文件；config.yaml 由主应用生成，归 zhimou-openapi 卸载时清理。
运维工具：zhimou_openapi 命令行#
主应用可执行文件位于 /opt/zhimou/zhimou_openapi（自定义 prefix 时在 $PREFIX/zhimou_openapi）。执行运维工具前必须先 cd 进入安装目录（程序依赖当前工作目录读取配置与数据），以下所有示例都以 cd /opt/zhimou 开头。不带任何参数即启动 HTTP 服务（常驻）；查询/维护/安装类参数执行完对应动作后退出。信息查询#
服务管理（对应 systemd 单元 zhimou_openapi）#
| 参数 | 说明 |
|---|
-service <命令> | start | stop | restart | log |
-n <N> | 配合 -service log：显示最近 N 行（默认 100） |
-f | 配合 -service log：持续跟踪日志 |
密钥维护#
-factory-reset 会清空全部用户数据与授权且不可恢复，执行前请务必确认。
安装授权码与应用包#
以下命令经本机回环调用运行中的服务，执行时会交互式输入 appsecret：
主应用配置文件 config.yaml#
主应用 zhimou_openapi 启动时读取当前工作目录下的 config.yaml（默认安装即 /opt/zhimou/config.yaml）。首次启动若文件不存在，会按代码内置默认值自动生成一份，权限固定 0600（文件内含 MinIO / MQTT 明文凭证，勿放宽权限或外传）。默认生成的 config.yaml（gb28181 / dji_api2 可选段分别见 国标接入 与 上云API2接入）：顶层配置项#
| 字段 | 缺省值 | 说明 | 填错的典型现象 |
|---|
http_bind | 0.0.0.0 | API 服务监听地址（端口即「端口说明」中的 10042） | 改成 127.0.0.1 后客户端无法访问；改端口后客户端与防火墙需同步调整 |
http_port | 10042 | API 服务监听端口 | 与既有进程撞端口启动失败；网页首屏配置也会带上此端口供播放地址拼接 |
internal_ip | 127.0.0.1 | 本机对内可达 IP。接口返回的内部播放地址（http-flv / WHEP）用 internal_ip:http_port 拼接，图片直连地址也基于它 | 跨机访问时留 127.0.0.1，客户端会拿到指向自己的地址而无法播放（网页控制台在平台上浏览不受影响） |
external_url | http://127.0.0.1:10042 | 平台对外访问基址（含 scheme，不带尾部 /）。外部播放地址与事件图片 URL 由它派生 | 经域名 / NAT 对外服务时须填对外真实地址，否则回调与外链里是内网地址，客户端不可达 |
max_task_store | 1000 | 历史任务保留上限，超出的已停任务由定时清理删除（连带记录与对象存储目录）；≤0 关闭清理 | 设太小会过早丢失历史记录；设 0 不清理，数据库持续增长 |
media 段 — 流媒体（SRS）地址#
| 字段 | 缺省值 | 说明 |
|---|
internal_rtmp | rtmp://127.0.0.1:11935 | 内部 RTMP 推流基址：ailive 未指定 output_url 时向它推流，直播接口返回的内部地址基于它拼接。 |
external_rtmp | rtmp://127.0.0.1:11935 | 外部 RTMP 基址：直播接口返回给客户端的推 / 拉流地址用；跨机 / NAT 场景须填客户端可达的地址。 |
web_url | http://127.0.0.1:11980 | SRS HTTP 服务地址（对应本机端口 11980），网页预览播放器拉流用；仅手动编辑 + 重启生效 |
api_url | http://127.0.0.1:11985 | SRS API 地址（对应本机端口 11985），进程内接口调用用；仅手动编辑 + 重启生效 |
minio / mqtt / report / datahub 段#
| 字段 | 缺省值 | 说明 |
|---|
minio.endpoint | 127.0.0.1:19000 | 对象存储 MinIO 地址（host:port，不带 scheme），默认即本机 openapi_minio |
minio.access_key / secret_key | minioadmin / openapi@zhimou | MinIO 凭证，须与 openapi_minio 服务实际凭证一致 |
minio.bucket | openapi | 存储桶名，不存在时自动创建 |
minio.region | 空 | 留空即可；仅对接非 MinIO 的 S3 兼容存储（如 OSS）时才需要 |
minio.use_ssl | false | 是否以 https 访问 MinIO；本机回环部署保持 false |
mqtt.enable | true | 关闭后不连 broker，事件不再走 MQTT 发布 |
mqtt.broker_host / broker_port | 127.0.0.1 / 11883 | MQTT broker 地址，默认即本机 openapi_nanomq 的 TCP 端口 |
mqtt.client_id | openapi_client | 客户端 ID，同机多实例部署时需互不相同 |
mqtt.username / password | openapi / openapi@zhimou | 连接 broker 的凭证，须与 nanomq 侧配置一致 |
mqtt.lwt.* | 全关闭（enable: false） | 遗嘱消息（Last Will），高级可选项，无特殊需求保持默认即可 |
report.http.url | 空 | 事件 HTTP 回调地址，空 = 不做 HTTP 回调； |
report.http.retry | 3 | HTTP 回调失败重试次数 |
report.mqtt.topic | /openapi/event | 事件 MQTT 发布主题，订阅侧与此对齐； |
datahub.enable | false | 回传开关：开启后任务消息 / 快照 / 平台信息同步到数据云用于模型优化，无相关需求保持关闭； |
gb28181 段（GB28181 国标视频接入）与 dji_api2 段（大疆上云 API / FlightHub PaaS 对接）默认关闭，配置项与接入步骤分别见 国标接入 与 上云API2接入。
常见问题排查#
服务未起来：按依赖链顺序检查，前置任一服务未就绪都会影响主应用。 API 无响应：确认 10042 端口已监听且未被占用。 WHEP 播放一直停在“连接中”/ WHIP 推流建不起来 ：先看 18000 的 UDP 是否在监听、防火墙是否同时放行了 udp 与 tcp；再看客户端拿到的 candidate 地址能不能直连（跨机 / NAT / 容器场景需改 candidate，见前文「WebRTC 地址下发（candidate）」）。
端口被占用：一键脚本安装前会检查这些端口（TCP 用 ss -ltn，WebRTC 的 18000 另查 ss -lun），任一端口被占用即中止安装（不会带着冲突继续装），并打印是哪个端口（18000/tcp 与 18000/udp 分开报）。需先排查并停止占用进程（常见为旧版本服务仍在运行）后重试；确认是旧版本包占用可加 --force-new-install 全新安装。对外开放端口（10042/11883/18083/11935/18000）还需在防火墙 / 安全组放行（18000 需 udp 与 tcp 都放行），本地监听端口（19000/13306/11985/11980）无需放行。
openapi-depends 安装报依赖缺失（deb / rpm）：MySQL 运行需宿主机提供 libaio（deb 包名 libaio1，24.04 为 libaio1t64；rpm 为 libaio）、libnuma1、libncurses6、libtinfo6（rpm 侧为对应同名库）；一键脚本会自动尝试安装 libaio，若包已装但 libaio.so.1 链接丢失，会先 ldconfig、再按发行版用 apt 或 yum/dnf 重装修复。
openapi-depends 安装报 exit status 127（deb 的 postinst / rpm 的 %post）：安装期的 MySQL 冒烟检查未通过。127 是动态链接器找不到依赖库时的固定退出码，最常见的是 libaio 包已安装、但 libaio.so.1 链接丢失（目录里只剩 libaio.so.1.0.1，ldconfig 解析不到 soname）。先确认再修复，然后重装：deb 侧修复前不应用 dpkg --configure -a 重试：冒烟检查失败说明 mysqld 连 --version 都跑不起来，重配只会重复失败；rpm 侧 %post 是宽容模式，修好 libaio 后直接 rpm -Uvh --replacepkgs openapi-depends-*.rpm 重装即可（数据保留）。 