文档中心

向量数据库VikingDB

资源导入与同步

上传飞书文档

概述

OpenViking 支持通过 UAT（User Access Token，用户访问凭证）模式导入飞书文档。使用该模式时，OpenViking 会以用户身份读取飞书资源，并将文档内容解析、切片、索引后写入指定数据库。
UAT 模式适用于以下场景：

用户主动上传或导入自己有权限访问的飞书文档。
临时联调、测试或一次性导入私有文档。
文档权限归属于个人或小范围协作空间，不需要应用身份长期同步。

UAT 模式下，OpenViking 只能读取当前授权用户可访问且授权范围允许读取的飞书资源。

支持的导入范围

OpenViking 支持导入以下飞书资源：

飞书文档 Docx
飞书电子表格 Sheet
飞书多维表格 Base
飞书知识库 Wiki 节点

其中，Wiki 节点会先解析为对应的真实云文档对象，再进入后续读取和解析流程。

上传方式

本地文件支持控制台上传，CLI上传，API上传三种方式。

控制台上传

打开OpenViking首页，点击输入栏右侧“+”，“数据源同步”中选择“飞书文档”。

填入鉴权参数（获取见“获取鉴权参数”章节），勾选授权须知，完成授权。

填入飞书文档链接，选择目标目录，点击“导入”，即可上传。

CLI上传

示例如下，具体命令与参数详见 add-resource-添加资源。

ov add-resource "https://your-tenant.feishu.cn/docx/DOC_TOKEN" --args feishu_access_token:u-YOUR_USER_ACCESS_TOKEN

API上传

示例如下，具体命令与参数详见 add_resource-导入资源。

curl -X POST \
  "$OPENVIKING_DATA_HOST/api/v1/resources" \
  -H "Authorization: Bearer {api_key}" \
  -H "Content-Type: application/json" \
  -d '{
    "path": "https://example.feishu.cn/docx/<DOCX_TOKEN>",
    "to": "viking://resources/feishu-doc-watch-demo",
    "reason": "定时同步飞书文档",
    "watch_interval": 30,
    "args": {
      "feishu_access_token": "<UAT>",
      "feishu_refresh_token": "<REFRESH_TOKEN>"
    }
  }'

获取鉴权参数

在上传前需要获取鉴权参数，有两种方式，推荐使用自动化脚本配置

方式1：自动化脚本配置（推荐）

首先，在终端输入以下代码，从而创建飞书应用。

# 检查node版本
node -v

# 安装飞书CLI 
npm install -g @larksuite/cli

# 创建飞书应用
lark-cli config init --new

扫码并创建应用，在终端输入以下代码，完成授权。

# 应用授权
lark-cli auth login --scope "docx:document:readonly wiki:node:read sheets:spreadsheet:read base:app:read base:table:read base:view:read base:field:read base:record:retrieve offline_access docs:document.media:download"

浏览器打开https://open.larkoffice.com/app?lang=zh-CN，点击刚刚创建的应用，在“安全设置”里，配置重定向URL http://localhost:8080/callback

获取app_id, app_secret。

下载以下脚本，在终端执行如下命令，完成授权

main.py

未知大小

python3 main.py  <app_id>  <app_secret>

在新打开的标签页内，获取相关参数，用于后续上传

方式2：手动配置

第一步：完成飞书应用配置，获取App_id, App_secret

在飞书开放平台开发者后台已创建或选择一个可用的飞书应用。

在应用后台配置重定向URL(redirect_uri)，可填入http://localhost:3001/api/feishu/callback；打开“刷新user_access_token”。

开通读取飞书资源所需的用户身份权限。

常用只读权限如下：

资源类型	推荐权限	说明
飞书文档 Docx	`docx:document:readonly`	读取文档信息、正文和文档块
Wiki 节点	`wiki:node:read`	将 Wiki 节点解析为真实文档对象
电子表格	`sheets:spreadsheet:read`	读取电子表格内容
多维表格	`base:app:read`、`base:table:read`、`base:view:read`、`base:field:read`、`base:record:retrieve`	读取 Base 应用、表、视图、字段和记录
云文档素材	`docs:document.media:download`	下载文档、表格或 Base 中的图片、附件等素材
离线刷新	`offline_access`	获取 refresh_token，用于长期授权或定时同步

推荐的基础权限组合如下：

docx:document:readonly wiki:node:read sheets:spreadsheet:read base:app:read base:table:read base:view:read base:field:read base:record:retrieve

如需解析图片、附件等内嵌素材，可追加：

docs:document.media:download

如需定时同步，需要在 “安全设置” 中开启 “刷新 user_access_token” ，并追加：

offline_access

注意：飞书应用后台新增权限后，已签发的 UAT 不会自动获得新权限。应用权限变更并发布后，用户需要重新授权，才能获取包含新权限的 UAT。

创建版本并发布应用权限变更。

获取应用凭证，即App_id, App_secret，供后续使用。

第二步：获取 user_access_token 与 refresh_token

user_access_token 是 UAT 模式的核心凭证。OpenViking 会使用该 Token 以用户身份读取飞书文档。
refresh_token用于获取新的 user_access_token，供定时同步和长期授权使用。

获取授权码

原理参考文档：获取授权码

按如下模版拼接授权链接，点击跳转至飞书 OAuth 授权页。

https://accounts.feishu.cn/open-apis/authen/v1/authorize?client_id=<APP_ID>&response_type=code&redirect_uri=<URL_ENCODED_REDIRECT_URI>&scope=<URL_ENCODED_SCOPES>&prompt=consent&state=<RANDOM_STATE>

参数说明：

参数	是否必填	说明
`client_id`	是	飞书应用的 App ID
`response_type`	是	固定为 `code`
`redirect_uri`	是	授权完成后的回调地址，需提前在飞书应用后台登记示例：http://localhost:3001/api/feishu/callback
`scope`	是	本次申请的权限范围，多个 scope 使用空格分隔示例：
`prompt`	否	建议设置为 `consent`，用于触发用户确认授权
`state`	是	随机字符串，用于防止 CSRF 攻击

示例：

https://accounts.feishu.cn/open-apis/authen/v1/authorize?client_id=<APP_ID>&response_type=code&redirect_uri=<redirect_uri>&scope=docx:document:readonly wiki:node:read sheets:spreadsheet:read base:app:read base:table:read base:view:read base:field:read base:record:retrieve docs:document.media:download offline_access&prompt=consent&state=feishu_oauth_20260819

用户授权成功后，飞书会回调到 redirect_uri，并携带：

code=<AUTH_CODE>&state=<RANDOM_STATE>

授权码 code 有效期较短且只能使用一次，请在服务端收到后立即换取 Token。

使用 code 换取 UAT

原理参考文档：
获取新版 user_access_token
历史版 user_access_token

终端使用授权码调用飞书 Token 接口：

curl -X POST \
  'https://accounts.feishu.cn/oauth/v3/token' \
  -H 'Content-Type: application/json; charset=utf-8' \
  -d '{
    "grant_type": "authorization_code",
    "client_id": "<APP_ID>",
    "client_secret": "<APP_SECRET>",
    "code": "<CODE>",
    "redirect_uri": "<REDIRECT_URI>"
  }'

成功后，响应中的 access_token 即为 user_access_token。
如果授权范围中包含 offline_access，响应中还会包含 refresh_token，可用于后续刷新 UAT。

最近更新时间：2026.09.16 20:18:44

这个页面对您有帮助吗？

有用

无用

向量数据库VikingDB

控制台上传 #

CLI上传 #

API上传 #

方式1：自动化脚本配置（推荐） #

方式2：手动配置 #