快速开始：部署、登录与首次检测

你准备如何开始？

在电脑上体验准备 Docker 与项目代码，用测试视频了解系统流程。使用预装设备连接设备，接入视频并启动随附任务。在自有边缘硬件上部署先确认平台与基础系统，再选择对应安装方式。

选择下面对应的步骤展开；电脑体验无需配置设备静态 IP。

项目	说明
适合谁	第一次部署或使用 CosmoEdge 的用户、实施人员和开发者
完成后能做什么	部署或连接系统，完成设备网络与时间设置，接入视频，分配算法并验证结果
使用前提	x86 主机已安装 Docker，Apple Silicon Mac 已准备 Docker Desktop Preview 环境，或已有预装 CosmoEdge 的边缘设备
预计时间	原生 x86 首次构建约 15–30 分钟；Mac amd64 仿真可能更久；预装设备约 15–25 分钟
是否需要设备	三选一：x86 Docker 主机、Apple Silicon Mac Preview，或预装 CosmoEdge 的边缘设备；首次检测不要求摄像机
最终验收结果	通道处于运行状态，实时展示出现算法叠加结果，事件中心可查询到符合规则的事件或统计结果

本页目标不是“把页面打开”，而是完成一次可验证的首次检测。完整路径是：

1. 选择 x86 Docker、macOS Preview 或边缘设备路径并让系统可访问。
2. 如果使用默认静态 IP 的边缘设备，先配置电脑 IP，再登录并调整设备网络与时间。
3. 接入一段离线测试视频。
4. 为视频分配一个场景任务并启动分析。
5. 在实时展示和事件中心验证结果。

默认密码修改、边缘设备网络设置和时间校对是正式使用前的必要操作；人流量统计示例属于完整补充练习，不阻塞“未戴安全帽”首次检测的验收。

1. 部署或连接系统

在电脑上体验：Linux、Windows、Mac Preview

1.1 路径 A：x86 主机使用 Docker

适用于 Linux x86_64 主机。Windows 用户使用仓库中的 docker-compose.x86.windows.yml。Apple Silicon Mac 使用下一节的独立 Preview 路径。

旧版教程记录过一套已验证环境：Ubuntu 22.04.2、Intel Core i9-13900F、64 GB 内存、 Docker 29.1.3 和 Docker Compose v5.1.4。它只是一次验证快照，不是最低配置要求；实际支持情况以仓库根目录的 README、当前 Compose 文件和目标模型资源占用为准。

Docker Compose V2 使用 docker compose。若环境仍安装独立的旧版 Compose，需要把命令中的 docker compose 替换为 docker-compose。

中国大陆网络建议从 Gitee 获取代码：

git clone https://gitee.com/cosmo-wander-ai/cosmo-edge.git
cd cosmo-edge

也可以从 GitHub 主仓获取：

git clone https://github.com/cosmo-wander-ai/cosmo-edge.git
cd cosmo-edge

Linux：

docker compose -f docker-compose.x86.yml up -d --build
docker compose -f docker-compose.x86.yml ps

Windows PowerShell：

docker compose -f docker-compose.x86.windows.yml up -d --build
docker compose -f docker-compose.x86.windows.yml ps

首次构建会下载依赖并编译，耗时取决于网络和主机性能。

成功状态：

• docker compose ... ps 中服务为 Up 或 running；
• 浏览器可以打开 http://127.0.0.1:8080；
• 远程访问时，将 127.0.0.1 替换为 x86 主机 IP，并确认主机防火墙允许 TCP 8080。

1.2 路径 B：Apple Silicon macOS Preview

如果尚未获取代码，先执行以下命令；已进入仓库目录则跳过：

git clone https://gitee.com/cosmo-wander-ai/cosmo-edge.git
# 也可使用 https://github.com/cosmo-wander-ai/cosmo-edge.git
cd cosmo-edge

Mac 使用隔离的 linux/amd64 Docker Preview。先阅读 Mac 准入、许可和能力边界，再运行：

./scripts/macos-docker-preview.sh doctor
./scripts/macos-docker-preview.sh up
./scripts/macos-docker-preview.sh status

成功后只从本机打开 http://127.0.0.1:8080。这条路径面向单路离线视频体验， 不是原生 macOS 二进制、Sophon/Rockchip NPU 部署或生产性能证据。

使用预装设备：连接网络与电源

1.3 路径 C：预装 CosmoEdge 的边缘设备

本节以 BM1688 预装设备演示首次连接。其他机型请按对应交付说明操作；完整平台支持与安装方式见平台支持表。下图为旧版教程使用的 BM1688 双网口设备，外壳、接口标识和参数以实际设备标签与交付清单为准。

旧版示例设备的标称配置如下，保留用于识别同型号设备，不把它作为所有 CosmoEdge 设备的通用要求：

硬件	旧版示例规格
处理器	Sophon BM1688
主控	8 核 ARM Cortex-A53，最高 1.6 GHz
内存	8 GB LPDDR4
存储	64 GB
AI 算力	标称 16 TOPS
网络	2 个 10/100/1000 Mbps 自适应网口
其他接口	USB 3.0 × 2、USB Type-C × 1、HDMI × 1、TF × 1、SIM × 1

开源软件无需购买设备。需要开箱即用的认证设备时，可查看 CosmoEdge-ready 认证设备；项目部署咨询可联系 hello@cosmowander.ai。

连接电源和网络

1. 用网线连接设备的以太网口与路由器、交换机或操作电脑。首次设置推荐电脑与设备直连，减少 DHCP、VLAN 和防火墙变量。

   

2. 连接设备匹配的电源适配器。

   

3. 通电后等待约 60 秒。示例设备启动完成时，PWR 指示灯常亮，网络指示灯在有数据传输时闪烁；不同机型的颜色和灯位以硬件说明为准。

   

   

为直连电脑配置静态 IP

默认地址不是 DHCP 地址

当前 BM1688 发行包的默认管理 IP 是 192.168.100.1，子网掩码是 255.255.255.0。电脑直连时必须先把电脑网卡设为同网段地址，例如 192.168.100.10/24。不要把电脑设为 192.168.100.1，否则会发生 IP 冲突。

Windows 操作路径：

1. 打开 设置或控制面板 → 网络和 Internet → 网络连接/更改适配器设置，找到与设备相连的以太网卡。

   

2. 打开该网卡属性，选择 Internet 协议版本 4（TCP/IPv4）。

   

3. 选择手动地址，填写一个未占用的 192.168.100.x 地址、子网掩码 255.255.255.0，然后保存。直连调试不要求填写默认网关和 DNS。

   

macOS 或 Linux 的目标相同：只修改与设备相连的网卡，为它配置一个未占用的 192.168.100.x/24 地址。保留原网络参数记录，完成设备网络迁移后再恢复。

在自有边缘硬件上部署

先查看平台支持与安装方式，确认目标芯片和基础系统，再按部署指南安装。安装包需要与芯片匹配；已准备好的 Linux 设备可以按对应安装步骤操作。软件安装包不是任意硬件的操作系统镜像。

安装后确认控制台可访问，并检查本例需要的模型与场景任务，再继续下面的登录和首次检测。

2. 登录并完成首次系统设置

2.1 打开登录页

• x86 本机：http://127.0.0.1:8080
• x86 远程主机：http://<主机 IP>:8080
• 默认 BM1688 设备：http://192.168.100.1
• 已修改网络的设备：http://<设备当前 IP>

推荐使用最新版 Chrome 或 Edge。初始账号为：

• 用户名：admin
• 密码：admin

登录后应进入系统首页或运行总览。首次登录完成后应修改默认密码。

系统首页可用于快速观察 CPU、内存或显存、NPU、存储和网络等资源指标。指标名称会随硬件后端变化；它们用于判断负载和健康状态，不等同于业务检测验收。

2.2 校对设备时间

告警查询、录像和日志都依赖正确时间。设备直连且不能访问 NTP 时，打开 系统管理 → 系统设置 → 时间设置，选择手动校时并使用 与计算机同步。 设备接入可联网局域网后，正式环境优先配置可达的 NTP 服务器。

成功状态：设备时间、时区与部署地点一致；随后产生的事件时间与操作电脑一致。

2.3 把设备 IP 迁移到业务局域网

若设备以后要同时访问摄像机、NTP 或外部服务，打开 系统管理 → 网络设置，把设备地址改为业务局域网中预留且未占用的固定 IP，并填写正确的子网掩码、网关和 DNS。

保存网络设置前：

1. 记录旧地址、新地址、掩码、网关和 DNS。
2. 确认新地址未被占用，并确认操作电脑能到达新网段。
3. 保存后等待网络服务重启，再用新地址重新登录。
4. 若电脑此前使用 192.168.100.x 直连地址，恢复电脑原有网络配置。

修改后旧地址会失效

网络设置生效后，192.168.100.1 通常不再可访问。不要立即恢复出厂设置；先把电脑切到新网段并访问新地址。

无法访问管理页时依次检查：电脑和设备是否同网段、网线和指示灯、电脑代理设置、地址是否冲突、浏览器访问的是 http 还是 https，以及本机是否同时存在优先级更高的 VPN 路由。

3. 添加测试视频

本例使用“未戴安全帽 / No Safety Helmet”场景任务，以及人员检测和安全帽分类两个模型。默认 x86 与 Mac Preview 构建使用仓库内的 ONNX 示例资源；Mac Preview 面向单路离线视频，不提供本地 VLM。预装设备请先按交付清单确认对应芯片的模型和场景任务。

如果任务列表中没有该场景，先查看模型资源说明，核对已安装资源与平台；使用自己的模型时按模型接入教程准备。模板文件本身不包含模型权重。

下载安全帽测试视频（MP4，19.1 MiB）

GitHub 固定版本备用下载。已克隆仓库的用户也可使用下面的本地文件。

仓库内提供可复现的安全帽测试素材：

data/test-video/Safety Helmet.mp4

已克隆仓库的用户直接使用该文件。只拿到设备的用户可从项目仓库的同一路径下载文件； 旧版教程还提供过 v1.0-videos 发布包，其中包含人流量统计演示素材。

1. 打开 视频接入。
2. 点击 添加。
3. 接入类型选择 离线视频。
4. 输入通道名称，例如“安全帽首次检测”。
5. 上传 Safety Helmet.mp4，然后保存。

成功状态：列表中出现新通道，并且没有持续显示连接、上传或解码错误。

使用摄像机是后续可选项

完成首次检测后，可把离线视频替换为 RTSP/RTSPS 网络视频源。先用本地素材排除网络、账号和摄像机编码差异，能更快确认系统本身是否正常。

4. 创建首次检测任务

1. 在新增通道的操作区进入 场景任务分配。

   

2. 页面包含三个主要区域：左侧是可选算法服务，中间是已分配服务及启停操作，右侧是所选服务的检测区域、参数和运行策略。不同版本的布局位置可能变化，但职责不变。

   

   

3. 从“所有服务”中选择 未戴安全帽。

4. 在 检测区域 中覆盖需要分析的主要作业区域。

5. 首次验证保持内置默认参数和运行策略。

6. 点击 保存。保存会创建通道与算法的关联并启动分析。

返回视频接入列表，确认通道运行开关已开启。

成功状态：

• 通道已关联“未戴安全帽”；
• 运行开关为开启或状态显示“进行中”；
• 页面没有持续出现启动失败提示。

5. 验证首次检测结果

5.1 实时展示

打开 实时展示。页面通常由通道列表、视频与算法叠加画面、实时事件列表组成， 并可切换单画面或多画面布局。

选择刚创建的通道，等待视频播放和模型初始化。

选择需要显示的算法叠加层。可见内容由 Pipeline 中的检测、追踪、规则和渲染能力决定。

安全帽示例的预期效果如下：

通过标准：

• 视频持续播放；
• 画面出现目标框、标签、追踪 ID、算法状态或统计值中的相应结果；
• 刷新页面后仍能重新进入该通道；
• 资源指标没有持续达到上限，通道没有反复重启。

5.2 事件中心

打开 事件中心，按通道、算法服务和时间范围查询。只有画面命中检测条件并满足告警时间、次数和去重规则时才会产生事件，因此“有实时框”与“有事件记录”是两个不同检查点。

补充：从源码构建 Sophon 升级包

如果需要从源码构建升级包，在仓库根目录通过 --chip <型号> 选项指定目标芯片：

# BM1688
./scripts/docker-compose.sh -f docker-compose.sophon.yml run --rm cosmo-sophon-package --chip bm1688

# CV186X
./scripts/docker-compose.sh -f docker-compose.sophon.yml run --rm cosmo-sophon-package --chip cv186x

find build_output/public-runtime -mindepth 2 -maxdepth 2 -type f -print

省略芯片型号参数时默认使用 bm1688。构建脚本会根据型号选择对应的模型资源目录， 无需手动填写模型路径。

构建包中的模型资源必须与目标芯片匹配；BM1688 与 CV186X 的产物不可互换。

把构建日志列出的唯一包名用于安装。需要通过 SSH 安装到已准备好的 Sophon Linux 设备时，请按部署指南：SSH 安装路径操作。文件传输、 解压、安装、重启、基础系统前提和恢复边界统一在该章节维护。

已有 CosmoEdge 正常运行时，也可以登录管理页面，进入 系统管理 → 系统维护 → 软件升级，选择同一个安装包并确认。升级期间保持供电；设备重启并 重新登录后，在设备信息中核对 软件版本 与安装包版本一致。SSH安装器面向已经准备好基础 系统的Sophon设备，并不是任意空白硬件的操作系统镜像安装器。

6. 完整补充示例：人流量统计

本节恢复旧版教程的人流量统计全流程。它用于理解“检测线、方向、追踪和统计结果”的关系； 如果当前资源中没有 人流量统计 服务，可以先完成前面的安全帽验收，再到 算法编排确认相应模板和模型是否已经导入。

6.1 准备通道并选择服务

1. 从仓库 v1.0-videos 标签的发布素材或自己的合法测试素材中选择一段有人穿过固定位置的视频。
2. 按第 3 节创建离线视频通道，例如“1 号教学楼东侧通道”。
3. 进入 场景任务分配，在 计数统计 分类中选择 人流量统计。

6.2 绘制检测线

人流量统计的关键区域不是多边形，而是一条带方向的检测线：

• 绘制：在画面中依次确定起点和终点；
• 方向切换：改变哪一侧穿越被计为进入或离开；
• 删除：移除错误的检测线后重新绘制。

点击 绘制，在业务位置先后点击两次确定检测线起点和终点。箭头方向用于区分进入和离开。

确认位置和方向正确后，点击 完成绘制。

6.3 设置离线视频运行策略

需要重复观察同一素材时，使用页面显示的 离线视频播放次数。表单允许 0–100： 0 表示无限循环，1–100 表示总播放次数。

保存并确认通道处于“进行中”。然后在实时展示中选择通道和 人流量统计 叠加层。 正常结果可能包含：

1. 行人类别与置信度；
2. 追踪目标 ID；
3. 相关算法节点耗时；
4. IN、OUT 等过线统计结果。

最后进入 事件中心 → 计数统计，按通道和算法服务查询。界面中的离开客流通常对应 OUT，净流入或进入统计对应 IN；以当前算法模板和页面字段为准。

7. 首次检测验收清单

• [ ] 已记录部署方式、当前访问地址和本次验证时间。
• [ ] x86 服务处于 Up/running，或边缘设备的电源和网络状态正常。
• [ ] 使用默认设备 IP 时，电脑已配置为不冲突的 192.168.100.x/24 地址。
• [ ] 已登录系统并修改默认密码；设备时间和时区正确。
• [ ] 设备迁移到业务网段后，可以通过新地址重新登录。
• [ ] Safety Helmet.mp4 已创建为离线视频通道。
• [ ] 通道已分配“未戴安全帽”任务并处于运行状态。
• [ ] 实时展示可以连续播放视频并显示算法结果。
• [ ] 使用命中规则的片段时，事件中心可以查询到对应事件。
• [ ] 若完成补充练习，检测线方向与 IN/OUT 统计结果一致。

以上与所选部署路径相关的项目全部完成，才算完成“首次检测”。

8. 常见问题

容器没有启动

按顺序检查：

docker compose -f docker-compose.x86.yml ps
docker compose -f docker-compose.x86.yml logs --tail=200
docker system df

确认 Docker 服务正在运行、磁盘空间足够、端口 8080 未被占用。更完整的入口见 故障排查。

默认设备地址打不开

1. 确认电脑网卡地址是未占用的 192.168.100.x/24，不是 192.168.100.1。
2. 临时关闭该网卡之外的 VPN 或代理，检查路由是否把 192.168.100.0/24 发往其他接口。
3. 电脑与设备直连，重新检查网线和网络指示灯。
4. 访问 http://192.168.100.1，不要自动改成 HTTPS。
5. 若设备地址曾被修改，使用记录的新地址，不要把恢复出厂设置作为第一步。

修改设备 IP 后失联

把电脑切换到新设备 IP 所在网段，再访问新地址；检查网关、掩码和地址冲突。 如果新旧地址都不可达，保留当前现场，不要连续断电或恢复出厂，先根据交付手册使用本地串口、显示器或维护入口核对网络配置。

登录页打不开或无法登录

1. x86 部署确认访问的是主机端口 8080，不是容器内部端口。
2. 远程访问检查主机 IP、防火墙和网段。
3. 首次登录使用 admin / admin；若密码已修改，使用新密码而不是重建容器。
4. 登录成功但页面时间异常时，先校对时间，再排查证书或会话过期问题。

视频保存后没有画面

按“文件可读 → 通道状态 → 解码日志 → 算法状态”的顺序检查：

1. 先使用仓库内的 MP4，避免同时排查 RTSP 网络问题。
2. 确认视频上传完成且通道已启用。
3. 查看服务日志中是否有文件读取、编码格式或解码错误。
4. 若实时视频正常但无算法叠加，重新检查场景任务是否已经保存并运行。

有检测框但没有事件

这通常不是连接故障。确认测试片段确实命中规则，再检查告警时间间隔、告警次数、 检测持续时间和静止目标去重。下一篇将逐项解释这些设置。

人流量统计方向相反或数值不更新

1. 使用 方向切换 校正检测线箭头。
2. 确认行人完整穿过检测线，而不是只在线的一侧移动。
3. 确认追踪 ID 在穿线过程中连续，没有因遮挡或目标过小反复变化。
4. 重新点击查询刷新统计结果，并检查所选通道、算法和时间范围。

下一步

继续阅读场景任务配置，学习如何精确设置检测区域、参数、运行策略和告警规则。