From f19c5688172240fcdb61f0019c7bf38ef2f6fa84 Mon Sep 17 00:00:00 2001 From: panxiao81 Date: Wed, 16 Sep 2026 16:11:19 +0000 Subject: [PATCH] =?UTF-8?q?=E8=A1=A5=E5=85=85=20Gitea=20Actions=20?= =?UTF-8?q?=E4=B8=8E=20Grafana=20=E9=9D=A2=E5=90=91=E4=BD=BF=E7=94=A8?= =?UTF-8?q?=E8=80=85=E7=9A=84=E5=85=A5=E9=97=A8=E6=8C=87=E5=8D=97?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 2 + documentation-backlog.md | 19 ++++++---- services/gitea.md | 76 +++++++++++++++++++++++++++++++++++++ services/grafana.md | 82 ++++++++++++++++++++++++++++++++++++++++ services/index.md | 4 +- 5 files changed, 174 insertions(+), 9 deletions(-) create mode 100644 services/gitea.md create mode 100644 services/grafana.md diff --git a/README.md b/README.md index ba60138..8c8f679 100644 --- a/README.md +++ b/README.md @@ -5,6 +5,8 @@ ## 从这里开始 - [服务总览](services/index.md)：有什么、有什么用、在哪里、状态依据是什么。 +- [Gitea / Actions 入门](services/gitea.md)：登录、创建仓库、运行第一个 CI 与选择 runner。 +- [Grafana 使用指南](services/grafana.md)：内存看板、指标查询和日志搜索。 - [SPIFFE/SPIRE](services/spire.md)：按 #34 整理的阶段状态、使用与 runbook 入口。 - [PostgreSQL Tenant Operator](services/postgresql-tenant-operator.md)：计划在共享 PostgreSQL 上提供的 DBaaS 中间层。 - [Gitea Dynamic Runner](services/gitea-dynamic-runner.md)：原 microVM runner，现支持 Pod/VM 两种一次性执行环境。 diff --git a/documentation-backlog.md b/documentation-backlog.md index 8a5569b..0e5e213 100644 --- a/documentation-backlog.md +++ b/documentation-backlog.md @@ -3,14 +3,19 @@ 本轮待核实事项已于 2026-09-16 收尾。以下是后续写作工作，不是未解决的状态核实任务， 也不代表所有相关项目都已部署或经过现场验收。需要补充事实时仍先向维护者对齐范围。 -## 优先补充的使用说明 +## 已补充使用指南 -1. Gitea / Actions：登录、创建仓库、选择 runner，以及可信任务限制。 -2. Grafana：登录、找到内存与 Swap 看板、查询指标和日志的一个完整例子。 -3. zot / SeaweedFS：拉取、发布授权、S3 客户端接入，以及数据备份边界。 -4. OpenBao：日常登录、按权限取用秘密、申请权限；与灾难恢复分开说明。 -5. NetBox：查看拓扑与 IPAM 的路径，强调目前是评估镜像，改动入口在 Git。 -6. codex-proxy、LiteLLM gateway、shared PostgreSQL、Tailscale、ps3netsrv、vlmcsd、k3s：整理用途和已知状态；这些目录缺少根 README。 +- [Gitea / Actions](services/gitea.md)：登录、建仓库、最小 CI、runner 选择和常见问题。 +- [Grafana](services/grafana.md)：内存看板、指标查询、日志搜索和数据源用途。 + +以上依据源码文档和上游说明整理，示例未在本轮执行，不作为现场验收记录。 + +## 后续使用说明 + +1. zot / SeaweedFS：拉取、发布授权、S3 客户端接入，以及数据备份边界。 +2. OpenBao：日常登录、按权限取用秘密、申请权限；与灾难恢复分开说明。 +3. NetBox：查看拓扑与 IPAM 的路径，强调目前是评估镜像，改动入口在 Git。 +4. codex-proxy、LiteLLM gateway、shared PostgreSQL、Tailscale、ps3netsrv、vlmcsd、k3s：整理用途和已知状态；这些目录缺少根 README。 ## 文档同步与来源链接 diff --git a/services/gitea.md b/services/gitea.md new file mode 100644 index 0000000..c222d2e --- /dev/null +++ b/services/gitea.md @@ -0,0 +1,76 @@ +--- +title: Gitea 与 Actions 使用指南 +lifecycle: active +evidence: documented +last_reviewed: 2026-09-16 +last_verified: null +--- + +# Gitea 与 Actions + +Gitea 托管 homelab 的代码、文档、issue 和 PR；Actions 执行仓库声明的 CI workflow。 +入口为 ，人类登录使用 [Authelia](authelia.md)。 + +本页依据现有服务 README、runner README、仓库 workflow 和官方使用文档整理。 +本轮没有重新验证登录或运行示例；下面的操作是使用指南，不是本轮执行记录。 + +## 登录并找到项目 + +1. 打开 Gitea，选择已配置的 Authelia/OIDC 登录入口。 +2. 在 Authelia 完成认证，返回 Gitea；应用权限由 Gitea 账号和仓库授权决定。 +3. 打开目标仓库：Code 看源码，Issues 看动态工作，Pull Requests 看待合并改动，Actions 看 CI。 + +登录成功但看不到仓库时，先确认当前账号与仓库权限；OIDC 登录本身不会赋予所有项目的管理权。 +已有账号应沿用原账号关联，遇到关联问题交由管理员处理，不另建同名账号规避。 + +## 创建与修改仓库 + +通过页面的 New Repository 创建仓库，选择所属用户或组织、名称及可见性。 +仓库里的 Clone 按钮提供当前准确的 HTTPS/SSH 地址，复制该地址到 Git 客户端即可。 +浏览器的 OIDC 会话不直接充当 Git 命令行凭据；客户端使用自己的凭据管理或已登记 SSH key。 + +日常修改先建分支、提交并推送，再开 PR 合并到 main。PR 应说明最终行为与验证结果， +不要把本机未提交的其他工作一并带入。基础设施仓库默认以中文维护 commit、PR 和文档。 + +## 第一个 CI workflow + +在可信的测试仓库中启用 Repository Actions，再添加 `.gitea/workflows/hello.yaml`： + +```yaml +name: Hello +on: [push] +jobs: + hello: + runs-on: self-hosted + steps: + - name: Check execution + run: echo 'homelab CI is running' +``` + +推送该文件后，进入 Actions，打开本次运行和 hello job。 +预期看到输出 `homelab CI is running` 且 job 成功；示例不需要检出源码或读取秘密。 +若仓库设置没有 Actions 开关，先确认自己的管理权限。 +workflow 路径、启用方式与事件规则见 [Gitea 官方入门](https://docs.gitea.com/usage/actions/quickstart/)。 + +`self-hosted` 来自现有 homelab-infra workflow。本页没有检查当前在线 runner： +如果任务排队，先查看 runner 是否在线以及是否匹配 labels，不能把入队当作执行成功。 + +## 选择 runner + +| 需求 | 使用入口 | +|---|---| +| 现有可信仓库的常规 CI | 已有 workflow 使用 `self-hosted`；常驻 runner 的实现见 `platform/gitea-runner/README.md` | +| 动态一次性 Pod 或 VM | [Dynamic Runner](gitea-dynamic-runner.md)，接口为 `[self-hosted, pod]` / `[self-hosted, vm]`；开发进度及启用条件以项目文档为准 | + +常驻 runner 使用 privileged DinD，README 明确限定可信 workflow；不要为不可信代码开放它。 +动态 runner 提供环境及获取自身 SPIFFE 身份的能力；登录下游、请求 token 和凭据清理由 workflow 负责。 + +## 遇到问题先看哪里 + +- 没有触发：看 Actions 是否启用、文件是否位于正确路径、事件是否匹配此次推送。 +- 一直排队：看仓库可用 runner、在线状态和 labels；动态 runner 的问题回到其项目文档。 +- job 失败：打开具体 step 的日志，从第一个失败步骤排查，不只看最终退出码。 +- Git 命令失败但网页能登录：分别检查 Git 使用的身份、凭据方式和仓库权限。 + +服务部署与升级恢复以 homelab-infra `apps/gitea/README.md` 为入口；常驻 runner 以 +`platform/gitea-runner/README.md` 为入口。本页不复制 token、密码或部署命令。 diff --git a/services/grafana.md b/services/grafana.md new file mode 100644 index 0000000..8d1d23d --- /dev/null +++ b/services/grafana.md @@ -0,0 +1,82 @@ +--- +title: Grafana 与可观测性使用指南 +lifecycle: active +evidence: documented +last_reviewed: 2026-09-16 +last_verified: null +--- + +# Grafana 与可观测性 + +从 查看 homelab 的指标、日志和追踪。 +使用 Authelia OIDC 登录；远程访问需要到 LAN 的路由及内网 DNS。 + +本页依据现有 observability README、Grafana 数据源配置、内存看板 JSON 和 exporter 说明整理， +部分来源仍在源码工作区、尚未提交。本轮未打开网页或执行查询；以下结果描述是使用预期。 + +## 先看主机内存与 Swap + +1. 打开 [Homelab 内存与 Swap](https://grafana.ad.ddupan.top/d/homelab-memory)。 +2. 时间范围选择最近 1 小时，需要定位问题时改成问题发生的具体时段。 +3. 先看“主机物理内存”“Swap 使用量”“Swap 换页速率”，再看程序/虚拟机 PSS 和 Pod working set。 +4. 对比异常发生前后的曲线，记录时间与相关程序或 Pod，便于继续查日志。 + +看板来源为 `platform/observability/grafana/dashboards/homelab-memory.json`。 +PSS、RSS、Pod working set 和 ZFS ARC 是不同统计口径，不应直接相加。 +“没有数据”表示当前查询没有返回匹配样本，不等于数值为零。 + +## 自己查一条指标 + +进入 Explore，选择 **VictoriaMetrics** 数据源，时间范围设为最近 1 小时， +在 Code 模式输入以下看板已有的表达式，再执行查询： + +```promql +node_memory_MemTotal_bytes{job="node-exporter"} + - node_memory_MemAvailable_bytes{job="node-exporter"} +``` + +它计算主机已用内存，单位为字节。预期按采集目标返回曲线；有多个目标时， +查看返回标签后选择相应 instance，避免把多台机器当作一台解读。 +该环境特意限定 `job="node-exporter"`，避免旧 docker-hosts 抓取同端口导致重复统计。 + +如需查看 Swap 换出活动，可使用看板已有查询： + +```promql +rate(node_vmstat_pswpout{job="node-exporter"}[5m]) +``` + +单位是 pages/s，不是 bytes/s。查询入口与编辑器行为见 +[Grafana Prometheus 查询文档](https://grafana.com/docs/grafana/latest/datasources/prometheus/query-editor/)。 + +## 找一段日志 + +1. 进入 Explore，切换到 **VictoriaLogs** 数据源，设定最近 15 分钟。 +2. 输入 `* | limit 20` 执行查询，展开一条结果，观察这套采集实际提供的字段。 +3. 用真实出现的 namespace、Pod 或应用字段收窄范围；不要预先假定字段名。 +4. 要找错误消息，可先输入 `error | limit 50`；有结果后按实际字段进一步筛选。 + +VictoriaLogs 使用 LogsQL。上述 limit 限制返回数量，不保证返回的是最新若干条。 +关键字没有结果时可以放宽时间范围并回到第一步，区分“没有该关键字”与“没有采集数据”。 +语法依据见 [VictoriaLogs 查询说明](https://docs.victoriametrics.com/victorialogs/querying/)。 + +## 三个数据源的分工 + +| 数据源 | 用途 | +|---|---| +| VictoriaMetrics | Prometheus 兼容指标查询，例如内存、CPU、采集健康 | +| VictoriaLogs | LogsQL 日志查询 | +| VictoriaTraces | Jaeger 兼容追踪查询；应用需要先接入追踪，不能仅凭数据源存在认为所有服务都有 trace | + +数据源名称来自 `platform/observability/grafana/values.yaml`。 + +## 出问题时与维护入口 + +- 域名打不开：先区分内网 DNS、到 LAN 的路由和浏览器证书错误。 +- 登录后无权限：检查 Grafana 的账号/角色授权，Authelia 登录不等于管理员权限。 +- 看板空白：检查时间范围、数据源和筛选条件，再区分缺少采集与查询失败。 +- 指标与日志不一致：先对齐时间和目标实例，再判断是否为采集范围不同。 + +部署、采集与恢复入口为 homelab-infra `platform/observability/README.md`； +内存指标解释见 `platform/observability/metrics/exporters/README.md`。 +看板配置由 Git/ConfigMap 管理，网页临时调整不作为持久配置的权威来源。 +旧 Compose 栈与数据已[清理](victoriametrics-legacy.md)，不要再使用旧实例作为排障入口。 diff --git a/services/index.md b/services/index.md index 10069d5..17b8c6a 100644 --- a/services/index.md +++ b/services/index.md @@ -17,7 +17,7 @@ SPIFFE/SPIRE 已按维护者授权补读 #34；LAN DNS 与 Authelia 已按维护 | [authelia](authelia.md) | 唯一主 OIDC broker、统一登录 | `auth.ddupan.top` | active；维护者于 2026-09-16 明确已在工作 | 维护者说明、`apps/authelia/` | 同步源码 README 中过时的 OIDC 阶段说明 | | [blocky](lan-dns.md) | LAN 主 DNS、广告过滤、分流 | `192.168.10.127:53` | 维护者说明已作为 DHCP 主 DNS，上游为路由器 | 维护者 2026-09-16 说明、`apps/blocky/README.md` | 无需逐台确认主机；旧源码说明待同步 | | codex-proxy | 代理服务，具体接口未记录 | `未记录` | 仅发现配置 | `apps/codex-proxy/docker-compose.yml` | 缺 README 与使用说明 | -| gitea | 代码托管与 Actions | `git.ddupan.top` | 记录已部署 | `apps/gitea/README.md` | 补首次使用与 runner 选择 | +| [gitea](gitea.md) | 代码托管与 Actions | `git.ddupan.top` | 记录已部署 | `apps/gitea/README.md` | 已有登录、最小 CI 与 runner 选择指南 | | http-echo | Flux 部署与漂移修复 canary | `集群内` | 记录已验证 | `apps/http-echo/README.md` | 已有验证步骤 | | litellm-gateway | 模型 API 网关，实际消费者未记录 | `未记录` | 仅发现配置 | `apps/litellm-gateway/docker-compose.yml` | 缺 README 与接入说明 | | marker | GPU 文档转换 API | `集群内端口 8001` | 配置与部署指南；未附上线记录 | `apps/marker/README.md` | 缺 API 使用例子 | @@ -42,7 +42,7 @@ SPIFFE/SPIRE 已按维护者授权补读 #34；LAN DNS 与 Authelia 已按维护 | gitea-runner | 可信 Gitea Actions 任务执行 | `Gitea Actions` | 记录已接管 Flux | `platform/gitea-runner/README.md` | 补 workflow label 与使用限制 | | k3s | 集群 CoreDNS 定制 | `集群内 DNS` | 仅发现 DNS 配置 | `platform/k3s/Corefile.desired` | 缺组件 README | | [nats](nats.md) | 集群共享消息与 JetStream 队列 | `nats.ad.ddupan.top:4222` | 已部署；维护者说明目前唯一消费者为 Dynamic Runner | 维护者 2026-09-16 说明、`platform/nats/README.md` | runner 消息队列约定以独立项目文档为准 | -| observability | Grafana、指标、日志和追踪 | `grafana.ad.ddupan.top` | 记录已接管 Flux；9 月 16 日变更入口 | `platform/observability/README.md` | 补看板和查询使用指南 | +| [observability / Grafana](grafana.md) | Grafana、指标、日志和追踪 | `grafana.ad.ddupan.top` | 记录已接管 Flux；9 月 16 日变更入口 | `platform/observability/README.md` | 已有看板、指标与日志查询指南 | | openebs | k3s 本地 ZFS 持久卷 | `localpv-zfs-ceph StorageClass` | 记录已接管 Flux | `platform/openebs/README.md` | 已有运维检查；补 PVC 使用边界 | | [spire](spire.md) | 跨基础设施的统一机器身份入口 | `Workload API / spire-oidc.ad.ddupan.top` | #34 记录基础设施与最小 OpenBao PoC 已完成；后续集成进行中 | [#34](https://git.ddupan.top/panxiao81/homelab-infra/issues/34)、[RUNBOOK](https://git.ddupan.top/panxiao81/homelab-infra/src/branch/main/platform/spire/RUNBOOK.md) | 已有接入指南；动态任务以 ticket 为准 |