RackPeek：用 WebUI 与 CLI 记录和管理家庭实验室与小型 IT 基础设施
RackPeek 是一个 WebUI + CLI 工具，用于文档化和管理家庭实验室及小规模 IT 基础设施，帮助追踪硬件、服务、网络及其相互关系，支持脚本化、可复用、开放数据格式（YAML），支持 Docker 与 Docker Compose 部署，并可用于生成 Ansible Inventory。
社区作者 · zZz
它解决什么问题
RackPeek 是一个面向家庭实验室（home lab）与小型 IT 基础设施的 WebUI 与 CLI 工具，核心目标是以清晰、可脚本化、可复用的方式记录和管理硬件、服务、网络以及它们之间的关系，避免企业级 CMDB 的臃肿、专有锁定，也避免淹没在多余的元数据和流程中。项目说明中提供了演示素材（见配图 1、配图 2、配图 3），分别展示了项目横幅、CLI 演示动图与 WebUI 界面动图。
项目强调的核心价值包括：
- 简洁（Simplicity）：范围有意识地保持窄小，追求清晰与实用，避免不必要的抽象和功能蔓延。
- 部署便捷（Ease of Deployment）：降低运维复杂度，安装、升级和日常使用应尽可能直接、低摩擦。
- 开放（Openness）：使用开放、非专有的数据格式，用户完全拥有自己的数据，可自由检查、迁移或复用。
- 社区（Community）：欢迎各种经验水平的贡献者，知识分享、指导和协作是项目文化核心。
- 隐私与安全（Privacy & Security）：无遥测、无广告、无跟踪、无人为限制；运行在你自己基础设施上的东西就留在你的基础设施上。
- 自我实践（Dogfooding）：为解决团队真实存在的问题而构建，实践中无用的功能不应存在。
- 有主见（Opinionated）：针对家庭实验室和自托管环境优化，而不是企业 CMDB 或企业文档工作流。
项目提供文档入口：Overview（概览）、Installation Guide（安装指南）、Ansible Inventory Generator Guide（Ansible Inventory 生成器指南）、CLI Commands Reference（CLI 命令参考）、Versioning（版本管理）。另有贡献指南 contribution-guidelines.md、开发速查 dev-cheat-sheet.md（构建、发布、Docker、测试命令）、测试指南 testing-guidelines.md。
项目还在收集家庭实验室用户的问卷反馈，用于确定方向与功能优先级；后续功能路线图正在讨论中。
状态存储：RackPeek 以 YAML 保存状态，默认位于容器内 /app/config 目录下的 config.yaml。
— 本文由 AI 根据公开来源辅助整理，命令、版本与许可证请在使用前到原始页面复核。
安装 / 开始使用
以下步骤来自项目 README 的 Docker 部署说明。
一、准备环境
- 准备一台可运行 Docker 的 Linux/自托管主机。
- 安装 Docker（如使用 Compose 方式，还需安装 Docker Compose）。
- 确认 8080 端口可用（如被占用需在启动命令中改映射端口）。
二、方式一
使用命名卷（Named volume）
- 先创建用于持久化配置的命名卷：
docker volume create rackpeek-config- 启动容器：
docker run -d \--name rackpeek \ -p 8080:8080 \ -v rackpeek-config:/app/config \ aptacode/rackpeek:latest
三、方式二
使用绑定挂载（Bind mount）
- 在宿主机准备配置目录（例如当前目录下的 config），将其挂载到容器内 /app/config：
docker run -d \--name rackpeek \ -p 8080:8080 \ -v $(pwd)/config:/app/config \ aptacode/rackpeek:latest
四、方式三
Docker Compose在 compose 文件中配置（原文排版已整理为标准缩进）： version: "3.9"
services: rackpeek: image: aptacode/rackpeek:latest container_name: rackpeek ports:
volumes:
restart: unless-stopped healthcheck: test: ["CMD", "curl", "-fsS", "http://localhost:8080/health"] interval: 30s timeout: 5s start_period: 15s retries: 3
- "8080:8080"
- rackpeek-config:/app/config
volumes: rackpeek-config:
五、首次运行
- 容器启动后，通过浏览器访问 http://localhost:8080 打开 WebUI。
config/ └── config.yaml 请确保该路径已挂载到命名卷或宿主机目录，否则容器重建后数据会丢失。
- 数据与状态以 YAML 形式存放在容器内 /app/config，目录结构为：
六、常见问题
- 8080 端口被占用：修改 -p 参数（例如 -p 9090:8080）或在 compose 中调整端口映射。
- 数据未持久化：检查是否挂载了 /app/config，命名卷方式需确认卷名一致。
- 健康检查失败：项目自带 healthcheck 使用 curl -fsS http://localhost:8080/health，需保证容器内可访问该地址并已安装 curl（健康检查命令由镜像提供）。
- 升级：镜像标签为 aptacode/rackpeek:latest，如需升级请拉取最新镜像后重建容器，注意事先确认 /app/config 已持久化。
- 更多安装细节、Ansible Inventory 生成器用法与全部 CLI 命令，参见项目文档中的 Installation Guide、Ansible Inventory Generator Guide 与 CLI Commands Reference。
