补充网关与远程客户端指南并归档 codex-proxy 状态

2026-09-16 18:17:09 +00:00
parent c2c3a2d74b
commit e6cd82e606
8 changed files with 240 additions and 6 deletions
@@ -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 基础设施；仅保留归属入口。
@@ -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/`；消费者清单与备份情况未在所读文件中记录。
@@ -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、宿主存储、网络和相容客户端；本页不修改容器或数据目录。
@@ -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、设备密钥或凭据内容。
@@ -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`。