# 05-01-k3s 部署 Homer 首页面板

> 在 K3s 中部署 Homer，作为家庭实验室的统一导航页。


## TL;DR

- **自动化验收**：`./scripts/verify.sh run 05-01`
- **关键前置**：按本文「前置条件」准备环境变量/Secret/入口 IP
- **成功判据**：达到本文「预期」且 playbook 断言通过
- **排障**：见本文「排障」

---

## Homer 相对「纯书签」的优势

- **不仅是跳转链接**：普通条目点击后打开 `url`；此外 Homer 支持多种**集成卡片类型**，由浏览器侧按配置去请求你填写的 **目标地址**，在首页上直接看到**简单、只读的实时反馈**（例如是否在线、几项系统指标），无需再开一个监控大盘。
- **与目标服务的「轻量交互」**：在 `config.yml` 里为条目声明 `type` 后，Homer 会对对应 `url` 发起约定格式的 HTTP 请求（由该类型定义），把返回结果渲染成卡片上的小部件；**不是**任意网站都能自动对接，目标需实现该类型要求的接口（如 Glances 的 Web/API）。
- **配置仍集中、易维护**：交互逻辑由 Homer 内置，你只维护 **YAML 里的 `url` / `type` / 少量参数**；适合家庭实验室「一眼看状态、一点进服务」。
- **与重型监控栈的关系**：这类交互偏**轻量展示**；若要做告警、长期存储、复杂查询，仍建议配合 Prometheus/Grafana 等，Homer 作为入口与概览即可。

---

## 部署思路

- Homer 作为普通 Web 应用运行在 K3s
- 通过 Traefik 暴露域名（例如 `home.example.com`）

---

## 快速部署

```bash
kubectl create ns homer
kubectl apply -f ansible/files/05-01/homer.yaml
```

**唯一真源**：[`ansible/files/05-01/homer.yaml`](../ansible/files/05-01/homer.yaml)（ConfigMap + Deployment + Service + Ingress）。

### 自定义导航（config.yml）

- 清单内 **ConfigMap `homer-config`** 的键 **`config.yml`** 即 Homer 主配置；**所有书签/分组只改这一段**，不必为每个链接单独写 Kubernetes YAML。
- 镜像约定：该文件挂载到容器内 **`/www/assets/config.yml`**（与 [b4bz/homer](https://hub.docker.com/r/b4bz/homer/) 说明一致）。
- Deployment 已设 **`INIT_ASSETS=0`**，避免启动脚本覆盖你提供的 `config.yml`。
- 修改后重新应用并滚动 Pod 生效：

```bash
kubectl apply -f ansible/files/05-01/homer.yaml
kubectl -n homer rollout restart deploy/homer
```

若只想用镜像默认页：按 `homer.yaml` 文件头注释删除 ConfigMap，并去掉 Deployment 中的 `env` / `volumes` / `volumeMounts`。

### `type: Glances` 卡片（目标机 CPU / 内存等）

在 `config.yml` 里可配置 **Glances** 类型条目，用于展示**某台机器**的系统指标（非普通超链接卡片）。

**示例（摘自 Homer 文档形态，按需改 `url`）：**

示例真源：[`ansible/files/05-01/homer-glances-item.example.yaml`](../ansible/files/05-01/homer-glances-item.example.yaml)

**在目标机用 Docker 跑 Glances（Web 模式）示例**（Homer 的 `url` 需指向该服务可访问地址，默认端口以镜像说明为准）：

示例真源：[`ansible/files/05-01/glances-docker-compose.example.yaml`](../ansible/files/05-01/glances-docker-compose.example.yaml)

**要点：**

- **`url` 指向谁，图上的 CPU / 内存 / swap / load 就是谁的数据**——即运行 **Glances** 并对外暴露接口的那台主机（或该进程的监听地址），**不是** Homer Pod 自己的指标，也不是任意 `https://my-service` 自动就能出数。
- **`stats`**：从该 Glances **目标**上选取要展示的字段，与「目标」一一对应。
- **多台机器**：每台通常需要 **各自的 Glances 实例**（不同主机、端口或反代路径），在 Homer 里 **多条目、多条 `url`**，一条对应一个目标。
- **目标上没有 Glances**：不能靠 `type: Glances` 拉指标；可改为普通 `items` 链接，或在目标上部署 Glances 后再填 `url`。
- **`url` 具体路径**（是否带 `/api/3` 等）取决于你所部署的 Glances 版本与暴露方式，以浏览器或 `curl` 能访问到的 Glances 接口为准。

---

## 验证

```bash
kubectl -n homer get pod,svc,ing -o wide
curl -I --max-time 3 http://192.168.2.61/
```

---

## 下一步

- `05-02-onenav首页面板.md`

## 排障

- **先看 playbook 输出**：失败时先定位是 deploy/wait/http_check 哪一步。
- **集群侧总览**：`kubectl get nodes -o wide`、`kubectl -n kube-system get pods -o wide`。
- **事件与日志**：`kubectl -n <ns> describe ...`、`kubectl -n <ns> logs ... --tail=200`。