RackPeek rpk CLI命令完整手册：150+子命令快速掌握服务器、交换机、路由器的清单化管理

RackPeek是一款面向家庭实验室（Home Lab）和小型 IT 环境的开源基础设施管理工具，核心是一个名为rpk的命令行工具（CLI），配合 Web UI 使用。本文是RackPeek rpk CLI 命令完整手册：带你快速掌握150+ 个子命令，用清单化的方式统一管理服务器、交换机、路由器、防火墙等硬件，以及系统与服务——数据全部存储在纯 YAML 文件中，无数据库、无供应商锁定。

5分钟上手：安装与第一条 rpk 命令

RackPeek 推荐用 Docker 一键部署（官方镜像aptacode/rackpeek），一条命令即可启动，默认监听8080端口，所有状态保存在config/config.yaml一个 YAML 文件里。

docker volume create rackpeek-config docker run -d --name rackpeek -p 8080:8080 \ -v rackpeek-config:/app/config aptacode/rackpeek:latest

部署完成后，容器内即可使用rpk命令，浏览器中则打开完整的 Web 管理界面（CLI 与 Web UI 操作同一份数据）。

💡 新手提示：任何命令加-h都会打印帮助信息，例如rpk servers -h会列出add / get / describe / set / del / rename / tree等全部子命令。

全局命令速览

rpk顶层共 16 个命令组（完整参考见 docs/Commands.md）：

掌握一套 CRUD 模式，通吃 9 类资源

RackPeek 最省心的设计：9 类资源共用同一套命令语法。学会rpk servers后，rpk switches、rpk routers等命令零成本迁移。每类资源都支持以下基础子命令：

• add <name>—— 新增资源
• list—— 列出全部资源
• get <name>/describe <name>—— 查看单个资源（describe输出更详细）
• set <name>—— 更新属性
• del <name>—— 删除资源
• rename <name> <new-name>—— 重命名
• summary—— 输出该类资源的硬件汇总报告
• label add|remove、tag add|remove—— 标签管理

不同资源类型的子资源（Sub-Resource）支持范围如下：

三类子资源命令同样是add / set / del，例如给服务器加一块硬盘：

rpk servers drive add ssd-1 --type ssd --size 2000 rpk servers cpu add cpu-1 --model "Intel i5-12400" --cores 6 --threads 12

服务器命令详解：rpk servers

rpk servers共 9 个子命令 + 4 组子资源（cpu/drive/gpu/nic），是命令最多的资源组之一（源码见 Shared.Rcl/Commands/Servers/）。

常用流程示例——登记一台 Proxmox 节点：

rpk servers add pve-01 rpk servers set pve-01 --ram 32 rpk servers describe pve-01 rpk servers tree pve-01 # 查看依赖树

其中set支持的关键参数包括--ram、--ram_mts、--ipmi等（完整参数见 docs/Commands.md）。tree子命令是服务器专属能力，配合 Web 端"硬件树"页面，可以直观看到"物理机 → 虚拟化平台 → 虚拟机"的层级关系。

交换机、路由器命令：端口管理是核心

网络设备的建模重点是端口。rpk switches、rpk routers、rpk firewalls三个命令组结构完全一致，均包含port add/set/del子命令（源码见 Shared.Rcl/Commands/Switches/）。

一次登记交换机型号与端口：

rpk switches add usw-pro-48 rpk switches set usw-pro-48 --Model "UniFi USW-Pro-48-PoE" --poe rpk switches port add eth --type rj45 --speed 1 --count 48 rpk switches port add sfp --type sfp+ --speed 10 --count 4

路由器同理：rpk routers port add同样支持--type、--speed、--count参数（参见 docs/Commands.md）。端口登记完成后，就可以用rpk connections命令把两端端口"接线"，例如把交换机第 3 组第 1 口连到路由器 WAN 口：

rpk connections add usw-pro-48 0 2 rb5009 0 0

connections add还支持--label、--notes参数给这条链路打标注，方便日后排障。

systems 与 services 命令：用 runs-on 串联三层架构

RackPeek 将基础设施分为三层（详见 resource-levels.md）：Hardware（硬件）→ Systems（系统）→ Services（服务），由runs-on属性串联。

systems 命令支持任意层级嵌套，是建模虚拟化平台的关键（set参数见 docs/Commands.md）：

rpk systems add proxmox-ve rpk systems set proxmox-ve --type hypervisor --os "Proxmox VE 8.3" --runs-on pve-01 rpk systems add media-vm rpk systems set media-vm --type vm --runs-on proxmox-ve

services 命令独有subnets子命令，可按 CIDR 前缀筛选服务关联的子网：

rpk services add jellyfin rpk services set jellyfin --ip 10.0.10.50 --port 8096 --protocol http --runs-on media-vm rpk services subnets --cidr 10.0.10.0/24

⚠️ 建模规则：服务只能运行在系统上，不能直接挂在硬件上；系统可以运行在硬件或其他系统上，且支持多个runs-on目标（例如集群服务）。

导出命令：一份清单喂饱 Ansible、SSH、hosts

RackPeek 最大的杀手锏：把清单文档直接变成自动化配置。

1️⃣ Ansible 清单生成（rpk ansible inventory，参数详解见 docs/Commands.md）：

rpk ansible inventory --format yaml --group-tags prod,staging --global-var ansible_user=admin -o inventory.yml

支持按 tag / label 分组、注入全局变量、ini 或 yaml 两种格式。

2️⃣ SSH 配置导出：自动读取资源上的标签作为连接信息：

rpk ssh export --include-tags prod,linux --default-port 22 -o ssh_config

3️⃣ hosts 文件导出：生成/etc/hosts兼容文件：

rpk hosts export --domain-suffix home.local -o hosts

三个导出命令都支持--include-tags/-o输出到文件，可直接接入 CI 脚本。

可视化与检索：graph、tags 命令组

• rpk graph topology—— 输出物理拓扑（硬件 + 连接）的 Mermaid 流程图，粘贴到任意 Mermaid 渲染器即可看图；
• rpk graph logical—— 输出按子网和主机分组的服务/系统逻辑图；
• rpk tags list—— 列出所有在用标签及引用次数；
• rpk tags show <tag>—— 反查携带某个标签的全部资源，非常适合"哪些设备属于生产环境"这类快速排查。

图形化结果也可以在 Web UI 的 Visualise 页面直接预览（仓库中 vhs/webui_screenshots/ 目录下保存了拓扑图等截图示例）。

数据安全：配置即 Git 仓库

所有命令修改的都是同一个 YAML 文件，因此 RackPeek 原生支持Git 集成：启动时自动在配置目录初始化 git 仓库，通过环境变量GIT_TOKEN、GIT_USERNAME配置任意 Git 服务（GitHub、Gitea、GitLab、Bitbucket 均可，详见 git-integration.md）。此后每次变更都会自动 commit 并同步到远端——你的基础设施文档从此拥有完整历史版本。

新手学习路线：三步吃透 150+ 子命令

1. 记语法模板：rpk <资源> <动作> [名称] [参数]，9 类资源完全同构，-h随时查参数；
2. 跑一遍完整建模流程：servers add→switches port add→connections add→systems set --runs-on→services set --runs-on，把三层架构串起来；
3. 用上导出能力：rpk ansible inventory+rpk graph topology，体会"文档即代码"的闭环。

完整命令树可在 CommandIndex.md 中按命令逐条跳转，全部 3700+ 行参考文档收录在 docs/Commands.md。照着上面的模板走一遍，150+ 子命令其实只需要记一套语法。