Kerberos 代理

Docker Hub | 文档 | 官网 | 查看演示

在继续之前，请注意，此仓库深入讨论了 Kerberos.io 技术栈中的一个组件——Kerberos 代理。如果您正在寻找端到端的部署指南，请参阅此处：[https://github.com/kerberos-io/deployment]。

Kerberos 代理是一款隔离且可扩展的视频（监控）管理代理，以 MIT 许可证开源发布。这意味着所有源代码均可供您或您的公司使用，并且您可以自由地使用、修改和分发这些源代码，只要保留原始许可证的引用即可。Kerberos 代理可用于商业用途（而 v2 版本则不支持）。更多关于许可证的信息，请参阅 [LICENSE 文件]。

:thinking: 前提条件

• 一台支持 RTSP H264 或 H265 编码流的 IP 摄像头，
  • （或者）一台 USB 摄像头、树莓派摄像头或其他摄像头，您可以将其转换为有效的 RTSP H264 或 H265 流 [参考：https://github.com/kerberos-io/camera-to-rtsp]。
• 任何能够运行二进制文件或容器的硬件设备（ARMv6、ARMv7、ARM64、AMD64），例如：树莓派、NVIDIA Jetson、Intel NUC、虚拟机、裸金属服务器或完整的 Kubernetes 集群。

:video_camera: 我的摄像头能正常工作吗？

市面上有各种各样的摄像头（USB、IP 等），很难判断 Kerberos 代理是否适用于您的设备。因此，我们列出了社区已确认兼容的摄像头型号 [参见：https://github.com/kerberos-io/agent/issues/59]。欢迎您也将自己的摄像头加入列表！

:books: 概述

快速上手

1. 快速入门 - Docker
2. 快速入门 - Balena
3. 快速入门 - Snap

简介

1. Kerberos 代理的世界

运行与自动化

1. 如何运行和部署 Kerberos 代理
2. 访问 Kerberos 代理
3. 通过卷挂载进行配置和持久化
4. 使用环境变量进行配置

深入了解

1. 加密
2. H264 与 H265 的区别

贡献

1. 通过 Codespaces 贡献
2. 开发与构建
3. 从源码构建
4. 为 Docker 构建

其他

1. 支持我们的项目
2. 最新动态
3. 贡献者

快速入门 - Docker

让您的 Kerberos 代理快速启动并运行的最简单方法是使用我们在 Docker Hub 上发布的公共镜像。选择特定标签后，运行以下 docker 命令，它将在端口 80 上打开您的 Kerberos 代理的 Web 界面，随后您就可以开始使用了。如需更灵活且持久化的部署，请参阅 运行与自动化 Kerberos 代理。

docker run -p 80:80 --name mycamera -d --restart=always kerberos/agent:latest

如果您想连接 USB 或树莓派摄像头，您需要运行我们的辅助容器 [https://github.com/kerberos-io/camera-to-rtsp]，该容器会将摄像头信号代理为 RTSP 流。在这种情况下，您需要将 Kerberos 代理容器配置为在主机网络中运行，以便直接连接到 RTSP 辅助容器。

docker run --network=host --name mycamera -d --restart=always kerberos/agent:latest

快速入门 - Balena

借助 Balena Cloud 的强大功能运行 Kerberos 代理。通过无缝的远程访问、空中更新、加密的公共 https 端点等功能，轻松监控您的 Kerberos 代理。请查看我们在 Balena Hub 上的应用程序“视频监控”，并创建您的第一个或多个 Kerberos 代理实例。

快速入门 - Snap

使用我们的 Snapcraft 软件包 运行 Kerberos Agent。

 snap install kerberosio

安装完成后，您可以在 /var/snap/kerberosio/common 找到 Kerberos Agent 的配置文件。按照以下方式运行 Kerberos Agent：

sudo kerberosio.agent -action=run -port=80

一个充满 Kerberos Agent 的世界

Kerberos Agent 是一款隔离且可扩展的视频（监控）管理代理，专注于用户体验、可扩展性、鲁棒性、扩展性和集成能力。除了 Kerberos Agent 外，Kerberos.io 还提供了许多其他工具，如 Kerberos Factory、Kerberos Vault 和 Kerberos Hub，以提供额外的功能：自定义云环境、自定义存储、集中概览、实时流媒体、机器学习等。

如上所述，Kerberos.io 采用了代理的概念。代理运行在您的摄像头旁边（或设备上），处理单个摄像头的视频流。它支持基于运动检测或连续录制，并通过用户友好的 Web 界面提供这些录像。Kerberos Agent 允许您连接到其他云服务或与自定义应用程序集成。Kerberos Agent 既可用于个人应用，也能扩展到企业级生产部署。更多关于 部署策略的信息请参见此处.

本仓库包含了您需要了解的关于我们核心产品 Kerberos Agent 的所有内容。以下是其主要特性和功能的简要列表：

• 低内存和 CPU 使用率。
• 简洁现代的用户界面。
• 多架构支持（ARMv6、ARMv7、ARM64、AMD64）。
• 多路流支持，例如以 H265 格式录制、以 H264 格式进行直播和运动检测。
• 多摄像头支持：IP 摄像头（H264 和 H265）、USB 摄像头以及树莓派摄像头 通过 RTSP 代理。
• 每个实例仅管理一台摄像头（例如，每个容器对应一台摄像头）。
• 通过 MQTT 提供低分辨率流媒体，通过 WebRTC 提供高分辨率流媒体（仅支持 H264/PCM 格式）。
• 从 Kerberos Hub 向 IP 摄像头发送回传音频（需 PCM ULAW 编解码器）。
• 支持以 MP4 容器格式录制音频（AAC）和视频（H264/H265）。
• 通过 MQTT 使用 RSA 和 AES 实现端到端加密（用于直播、ONVIF 协议、远程配置等）。
• 条件录制：离线模式、运动区域、时间表、连续录制、Webhook 触发条件等。
• 运动检测时的前后录制功能。
• 使用 AES-256-CBC 对静态数据进行加密。
• 支持创建分段录制，并通过 HLS fMP4 格式进行流媒体传输。
• 可根据需求选择合适的部署方式 参见如何运行和部署 Kerberos Agent，并结合您常用的工具：docker、docker compose、ansible、terraform、kubernetes 等。
• 云存储/持久化：Kerberos Hub、Kerberos Vault 和 Dropbox。(正在进行中：Minio、Storj、Google Drive、FTP 等)
• 输出功能：当特定事件（如运动检测或开始录制）发生时，触发集成（Webhooks、MQTT、脚本等）。
• 通过 Swagger 提供 REST API 访问及文档（如触发录制、更新配置等）。
• MIT 许可证

如何运行和部署 Kerberos Agent

如前所述，Kerberos Agent 是一个容器。您可以使用多种方法和自动化工具对其进行部署，包括 docker、docker compose、kubernetes 等。为了简化您的 Kerberos.io 使用体验，我们提供了具体的部署示例，帮助您更快地开始使用 Kerberos.io。

我们已在本仓库的 deployments 目录 中记录了不同的部署模式。您可以在其中学习并找到以下部署方式：

• 静态二进制文件
• Docker
• Docker Compose
• Kubernetes
• Red Hat OpenShift 与 Ansible
• Terraform
• Salt
• Balena
• Snap

默认情况下，您的 Kerberos Agent 会将所有配置和录制文件存储在容器内部。为了帮助您实现自动化并保持更一致的数据治理，您可以挂载卷来配置和持久化 Kerberos Agent 的数据，或者通过环境变量来配置每个 Kerberos Agent。

访问 Kerberos Agent

在使用上述任一部署模式成功部署 Kerberos Agent 后，您将能够访问 Kerberos Agent 的用户界面。系统会显示登录页面，要求输入凭据。

Kerberos Agent 的默认用户名和密码为：

• 用户名：root
• 密码：root

请注意，在最终部署时应更改用户名和密码，请参阅下方的通过环境变量配置部分。

通过挂载卷进行配置和持久化

下面以 docker 为例展示了如何挂载主机目录，但该方法同样适用于 上述所有部署模式和工具。

您可以通过 -v 选项将卷挂载到容器中。要挂载您自己的配置文件和录制文件夹，请运行以下命令：

docker run -p 80:80 --name mycamera \
-v $(pwd)/agent/config:/home/agent/data/config \
-v $(pwd)/agent/recordings:/home/agent/data/recordings \
-d --restart=always kerberos/agent:latest

有关每种部署和自动化工具的更多示例，请参阅 部署章节。请务必检查您所挂载目录/卷的权限。更多信息请参见 此问题。

chmod -R 755 kerberos-agent/
chown 100:101 kerberos-agent/ -R

通过环境变量进行配置

除了挂载配置文件外，您还可以使用环境变量来覆盖配置。这使得使用 docker compose 或 kubernetes 部署更加简单和可扩展。采用这种方法，我们还能简化通过 ansible 和 terraform 的自动化流程。

docker run -p 80:80 --name mycamera
-e AGENT_NAME=mycamera
-e AGENT_TIMEZONE=Europe/Brussels
-e AGENT_CAPTURE_IPCAMERA_RTSP=rtsp://fake.kerberos.io/stream
-e AGENT_CAPTURE_CONTINUOUS=true
-d --restart=always kerberos/agent:latest

名称	描述	默认值
LOG_LEVEL	日志级别，可选值为 "info"、"warning"、"debug"、"error" 或 "fatal"。	"info"
LOG_OUTPUT	日志输出格式，可选值为 "json" 或 "text"。	"text"
AGENT_MODE	可选择以 'release' 模式运行用于生产环境，或以 'demo' 模式用于展示。	"release"
AGENT_TLS_INSECURE	指定是否对内部 HTTP 客户端使用 InsecureSkipVerify。	"false"
AGENT_USERNAME	用于在 Kerberos Agent 登录页面进行身份验证的用户名。	"root"
AGENT_PASSWORD	用于在 Kerberos Agent 登录页面进行身份验证的密码。	"root"
AGENT_KEY	您的 Kerberos Agent 的唯一标识符，此值会自动生成，但也可手动覆盖。	""
AGENT_NAME	Agent 的友好名称。	"agent"
AGENT_TIMEZONE	用于时间转换的时区。	"Africa/Ceuta"
AGENT_REMOVE_AFTER_UPLOAD	启用后，成功上传到存储的录像将从磁盘中删除。	"true"
AGENT_OFFLINE	确保不建立任何外部连接。	"false"
AGENT_AUTO_CLEAN	清理录像目录。	"true"
AGENT_AUTO_CLEAN_MAX_SIZE	如果启用 AUTO_CLEAN，设置录像目录的最大大小（单位：MB）。	"100"
AGENT_TIME	启用 Kerberos Agent 的定时任务	"false"
AGENT_TIMETABLE	用于指定录像开始和结束时间的每周时间表："start1,end1,start2,end2;start1.."	""
AGENT_REGION_POLYGON	用于运动检测的单个多边形区域："x1,y1;x2,y2;x3,y3;..."	""
AGENT_CAPTURE_IPCAMERA_RTSP	目标摄像机的全高清 RTSP 端点。	""
AGENT_CAPTURE_IPCAMERA_SUB_RTSP	用于直播流（WebRTC）的子码流 RTSP 端点。	""
AGENT_CAPTURE_IPCAMERA_BASE_WIDTH	强制设置实时预览处理的特定宽度分辨率。	""
AGENT_CAPTURE_IPCAMERA_BASE_HEIGHT	强制设置实时预览处理的特定高度分辨率。	""
AGENT_CAPTURE_IPCAMERA_ONVIF	标记为符合 ONVIF 规范的设备。	""
AGENT_CAPTURE_IPCAMERA_ONVIF_XADDR	摄像机上运行的 ONVIF 端点/地址。	""
AGENT_CAPTURE_IPCAMERA_ONVIF_USERNAME	用于 ONVIF 身份验证的用户名。	""
AGENT_CAPTURE_IPCAMERA_ONVIF_PASSWORD	用于 ONVIF 身份验证的密码。	""
AGENT_CAPTURE_MOTION	开启或关闭运动检测功能。	"true"
AGENT_CAPTURE_LIVEVIEW	开启或关闭实时预览功能。	"true"
AGENT_CAPTURE_SNAPSHOTS	开启或关闭截图生成功能。	"true"
AGENT_CAPTURE_RECORDING	开启或关闭录像功能。	"true"
AGENT_CAPTURE_CONTINUOUS	开启连续录制模式（"true"）或运动触发模式（"false"）。	"false"
AGENT_CAPTURE_PRERECORDING	如果 CONTINUOUS 设置为 false，则指定运动事件发生前后的录制时长（秒）。	"10"
AGENT_CAPTURE_POSTRECORDING	如果 CONTINUOUS 设置为 false，则指定运动事件发生后的录制时长（秒）。	"20"
AGENT_CAPTURE_MAXLENGTH	单个录像的最大时长（秒）。	"30"
AGENT_CAPTURE_PIXEL_CHANGE	如果 CONTINUOUS 设置为 false，则指定触发运动检测所需的像素变化数量。	"150"
AGENT_CAPTURE_FRAGMENTED	将录制的 MP4 文件格式设置为分片式（适用于 HLS）。	"false"
AGENT_CAPTURE_FRAGMENTED_DURATION	如果 AGENT_CAPTURE_FRAGMENTED 设置为 true，则定义每个分片的时长（秒）。	"8"
AGENT_MQTT_URI	用于双向通信（实时预览、ONVIF 等）的 MQTT 代理端点	"tcp://mqtt.kerberos.io:1883"
AGENT_MQTT_USERNAME	MQTT 代理的用户名。	""
AGENT_MQTT_PASSWORD	MQTT 代理的密码。	""
AGENT_REALTIME_PROCESSING	如果 AGENT_REALTIME_PROCESSING 设置为 true，Agent 会将关键帧发送到指定主题	""
AGENT_REALTIME_PROCESSING_TOPIC	关键帧将以 base64 编码格式发送到的主题。	""
AGENT_STUN_URI	使用 WebRTC 时，需要提供 STUN 服务器。	"stun:turn.kerberos.io:8443"
AGENT_FORCE_TURN	强制使用 TURN 服务器，仅生成中继候选者。	"false"
AGENT_TURN_URI	使用 WebRTC 时，需要提供 TURN 服务器。	"turn:turn.kerberos.io:8443"
AGENT_TURN_USERNAME	用于 WebRTC 的 TURN 用户名。	"username1"
AGENT_TURN_PASSWORD	用于 WebRTC 的 TURN 密码。	"password1"
AGENT_CLOUD	将录像存储在 Kerberos Hub（s3）、Kerberos Vault（kstorage）或 Dropbox（dropbox）中。	"s3"
AGENT_HUB_ENCRYPTION	开启或关闭从您的 Kerberos Agent 到 Kerberos Hub 的流量加密。	"true"
AGENT_HUB_URI	Kerberos Hub API，默认为我们提供的 Kerberos Hub SAAS。	"https://api.hub.domain.com"
AGENT_HUB_KEY	与您在 Kerberos Hub 中的账户关联的访问密钥。	""
AGENT_HUB_PRIVATE_KEY	与您在 Kerberos Hub 中的账户关联的私钥。	""
AGENT_HUB_REGION	您希望上传录像的 Kerberos Hub 区域。	""
AGENT_HUB_SITE	您在 Kerberos Hub 账户中创建的站点 ID。	""
AGENT_KERBEROSVAULT_URI	Kerberos Vault API 的 URL。	"https://vault.domain.com/api"
AGENT_KERBEROSVAULT_ACCESS_KEY	Kerberos Vault 账户的访问密钥。	""
AGENT_KERBEROSVAULT_SECRET_KEY	Kerberos Vault 账户的秘密密钥。	""
AGENT_KERBEROSVAULT_PROVIDER	您创建的 Kerberos Vault 提供商（可选）。	""
AGENT_KERBEROSVAULT_DIRECTORY	在 Kerberos Vault 中用于存储录像的目录。	""
AGENT_KERBEROSVAULT_SECONDARY_URI	Kerberos Vault API 的 URL。	"https://vault.domain.com/api"
AGENT_KERBEROSVAULT_SECONDARY_ACCESS_KEY	第二个 Kerberos Vault 账户的访问密钥。	""
AGENT_KERBEROSVAULT_SECONDARY_SECRET_KEY	第二个 Kerberos Vault 账户的秘密密钥。	""
AGENT_KERBEROSVAULT_SECONDARY_PROVIDER	您创建的第二个 Kerberos Vault 提供商（可选）。	""
AGENT_KERBEROSVAULT_SECONDARY_DIRECTORY	在第二个 Kerberos Vault 中用于存储录像的目录。	""
AGENT_DROPBOX_ACCESS_TOKEN	您 Dropbox 应用程序的访问令牌，用于利用 Dropbox SDK。	""
AGENT_DROPBOX_DIRECTORY	在 Dropbox 中用于存储录像的目录。	""
AGENT_ENCRYPTION	开启或关闭 MQTT 消息的端到端加密。	"false"
AGENT_ENCRYPTION_RECORDINGS	开启或关闭录像的端到端加密。	"false"
AGENT_ENCRYPTION_FINGERPRINT	密钥对（公钥/私钥）的指纹，以便您知道使用哪一对。	""
AGENT_ENCRYPTION_PRIVATE_KEY	用于解密和签名通过 MQTT 发送请求的私钥（非对称/RSA）。	""
AGENT_ENCRYPTION_SYMMETRIC_KEY	用于加密和解密通过 MQTT 发送请求的对称密钥（AES）。	""
AGENT_SIGNING	开启或关闭录像签名功能。	"true"
AGENT_SIGNING_PRIVATE_KEY	用于对录像指纹进行签名以验证来源的私钥（RSA）。	"" - 如为空则使用默认密钥

加密

您可以通过启用加密设置，使用自定义的 AES 和 RSA 密钥对录制文件及传出的 MQTT 消息进行加密。一旦启用，所有录制文件将使用 AES-256-CBC 和您的对称密钥进行加密。您可以使用默认的 openssl 工具链，通过 AES 密钥解密录制文件，具体命令如下：

openssl aes-256-cbc -d -md md5 -in encrypted.mp4 -out decrypted.mp4 -k your-key-96ab185xxxxxxxcxxxxxxxx6a59c62e8

或者，您也可以使用 Kerberos Agent 二进制文件解密整个录制文件夹，命令如下：

go run main.go -action decrypt ./data/recordings your-key-96ab185xxxxxxxcxxxxxxxx6a59c62e8

对于单个文件，可以使用以下命令：

go run main.go -action decrypt ./data/recordings/video.mp4 your-key-96ab185xxxxxxxcxxxxxxxx6a59c62e8

H.264 与 H.265

在视频编解码器（Codec）领域，市场上主要有两种主流编码格式：H.264 和 H.265。根据您的应用场景，可以选择其中一种或同时使用两者。我们将简要概述这两种编码格式在视频监控和视频分析领域的优缺点。如果您想深入了解，可以进一步查阅互联网上的相关资料（当然，纸质书籍仍然是一种不错的选择）。

• H.264（也称为 AVC 或 MPEG-4 Part 10）

  • 是最常见的编码格式，也是 IP 摄像机中最广泛支持的。
  • 大多数浏览器、操作系统和第三方应用都支持该格式。
  • 可以嵌入到商业软件和第三方应用中。
  • 提供多种压缩级别（高、中、低等）。
  • 在中等压缩比下，画质更好且压缩效率更高，产生的伪影更少。
  • 支持 WebRTC 等技术。

• H.265（也称为 HEVC）

  • 不被旧式摄像机支持，但正在逐渐普及于“较新”的 IP 摄像机。
  • 由于授权许可问题，可能并非所有平台都支持。例如，在某些 Linux 发行版的浏览器中就不支持。
  • 如果将其嵌入商业产品中，需要支付授权费用，请务必注意。
  • 压缩效率更高（比 H.264 高约 50%）。
  • 在运动场景中容易出现伪影，而 H.264 则表现更好。
  • 使用相同分辨率、时长和帧率录制同一段视频时，H.265 的文件大小约为 H.264 的一半。
  • 不支持 WebRTC 等技术。

结论：根据具体应用场景，您可以选择其中一种编码格式，也可以同时使用两者。例如，可以使用 H.264 作为主码流进行直播，而用 H.265 作为子码流进行录制。如果希望在跨平台和跨浏览器环境中播放录制内容，则建议选择 H.264，因为它具有更好的兼容性。

使用 Codespaces 贡献代码

参与开源项目的一大障碍通常是本地开发环境的搭建。原因在于，您可能已经安装了用于其他项目的工具和库，而 Kerberos Agent 所需的依赖（如 FFmpeg）可能需要不同版本。这就会陷入所谓的“依赖地狱”……

借助 Codespaces，Kerberos Agent 仓库提供了这一功能，您可以在几分钟内快速搭建所需的开发环境。只需点击页面顶部的 <> Code 选项卡，即可创建一个 Codespace，并使用 Kerberos Devcontainer 基础镜像。该镜像包含了所有必要的依赖项：FFmpeg、OpenCV、Golang、Node.js、Yarn 等。

等待几分钟后，您将在浏览器中看到一个美观的 Visual Studio Code 界面，此时您就可以开始编写代码了！

GitHub Codespace 启动后会自动安装一些依赖项。安装完成后，请打开 ui/src/config.json 文件，取消注释并修改以下部分。请务必将 externalHost 变量替换为您将在下一步获取的 DNS 名称。

// 当使用 codespaces 或其他特殊 DNS 名称时，请取消注释此行（这些名称通常不由您控制）
// 将其替换为 Kerberos Agent 服务器的 DNS 名称（即 codespace 的 URL）
const externalHost = 'cedricve-automatic-computing-machine-v647rxvj4whx9qp-80.preview.app.github.dev';

const dev = {
  ENV: 'dev',
  HOSTNAME: externalHost,
  //API_URL: `${protocol}//${hostname}:80/api`,
  //URL: `${protocol}//${hostname}:80`,
  //WS_URL: `${websocketprotocol}//${hostname}:80/ws`,

  // 当使用 codespaces 或其他特殊 DNS 名称时，请取消注释上述行，并注释掉上面的代码
  API_URL: `${protocol}//${externalHost}/api`,
  URL: `${protocol}//${externalHost}`,
  WS_URL: `${websocketprotocol}//${externalHost}/ws`,
};

接下来，打开两个终端：一个用于 ui 项目，另一个用于 machinery 项目。

1. 终端 A：

    cd machinery/
    go run main.go -action run -port 80
   

2. 终端 B：

    cd ui/
    yarn start
   

执行完成后，会出现一个提示框，显示“端口转发”。您应该会看到两个端口被打开，一个是 ui 项目的 3000 端口，另一个是 machinery 项目的 80 端口。请右键点击 80 端口，将其可见性从“私有”改为“公共”，这样可以避免 CORS 错误。

如前所述，复制 machinery 的 DNS 名称，并将其粘贴到 ui/src/config.json 文件中。完成设置后，刷新浏览器中的 ui 页面，您应该能够使用默认凭据 root 和 root 登录系统。

开发与构建

Kerberos Agent 分为两个部分：machinery 和 web。这两个部分分别位于仓库中的相应文件夹内。要在本地开发或运行应用程序，您需要按照以下说明同时启动 machinery 和 web。而在生产环境中，整个应用会被打包成一个单一的可部署产物，更多相关信息请参阅 生产环境构建。

UI

web 部分是一个基于 React 的项目，它是最终用户查看录制内容、直播流以及修改 machinery 配置的主要入口。

git clone https://github.com/kerberos-io/agent
cd ui
yarn start

这将启动一个 Web 服务器，并在 3000 端口上运行 Web 应用程序。

登录成功后，您将看到仪表盘页面。在正确配置 Agent 后，您应该能够看到实时画面以及已记录到磁盘上的事件信息。

机器

machinery 是一个 Golang 项目，提供两项功能：一方面，它作为 Kerberos 代理，负责处理摄像头数据及其他逻辑等繁重任务；另一方面，它又充当一个 Web 服务器（Rest API），允许来自 Web（React）或其他自定义应用程序的通信。该 API 使用 swagger 进行文档化。

你可以通过以下命令简单地运行 machinery：

git clone https://github.com/kerberos-io/agent
cd machinery
go run main.go -action run -port 80

这将启动 Kerberos 代理，并在端口 80 上运行一个 Web 服务器。你也可以根据自己的需求更改端口号。我们强烈推荐使用 Goland 或 Visual Studio Code，因为它们内置了完整的调试和代码检查功能。

从源码构建

在生产环境中运行 Kerberos 代理只需一个二进制文件即可。尽管如此，我们仍有两个部分：machinery 和 web，它们会在构建时被合并。具体流程如下。

UI

要构建 Kerberos 代理的 Web 应用程序，你只需运行 yarn 的 build 命令。这将在 web 目录下创建一个 build 目录，其中包含 React 应用程序的压缩版本。除此之外，我们还会将这个 build 目录移动到 machinery 目录中。

cd ui
yarn build

Machinery

构建 machinery 同样非常简单 🚀，只需使用 go build 即可生成一个包含所有内容的单个二进制文件——这都要感谢 Golang。构建完成后，你会得到一个名为 main 的二进制文件，它包含了运行 Kerberos 代理所需的一切。

还记得 web 部分的构建步骤吗？在构建过程中，我们会将 build 目录移动到 machinery 目录中。在 machinery 中的 Web 服务器里，会引用这个 build 目录。这样一来，就只需要一个 Web 服务器就能完成所有工作。

cd machinery
go build

为 Docker 构建

在这个 agent 仓库的根目录下，你会找到一个 Dockerfile。该文件包含了构建和打包 Kerberos 代理 的指令。需要注意的是，我们是从一个预构建的基础镜像 kerberos/base:xxx 开始的。这个基础镜像已经包含了 Golang、FFmpeg 和 OpenCV 等工具，这样可以加快编译速度。

通过运行 docker build 命令，你将创建 Kerberos 代理的 Docker 镜像。构建完成后，你可以直接将其作为 Docker 容器运行。

docker build -t kerberos/agent .

新增内容

该仓库包含了 Kerberos.io 的下一代产品——Kerberos 代理（v3），它是 machinery 和 web 仓库的继任者。技术栈和架构都发生了重大变化。当前此版本仍在积极开发中，你可以在 develop 分支和 项目概览中跟踪进展。

更多相关信息请参阅下方的 常见问题解答。

贡献者

本项目得以存在，离不开所有贡献者的努力。太棒了！

Kerberos Agent 快速上手指南

Kerberos Agent 是一个开源、可扩展的视频监控管理代理，支持在多种硬件架构（ARM/AMD64）上运行。它专注于低资源占用、现代用户界面以及与云服务的灵活集成。

环境准备

在部署之前，请确保满足以下硬件和软件要求：

硬件要求

• 计算设备：支持运行二进制文件或容器的任何硬件，包括：
  • Raspberry Pi (ARMv6, ARMv7, ARM64)
  • Nvidia Jetson
  • Intel NUC
  • 虚拟机 (VM) 或物理服务器 (AMD64)
  • Kubernetes 集群
• 摄像头设备（任选其一）：
  • 支持 RTSP H264 或 H265 编码流的 IP 摄像头。
  • USB 摄像头、树莓派摄像头或其他相机（需配合 camera-to-rtsp 侧边车容器转换为 RTSP 流）。

软件依赖

• Docker：推荐安装最新稳定版（用于容器化部署）。
• 网络：确保设备可以访问互联网以拉取镜像，或已配置私有镜像仓库。

提示：社区维护了一份已验证兼容的摄像头型号列表，部署前可查阅 Camera Compatibility List。

安装步骤

最快捷的安装方式是使用 Docker。以下提供两种常见场景的命令。

场景一：连接 IP 摄像头（标准模式）

适用于直接通过 RTSP 连接的 IP 摄像头。此命令将启动 Agent 并映射 80 端口以访问 Web 界面。

docker run -p 80:80 --name mycamera -d --restart=always kerberos/agent:latest

场景二：连接 USB/树莓派摄像头（宿主机网络模式）

如果您使用 USB 摄像头或树莓派原生摄像头，需要先运行 camera-to-rtsp 侧边车将视频流转为 RTSP。此时 Agent 需要运行在宿主机网络模式下，以便直接连接本地 RTSP 流。

docker run --network=host --name mycamera -d --restart=always kerberos/agent:latest

其他部署方式：

• Balena Cloud: 可通过 Balena Hub 一键部署，支持远程管理和 OTA 更新。
• Snapcraft: 在支持 Snap 的 Linux 系统上，运行 snap install kerberosio，然后执行 sudo kerberosio.agent -action=run -port=80。
• Kubernetes/Ansible/Terraform: 详细编排文件请参考官方仓库的 deployments 目录。

基本使用

安装完成后，您可以立即通过浏览器进行管理。

1. 访问管理界面 打开浏览器，访问 http://<您的设备 IP>:80。

   • 如果是本地运行，访问 http://localhost:80。

2. 配置摄像头

   • 在 Web 界面中，输入摄像头的 RTSP 地址（例如：rtsp://username:password@ip_address:554/stream）。
   • 如果是 USB 摄像头配合侧边车使用，通常地址为 rtsp://localhost:8554/live（具体取决于 sidecar 配置）。

3. 开始监控

   • 配置完成后，Agent 将自动开始处理视频流。
   • 您可以在界面上查看实时直播、配置运动检测区域、设置录制计划（连续录制或触发录制）。
   • 录制的视频片段默认存储在容器内，建议在生产环境中通过 -v 参数挂载卷来持久化数据（例如：-v /data/recordings:/opt/kerberos/recordings）。

4. 高级功能

   • 多码流支持：可同时配置 H265 用于存储，H264 用于低延迟直播。
   • 集成输出：配置 Webhooks、MQTT 或脚本，在检测到运动时触发外部通知。
   • 加密：支持端到端加密传输及静态数据加密（AES-256-CBC）。

现在您已经成功运行了 Kerberos Agent，可以进一步探索其与 Kerberos Hub、Vault 等组件的集成以实现云端管理。