Knowledge Agent Template 生产部署完全指南:环境变量、GitHub App 配置与自托管
Knowledge Agent Template 生产部署完全指南:环境变量、GitHub App 配置与自托管
Knowledge Agent Template 是一个开源的基于文件系统与知识库的 AI Agent 模板:它通过 grep、find、cat 等命令在沙箱中直接检索你的文档,无需向量数据库和 embedding,即可部署为聊天应用、GitHub Bot、Discord Bot。本文带你完成生产部署的三大核心环节:环境变量配置、GitHub App 创建、自托管上线,全程零冗余、按步骤执行即可完成。
一、部署前必读:它凭什么不需要向量数据库?
在动手之前,先花 30 秒理解它的部署逻辑,这决定了你需要配置哪些环境变量:
- Sources 入库:知识源(GitHub 仓库、YouTube 转录等)配置存在数据库中,通过管理后台维护
- 内容同步:同步流程把各源的内容聚合到一个快照仓库(Snapshot Repo)
- 沙箱检索:用户提问时,Agent 在隔离沙箱中执行文件检索命令
- 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 个步骤
- 进入 GitHub 的 Settings → Developer settings → GitHub Apps → New GitHub App
- 填写基础信息:
- 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:生成一个随机字符串并保存
- App name:机器人名称,如
- Account permissions:
Email addresses→ Read-only(登录时按邮箱识别用户) - Repository permissions:
Issues→ Read & Write(机器人读 Issue 并回复)Metadata→ Read-only(GitHub 对所有 App 的强制要求)- 若想让管理后台自动管理快照仓库,再加
Contents→ Read & Write,以及Administration→ Read & Write
- Events:勾选 Issues 和 Issue comments 两个 Webhook 事件
- 创建完成后,从 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(用户/组织)并具备上述权限。
四、自托管部署: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 首次上线后的三件事
- 添加知识源:进入
/admin→ Sources → Add source,配置 GitHub 仓库或 YouTube 频道 - 触发同步:点击 Sync,同步以可重跑的 Workflow 执行——从最新快照创建沙箱、克隆各源仓库、只保留
.md/.json等文档文件、推送到快照仓库并重建快照 - 配置 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。

