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 的交互逻辑。

获取访问凭证

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 发送到飞书认证接口，从响应中提取访问凭证。

文件上传

defupload_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)

逻辑说明：

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

上传触发点

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

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. 拥有飞书账号，且具有管理员权限（用于审批应用）
2. 飞书云盘中已有目标文件夹（用于存放上传的报告）

配置流程概览

阶段一：创建飞书应用

1.1 进入开发者后台

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

1.2 填写应用信息

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

1.3 记录应用凭证

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

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

阶段二：配置 API 权限

2.1 进入权限管理

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

2.2 搜索并添加所需权限

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

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

阶段三：发布应用

3.1 创建版本

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

1. 点击「保存」

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

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

4.1 启用机器人能力

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

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

有两种方法可以授权：

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

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

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

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

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

4.3 获取文件夹 Token

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

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

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

folder_token = fldcnXXXXXXXXXXXX

阶段五：配置环境变量

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

# 飞书配置APP_ID=cli_xxxxxxxxxxxxxAPP_SECRET=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxFEISHU_FOLDER_TOKEN=fldcnXXXXXXXXXXXX

常见问题排查

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