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

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 中，分析完成后自动触发上传：

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("自动上传飞书失败。")

飞书平台配置详解

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

前置条件

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

配置流程概览

<img alt="配置流程概览图" height="1996" src="/uploadfile/2026/1010/$1