知归 KnowWhere · 个人 AI 知识归档工具

准备环境，拉取项目

准备 Git 和已运行的 Docker。Docker 镜像内已包含 Python、uv 和 FFmpeg，本机不需要单独安装它们。

Windows · PowerShell

安装 Git for Windows 和 Docker Desktop，按安装提示启用 WSL 2。启动 Docker Desktop，使用 Linux 容器，然后重新打开 PowerShell。

macOS · 终端

安装 Git 和 Docker Desktop，按芯片类型选择安装包。启动 Docker Desktop，再打开终端。

Linux · 终端

通过发行版包管理器安装 Git，再按 Docker Engine 安装指南及 Compose 插件指南完成安装并启动 Docker 服务。确认当前账号能运行 Docker 后再继续。

检查工具

git --version
docker compose version
docker info

前三条命令应显示版本信息和 Docker 服务端信息；若提示无法连接 Docker，请先启动 Docker 服务。

拉取项目

git clone https://github.com/ybh-ybh/know-where.git
cd know-where

PowerShell · 复制配置

Copy-Item .env.example .env

macOS / Linux · 复制配置

cp .env.example .env

创建你的飞书机器人

登录飞书开放平台开发者后台，创建“企业自建应用”，名称可填写“知归”。
在“添加应用能力”中启用“机器人”。
打开“凭证与基础信息”，复制 App ID（通常以 cli_ 开头）和 App Secret，稍后填入本机 .env。
在“权限管理”中搜索并添加下表权限。控制台若细分文档权限，选择创建/编辑新版文档和添加云文档协作者。
在版本发布时，将应用可用范围设为你本人。事件订阅和最终发布在第 6 步完成。

权限标识	用途
`im:message.p2p_msg:readonly`	读取发给机器人的私聊消息
`im:message:send_as_bot`	以机器人身份回复消息
`bitable:app`	创建、编辑和管理多维表格
`drive:drive.metadata:readonly`	读取归档空间所有者
`docs:doc`	管理正文文档
`docs:permission.member:create`	添加云文档协作者；控制台拆分文档权限时申请

知归使用长连接，无需公网域名、Webhook 回调地址、Verification Token 或 Encrypt Key。个人使用范围由飞书应用可用范围控制，请勿设为全员。

完成标志 机器人能力已开启，取得应用凭据并添加所需权限。

准备模型，填写 .env

在你选择的模型服务控制台创建 API Key，查找其 OpenAI 兼容 Chat Completions 接口根地址和模型 ID。下面六项是主线必填配置，替换占位值后保存。

dotenv · 六项必填

# 数据库连接地址：按第 4 步选择的路径填写。
KW_DATABASE_URL=postgresql+psycopg://knowwhere:替换为数据库密码@postgres:5432/knowwhere
# 飞书自建应用的凭据。
KW_FEISHU_APP_ID=cli_替换为你的AppID
KW_FEISHU_APP_SECRET=替换为你的AppSecret
# 文本模型：填写供应商的兼容接口根地址和实际模型ID。
KW_LLM_API_KEY=替换为你的APIKey
KW_LLM_BASE_URL=https://你的模型服务地址/v1
KW_LLM_MODEL=替换为你的模型ID

Base URL 使用供应商提供的根地址，不要追加 /chat/completions。
保留模板的 KW_ASR_PROVIDER=faster_whisper 和 KW_TEMP_STORAGE_PROVIDER=local。
视觉模型三项此时可继续注释。

只在本机编辑 .env。此页面不需要你填写密钥；不要把 .env 上传到 GitHub。数据库地址在下一步补全。

完成标志 已填写自己的飞书与文本模型配置，准备补全数据库连接。

准备 PostgreSQL

新建数据库 · 可选 Compose 配置

仓库已经提供 compose.postgres.yml。它会单独启动 PostgreSQL 17 容器，数据保存在命名卷中，不开放主机端口。请自行生成至少 24 位随机字母数字密码，并在 .env 中填写下面两项；两处密码必须相同。

dotenv · 新建数据库

# 自行生成的数据库密码；只供可选 PostgreSQL 容器使用。
KW_POSTGRES_PASSWORD=替换为你的随机字母数字密码
# 用同一个密码替换此处，主机名保持 postgres。
KW_DATABASE_URL=postgresql+psycopg://knowwhere:替换为你的随机字母数字密码@postgres:5432/knowwhere

启动数据库

docker compose -f compose.yml -f compose.postgres.yml up -d postgres
docker compose -f compose.yml -f compose.postgres.yml ps postgres

等待状态显示 healthy 后继续。数据库名和用户名均为 knowwhere。密码仅在空数据卷第一次初始化时生效，之后只修改 .env 不会改变数据库中已有账号密码。

使用已有数据库

先在 PostgreSQL 管理工具中创建专用数据库和账号，确保账号能连接并创建、修改表。将实际连接信息填入 .env：

dotenv · 已有数据库

KW_DATABASE_URL=postgresql+psycopg://用户名:URL编码后的密码@容器可访问的数据库主机:5432/knowwhere

不要启用 compose.postgres.yml，也不需要 KW_POSTGRES_PASSWORD。若密码含 @、:、/、% 等字符，先对密码部分进行 URL 编码，端口使用数据库实际端口。

容器内的 localhost / 127.0.0.1 是容器自身。远程数据库使用容器可达的域名或 IP；Windows/macOS Docker Desktop 上的宿主机数据库可使用 host.docker.internal，并确认 PostgreSQL 监听地址和访问规则允许 Docker 连接。Linux 主机上的数据库需提供容器可达的主机地址，不直接套用 localhost。

完成标志 新建数据库为 healthy；或已有数据库已建好，.env 中填写了容器可达的连接地址。

构建镜像，启动知归

首次构建会下载系统和 Python 依赖，请等待命令完成。接着迁移数据库并检查连接：

构建镜像 · 新建数据库

docker compose -f compose.yml -f compose.postgres.yml build app

构建镜像 · 已有数据库

docker compose build app

迁移与健康检查 · 新建数据库

docker compose -f compose.yml -f compose.postgres.yml run --rm app migrate-and-health

迁移与健康检查 · 已有数据库

docker compose run --rm app migrate-and-health

成功输出 OK: migrations + config + postgresql。此时验证的是配置和数据库，不代表飞书权限或模型接口已验证。

后台启动机器人 · 新建数据库

docker compose -f compose.yml -f compose.postgres.yml --profile gateway up -d gateway

后台启动机器人 · 已有数据库

docker compose --profile gateway up -d gateway

查看状态与日志 · 新建数据库

docker compose -f compose.yml -f compose.postgres.yml --profile gateway ps
docker compose -f compose.yml -f compose.postgres.yml logs --tail 50 gateway

查看状态与日志 · 已有数据库

docker compose --profile gateway ps
docker compose logs --tail 50 gateway

gateway 应保持运行。若不断重启，先到下方排错区域检查原因。不要仅凭“长连接已启动”这一行判断已成功连到飞书，下一步还要检查飞书控制台并发送消息验证。

完成标志 数据库检查通过，Gateway 容器持续运行，准备回飞书设置事件。

订阅消息事件，发布应用

保持 Gateway 运行，回到飞书开发者后台的“事件与回调 → 事件配置”（部分界面称“事件订阅”）。
编辑订阅方式，选择“使用长连接接收事件”，保存并确认连接在线。若提示未建立长连接，检查第 5 步的日志和应用凭据后重试。
添加“接收消息”事件，标识为 im.message.receive_v1。
到“版本管理与发布”创建版本，确认机器人能力、所需权限和事件已包含，将应用可用范围设置为你本人。
提交发布。若企业要求审核，请等待管理员批准和安装后再继续。

权限生效后，初始化飞书归档空间：

初始化飞书 · 新建数据库

docker compose -f compose.yml -f compose.postgres.yml run --rm app init-feishu

初始化飞书 · 已有数据库

docker compose run --rm app init-feishu

命令会输出 workspace_url=... 和 schema_version=...。多维表格和字段由程序创建，无需自己填 app_token 或 table_id。此时资源可能仍由应用持有；下一步发送有效链接后，程序才会授予个人用户访问权限。

完成标志 应用已发布且权限生效，初始化命令返回工作区地址。

发送链接，完成第一条归档

在飞书客户端搜索并打开你创建的“知归”机器人私聊，直接发送下面的公开仓库链接：

发送给飞书机器人

https://github.com/ybh-ybh/know-where

先收到“知归已收到，正在提取、总结并归档。”
等待模型处理完成，收到“归档完成：”及记录链接。
打开记录，检查标题、原始链接、分类、摘要和关键观点。也可查看多维表格的未读与分类视图。

第一次请使用文字内容验证。只发送“绑定知归”不会触发归档；视频与图文可在下方扩展能力中继续配置。

完成标志 机器人返回归档完成，且你能打开记录、看到本次链接及整理结果。到这里主线部署完成。

日常运行与更新

查看日志、停止与恢复机器人

实时日志 · Ctrl+C 仅退出查看 · 新建数据库

docker compose -f compose.yml -f compose.postgres.yml logs -f gateway

实时日志 · Ctrl+C 仅退出查看 · 已有数据库

docker compose logs -f gateway

仅停止机器人 · 新建数据库

docker compose -f compose.yml -f compose.postgres.yml stop gateway

仅停止机器人 · 已有数据库

docker compose stop gateway

恢复运行 · 新建数据库

docker compose -f compose.yml -f compose.postgres.yml --profile gateway up -d gateway

恢复运行 · 已有数据库

docker compose --profile gateway up -d gateway

修改 .env 后重新创建容器

只运行 restart 不会重新载入 env_file。修改配置后执行：

应用新配置 · 新建数据库

docker compose -f compose.yml -f compose.postgres.yml --profile gateway up -d --force-recreate gateway

应用新配置 · 已有数据库

docker compose --profile gateway up -d --force-recreate gateway

更新代码

先暂停向机器人发送链接，等待当前归档完成，再停止 Gateway 接收新任务：

更新前停止机器人 · 新建数据库

docker compose -f compose.yml -f compose.postgres.yml stop gateway

更新前停止机器人 · 已有数据库

docker compose stop gateway

然后备份数据库。新建数据库可执行以下命令，将容器内备份复制到当前目录；已有数据库请使用供应商备份或 pg_dump。完成备份后再拉取代码并更新。

备份数据库 · 同名文件会被覆盖

docker compose -f compose.yml -f compose.postgres.yml exec -T postgres pg_dump -U knowwhere -d knowwhere -Fc -f /tmp/knowwhere-backup.dump
docker compose -f compose.yml -f compose.postgres.yml cp postgres:/tmp/knowwhere-backup.dump ./knowwhere-backup.dump

拉取更新

git pull --ff-only

构建、迁移、更新 · 新建数据库

docker compose -f compose.yml -f compose.postgres.yml build app
docker compose -f compose.yml -f compose.postgres.yml run --rm app migrate-and-health
docker compose -f compose.yml -f compose.postgres.yml --profile gateway up -d --force-recreate gateway

构建、迁移、更新 · 已有数据库

docker compose build app
docker compose run --rm app migrate-and-health
docker compose --profile gateway up -d --force-recreate gateway

若 git pull 提示存在本地改动或分支分叉，先保存改动、处理提示，不强行覆盖。

停止整套容器

停止容器并保留数据卷 · 新建数据库

docker compose -f compose.yml -f compose.postgres.yml --profile gateway down

停止容器并保留数据卷 · 已有数据库

docker compose --profile gateway down

新建数据库方式会同时停止 PostgreSQL；已有数据库不会受此命令停止。恢复时先按第 4 步启动数据库，再恢复 Gateway。不要添加 -v，否则会删除本项目管理的数据卷。

完成标志 能查看运行状态、应用配置更新，并知道如何备份和保留数据停止服务。

按需开通更多能力

下面均为可选项。先完成第一条文字归档，再根据自己收藏的内容类型启用。

图文识别 · 小红书 / 抖音

选择支持图片输入的 OpenAI 兼容视觉模型，在 .env 中取消这三项注释并全部填写：

dotenv · 视觉模型

# 图片理解服务的密钥、兼容接口根地址和模型ID。
KW_VISION_API_KEY=替换为你的视觉APIKey
KW_VISION_BASE_URL=https://视觉服务地址/v1
KW_VISION_MODEL=替换为视觉模型ID

载入视觉配置 · 新建数据库

docker compose -f compose.yml -f compose.postgres.yml --profile gateway up -d --force-recreate gateway

载入视觉配置 · 已有数据库

docker compose --profile gateway up -d --force-recreate gateway

发一条公开图文笔记链接，确认收到归档完成，打开记录检查图片内容提炼结果。三项必须一起填写；图片会发送给你配置的视觉服务。

视频转录 · 默认本地 Whisper

模板默认已启用本地转录，Docker 内包含 FFmpeg。保留以下配置即可：

dotenv · 本地转录

KW_ASR_PROVIDER=faster_whisper
KW_TEMP_STORAGE_PROVIDER=local
KW_FASTER_WHISPER_MODEL=small
KW_FASTER_WHISPER_DEVICE=cpu
KW_FASTER_WHISPER_COMPUTE_TYPE=int8

首次处理视频会下载模型，模型缓存保存在 asr-models 卷中。下载需要可用网络，CPU 转录耗时随视频长度与机器性能变化。发一条短的公开视频链接，等待归档后检查转录内容和摘要。B站只分析简介与语音，不理解视频画面。

如果从腾讯 ASR 切回本地，先重新构建镜像再创建 Gateway：

切换转录方式 · 新建数据库

docker compose -f compose.yml -f compose.postgres.yml build app
docker compose -f compose.yml -f compose.postgres.yml --profile gateway up -d --force-recreate gateway

切换转录方式 · 已有数据库

docker compose build app
docker compose --profile gateway up -d --force-recreate gateway

腾讯云 ASR · 私有 COS 中转

在腾讯云开通录音文件识别服务。
在 COS 创建你账号下的存储桶，访问权限选择私有，记录地域和完整 Bucket 名。
为专用访问凭据授权所需 ASR 调用及该 Bucket 下对象上传、读取和删除权限，获取 AppID、SecretId 和 SecretKey。
修改下面配置，替换占位值后重新构建并创建 Gateway。

dotenv · 腾讯转录

KW_ASR_PROVIDER=tencent
KW_TEMP_STORAGE_PROVIDER=tencent_cos
# 腾讯云账号与访问凭据。
KW_TENCENTCLOUD_APP_ID=替换为账号AppID
KW_TENCENTCLOUD_SECRET_ID=替换为SecretId
KW_TENCENTCLOUD_SECRET_KEY=替换为SecretKey
# 私有存储桶的地域和完整名称。
KW_COS_REGION=ap-shanghai
KW_COS_BUCKET=你的桶名-你的AppID

重新构建并切换腾讯 ASR · 新建数据库

docker compose -f compose.yml -f compose.postgres.yml build app
docker compose -f compose.yml -f compose.postgres.yml --profile gateway up -d --force-recreate gateway

重新构建并切换腾讯 ASR · 已有数据库

docker compose build app
docker compose --profile gateway up -d --force-recreate gateway

发送一条短视频验证转录和归档。临时音频通过私有 COS 的短时访问地址供 ASR 读取，默认在任务结束后清理。腾讯云服务按其规则计费；仅修改 ASR 配置后 restart 不足以完成切换。

小红书访问受限时 · 配置自己的网页会话

先在自己的浏览器打开原始分享链接，确认笔记可见；需要时自行登录并完成验证。
打开开发者工具的 Network（网络）面板并刷新，选择发往 www.xiaohongshu.com 或 xiaohongshu.com 的页面请求。
从 Request Headers 复制 Cookie 的值，不包含 Cookie: 前缀，写入本机 .env：

dotenv · 可选会话

KW_XIAOHONGSHU_COOKIE='a1=你的实际值; web_session=你的实际值'

重新载入会话 · 新建数据库

docker compose -f compose.yml -f compose.postgres.yml --profile gateway up -d --force-recreate gateway

重新载入会话 · 已有数据库

docker compose --profile gateway up -d --force-recreate gateway

重新发送原分享链接，确认内容提取和最终归档均成功。Cookie 不需要重建镜像，但需要重建容器；代码首次升级时需先 build。不要提交或分享 Cookie。会话不能保证绕过验证或限流；遇到验证请回浏览器处理，遇到限流稍后再试，程序不会自动登录。

遇到问题，从这里检查

Docker 无法连接

打开 Docker Desktop 或启动 Docker 服务，再运行 docker info。Linux 若提示权限不足，按官方安装说明配置当前账号的 Docker 访问权限。

数据库不可达或认证失败

新建数据库先检查 postgres 是否 healthy，确认两处密码一致。已有数据库检查地址、端口、监听规则与防火墙；不要使用容器内 localhost 连接宿主机。已有数据卷的密码不能只改 .env 来重置。

提示缺少配置、REPLACE_ME 或格式错误

确认文件名为 .env 且位于项目根目录，六项必填字段均已替换。视觉三项要么全不填，要么全部填写。修改后重新创建 Gateway。

飞书提示未建立长连接

检查 gateway 是否持续运行、应用 App ID 和 App Secret 是否匹配、部署环境能否访问飞书。保持 Gateway 运行，再回控制台保存长连接方式。

机器人无回复、权限不足或工作区无法访问

确认订阅 im.message.receive_v1、应用范围包含自己、权限和新版本已发布并审核通过；重新运行 init-feishu，再发送真实支持链接。首次私聊前工作区链接可能还未授予你访问权。

模型接口鉴权失败或找不到模型

核对供应商控制台的 API Key、额度、模型 ID 及兼容 Base URL。不要把完整 chat/completions 路径填进 Base URL。修改 .env 后重新创建 Gateway，再重新发送内容链接。

视频模型下载失败或处理慢

确认部署机器能访问模型下载源，检查磁盘和内存。首次下载和 CPU 转录需等待，可先用文字链接确认主线。也可按上方步骤改用腾讯 ASR，并重新构建镜像。

排错 · 查看状态和近期日志 · 新建数据库

docker compose -f compose.yml -f compose.postgres.yml --profile gateway ps
docker compose -f compose.yml -f compose.postgres.yml logs --tail 100 gateway

排错 · 查看状态和近期日志 · 已有数据库

docker compose --profile gateway ps
docker compose logs --tail 100 gateway

寻求帮助时说明卡在哪一步和错误信息；先隐藏密钥、Cookie 和带令牌的链接。

支持的内容来源

微信公众号

稀土掘金

GitHub

小红书

抖音

B站

让收藏，更容易回顾和使用

随手发个链接，剩下自动完成

散落各个平台，统一收进知识库

长文和视频，先看懂重点

按自己的习惯，整理和消化

开始使用，把第一条内容收进知识库