From e6cd82e60687bb3840770ecffb4ffe60c2db65fc Mon Sep 17 00:00:00 2001 From: panxiao81 Date: Wed, 16 Sep 2026 18:17:09 +0000 Subject: [PATCH] =?UTF-8?q?=E8=A1=A5=E5=85=85=E7=BD=91=E5=85=B3=E4=B8=8E?= =?UTF-8?q?=E8=BF=9C=E7=A8=8B=E5=AE=A2=E6=88=B7=E7=AB=AF=E6=8C=87=E5=8D=97?= =?UTF-8?q?=E5=B9=B6=E5=BD=92=E6=A1=A3=20codex-proxy=20=E7=8A=B6=E6=80=81?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 3 ++ documentation-backlog.md | 10 +++++- services/index.md | 11 +++--- services/litellm-gateway.md | 68 +++++++++++++++++++++++++++++++++++++ services/ps3netsrv.md | 47 +++++++++++++++++++++++++ services/tailscale.md | 62 +++++++++++++++++++++++++++++++++ services/vlmcsd.md | 41 ++++++++++++++++++++++ verification.md | 4 +++ 8 files changed, 240 insertions(+), 6 deletions(-) create mode 100644 services/litellm-gateway.md create mode 100644 services/ps3netsrv.md create mode 100644 services/tailscale.md create mode 100644 services/vlmcsd.md diff --git a/README.md b/README.md index eb3e858..3d404f9 100644 --- a/README.md +++ b/README.md @@ -12,6 +12,9 @@ - [OpenBao 使用指南](services/openbao.md)：日常登录、按权限取密与机器身份边界。 - [NetBox 使用指南](services/netbox.md)：浏览设备和 IPAM，按 Git 来源维护资产镜像。 - [SPIFFE/SPIRE](services/spire.md)：按 #34 整理的阶段状态、使用与 runbook 入口。 +- [LiteLLM 网关](services/litellm-gateway.md)：模型 API 接入参数与请求示例。 +- [Tailscale](services/tailscale.md)：远程客户端、子网路由与 Service 入口。 +- [ps3netsrv](services/ps3netsrv.md) / [vlmcsd](services/vlmcsd.md)：客户端接入与故障入口。 - [共享 PostgreSQL 使用指南](services/shared-postgresql.md)：应用接入、连接示例与共享实例维护边界。 - [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 bd84b3e..384dbaf 100644 --- a/documentation-backlog.md +++ b/documentation-backlog.md @@ -14,11 +14,19 @@ - [共享 PostgreSQL](services/shared-postgresql.md)：应用接入、连接检查与共享实例维护边界。 +- [LiteLLM](services/litellm-gateway.md)：模型请求、认证边界与独立数据库依赖。 +- [Tailscale](services/tailscale.md)：客户端接入、子网路由和 operator Service 的区别。 +- [ps3netsrv](services/ps3netsrv.md)、[vlmcsd](services/vlmcsd.md)：客户端使用与配置入口。 + 以上依据源码文档和上游说明整理，示例未在本轮执行，不作为现场验收记录。 ## 后续使用说明 -1. codex-proxy、LiteLLM gateway、Tailscale、ps3netsrv、vlmcsd、k3s：整理用途和已知状态；这些目录缺少根 README。 +1. k3s：补 CoreDNS 定制说明；目录缺少根 README。 +2. marker、openviking、smtp-relay、external-secrets、openebs 等：按服务总览逐步补齐消费示例。 + +codex-proxy 已按维护者“应该是退役的”的说明移至归档范围，不再补新接入指南。 +本轮新增的四份使用指南已完成；其源码目录仍缺根 README，权威配置入口已在各页列出。 ## 文档同步与来源链接 diff --git a/services/index.md b/services/index.md index b5a767e..a1c8c23 100644 --- a/services/index.md +++ b/services/index.md @@ -16,20 +16,19 @@ 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](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 与接入说明 | +| [litellm-gateway](litellm-gateway.md) | 模型 API 网关，实际消费者未记录 | `宿主 TCP 4000；地址未记录` | 仅发现配置 | `apps/litellm-gateway/docker-compose.yml` | 已有参数、请求示例与依赖说明 | | marker | GPU 文档转换 API | `集群内端口 8001` | 配置与部署指南；未附上线记录 | `apps/marker/README.md` | 缺 API 使用例子 | | netboot | PXE 与系统安装 | `192.168.10.127` | 有部署及使用记录 | `apps/netboot/README.md` | 已有客户端启动说明 | | [netbox](netbox.md) | 网络资产与地址管理评估 | `netbox.ad.ddupan.top` | 记录已部署；评估用途 | `apps/netbox/README.md` | 已有浏览与 Git 修改入口指南 | | openviking | 上下文检索服务 | `记录端口 1933 / 8020` | 配置与部署指南；未附上线记录 | `apps/openviking/README.md` | 缺导入、查询的完整例子 | -| ps3netsrv | PS3 网络内容服务 | `未记录` | Docker 运维文档记录运行 | `apps/ps3netsrv/docker-compose.yml` | 缺客户端使用与挂载说明 | +| [ps3netsrv](ps3netsrv.md) | PS3 网络内容服务 | `宿主 TCP 38008；地址未记录` | Docker 运维文档记录运行 | `apps/ps3netsrv/docker-compose.yml` | 已有客户端与内容目录指南 | | [seaweedfs](seaweedfs.md) | S3 对象存储 | `s3.ad.ddupan.top` | zot 文档记录已使用 | `apps/seaweedfs/README.md` | 已有客户端读写指南与备份边界说明 | | [shared-postgresql](shared-postgresql.md) | 共享 PostgreSQL / CNPG | `shared-db namespace` | 历史迁移记录已完成 | `apps/shared-postgresql/migration.md` | 已有连接、应用接入与共享资源边界指南 | | smtp-relay | 应用经 Microsoft 365 发信 | `smtp-relay.smtp-relay.svc.cluster.local:25` | 有配置与测试指南；未附上线记录 | `apps/smtp-relay/README.md` | 补发信链路与消费者说明 | -| tailscale | 远程网络与子网路由 | `Tailscale 网络` | 有配置；本轮未读敏感安装脚本 | `apps/tailscale/subnet-routes.sh` | 缺 README、路由与客户端说明 | -| vlmcsd | KMS 兼容服务，使用范围未记录 | `未记录` | 仅发现配置 | `apps/vlmcsd/compose.yaml` | 缺 README 与状态说明 | +| [tailscale](tailscale.md) | 远程网络与子网路由 | `Tailscale 网络` | 有配置；本轮未读敏感安装脚本 | `apps/tailscale/subnet-routes.sh` | 已有远程访问与路由边界指南 | +| [vlmcsd](vlmcsd.md) | KMS 兼容服务，使用范围未记录 | `宿主 TCP 1688；地址未记录` | 仅发现配置 | `apps/vlmcsd/compose.yaml` | 已有协议入口与客户端指南；未查询现场 | | [zot](zot.md) | OCI 镜像与制品仓库 | `zot.ad.ddupan.top / zot-push.ad.ddupan.top` | 文档记录 9 月 16 日验收 | `apps/zot/README.md` | 已有拉取与发布模板；实际 publisher 授权以项目配置为准 | ## 平台 @@ -69,6 +68,8 @@ SPIFFE/SPIRE 已按维护者授权补读 #34；LAN DNS 与 Authelia 已按维护 ## 计划、归档与范围外 +- codex-proxy：维护者于 2026-09-16 表述为“应该是退役的”，按退役方向归档；源码目录仍保留，未确认现场清理情况，不再作为新接入对象。 + - [旧 VictoriaMetrics Compose](victoriametrics-legacy.md)：旧配置和三个数据卷已于 2026-09-16 按维护者要求删除；现役监控在 platform/observability。 - [e5renew、research-auto](external-consumers.md)：GitHub 上的外部消费者，不属于 homelab 基础设施；仅保留归属入口。 diff --git a/services/litellm-gateway.md b/services/litellm-gateway.md new file mode 100644 index 0000000..253360b --- /dev/null +++ b/services/litellm-gateway.md @@ -0,0 +1,68 @@ +--- +title: LiteLLM 网关使用指南 +lifecycle: unknown +evidence: configuration +last_reviewed: 2026-09-16 +last_verified: null +--- + +# LiteLLM gateway + +为客户端提供模型 API 代理。维护者于 2026-09-16 表示没有需要补充的动态改动或退役事项； +本页依据 `apps/litellm-gateway/docker-compose.yml` 与 `config.yaml` 整理，不代表已验证运行状态。 + +## 接入参数 + +Compose 映射宿主 TCP `4000` 到网关 `4000`，没有在这些文件中记录统一访问域名。 +先由维护者提供实际 base URL、客户端认证要求及可用模型；不能把宿主端口自动当成公网入口。 +网关客户端的认证与网关访问上游模型的认证是两层配置，不能把服务端认证文件交给消费者。 + +配置中的模型别名包括 `chatgpt/gpt-5.4` 和 `hf/google/embeddinggemma-300m` 等， +分别面向聊天和 embedding；这里只表示路由声明，不保证上游账号有权限或模型当下可用。 +完整别名以 `config.yaml` 为准。不要因名字含有 codex，就把这个网关与已退役的 codex-proxy 混为一体。 + +## 第一次聊天请求 + +在已获授权的客户端环境中，将 `LITELLM_BASE_URL` 设置为维护者提供的 API 根地址， +`LITELLM_MODEL` 设置为获准使用的聊天模型别名。 +如果该入口要求 Bearer key，通过既有秘密注入方式提供 `LITELLM_API_KEY`；是否需要 key 以实际接入约定为准。 +下面使用 Python 标准库，token 不放在命令行中；请求会调用上游模型并消耗对应配额。 + +```python +import json +import os +import urllib.request + +base = os.environ["LITELLM_BASE_URL"].rstrip("/") +headers = {"Content-Type": "application/json"} +key = os.environ.get("LITELLM_API_KEY") +if key: + headers["Authorization"] = "Bearer " + key +payload = { + "model": os.environ["LITELLM_MODEL"], + "messages": [{"role": "user", "content": "Reply with OK."}], +} +request = urllib.request.Request( + base + "/chat/completions", + data=json.dumps(payload).encode(), + headers=headers, + method="POST", +) +with urllib.request.urlopen(request, timeout=60) as response: + result = json.load(response) +print(result["choices"][0]["message"]["content"]) +``` + +预期收到模型回复。接口结构参考 [LiteLLM 客户端文档](https://docs.litellm.ai/docs/proxy/user_keys)， +本轮没有执行请求。该示例面向聊天模型，不能直接拿 embedding 模型替换。 + +## 依赖与排障 + +这套 Compose 包含独立的 PostgreSQL 16 和 Prometheus，数据库卷为 `postgres_data`， +指标卷为 `prometheus_data`；这里的数据库不是[集群共享 PostgreSQL](shared-postgresql.md)。 +Compose 还挂载配置文件及宿主 `auth.json`，后者属于上游认证材料，不进入 wiki、日志或 AI 上下文。 +镜像配置使用 `dev` 标签，接入行为需与实际部署版本相符，不能仅凭最新上游文档认定功能已启用。 + +连接失败先核对宿主与端口；401/403 需区分网关认证和上游认证；模型错误先核对别名及上游权限； +超时或限额错误再检查上游响应。不要通过打印认证文件或完整带鉴权请求排障。 +部署来源为 homelab-infra `apps/litellm-gateway/`；消费者清单与备份情况未在所读文件中记录。 diff --git a/services/ps3netsrv.md b/services/ps3netsrv.md new file mode 100644 index 0000000..d4022e6 --- /dev/null +++ b/services/ps3netsrv.md @@ -0,0 +1,47 @@ +--- +title: ps3netsrv 使用指南 +lifecycle: unknown +evidence: configuration +last_reviewed: 2026-09-16 +last_verified: null +--- + +# ps3netsrv + +为 PS3 客户端通过网络读取游戏内容提供服务。 +维护者于 2026-09-16 表示没有需补充的动态事项；本页依据工作区 +`apps/ps3netsrv/docker-compose.yml` 整理。该文件有未提交修改，以此处注明的工作区为来源。 +本轮没有查询容器、磁盘内容或客户端状态。 + +## 入口与内容目录 + +| 项目 | 配置记录 | +|---|---| +| 镜像 | `shawly/ps3netsrv:latest` | +| TCP 端口 | 宿主 `38008` → 容器 `38008` | +| 宿主内容目录 | `/mnt/pool/games/ps3` | +| 容器内目录 | `/games`，当前映射为读写 | + +所读 Compose 没有指定客户端应使用的宿主 IP 或域名，接入时由维护者提供实际地址。 +这不是浏览器 HTTP 服务，也不能将路径挂载成功等同于客户端已发现内容。 + +## 第一次从 PS3 浏览内容 + +1. 确认目标内容已放入宿主映射目录，且容器配置的用户具有读取权限。 +2. 按客户端要求组织子目录，例如 ISO 内容位于 `PS3ISO/`，目录形式内容位于 `GAMES/`。 +3. 在 webMAN MOD 的网络内容设置中填入服务器地址和端口 `38008`，启用对应网络内容扫描。 +4. 刷新内容列表，选择一个条目挂载并读取，确认整个客户端路径。 + +目录结构见 [容器项目说明](https://github.com/shawly/docker-ps3netsrv)，客户端操作见 +[webMAN MOD PS3 NET Server](https://github.com/aldostools/webMAN-MOD/wiki/~-PS3-NET-Server)。 +本轮未执行以上步骤；具体客户端版本的菜单名称可能不同。 + +## 排障与维护边界 + +- 无法连接：核对实际宿主地址、TCP 端口和客户端到宿主的网络。 +- 列表为空：核对宿主目录、子目录结构、文件权限与客户端扫描设置。 +- 发现内容但读取失败：核对文件可读性及客户端格式支持，再看服务日志。 + +Compose 的 `USER_ID` / `GROUP_ID` 控制容器读文件时的身份；调整前核对宿主所有权， +不要为排障递归修改整个存储池的权限。挂载目录属于内容数据，重建容器不会替代数据备份。 +依赖为 Docker、宿主存储、网络和相容客户端；本页不修改容器或数据目录。 diff --git a/services/tailscale.md b/services/tailscale.md new file mode 100644 index 0000000..6caf364 --- /dev/null +++ b/services/tailscale.md @@ -0,0 +1,62 @@ +--- +title: Tailscale 远程访问指南 +lifecycle: unknown +evidence: documented +last_reviewed: 2026-09-16 +last_verified: null +--- + +# Tailscale + +Tailscale 提供远程访问 homelab 的网络路径。维护者于 2026-09-16 表示没有需补充的动态事项； +本页根据 `apps/tailscale/subnet-routes.sh` 和共享 PostgreSQL Service 配置整理。 +未读取含 OAuth 值的安装脚本，也未查询 tailnet、路由批准状态或现场连通性。 + +## 两种访问路径 + +| 路径 | 来源记录的用途 | +|---|---| +| laptop 子网路由 | 访问 LAN 与两个 SDN 网段中的原有地址 | +| Kubernetes operator 暴露 Service | 为特定 Service 提供 tailnet 入口，例如共享 PostgreSQL | + +子网脚本将 laptop（LAN 地址 `192.168.10.127`）记录为唯一子网路由器，声明以下完整路由集合： + +- `192.168.10.0/24`：homelab LAN。 +- `10.60.0.0/24`：SDN labnet。 +- `10.61.0.0/24`：SDN retronet。 + +operator 管理的 Service 入口不能直接视为新的通用子网路由器。 +子网路由可达也不等于拥有所有目标服务的应用权限。 + +## 第一次从远程客户端访问 + +1. 在自己的客户端登录维护者指定的 tailnet，完成该设备所需的批准流程。 +2. 确认客户端接受子网路由。Linux 客户端需要时可执行下面的设置；它改变本机路由接受配置。 +3. 打开已有权限的 LAN 服务，例如 [Grafana](grafana.md)。域名还须通过适当的 DNS 配置解析。 + +```bash +sudo tailscale set --accept-routes=true +``` + +客户端行为见 [Tailscale 子网路由文档](https://tailscale.com/docs/features/subnet-routers)。 +服务登录仍按该服务自己的流程进行。 +如果访问 operator 暴露的 Service，使用维护者提供的 tailnet 地址； +不要把 Kubernetes `.svc.cluster.local` 名称当成远程客户端已经可解析的名称。 + +## 路由、DNS 与权限分别检查 + +“客户端已登录”“路由已广播”“路由已批准”“访问规则允许”和“目标服务可用”是不同条件。 +LAN 的 [Blocky / 路由器 DNS 设计](lan-dns.md) 不自动证明远程客户端已获得相同解析配置。 +IP 可达而域名失败时，先查看远程客户端 DNS 路径，不直接改 LAN DNS。 + +脚本记录两个 SDN 网段由 laptop 从 VyOS 通过 OSPF 学习。 +即使 Tailscale 仍广播这两个前缀，底层 OSPF 路由缺失也会导致转发失败。 +新增路由还需 tailnet 批准及访问规则配合，单看广播配置不足以验收。 + +`apps/tailscale/subnet-routes.sh` 是维护端脚本，`--advertise-routes` 替换完整集合； +普通客户端接入无需执行它。新增网段时按完整声明审查，避免意外移除既有路由。 +现有脚本提供批准信息的查看方法；执行现场检查前仍需按本库规则对齐范围。 + +依赖为 Tailscale 控制与数据路径、laptop 转发及目标网络；SDN 另依赖 VyOS/OSPF， +operator Service 另依赖 Kubernetes 和 operator。 +本页没有记录 tailnet OAuth、设备密钥或凭据内容。 diff --git a/services/vlmcsd.md b/services/vlmcsd.md new file mode 100644 index 0000000..b06260c --- /dev/null +++ b/services/vlmcsd.md @@ -0,0 +1,41 @@ +--- +title: vlmcsd 服务入口 +lifecycle: unknown +evidence: configuration +last_reviewed: 2026-09-16 +last_verified: null +--- + +# vlmcsd + +homelab 中的 KMS 兼容服务，配置使用 `mikolatero/vlmcsd` 镜像。 +维护者于 2026-09-16 表示没有需补充的动态事项；本页依据 +`apps/vlmcsd/compose.yaml` 整理，未检查运行状态或客户端。 + +## 入口与客户端使用 + +Compose 将宿主 TCP `1688` 映射到容器 `1688`。实际宿主地址和客户端使用范围未在该文件中记录， +接入时由维护者提供；它是协议服务，不是网页，也没有仓库中已记录的 OIDC 登录步骤。 + +已有 Windows KMS 客户端需要指定服务器时，在管理员终端中将 `YOUR_KMS_HOST` 替换为已提供的地址： + +```powershell +cscript.exe "$env:SystemRoot\System32\slmgr.vbs" /skms YOUR_KMS_HOST:1688 +cscript.exe "$env:SystemRoot\System32\slmgr.vbs" /ato +cscript.exe "$env:SystemRoot\System32\slmgr.vbs" /dlv +``` + +第一步修改该客户端的 KMS 目标，第二步发起激活请求，第三步查看结果； +适用前提是客户端版本与其已有授权配置支持 KMS，不能将端口连通当成激活成功。 +命令依据[镜像项目使用说明](https://github.com/mikolatero/docker-vlmcsd)，本轮未执行。 +已有客户端无需为了接入此服务先卸载产品密钥；本页不复制那类重置步骤。 + +## 故障与依赖 + +连接失败先核对宿主地址、TCP `1688` 与网络规则；服务可达但请求失败时， +结合客户端详细状态和服务日志区分协议、版本及客户端配置问题。 +具体客户端清单、DNS 自动发现记录和宿主位置未从所读 Compose 得到，不能自行补成现状。 + +依赖为 Docker 与客户端到宿主的网络。所读 Compose 未声明持久卷； +这只描述此服务配置，不代表客户端状态可以随意清除。 +维护配置入口为 homelab-infra `apps/vlmcsd/compose.yaml`。 diff --git a/verification.md b/verification.md index f42927c..7bcb518 100644 --- a/verification.md +++ b/verification.md @@ -44,6 +44,10 @@ SPIFFE/SPIRE 按维护者指定，以 [#34](https://git.ddupan.top/panxiao81/hom ## 已确认的归属与范围 +- 维护者于 2026-09-16 说明 codex-proxy“应该是退役的”，已从现役应用列表移至归档范围； + 未查询运行环境，也没有删除源码或数据。LiteLLM、Tailscale、ps3netsrv、vlmcsd 无需补充动态事项， + 已基于仓库配置补使用指南；这不等于新增的现场验收。 + - e5renew 和 research-auto 已由维护者明确为 GitHub 上的[外部消费者](services/external-consumers.md)， 不属于 homelab 基础设施，不再列为盘点盲区或缺失组件。 - `gitea-microvm-runner` 已更名 `gitea-dynamic-runner`，按维护者指定查阅 README，