homelib (Meltforce)

homelib

Homelab库存服务从多个来源收集基础设施数据，并通过web UI、JSON API和MCP服务器提供统一的视图。

Homelib将Proxmox、Tailscale、Hetzner Cloud、Komodo和UniFi的主机、服务、网络和容量数据聚合到一个SQLite数据库中。它通过以下方式作为Tailscale节点运行 终端交换网络 --不需要反向代理或身份验证层。

注： 这是一个为我自己的家庭实验室建立的个人副项目。它按原样发布，可能看不到定期更新或主动维护。

Claude using homelib's MCP tools for capacity planning

特性

• 多源采集 -Proxmox（SSH）、Tailscale（本地+控制平面API）、Hetzner Cloud、Komodo、UniFi
• MCP服务器 --通过以下方式集成AI/代理的13个工具 模型上下文协议，可从Claude、Claude Code或任何MCP客户端使用
• 网页用户界面 --仪表板、主机浏览器、服务、网络、Tailscale ACL查看器、容量规划器
• 应用程序接口 -具有过滤和搜索功能的完整REST API
• 主机合并 --对从多个来源发现的主机进行重复数据消除和合并
• 交叉引用 --验证跨源的区域分配，生成不匹配的发现
• 产能规划 --使用可用容量和区域聚合进行每节点CPU/内存分配跟踪
• 角色充实 --通过配置为主机标记基础设施角色和应用程序类别
• 插件系统 --使用输出JSON的自定义脚本（本地或SSH）扩展集合
• 预定收款 --基于Cron的可配置保留
• 优雅降级 --失败的收集器不会阻止其他收集器

截图

MCP服务器

Homelib公开了一个 模型上下文协议 服务器在 /mcp （流式HTTP）。这让人工智能助手可以直接查询您的基础设施——询问容量、查找主机、在库存中搜索或触发集合。

与克劳德一起使用

要将homelib的MCP服务器与Claude.ai或其他远程MCP客户端一起使用，请参阅 tsmcp --一个网关，通过OAuth身份验证在互联网上公开基于tsnet的MCP服务器（如homelib）。

对于您Tailscale网络上的Claude Code或其他本地MCP客户端，请直接指向 https://.your-tailnet.ts.net/mcp.

设置

Homelib通过tsnet作为自己的节点加入您的Tailscale网络。在第一次开始时，它需要一个 尾标认证密钥 注册。之后，tsnet将保持其状态并自动重新连接。

1.创建Tailscale身份验证密钥

在中生成可重用的身份验证密钥 Tailscale管理控制台.将其设置为 ts_auth_key 在您的配置中或作为 HOMELIB_TS_AUTH_KEY 环境变量。

2.创建配置

cp config.example.yaml config.yaml

编辑 config.yaml --启用所需的收集器，并为其API配置机密。看 配置 了解详情。

3.跑步

Docker Compose（推荐）

services:
  homelib:
    image: meltforce/homelib:latest
    restart: unless-stopped
    volumes:
      - ./data:/data
    environment:
      - HOMELIB_TS_AUTH_KEY=tskey-auth-xxxxx  # only needed on first start

放置您的 config.yaml 在 ./data/config.yaml那么：

docker compose up -d

一旦homelib在Tailscale注册，您就可以删除 HOMELIB_TS_AUTH_KEY 变量。

Docker运行

docker run -d \
  --name homelib \
  --restart unless-stopped \
  -v $(pwd)/data:/data \
  -e HOMELIB_TS_AUTH_KEY=tskey-auth-xxxxx \
  meltforce/homelib:latest

二进制

go build -o homelib .

# Development (localhost:8080, no Tailscale)
./homelib --local --config config.yaml

# Production (tsnet)
export HOMELIB_TS_AUTH_KEY=tskey-auth-xxxxx
./homelib --config config.yaml

4.访问权限

运行后，homelib可在 https://.your-tailnet.ts.net （默认为配置中的主机名 homelib).无需端口转发或反向代理——访问由您的Tailscale ACL控制。

配置

复制 config.example.yaml 并编辑以匹配您的环境。所有的秘密都通过一个链来解决：

1. 环境变量 HOMELIB_ （例如。 HOMELIB_HETZNER_API_TOKEN)
2. 在首尔贸易中心 秘密商店（如果 secret_backend.type: setec)
3. 1Password命令行界面 op:// 引用（如果值以开头 op://)
4. 字面值

收集器

Tailscale收集器始终处于活动状态-homelib通过tsnet在Tailscale上运行，并使用本地API作为其主要数据源。其他收集器可以独立启用/禁用。所有收集器同时运行。

角色

通过以下方式用应用程序和类别元数据丰富发现的主机 roles 部分。应用程序和类别显示在主机表、容量页面和主机详细信息视图中。

roles:
  application_categories:
    jellyfin: media-server
    immich: photos
    vaultwarden: security

  guest_overrides:
    my-vm: homeassistant    # when hostname != application name

  tailscale_devices:
    my-nas:
      role: fileserver
      application: truenas

  proxmox_nodes:
    my-node:
      infrastructure_role: hypervisor
      workload_specialization: general

插件

使用返回JSON的脚本扩展homelib。插件在本地或通过SSH运行，可以贡献主机、发现和指标。

plugins:
  - name: my-plugin
    enabled: true
    type: ssh              # or "local"
    host: my-server
    user: root
    command: /usr/local/bin/my-script --json
    timeout: 30s
    schedule: default

插件输出架构：

{
  "plugin": "my-plugin",
  "version": "1.0",
  "hosts": [
    { "name": "host1", "host_type": "vm", "details": {} }
  ],
  "metrics": { "metric_name": "value" },
  "findings": [
    { "severity": "warning", "host_name": "host1", "message": "High memory usage" }
  ]
}

REST API

所有端点都在 /api/v1/。响应是JSON。

建筑

config.yaml
    |
    v
  main.go
    |-- Store (SQLite, WAL mode)
    |-- Orchestrator
    |     |-- Collectors (Proxmox, Tailscale, Hetzner, Komodo, UniFi)
    |     |-- Plugins (custom scripts)
    |     |-- Merge (deduplicate hosts across sources)
    |     |-- Crossref (validate zones, enrich roles)
    |     '-- Persist results
    |-- Scheduler (cron)
    |-- HTTP Server
    |     |-- Web UI (embedded templates)
    |     '-- JSON API
    '-- MCP Server (/mcp)

项目结构

main.go                    Entry point, tsnet, HTTP server, scheduler
internal/
  config/                  YAML config, secret resolution
  model/                   Data types (Host, Service, Network, Finding, etc.)
  collector/               Collector interface + implementations
  crossref/                Zone validation, role enrichment
  store/                   SQLite persistence (WAL mode)
  capacity/                Capacity planning calculations
  scheduler/               Cron scheduling
  server/                  HTTP handlers (Web UI + JSON API)
  mcp/                     MCP server (Streamable HTTP)
  web/                     Embedded templates + static assets

许可证

麻省理工学院