把公司资料塞进向量库，最容易漏掉的一件事是权限：Agent 检索时把某人本不该看到的文档一起召回，答案还带着原始片段。PipesHub 是 Apache 2.0 开源的「智能体上下文层」，先把 Slack、Google Drive、Jira、GitHub、Microsoft 365、Notion 等来源接进来并保持原有访问控制，再让 Agent 通过统一搜索、MCP 或 SDK 使用这份带引用的上下文。本教程按官方 README 与部署说明六步落地：起栈、接源、验权限、配 MCP 客户端、治理密钥。所有命令与字段均按官方原文给出，未确证的细节一律写进提示框，不臆造。
先弄清：上下文层不等于又一个向量库
PipesHub 把「接数据、保权限、给引用、供检索」收在同一层，Agent 不必各自实现一遍。官方 README 里这套栈分三块，先分清谁负责什么，后面排障才不会找错地方：
| 组成 | 作用 | 本教程要不要动 |
|---|---|---|
| Web 应用（Next.js） | 搜索、问答、连接器与账号管理界面 | 主要操作面 |
| API（Node.js） | 账号、权限、知识库与文件 | 间接调用 |
| Python 服务 | 连接器同步、文档解析、带引用的问答 | 看日志排障 |
| Neo4j / ArangoDB | 知识图谱，记录文档、人、工单、代码之间关系 | 安装器里选 |
| Qdrant + MongoDB + Redis | 向量检索、文档数据、缓存 | 安装器里选 |
版本口径与体量先说清：官方 README 未写死当前版本号，用 ./install.sh --version TAG 可钉镜像标签（文档示例为 --version 0.7.0），具体可用标签以发布页为准。full 部署会同时拉起图谱库、向量库、消息队列等多个容器，属于重型栈；先在测试机跑 slim 档，别直接上生产服务器。官方明确要求云服务器用 HTTPS，纯 HTTP 下浏览器会拦截部分请求并出现白屏。
Step 1：确认 Docker 环境，下载并审阅安装器
官方 Quickstart 推荐一条命令，但安装器会在本机写入 ./pipeshub 目录、生成 .env 并启动多个容器。团队机器建议走「先下载、再审阅、后执行」这条路线：
# 前置：Docker 与 Compose v2（README 明确要求 Compose v2）
docker --version
docker compose version
# 路线 A：先下载审阅再执行（推荐）
curl -fsSL https://get.pipeshub.com/install -o pipeshub-install.sh
less pipeshub-install.sh
bash pipeshub-install.sh
# 路线 B：官方一键安装（等价于上面的安装器）
curl -fsSL https://get.pipeshub.com/install | bash
# 路线 C：克隆仓库后从源码构建镜像
git clone https://github.com/pipeshub-ai/pipeshub-ai.git
cd pipeshub-ai
./install.sh
./install.sh --build--build 只在克隆仓库路线可用，用于从本地源码构建镜像；一键安装脚本始终使用预构建镜像。安装器会依次检查 Docker、内存与磁盘，询问 slim 或 full 部署，允许改选图谱库、消息代理与 KV 存储。管道执行与密钥风险：curl ... | bash 会直接执行远端脚本，生产环境请走路线 A。安装器生成的 .env 含随机密钥与连接器凭据，务必加入 .gitignore，不要提交进仓库，也不要贴进聊天或工单；后续接企业连接器时产生的 OAuth 凭据同样按密钥管理。
Step 2：起栈并确认服务健康
安装器会自动生成随机密钥、拉取镜像、启动容器，并等待服务通过健康检查后打印访问地址。完成后打开 http://localhost:3000。需要复现或交给 CI 时，用下面这组参数控制行为：
# 接受全部默认值，跳过交互（CI 友好）
./install.sh --yes
# 钉住镜像标签，避免下次部署悄悄升版
./install.sh --version 0.7.0
# 重跑配置向导并覆盖已有 .env
./install.sh --reconfigure
# 只生成 .env 并打印 compose 命令，不启动容器
./install.sh --print-env-only
# 服务没起来时，在 compose 文件所在目录看日志
docker compose logs--print-env-only 适合把配置差异纳入代码评审：先看清将要写入哪些变量，确认后再真正起栈。官方排障清单也是这四项：确认 HTTPS、看 compose 日志、核对 env.template、查 docs.pipeshub.com。云服务器必须终止 TLS：官方明确写到，部署在云主机上时要用 Cloudflare、Nginx 或 Traefik 终止 HTTPS；纯 HTTP 访问会因为浏览器拦截请求而出现白屏，这不是服务没起来。本机 localhost 不在该限制内。
Step 3：接一个数据源，跑通索引
先用一份不含敏感信息的本地文档练手，避免一开始就要企业 OAuth 授权。在界面的连接器区添加本地文件，等待索引完成后打开记录列表，确认文档被解析成可检索的块：
# 准备一份测试语料（放在你自己的临时目录）
mkdir -p ./pipeshub-demo
printf '%s\n' '项目代号：灯塔' '值班表：周一 A 组，周二 B 组' '发布流程：先评审，再灰度' > ./pipeshub-demo/ops.md
# 界面操作顺序（官方连接器流程）
# 1. Connectors 里选本地文件，上传 ops.md
# 2. 选择实时或定时索引
# 3. Records 列表出现该文档，点开确认解析出的文本块官方列出的可索引格式包括 PDF（含扫描件）、Word、Excel、PPT、CSV、Markdown、HTML、纯文本、Google Docs/Sheets/Slides 与图片；扫描件由 Docling、pdfplumber 或视觉模型做 OCR。接入 Slack、Drive、Jira 等企业连接器时，按界面指引完成授权并再次选择实时或定时索引。
格式边界：官方 FAQ 写明音频与视频文件可以存储，但尚未被索引；因此不要让 Agent 去检索只存在于录音里的内容。另外，连接器数量与格式支持会随版本变化，以当前部署版本的文档为准。
Step 4：验收权限感知检索与块级引用
这一步是 PipesHub 的核心价值，也是最容易跳过的一步。官方说明：访问控制在查询执行时按源系统自身权限解析，而不是建索引时近似估算；回答会带上指向原始文档块的精确引用。做一次对照实验：
| 验证项 | 操作 | 预期结果 |
|---|---|---|
| 基础问答 | 在统一搜索里问「灯塔项目的发布流程是什么」 | 答案来自 ops.md，并附可点开的块级引用 |
| 权限隔离 | 换用无该知识库权限的账号问同一问题 | 不返回受保护内容，也不在引用里泄漏片段 |
| 图谱检索 | 追问涉及人与工单关系的问题 | 答案沿知识图谱关联展开，而非单次召回 |
# 官方描述的问答链路（概念示意，非可执行 API 参数）
# agent loop = hybrid search + grep + knowledge graph navigation + full document reading
# 结果 = grounded answer + precise block citations to original documents
# 权限 = resolved at query time against the source system permissions别把引用当授权证明：块级引用说明答案有出处，但不代表当前提问者本应有该文档的读权限。权限必须靠源系统侧的配置与同步来保证；如果连接器权限同步尚未完成，检索结果可能滞后，先把同步状态确认完再放行给业务使用。
Step 5：生成个人令牌，把上下文层接进编码 Agent
官方给出两条接入路径：自托管时按 pipeshub-ai/mcp-server 仓库的 README 起 MCP server；使用官方托管版时，编码 Agent 连 https://app.pipeshub.com/mcp。无论哪条，凭据都走个人访问令牌：
# 1. 工作区里签发长期凭据（界面路径，官方原文）
# Developer settings -> Personal Access Tokens -> New token
# 有效期可选 30 / 90 / 365 天或永不过期
# 2. 在支持远程 MCP 的客户端里新增服务器，填入两项
# URL: 你的 PipesHub MCP 地址（托管版为 https://app.pipeshub.com/mcp）
# Header: Authorization: Bearer 你的令牌
# 3. 保存后重启会话，让客户端重新拉取工具列表
# 4. 官方 README 里的示例 Agent 启动方式（Omnigent 示例包）
PIPESHUB_MCP_URL=https://app.pipeshub.com/mcp PIPESHUB_MCP_TOKEN=你的令牌 omnigent run examples/pipeshub/客户端配置文件的字段结构依各自实现而定，常见的写法是声明一个远程 MCP server 并附带请求头；具体键名请以你所用客户端的文档为准，不要照抄别的项目模板。
令牌安全：「永不过期」选项请只在受控环境使用；令牌等同于账号凭据，写进 MCP 配置文件时要确认该文件不被提交到仓库。自托管 MCP server 的具体地址与参数由其独立仓库 README 给出，官方主仓库没有写死，本文不臆测端口或路径。
Step 6：固定版本、留审计线索、排障
把部署配置当作代码来管：钉版本、把 .env 排除在版本库外、保留日志与升级记录。官方还提供 Python、TypeScript、Go 三套 SDK 与 pipeshub-ai/examples 里的分步示例，适合把检索能力接进自己的应用而不只靠界面。
# 钉版本 + 只输出配置，便于评审与复现
./install.sh --version 0.7.0 --print-env-only
# 排障四件套（官方顺序）
docker compose logs
# 对照 env.template 检查变量
# 云部署确认 HTTPS 已终止 TLS
# 查 docs.pipeshub.com 对应章节
# 官方 SDK 与示例仓库位置
# Python: pipeshub-ai/pipeshub-sdk-python（PyPI 包 pipeshub-sdk）
# TypeScript: pipeshub-ai/pipeshub-sdk-typescript（npm 包 @pipeshub-ai/sdk）
# Go: pipeshub-ai/pipeshub-sdk-go
# 分步教程: pipeshub-ai/examples升级前先备份：--reconfigure 会覆盖已有 .env，--version 换镜像标签可能带来数据格式变化。升级前备份 .env 与数据卷，并在测试环境跑一遍检索与权限对照，再动生产。项目为 Apache 2.0 许可。
常见问题速查
| 现象 | 排查方向 |
|---|---|
| 界面白屏 | 云部署用了纯 HTTP；按官方说明用 Nginx、Traefik 或 Cloudflare 终止 TLS |
| 容器起不来 | 看 docker compose logs，核对内存与磁盘是否满足安装器前置检查 |
| 记录列表为空 | 连接器授权是否完成、索引任务是否跑完、文件格式是否在支持列表内 |
| 答案没有引用 | 确认走的是统一搜索或 Agent 问答，而非直连模型；检查文档是否被解析成文本块 |
| Agent 查不到资料 | 确认 MCP 会话已重启、令牌有效，且该令牌所属账号对知识库有读权限 |
| 音频视频搜不到 | 官方明确这两类可存储但尚未索引，需先转成受支持格式 |
做到哪一步算成功
本机 http://localhost:3000 可打开，本地上传的 ops.md 在 Records 里可见并能被检索到；问「灯塔项目的发布流程是什么」能拿到带块级引用的答案，换用无权限账号后同一问题不再返回该内容；用刚签发的 PAT 配好 MCP 客户端并重启会话，Agent 能调用检索工具且结果仍遵循该账号权限；./install.sh --version TAG --print-env-only 能稳定输出一份不含明文密钥外泄、可纳入评审的配置。做到这四点，说明上下文层已经从「装起来了」走到「可以交给 Agent 用了」。