From 45a29bf9b9751265fbdaf2e34a70ec2afe8b5a96 Mon Sep 17 00:00:00 2001 From: panxiao81 Date: Wed, 16 Sep 2026 15:29:27 +0000 Subject: [PATCH] =?UTF-8?q?=E6=98=8E=E7=A1=AE=20NATS=20=E5=85=B1=E4=BA=AB?= =?UTF-8?q?=E6=9C=8D=E5=8A=A1=E5=AE=9A=E4=BD=8D=E5=8F=8A=E5=8A=A8=E6=80=81?= =?UTF-8?q?=20runner=20=E6=96=87=E6=A1=A3=E7=9A=84=E8=BF=9B=E5=BA=A6?= =?UTF-8?q?=E5=BD=92=E5=B1=9E?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 1 + architecture/constraints.md | 1 + services/gitea-dynamic-runner.md | 16 +++++++++++----- services/index.md | 6 +++--- services/nats.md | 30 ++++++++++++++++++++++++++++++ verification.md | 7 +++++-- 6 files changed, 51 insertions(+), 10 deletions(-) create mode 100644 services/nats.md diff --git a/README.md b/README.md index 01aba53..d17c9a1 100644 --- a/README.md +++ b/README.md @@ -8,6 +8,7 @@ - [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 两种一次性执行环境。 +- [NATS](services/nats.md)：已部署的集群共享消息服务，目前仅 Dynamic Runner 消费。 - [LAN DNS](services/lan-dns.md)：Blocky 主 DNS、路由器上游与备用、Samba AD 域 DNS 的现状。 - [Authelia](services/authelia.md)：active 的唯一主 OIDC broker 与登录入口。 - [待核实与文档缺口](verification.md)：互相矛盾的记录、缺少使用说明的服务、下一步核实方法。 diff --git a/architecture/constraints.md b/architecture/constraints.md index f804016..56b8362 100644 --- a/architecture/constraints.md +++ b/architecture/constraints.md @@ -18,6 +18,7 @@ | NetBox 目前是评估，拓扑由 Git 管理 | 不把网页编辑结果当作新的权威数据 | `apps/netbox/README.md`、`CLAUDE.md` | | 现有 privileged DinD runner 只运行可信 workflow | 实例级 runner 不能视为不可信任务隔离边界 | `platform/gitea-runner/README.md` | | 每个动态 Pod/VM 应能独立取得自身 SPIFFE 身份；runner 只提供执行环境 | 登录目标、audience、token 交换及业务凭据生命周期由 workflow 决定；服务自行维护权限 | [Dynamic Runner 设计原则](../services/gitea-dynamic-runner.md)，维护者于 2026-09-16 明确 | +| NATS 是集群共享消息服务，目前仅 Dynamic Runner 消费 | 平台服务与消费者职责分开；runner 的 durable 等动态业务约定由其项目文档维护 | [NATS](../services/nats.md)，维护者于 2026-09-16 说明 | | zot 匿名入口只读；鉴权入口必须按具体身份授权 | 能认证不代表可以推送；不得给整个 trust domain 写权限 | `apps/zot/README.md` | 通用变更约束：先做适用的 plan/check/diff，再操作现场；不将凭据和 Terraform state diff --git a/services/gitea-dynamic-runner.md b/services/gitea-dynamic-runner.md index 75644d8..48b62ba 100644 --- a/services/gitea-dynamic-runner.md +++ b/services/gitea-dynamic-runner.md @@ -15,9 +15,10 @@ sources: 它为 Gitea Actions 按需创建一次性执行环境，支持 Kubernetes Pod 和 Cloud Hypervisor microVM；每个环境只执行一个 job，结束后销毁环境及本地状态。 -更名由维护者提供；以下内容依据 2026-09-16 查阅的项目 README。 -README 描述了 bootstrap 实现与后续路线，没有明确记录当前部署范围或端到端上线验收。 -本页因此按试验阶段记录，不表示现场 runner 已注册或下面的 labels 已可调度；本轮未查询现场。 +更名由维护者提供；以下组件与接口说明依据 2026-09-16 查阅的项目 README。 +维护者进一步明确：**项目正在积极开发，具体启用范围和实现进度以该项目文档为准。** +本页保留用途、设计原则和该次 README 的摘要，不另行维护部署范围或消息队列参数清单。 +本轮未查询现场，不将设计接口视为已完成的上线验收。 ## workflow 如何选择执行环境 @@ -55,7 +56,11 @@ Gitea workflow_job webhook `microvm-runner-launch` 管理 VM 的临时磁盘、网络及清理，`guest-runner` 领取一次性 注册凭据并以 ephemeral 模式注册。`pod-worker` 创建 Kubernetes 执行 Pod。 -同一 runner label 的 worker 共享同一个 durable consumer，通过增加 worker 或 capacity 扩容。 +该次 README 描述同一 runner label 的 worker 共享同一个 durable consumer，通过增加 worker +或 capacity 扩容。具体 durable 名称和后续调度改动以项目文档为准。 + +[NATS](nats.md) 作为集群共享服务部署；维护者说明当前只有 Dynamic Runner 消费它， +不因此将 NATS 视为 runner 私有组件。 webhook → NATS 是尽快验证 Pod/VM 生命周期的 bootstrap 实现。 长期目标是 controller 兼容 Gitea Runner 协议，直接注册、声明 labels、领取 task， @@ -96,4 +101,5 @@ runner 不应替 workflow 选择下游 role/policy，或统一代理其业务凭 - [Runner 协议路线](https://git.ddupan.top/panxiao81/gitea-dynamic-runner/src/branch/main/docs/runner-protocol-roadmap.md)：README 指向的长期调度路线与迁移边界，本轮未逐篇复核。 - [SPIFFE/SPIRE](spire.md)：统一机器身份的设计定位与阶段依据。 -后续需补充实际启用范围、workflow 验收示例和失败任务排障入口；查询前先向维护者对齐动态工作。 +实际启用范围、workflow 验收、排障及消息队列约定在项目文档中维护。 +开发中的变化直接以项目文档为准，知识库不另列“启用范围待核实”任务。 diff --git a/services/index.md b/services/index.md index a1bc7a5..4ce9591 100644 --- a/services/index.md +++ b/services/index.md @@ -40,7 +40,7 @@ SPIFFE/SPIRE 已按维护者授权补读 #34；LAN DNS 与 Authelia 已按维护 | external-secrets | OpenBao 到 Kubernetes 的秘密投射 | `Kubernetes API` | Helm 记录已接管；对象范围需区分 | `platform/external-secrets/README.md` | 补新增秘密引用的使用流程 | | gitea-runner | 可信 Gitea Actions 任务执行 | `Gitea Actions` | 记录已接管 Flux | `platform/gitea-runner/README.md` | 补 workflow label 与使用限制 | | k3s | 集群 CoreDNS 定制 | `集群内 DNS` | 仅发现 DNS 配置 | `platform/k3s/Corefile.desired` | 缺组件 README | -| nats | 共享消息与 JetStream 队列 | `nats.ad.ddupan.top:4222` | 有配置与拓扑记录；现场待核实 | `platform/nats/README.md` | 补生产/消费示例与队列检查 | +| [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` | 补看板和查询使用指南 | | 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 为准 | @@ -54,7 +54,7 @@ SPIFFE/SPIRE 已按维护者授权补读 #34；LAN DNS 与 Authelia 已按维护 | docker | 宿主 Docker 网络管理 | `laptop` | 记录已迁移地址池 | `infrastructure/docker/README.md` | 已有 DN42 与挂载路径约束 | | kata-lab | Kata VM 试验环境 | `历史 VMID 147` | 记录 9 月 14 日已销毁 | `infrastructure/kata-lab/README.md` | 保留验证历史，勿当现役 VM | | kata-lxc-lab | LXC 内 Kata worker 试验 | `pve2 / 记录地址 192.168.10.128` | 记录 PoC 验证；非正式生产服务 | `infrastructure/kata-lxc-lab/README.md` | 明确与 microVM runner 的职责 | -| microvm-runner（历史目录名） | 动态 runner 的 homelab 基础设施记录 | 当前项目接口见 [Dynamic Runner](gitea-dynamic-runner.md) | 旧工作区记录 PoC；独立项目已更名并扩展到 Pod/VM，实际启用范围未查询 | `infrastructure/microvm-runner/README.md`、独立项目 README | 软件与基础设施职责已明确；旧 kind-microvm label 不作为当前接口 | +| microvm-runner（历史目录名） | 动态 runner 的 homelab 基础设施记录 | 当前项目接口见 [Dynamic Runner](gitea-dynamic-runner.md) | 独立项目已更名并扩展到 Pod/VM，正在积极开发 | `infrastructure/microvm-runner/README.md`、独立项目文档 | 具体启用范围和实现进度以独立项目文档为准 | | oci | 云主机、网络与站点互联 | `OCI ap-osaka-1` | 有恢复、接管与网络实施记录 | `infrastructure/oci/README.md` | 补跨站点使用入口 | | openbao | 秘密管理与内部 CA | `bao.ad.ddupan.top` | 有部署与接管记录 | `infrastructure/openbao/README.md` | 补日常使用和恢复入口 | | proxmox | PVE、虚拟化与主机基础设施 | `PVE 管理入口` | 已有基础设施；README 混有设计设想 | `infrastructure/proxmox/README.md` | 分离当前环境与 workload identity 设想 | @@ -68,7 +68,7 @@ SPIFFE/SPIRE 已按维护者授权补读 #34；LAN DNS 与 Authelia 已按维护 ## 计划、归档与范围外 -- [Gitea Dynamic Runner](gitea-dynamic-runner.md)：独立开发的动态 Pod/VM runner，原名 gitea-microvm-runner；README 描述 bootstrap 实现与长期调度路线，部署范围尚未查询。 +- [Gitea Dynamic Runner](gitea-dynamic-runner.md)：正在积极开发的动态 Pod/VM runner，原名 gitea-microvm-runner；具体启用范围、调度和队列约定以项目文档为准。 - [PostgreSQL Tenant Operator](postgresql-tenant-operator.md)：计划中的 DBaaS 中间层，管理共享实例中的数据库与账号；README 记录为 API 骨架阶段，不代表服务已上线。 - [workload-sts](../architecture/workload-sts-history.md)：已归档的早期机器身份方案；停止开发、不部署 PoC，由 SPIFFE/SPIRE 替代。 - Backstage：规划中的服务目录与文档入口；本轮未发现独立部署目录。 diff --git a/services/nats.md b/services/nats.md new file mode 100644 index 0000000..aa208e3 --- /dev/null +++ b/services/nats.md @@ -0,0 +1,30 @@ +--- +title: NATS +lifecycle: active +evidence: documented +last_reviewed: 2026-09-16 +last_verified: null +sources: + - 维护者于 2026-09-16 提供的部署与消费者说明 +--- + +# NATS + +**NATS 已作为集群共享消息服务部署，目前唯一的消费者是 Dynamic Runner。** +这是维护者于 2026-09-16 提供的现状；本轮未查询运行环境。 + +共享服务的定位不随当前消费者数量改变。NATS 属于平台基础设施， +Dynamic Runner 使用它传递任务消息，但不独占消息服务的用途和生命周期。 + +## 如何接入与维护 + +平台部署、连接入口、TLS 和账户配置以 homelab-infra 的 `platform/nats/README.md` +及其配置为维护入口。新增消费者应使用适合自身的账户与权限，不能直接沿用 runner 的业务约定。 + +Dynamic Runner 的 stream、subject、durable 名称、worker 配置和具体启用范围，以 +[gitea-dynamic-runner 项目文档](https://git.ddupan.top/panxiao81/gitea-dynamic-runner) +为准。项目正在积极开发，知识库不复制维护这些易变细节，也不把旧示例的 durable 名称差异 +单独列为必须查询现场的冲突。 + +知识库只保留[Dynamic Runner 的用途与职责边界](gitea-dynamic-runner.md)。 +涉及 runner 的实际配置和实现进度时，先按项目文档接续工作；需要扩大查询范围时再向维护者确认。 diff --git a/verification.md b/verification.md index 1c56f95..5739ffc 100644 --- a/verification.md +++ b/verification.md @@ -6,6 +6,11 @@ ## 已对齐的动态工作 +NATS 已作为集群共享服务部署，当前唯一消费者为 Dynamic Runner，见 [NATS](services/nats.md)。 +维护者明确 Dynamic Runner 正在积极开发，其启用范围、durable 名称和实现进度以 +[项目文档](https://git.ddupan.top/panxiao81/gitea-dynamic-runner)为准。 +不再将旧示例的 durable 名称差异或启用范围列为独立待核实项。 + Authelia 已按维护者于 2026-09-16 的说明标为 **active、唯一的主 OIDC broker**， 见 [Authelia](services/authelia.md)。原工作区的“OIDC 后续启用”描述待同步， 不再将其列为上线状态冲突，也不据此发起现场核实。 @@ -24,8 +29,6 @@ SPIFFE/SPIRE 按维护者指定，以 [#34](https://git.ddupan.top/panxiao81/hom | 项目 | 两边的记录 | 核实与收敛方式 | |---|---|---| -| Dynamic Runner 的启用范围 | 新仓库 README 定义 Pod/VM 两种接口；旧工作区仍记录 kind-microvm PoC | 软件与基础设施归属已由 README 明确；实际启用范围先问维护者，再按指定 ticket 或验证记录补充，不将旧 PoC 当作新接口已上线的依据 | -| NATS durable 名称 | NATS 文档示例为 `kind-microvm-pve2`；microVM 文档配置为 `kind-microvm`，要求同类 worker 共享 durable | 查运行配置和 consumer；统一文档，避免多 worker 队列语义不一致 | | 旧 VictoriaMetrics Compose | `platform/observability/README.md` 说已替代；`apps/victoriametrics/` 仍留配置 | 只读检查 Docker 与采集目标，确认是否仍承担职责，再标记退役或迁移 | ## 优先补充的使用说明