Beacon

开源、轻量、现代化的主机与 Docker 容器监控平台
_{An open-source, lightweight and modern host & Docker monitoring platform}

中文 · English

项目简介 · 功能特性 · 系统架构 · 快速开始 · 技术栈 · 项目结构 · 项目文档

Beacon 是一个采用 Server-Agent 架构的主机监控与 Docker 容器管理平台，面向需要统一观察、管理多台服务器的个人开发者与小型团队。

• Beacon Server 提供 Web UI、HTTP API、认证授权、审计、监控数据存储与任务编排。
• Collia Agent 采集主机和 Docker 指标，通过 HTTP 上报监控批次，并主动建立反向 gRPC tunnel 接收 Server 控制调用。
• 查询与控制请求必须显式指定 Agent，避免默认节点回退或跨节点读取。

官网：beacon.amuluze.com · 仓库：github.com/amuluze/beacon

• 查看 Docker 版本与运行状态。
• 管理容器的创建、启动、停止、重启、删除与日志。
• 管理镜像导入、导出、删除和虚悬镜像清理。
• 创建、删除并查看 Docker 网络状态。

• 查看主机名、启动时间、发行版、内核与系统类型。
• 观察 CPU、内存、磁盘 IO 与网络 IO 趋势。
• 配置 CPU、内存和磁盘使用率告警阈值及统一消息标题，通过邮件或支持可选加签的钉钉群机器人 Webhook 接收通知。
• 通过明确选择的 Agent 执行容器控制操作。

• 用户、角色与接口权限管理。
• 登录、登出和系统操作审计。
• 生产模式下校验签名密钥、Agent 加入令牌与安装令牌。

• Agent 版本上报与在线状态跟踪。
• Collia amd64/arm64 安装包由 Beacon 镜像统一提供。
• 支持远程更新、自更新、卸载和反向 tunnel 控制。

flowchart LR
    User["Web UI / API Client"] -->|"HTTP / WebSocket<br/>X-Agent-ID or agent_id"| Beacon["Beacon Server"]
    Beacon --> DB[("Server monitoring DB")]
    Collia["Collia Agent"] -->|"HTTP monitoring report"| Beacon
    Collia -->|"Reverse gRPC tunnel"| Beacon
    Beacon -->|"Control call by Agent ID"| Collia
    Collia --> Runtime["Host OS / Docker Engine"]

Beacon 将三条路径明确分离：

1. 监控查询：Web 请求从 Server 本地监控表读取指定 Agent 的数据。
2. 监控上报：Collia 通过 HTTP report 接口按批次原子写入 Server。
3. 控制调用：Beacon 通过 Collia 主动建立的反向 gRPC tunnel 调用目标 Agent。

更完整的边界、依赖方向和数据流见 架构文档 与 数据流文档。

bash -c "$(curl -fsSL https://beacon.amuluze.com/release/latest/manager.sh)" -- install BEACON_PUBLIC_BASE_URL=https://beacon.example.com

生产模式只接受 HTTPS。请先准备将该 HTTPS 地址转发到 Beacon Web 端口的可信反向代理；安装脚本会引导配置 Web 端口、Agent 控制端口，并生成认证、数据加密和首次管理员凭据。BEACON_DATA_ENCRYPTION_KEY 会保存在权限为 0600 的 .env 中且必须永久保留。

环境要求：

• Docker >= 20.10.9，并安装 Docker Compose。
• Go 1.25（本地开发后端时需要）。
• Node.js、pnpm 与 Task（构建 Web 资源时需要）。

# 克隆仓库
git clone https://github.com/amuluze/beacon.git
cd beacon

# 后端本地开发（SQLite + 开发配置）
task beacon:dev

# 前端开发
task beacon-web:install
task beacon-web:dev

# 构建完整镜像（内嵌前端产物与双架构 Collia 二进制）
docker build -f beacon/Dockerfile -t beacon:local .

本地开发默认通过 8000（HTTP）与 17000（Agent control）端口访问，仅用于开发/验证。生产部署前请生成独立的高强度密钥，并注入 BEACON_AUTH_SIGNING_KEY、BEACON_AGENT_INSTALL_TOKEN、BEACON_CONTROL_JOIN_TOKEN、BEACON_DATA_ENCRYPTION_KEY；首次建库还需设置 BEACON_BOOTSTRAP_ADMIN_PASSWORD。

Beacon 启动后，可从目标主机安装 Collia Agent（将地址、节点编号和 Token 替换为实际值）：

curl -fsSL 'https://<beacon-host>/api/v1/host/install?node=1' | sudo bash -s -- --token=<install-token>

安装统计默认关闭，不会在未授权的情况下发送。只有管理员在 beacon/configs/config.toml 的 [InstallReport] 中显式设置 Enable = true 后，Beacon 才会向配置的 URL（默认 https://beacon.amuluze.com/api/v1/install/report）发送一次安装信息。

发送字段仅包括：install_id、image、version、public_base_url、install_dir、http_port、control_port、container_name、hostname。其中 install_id 是本地持久化的随机安装标识；该请求不包含管理员账号、密码、认证令牌、钉钉 Webhook、SMTP 密码或监控数据。

beacon/
├── beacon/                 # Server、Web UI、HTTP/WS API 与 tunnel client
│   ├── cmd/beacon/         # Server 进程入口
│   ├── service/            # 业务服务、路由、认证与数据访问
│   └── web/                # Vue 3 管理端
├── collia/                 # Agent 采集、Docker/主机操作与 tunnel service
├── common/                 # 共享 schema、数据库与 reverse tunnel transport
└── Taskfile.yml            # 工作区开发命令入口

架构、部署与 API 契约的完整文档见官网；快速上手以本 README 为准。

常用命令：

task beacon:dev
task beacon-web:dev
task collia:amd64

cd beacon && go test ./...
cd collia && go test ./...
cd common && go test ./...
cd beacon/web && pnpm test:run && pnpm ts && pnpm build

欢迎提交 Issue 和 Pull Request：

1. Fork 本仓库。
2. 创建功能分支并完成最小验证。
3. 提交清晰、可审查的变更。
4. 推送分支并创建 Pull Request。

Beacon 由作者利用业余时间持续维护。如果项目对你有帮助，欢迎给仓库点一个 ⭐，也可以请作者喝杯咖啡。

Beacon 基于 MIT License 开源。

特别感谢 JetBrains 为开源项目提供开发工具支持。

_{用 ❤️ 与 ☕ 打造 · Built with ❤️ and ☕}