Python之文档自动上传至飞书云盘

在完成文章分析后，需要将生成的报告自动备份到飞书云盘，避免手动传输的繁琐。

整体架构

上传流程的架构设计：

核心流程

整个上传过程分为四个步骤：

步骤 1：初始化

输入：环境变量（APP_ID、APP_SECRET、FEISHU_FOLDER_TOKEN）
处理：FeishuUploader.__init__() 从环境变量读取凭证
输出：配置完成的上传器实例

步骤 2：身份认证

输入：APP_ID + APP_SECRET
处理：调用 POST /auth/v3/tenant_access_token/internal
输出：tenant_access_token（有效期 2 小时）

步骤 3：文件上传

输入：文件路径 + folder_token + tenant_access_token
处理：使用 MultipartEncoder 流式上传到 POST /drive/v1/files/upload_all
输出：成功时返回 file_token

步骤 4：结果处理

输入：API 响应
处理：检查响应码，记录成功/失败日志
输出：布尔结果（True/False）

关键代码实现

FeishuUploader 类

这个类封装了所有与飞书 API 的交互逻辑。

获取访问凭证

python 复制代码

def _get_tenant_access_token(self) -> Optional[str]:
    url = f"{self.BASE_URL}/auth/v3/tenant_access_token/internal"
    payload = {"app_id": self.app_id, "app_secret": self.app_secret}
    response = requests.post(url, json=payload, timeout=10)
    # 成功时返回 tenant_access_token

逻辑说明：将 App ID 和 App Secret 发送到飞书认证接口，从响应中提取访问凭证。

文件上传

python 复制代码

def upload_file(self, file_path: Path) -> bool:
    token = self._get_tenant_access_token()
    # 使用 MultipartEncoder 构建表单
    form = {
        'file_name': file_name,
        'parent_type': 'explorer',
        'parent_node': self.folder_token,
        'size': str(file_size),
        'file': (file_name, f)
    }
    multi_form = MultipartEncoder(form)
    response = requests.post(url, headers=headers, data=multi_form, timeout=60)

逻辑说明：

验证文件存在且 folder_token 已配置
获取身份认证凭证
构建包含文件元数据的表单
流式上传到飞书云盘 API

上传触发点

在 main.py 中，分析完成后自动触发上传：

python 复制代码

if results and any(r.success for r in results):
    report_path = reporter.generate_summaries_report(results, grouped_urls)
    logger.info("汇总分析成功，正在上传报告...")
    uploader = FeishuUploader()
    if uploader.upload_file(report_path):
        logger.info("自动上传飞书成功。")
    else:
        logger.error("自动上传飞书失败。")

飞书平台配置详解

这是整个流程中最容易出错的环节。很多开发者代码写好了，却在权限配置上卡住。

前置条件

拥有飞书账号，且具有管理员权限（用于审批应用）
飞书云盘中已有目标文件夹（用于存放上传的报告）

配置流程概览

阶段一：创建飞书应用

1.1 进入开发者后台

打开飞书开放平台
使用飞书账号登录
点击「创建企业自建应用」

1.2 填写应用信息

字段	说明
应用名称	应用的显示名称
应用描述	功能简介
应用图标	上传图标（可选）

填写完成后点击「创建」。

1.3 记录应用凭证

创建成功后，进入「凭证与基础信息」页面：

凭证	说明	特征
`App ID`	应用唯一标识	以 `cli_` 开头
`App Secret`	应用密钥	点击查看

⚠️ 重要：请妥善保管这些凭证，后续 API 认证需要使用。

阶段二：配置 API 权限

2.1 进入权限管理

在应用管理页面，进入「开发配置 」→「权限管理」
点击「开通权限」按钮

2.2 搜索并添加所需权限

在「API 权限」标签页下，搜索并添加以下权限：

权限名称	权限标识	类型	用途
`上传、下载文件到云空间`	`drive:file:upload`	租户级	上传文件到云盘
`查看、评论、编辑和管理云空间中所有文件`	`drive:file`	租户级	完整文件访问（备选）

推荐：使用 drive:file:upload，遵循最小权限原则。

阶段三：发布应用

3.1 创建版本

进入「应用发布 」→「版本管理与发布」
点击「创建版本」
填写版本信息：

字段	值
版本号	`1.0.0`
更新说明	`初始版本，支持云盘文件上传功能`
可用范围

点击「保存」

阶段四：配置文件夹访问权限

还需要配置文件夹权限，应用才能上传文件。

4.1 启用机器人能力

返回「开发者后台」→ 选择你的应用
进入「应用功能 」→「机器人」
点击「启用机器人」
配置机器人信息（名称、描述、头像）
发布新版本以激活机器人功能

4.2 添加应用为文件夹协作者

有两种方法可以授权：

方法 A：直接添加应用到文件夹

在浏览器或客户端打开飞书云盘
进入目标文件夹
点击右上角「... 」→「更多」→「添加文档应用」
搜索你的应用名称
选择应用，设置权限为「可编辑」
点击「确认」

📋 前提条件：应用必须已开通至少一个云文档 API 权限并已发布。

方法 B：通过群组添加应用

在飞书中创建一个新群组
将应用作为「机器人」添加到群组
打开目标文件夹 → 点击「分享」
邀请该群组作为协作者，权限设为「可编辑」

4.3 获取文件夹 Token

在飞书云盘中打开目标文件夹
从浏览器地址栏复制 URL：

plain 复制代码

https://feishu.cn/drive/folder/fldcnXXXXXXXXXXXX

提取 folder_token（/folder/ 后面的部分）：

plain 复制代码

folder_token = fldcnXXXXXXXXXXXX

阶段五：配置环境变量

在项目根目录创建或更新 .env 文件：

plain 复制代码

# 飞书配置
APP_ID=cli_xxxxxxxxxxxxx
APP_SECRET=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
FEISHU_FOLDER_TOKEN=fldcnXXXXXXXXXXXX

变量	来源	示例
`APP_ID`	开发者后台 → 凭证与基础信息	`cli_a1b2c3d4e5f6g7h8`
`APP_SECRET`	开发者后台 → 凭证与基础信息	`aB1cD2eF3gH4iJ5kL6mN7oP8`
`FEISHU_FOLDER_TOKEN`	飞书云盘 URL	`fldcnAbCdEfGhIjKlMnO`

常见问题排查

错误码	描述	解决方案
`1061004`	权限不足	将应用添加为文件夹协作者，权限设为可编辑
`1061073`	未开通权限	在开发者后台申请 `drive:file:upload` 权限
`1061044`	文件夹不存在	检查 `FEISHU_FOLDER_TOKEN` 是否正确
`99991663`	应用未找到	确认应用已发布且机器人已启用

源码 URL：https://github.com/alwaysrun/EmailExtractor