Knowledge Agent Template 生产部署完全指南:环境变量、GitHub App 配置与自托管

原创2026-10-16 06:50:141,862 阅读
文章标签:人工智能AI AgentAI 应用后端前端RAG

Knowledge Agent Template 生产部署完全指南:环境变量、GitHub App 配置与自托管

Knowledge Agent Template 是一个开源的基于文件系统与知识库的 AI Agent 模板:它通过 grep、find、cat 等命令在沙箱中直接检索你的文档,无需向量数据库和 embedding,即可部署为聊天应用、GitHub Bot、Discord Bot。本文带你完成生产部署的三大核心环节:环境变量配置、GitHub App 创建、自托管上线,全程零冗余、按步骤执行即可完成。

Knowledge Agent Template 生产部署界面

一、部署前必读:它凭什么不需要向量数据库?

在动手之前,先花 30 秒理解它的部署逻辑,这决定了你需要配置哪些环境变量:

  1. Sources 入库:知识源(GitHub 仓库、YouTube 转录等)配置存在数据库中,通过管理后台维护
  2. 内容同步:同步流程把各源的内容聚合到一个快照仓库(Snapshot Repo)
  3. 沙箱检索:用户提问时,Agent 在隔离沙箱中执行文件检索命令
  4. AI 回答:工具与 Vercel AI SDK 兼容,可接入任意 LLM

完整架构可参考 docs/ARCHITECTURE.md,同步流程实现在 apps/app/server/workflows/sync-docs/。

二、环境变量清单:3 个必填 + 1 个本地开发专用

项目提供了完整的环境变量模板,复制一份再填写即可:

cp apps/app/.env.example apps/app/.env

模板文件位于 apps/app/.env.example,逐项说明在 docs/ENVIRONMENT.md。

2.1 必填变量(部署 Vercel 或自托管都必需)

变量 用途 如何获取
BETTER_AUTH_SECRET 会话与令牌签名密钥 终端执行 openssl rand -hex 32 生成随机值
GITHUB_CLIENT_ID GitHub OAuth 登录凭证 GitHub App 设置页的 Client ID
GITHUB_CLIENT_SECRET GitHub OAuth 登录凭证 GitHub App 设置页生成 Client Secret

2.2 本地开发专用变量

变量 说明
AI_GATEWAY_API_KEY Vercel AI Gateway 的 API Key,用于路由到任意 AI 模型。部署到 Vercel 时不需要——平台会通过 OIDC 令牌自动鉴权,仅本地开发时需要

💡 小贴士:其余变量(沙箱、Bot、Redis 等)都是可选的,可以上线后在管理界面再配置。

2.3 沙箱与同步相关(可选,建议了解)

变量 默认值 说明
NUXT_GITHUB_SNAPSHOT_REPO — 快照仓库,owner/repo 格式,可在管理界面配置
NUXT_GITHUB_SNAPSHOT_BRANCH main 快照使用的分支
NUXT_GITHUB_TOKEN — 兜底 PAT,仅在 GitHub App 令牌不可用时才需要

三、GitHub App 配置:一个 App 同时搞定登录 + Bot

Knowledge Agent Template 的巧妙设计是:一个 GitHub App 既承担用户 OAuth 登录,又驱动 GitHub Bot(Webhook 事件),避免维护两套 App。详细流程见 apps/app/app/content/docs/getting-started.md。

3.1 创建 GitHub App 的 6 个步骤

  1. 进入 GitHub 的 Settings → Developer settings → GitHub Apps → New GitHub App
  2. 填写基础信息:
    • App name:机器人名称,如 my-agent
    • Homepage URL:你的实例地址(本地开发填 http://localhost:3000)
    • Callback URL:<your-url>/api/auth/callback/github(OAuth 登录用)
    • Webhook URL:<your-url>/api/webhooks/github(Bot 用)
    • Webhook secret:生成一个随机字符串并保存
  3. Account permissions:Email addresses → Read-only(登录时按邮箱识别用户)
  4. Repository permissions:
    • Issues → Read & Write(机器人读 Issue 并回复)
    • Metadata → Read-only(GitHub 对所有 App 的强制要求)
    • 若想让管理后台自动管理快照仓库,再加 Contents → Read & Write,以及 Administration → Read & Write
  5. Events:勾选 Issues 和 Issue comments 两个 Webhook 事件
  6. 创建完成后,从 App 设置页收集 5 个值:
页面上的值 对应环境变量
App ID NUXT_GITHUB_APP_ID
Client ID GITHUB_CLIENT_ID
Client secret(生成) GITHUB_CLIENT_SECRET
Private key(生成,PEM 格式) NUXT_GITHUB_APP_PRIVATE_KEY
Webhook secret NUXT_GITHUB_WEBHOOK_SECRET

3.2 两个容易踩的坑

  • 必须把 App 设为 Public:在设置页底部的 Danger Zone 操作。保持 Private 时组织安装器不会出现,只能装到个人账户。
  • 安装到目标仓库:在 Install App 标签页选择要启用机器人的仓库;若需自动管理快照仓库,确保 App 已安装到目标 owner(用户/组织)并具备上述权限。

Knowledge Agent Template 聊天界面与 Bot 效果

四、自托管部署:4 条命令跑起来

4.1 最快启动步骤

# 1. 克隆仓库
git clone https://gitcode.com/gh_mirrors/kn/knowledge-agent-template
cd knowledge-agent-template

# 2. 安装依赖(项目默认使用 bun)
bun install

# 3. 配置环境变量
cp apps/app/.env.example apps/app/.env
# 编辑 .env,填入第二节中的必填变量

# 4. 启动
bun run dev

应用将在 http://localhost:3000 可用。⚠️ 注意:第一个注册的用户自动获得管理员权限,请在生产环境想好"谁第一个登录"。

4.2 首次上线后的三件事

  1. 添加知识源:进入 /admin → Sources → Add source,配置 GitHub 仓库或 YouTube 频道
  2. 触发同步:点击 Sync,同步以可重跑的 Workflow 执行——从最新快照创建沙箱、克隆各源仓库、只保留 .md/.json 等文档文件、推送到快照仓库并重建快照
  3. 配置 Agent 行为:/admin/agent 可调整回复风格、模型、温度、引用方式等

管理后台还提供统计(/admin/stats)、API Keys(/admin/api-keys)等模块,路由实现见 apps/app/app/pages/admin/。

五、可选扩展:Bot、Redis 与 YouTube

确认核心功能跑通后,再按需添加这些可选环境变量(完整说明见 docs/ENVIRONMENT.md):

GitHub Bot(依赖第三节的 App 凭证):

变量 说明
NUXT_PUBLIC_GITHUB_APP_NAME GitHub App 名称
NUXT_GITHUB_APP_ID / NUXT_GITHUB_APP_PRIVATE_KEY App ID 与私钥
NUXT_GITHUB_WEBHOOK_SECRET Webhook 密钥

Discord Bot:NUXT_DISCORD_BOT_TOKEN、NUXT_DISCORD_PUBLIC_KEY、NUXT_DISCORD_APPLICATION_ID,交互端点设为 <your-url>/api/webhooks/discord。

生产环境状态持久化:

  • REDIS_URL:机器人状态的 Redis 连接地址;不配置则用内存态,重启后丢失,生产环境强烈建议配置
  • NUXT_YOUTUBE_API_KEY:仅当同步 YouTube 源时需要

六、部署自查清单

检查项 状态
3 个必填环境变量已填写 ☐
本地开发时已配置 AI_GATEWAY_API_KEY ☐
GitHub App 设为 Public 并完成仓库安装 ☐
Webhook 订阅了 Issues + Issue comments ☐
首个登录用户已确认为管理员本人 ☐
生产环境配置了 REDIS_URL ☐
管理后台添加知识源并成功 Sync ☐

总结:Knowledge Agent Template 的部署门槛并不高——3 个环境变量 + 1 个 GitHub App 就能上线,文件检索代替向量库的设计还帮你省掉了 embedding 基础设施的运维成本。建议阅读 docs/CUSTOMIZATION.md 完成品牌改名,以及 docs/SOURCES.md 了解更多知识源类型,把它真正变成你自己的知识库 Agent。

登录后查看全文
knowledge-agent-template