补充文档转换、上下文检索与应用发信指南
This commit is contained in:
@@ -15,6 +15,8 @@
|
||||
- [LiteLLM 网关](services/litellm-gateway.md)：模型 API 接入参数与请求示例。
|
||||
- [Tailscale](services/tailscale.md)：远程客户端、子网路由与 Service 入口。
|
||||
- [ps3netsrv](services/ps3netsrv.md) / [vlmcsd](services/vlmcsd.md)：客户端接入与故障入口。
|
||||
- [Marker](services/marker.md) / [OpenViking](services/openviking.md)：文档转换与上下文检索。
|
||||
- [SMTP relay](services/smtp-relay.md)：应用发信参数、测试与投递排障。
|
||||
- [External Secrets](services/external-secrets.md)：应用秘密投射与更新流程。
|
||||
- [OpenEBS](services/openebs.md)：PVC 申请、绑定和数据回收边界。
|
||||
- [k3s DNS](services/k3s-dns.md)：Pod 解析、内部域分流与缓存规则。
|
||||
|
||||
@@ -21,11 +21,15 @@
|
||||
- [External Secrets](services/external-secrets.md)、[OpenEBS](services/openebs.md)：应用秘密与 PVC 消费示例。
|
||||
- [k3s DNS](services/k3s-dns.md)：Pod 解析路径、配置意图与排障入口。
|
||||
|
||||
- [Marker](services/marker.md)、[OpenViking](services/openviking.md)：转换与导入、等待、检索、读取示例。
|
||||
- [SMTP relay](services/smtp-relay.md)：应用配置、测试邮件与投递边界。
|
||||
|
||||
以上依据源码文档和上游说明整理，示例未在本轮执行，不作为现场验收记录。
|
||||
|
||||
## 后续使用说明
|
||||
|
||||
1. marker、openviking、smtp-relay 等：按服务总览逐步补齐消费示例。
|
||||
1. cert-manager、Envoy Gateway：补新服务的证书与 HTTP 入口接入路径。
|
||||
2. Samba AD、OCI、Proxmox：按已有来源补日常管理入口，涉及动态状态前先对齐维护者。
|
||||
|
||||
codex-proxy 已按维护者“应该是退役的”的说明移至归档范围，不再补新接入指南。
|
||||
LiteLLM、Tailscale、ps3netsrv、vlmcsd 与 k3s 的 wiki 指南已补；源码目录仍缺根 README，配置入口已在各页列出。
|
||||
|
||||
+3
-3
@@ -19,14 +19,14 @@ SPIFFE/SPIRE 已按维护者授权补读 #34；LAN DNS 与 Authelia 已按维护
|
||||
| [gitea](gitea.md) | 代码托管与 Actions | `git.ddupan.top` | 记录已部署 | `apps/gitea/README.md` | 已有登录、最小 CI 与 runner 选择指南 |
|
||||
| http-echo | Flux 部署与漂移修复 canary | `集群内` | 记录已验证 | `apps/http-echo/README.md` | 已有验证步骤 |
|
||||
| [litellm-gateway](litellm-gateway.md) | 模型 API 网关，实际消费者未记录 | `宿主 TCP 4000；地址未记录` | 仅发现配置 | `apps/litellm-gateway/docker-compose.yml` | 已有参数、请求示例与依赖说明 |
|
||||
| marker | GPU 文档转换 API | `集群内端口 8001` | 配置与部署指南；未附上线记录 | `apps/marker/README.md` | 缺 API 使用例子 |
|
||||
| [marker](marker.md) | GPU 文档转换 API | `集群内端口 8001` | 配置与部署指南；未附上线记录 | `apps/marker/README.md` | 已有转换示例；部署镜像仍为占位符 |
|
||||
| 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` | 缺导入、查询的完整例子 |
|
||||
| [openviking](openviking.md) | 上下文检索服务 | `记录端口 1933 / 8020` | 配置与部署指南；未附上线记录 | `apps/openviking/README.md` | 已有导入、任务查询、检索与原文读取指南 |
|
||||
| [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` | 补发信链路与消费者说明 |
|
||||
| [smtp-relay](smtp-relay.md) | 应用经 Microsoft 365 发信 | `smtp-relay.smtp-relay.svc.cluster.local:25` | 有配置与测试指南；未附上线记录 | `apps/smtp-relay/README.md` | 已有应用参数、测试邮件与投递边界指南 |
|
||||
| [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 授权以项目配置为准 |
|
||||
|
||||
@@ -0,0 +1,63 @@
|
||||
---
|
||||
title: Marker 文档转换指南
|
||||
lifecycle: unknown
|
||||
evidence: documented
|
||||
last_reviewed: 2026-09-16
|
||||
last_verified: null
|
||||
---
|
||||
|
||||
# Marker
|
||||
|
||||
Marker 用 GPU 将 PDF 转为 Markdown 等格式。本页依据 homelab-infra `apps/marker/README.md`、
|
||||
Dockerfile 与 Kubernetes manifests，以及下列上游 API 源码整理，未查询运行环境。
|
||||
源码 Deployment 仍使用 `<your-registry>/marker:latest` 占位符，不能据此认定服务已经上线。
|
||||
|
||||
## 使用前提与入口
|
||||
|
||||
先由维护者完成镜像构建、部署与可达性确认，再使用集群内入口
|
||||
`http://marker.default.svc.cluster.local:8001`。所读配置没有记录外部域名或客户端认证流程。
|
||||
普通应用无需重新执行 README 中的部署步骤。
|
||||
|
||||
镜像未固定 `marker-pdf` 版本，示例必须与实际部署的 `/docs` 接口说明核对。
|
||||
上游当前 `marker_server` 默认绑定 `127.0.0.1`，而本地配置只传 `--port`；
|
||||
如果所构建版本也如此，维护者需设置 `--host 0.0.0.0` 才能供 Service 访问。
|
||||
这是部署前检查点，本轮未修改 manifest 或判定现场故障。
|
||||
|
||||
## 转换一个 PDF
|
||||
|
||||
在能访问该 Service 的客户端，准备一份适合测试的 `sample.pdf`，设置 `MARKER_BASE_URL`
|
||||
为已确认的入口。上传会处理文件并占用 GPU，先以单个小文件串行验证：
|
||||
|
||||
```bash
|
||||
curl --fail --silent --show-error \
|
||||
-F '[email protected];type=application/pdf' \
|
||||
-F 'output_format=markdown' \
|
||||
"${MARKER_BASE_URL:?请设置已确认的入口}/marker/upload" \
|
||||
-o marker-result.json
|
||||
```
|
||||
|
||||
检查转换是否成功，再将 Markdown 保存到本地：
|
||||
|
||||
```python
|
||||
import json
|
||||
from pathlib import Path
|
||||
|
||||
result = json.loads(Path("marker-result.json").read_text())
|
||||
if result.get("success") is not True:
|
||||
raise SystemExit("转换失败，请检查返回的 error 字段")
|
||||
Path("sample.md").write_text(result["output"])
|
||||
```
|
||||
|
||||
接口和返回结构依据 [Marker server 源码](https://github.com/datalab-to/marker/blob/master/marker/scripts/server.py)。
|
||||
HTTP 成功不等于转换成功，需要检查 `success`。返回还可能包含图片数据；仅写出 `output`
|
||||
不会将图片自动保存为独立附件。需要完整图文时应按实际版本返回的图片字段另行保存并核对引用。
|
||||
|
||||
## 资源与文档边界
|
||||
|
||||
本地 README 的目标是适配 4 GB 显存，保持单副本、单 worker，并避免并发转换。
|
||||
显存不足时先缩小测试文件或处理范围，不直接增加副本或并发。
|
||||
Pod 没有业务 PVC，消费者应保存转换结果，不能将容器临时目录当文档库。
|
||||
|
||||
转换结果需要复核表格、代码、顺序及遗漏，再写入知识库；转换工具不确认文档事实或当前服务状态。
|
||||
连接失败检查部署入口与监听地址，转换失败检查文件、模型加载及 GPU 资源。
|
||||
依赖为 Kubernetes、GPU 设备支持、模型与临时磁盘；部署维护入口为 `apps/marker/README.md`。
|
||||
@@ -0,0 +1,100 @@
|
||||
---
|
||||
title: OpenViking 导入与查询指南
|
||||
lifecycle: unknown
|
||||
evidence: documented
|
||||
last_reviewed: 2026-09-16
|
||||
last_verified: null
|
||||
---
|
||||
|
||||
# OpenViking
|
||||
|
||||
OpenViking 为文档和 agent 上下文提供导入与检索能力。
|
||||
本页依据 homelab-infra `apps/openviking/README.md`、Compose 和上游接口文档整理，未访问实例。
|
||||
仓库提供部署方案，未据此断言服务已上线或 wiki 已自动同步到索引。
|
||||
|
||||
## 入口与数据位置
|
||||
|
||||
| 用途 | Compose 默认值 |
|
||||
|---|---|
|
||||
| HTTP API | 宿主端口 `1933` |
|
||||
| Console/UI | 宿主端口 `8020` |
|
||||
| embedding endpoint | 宿主回环地址 `127.0.0.1:8081` |
|
||||
| 持久数据与配置 | `./data` |
|
||||
| embedding 模型缓存 | `./models` |
|
||||
|
||||
这些端口可被环境配置覆盖，实际宿主地址、客户端 key 与权限由维护者提供。
|
||||
服务端 VLM 使用 `openai-codex` provider，本地 embedding 服务使用 llama.cpp CUDA 镜像；
|
||||
客户端 API key 与服务端模型认证不是同一份凭据，不将服务端 OAuth 数据交给检索客户端。
|
||||
当前镜像标签为 `latest`，接口需与实际部署版本核对。
|
||||
|
||||
## 导入、等待、查询与读取
|
||||
|
||||
先设置 `OPENVIKING_BASE_URL` 为已授权的 API 根地址；入口需要 key 时，通过既有秘密注入方式
|
||||
提供 `OPENVIKING_API_KEY`。以下 Python 标准库片段共用同一会话；只处理一份公开上游 README，
|
||||
会写入索引并触发模型处理。本轮没有执行导入或请求。
|
||||
|
||||
```python
|
||||
import json
|
||||
import os
|
||||
import urllib.parse
|
||||
import urllib.request
|
||||
|
||||
base = os.environ["OPENVIKING_BASE_URL"].rstrip("/")
|
||||
headers = {"Content-Type": "application/json"}
|
||||
if os.environ.get("OPENVIKING_API_KEY"):
|
||||
headers["X-API-Key"] = os.environ["OPENVIKING_API_KEY"]
|
||||
|
||||
def request(path, payload=None):
|
||||
data = None if payload is None else json.dumps(payload).encode()
|
||||
req = urllib.request.Request(base + path, data=data, headers=headers)
|
||||
with urllib.request.urlopen(req, timeout=120) as response:
|
||||
return json.load(response)
|
||||
|
||||
result = request("/api/v1/resources", {
|
||||
"path": "https://raw.githubusercontent.com/volcengine/OpenViking/refs/heads/main/README.md"
|
||||
})
|
||||
print(json.dumps(result, ensure_ascii=False, indent=2))
|
||||
```
|
||||
|
||||
从返回数据取得 `task_id` 与资源 URI。`accepted` 只表示已接收，随后用同一会话查询任务：
|
||||
|
||||
```python
|
||||
task_id = "REPLACE_WITH_RETURNED_TASK_ID"
|
||||
print(request("/api/v1/tasks/" + urllib.parse.quote(task_id, safe="")))
|
||||
```
|
||||
|
||||
任务到达 `completed` 后再搜索；`failed` 或 `cancelled` 应先处理原因，不能当作入库成功。
|
||||
避免因请求超时直接反复导入同一来源。参见上游
|
||||
[资源 API](https://github.com/volcengine/OpenViking/blob/main/docs/en/api/02-resources.md) 和
|
||||
[任务 API](https://github.com/volcengine/OpenViking/blob/main/docs/zh/api/17-tasks.md)。
|
||||
|
||||
```python
|
||||
print(request("/api/v1/search/find", {
|
||||
"query": "What is OpenViking?", "limit": 5
|
||||
}))
|
||||
```
|
||||
|
||||
从搜索结果中选择一个文件 URI，读取正文：
|
||||
|
||||
```python
|
||||
uri = "REPLACE_WITH_RETURNED_FILE_URI"
|
||||
query = urllib.parse.urlencode({"uri": uri})
|
||||
print(request("/api/v1/content/read?" + query))
|
||||
```
|
||||
|
||||
检索和读取方式见[上游检索文档](https://github.com/volcengine/OpenViking/blob/main/docs/en/api/06-retrieval.md)。
|
||||
返回目录时先查看其概览或子项再选文件，不把任意目录 URI 当正文文件使用。
|
||||
HTTP 成功之外，还要检查各次响应中的应用状态与错误信息；响应封装以部署版本为准。
|
||||
|
||||
## 人与 AI 如何使用检索结果
|
||||
|
||||
检索结果用于定位资料，最终结论回到原始 Markdown、源码 README 或 ticket 核对日期与证据。
|
||||
本 wiki 的 Git 仓库仍是正式文档来源；索引不是自动获得权威性的另一份状态记录。
|
||||
尚未建立本库自动导入、增量更新或删除同步的已验证流程，不能把旧索引结果当作当前事实。
|
||||
|
||||
导入前明确资料范围及模型处理边界。不要将凭据、Terraform state 或含秘密的整个工作目录批量导入。
|
||||
本地 embedding 不意味着所有语义处理都在本地完成，VLM 仍使用 README 所述的上游认证路径。
|
||||
|
||||
连接失败核对宿主端口；导入失败区分来源可达性与解析；任务卡住或结果缺失再查看 VLM、embedding
|
||||
与队列处理。数据在 `./data`，模型缓存可重新下载，两者不能按同一种可丢弃缓存处理。
|
||||
部署、模型初始化与认证维护回到 `apps/openviking/README.md`。
|
||||
@@ -0,0 +1,74 @@
|
||||
---
|
||||
title: SMTP relay 应用发信指南
|
||||
lifecycle: unknown
|
||||
evidence: documented
|
||||
last_reviewed: 2026-09-16
|
||||
last_verified: null
|
||||
---
|
||||
|
||||
# SMTP relay
|
||||
|
||||
为集群应用提供统一出站邮件入口：应用通过集群内 SMTP 连接 relay，
|
||||
relay 再使用 STARTTLS 与 XOAUTH2 向 Microsoft 365 提交邮件。
|
||||
本页依据 homelab-infra `apps/smtp-relay/README.md` 与 Service/Deployment 配置整理，
|
||||
本轮没有连接 relay、发送邮件或查询邮箱。
|
||||
|
||||
## 应用接入参数
|
||||
|
||||
| 参数 | 已记录值 |
|
||||
|---|---|
|
||||
| SMTP host | `smtp-relay.smtp-relay.svc.cluster.local` |
|
||||
| SMTP port | `25` |
|
||||
| 应用到 relay 的 TLS | 此内部链路按明文 SMTP 配置 |
|
||||
| 应用到 relay 的认证 | 不提供用户名或密码 |
|
||||
| From / envelope sender | `[email protected]` |
|
||||
| relay 的上游 | `smtp.office365.com:587`，STARTTLS + XOAUTH2 |
|
||||
|
||||
这里的无认证入口限于既定内部使用路径，不能直接把它暴露为外部发信入口。
|
||||
其他发件身份需要对应的 Send As 授权，不能只在应用中随意改 From。
|
||||
应用只需要 relay 参数，不需要读取或持有 Microsoft 365 refresh token。
|
||||
|
||||
## 发送一封接入测试邮件
|
||||
|
||||
下面在已能访问集群 Service 的应用环境中使用 Python 标准库。
|
||||
将 `SMTP_TEST_RECIPIENT` 设置为自己控制的收件地址；执行会真实发送邮件，应先得到该次发信授权。
|
||||
这份示例本轮未执行。
|
||||
|
||||
```python
|
||||
import os
|
||||
import smtplib
|
||||
from email.message import EmailMessage
|
||||
|
||||
recipient = os.environ["SMTP_TEST_RECIPIENT"]
|
||||
sender = "[email protected]"
|
||||
message = EmailMessage()
|
||||
message["From"] = sender
|
||||
message["To"] = recipient
|
||||
message["Subject"] = "Homelab SMTP relay test"
|
||||
message.set_content("SMTP relay integration test.")
|
||||
with smtplib.SMTP("smtp-relay.smtp-relay.svc.cluster.local", 25, timeout=30) as smtp:
|
||||
refused = smtp.send_message(message, from_addr=sender, to_addrs=[recipient])
|
||||
if refused:
|
||||
raise SystemExit("收件人被拒绝，请检查 relay 状态")
|
||||
```
|
||||
|
||||
客户端提交成功只表示 relay 接收，不保证最终送达。
|
||||
维护者随后结合 relay 投递日志与收件箱确认完整链路；也检查垃圾邮件文件夹。
|
||||
日志中的上游接收结果仍不能替代收件人侧确认。
|
||||
|
||||
## 失败时如何区分
|
||||
|
||||
- 连接超时或域名失败：检查集群 DNS、Service 与应用网络范围。
|
||||
- relay 接收但不送达：检查投递队列、上游连接和认证，而不是给应用配置上游密码。
|
||||
- `535 5.7.3`：源码提示检查 OAuth 身份是否为实际 sender，以及 token 是否需要重新初始化。
|
||||
- `5.7.60`：检查 From、envelope sender 与 Microsoft 365 的发信授权是否匹配。
|
||||
|
||||
消费者接入不能通过重跑完整 Terraform、部署或 OAuth 初始化流程来试错。
|
||||
refresh token 持久化在 `smtp-relay-tokens` PVC，SASL 层负责更新；
|
||||
它是可变运行数据，不是可复制进 wiki 的配置。
|
||||
源码的 device-code 流程使用 public client，维护说明明确 `CLIENT_SECRET` 留空；
|
||||
不要照抄同一旧 README 中与之不一致的“创建 client secret”注释。
|
||||
|
||||
初始化、重新授权、DKIM 与恢复入口为 `apps/smtp-relay/README.md`。
|
||||
其中 DKIM 等日期属于历史记录，本文不将其升级为新一次验证。
|
||||
依赖为 Kubernetes/DNS、token PVC、Microsoft 365 邮箱与授权、上游网络及域名邮件配置。
|
||||
Reference in New Issue
Block a user