前言与总结#

项目代码还请直接参见我的博客GitHub库的scripts文件夹

情况是这样的：我现在将日常任务管理、OKR编排和个人书库影音库放到了飞书里。得益于飞书强大的自定义能力和开放的 API 接口，我能够根据自身需求构建个性化的信息管理系统。然而，仅仅在飞书内部管理这些数据还不够，我还需要一个对外展示的窗口，尤其是针对我的书库——一个精美的、可自动更新的博客书架页。

在当前的技术栈中，Astro作为静态站点生成器（SSG）提供了很棒的博客框架与组件化能力。但传统静态博客的痛点在于：每当飞书书库新增条目时，需要手动导出数据、更新Front Matter、重新部署站点。这种机械的重复劳动显然违背了自动化管理的初衷。

为了解决这个问题，我设计了一个自动化工作流：通过Github Action自动从飞书多维表格中同步数据，并触发博客的自动构建与部署，整个流程节点如下：

数据源管理 在飞书多维表格（Bitable）中，我创建了一个结构化的书库表格，记录每本书的基本信息、阅读状态、笔记等。这种方式不仅便于日常管理，还能通过飞书移动端随时记录读书心得。
数据同步与处理 我编写了一个 Python 脚本来处理数据同步，主要功能包括：
- 通过飞书开放平台的 API 获取书库数据
- 智能处理书籍封面图片：
  - 自动压缩和转换为 WebP 格式
  - 优化图片尺寸（最大 800×1200）
  - 控制文件大小（不超过 300KB）
  - 保持透明通道（如果原图有的话）
- 将处理后的数据转换为博客可用的 JSON 格式
自动化部署 利用 GitHub Actions 的定时任务功能，系统会：
- 定期执行数据同步脚本
- 使用处理后的数据更新博客内容
- 自动触发站点重新构建和部署

通过这种方式，我实现了一个真正的“阅读优先”的工作流，只需要在飞书中维护书库数据，博客页面就会自动保持同步。

二、脚本代码解析#

1.环境配置与图片资源优化#

脚本通过环境变量管理敏感配置信息：

1
APP_ID = os.getenv('FEISHU_APP_ID')
2
APP_SECRET = os.getenv('FEISHU_APP_SECRET')
3
BITABLE_ID = os.getenv('FEISHU_BITABLE_ID')
4
TABLE_ID = os.getenv('FEISHU_TABLE_ID')

确保安全性，同时也方便在不同环境（本地开发/GitHub Action）间切换。

环境变量介绍：

FEISHU_APP_ID
- 飞书应用的唯一标识符
- 在创建飞书应用后可以在应用凭证页面获取
- 用于识别是哪个应用在访问飞书 API
FEISHU_APP_SECRET
- 飞书应用的密钥
- 与 APP_ID 配对使用，用于生成访问令牌（access token）
- 需要妥善保管，不能泄露
FEISHU_BITABLE_ID
- 多维表格的唯一标识符
- 可以从多维表格的 URL 中获取
- 用于指定要操作的具体多维表格
FEISHU_TABLE_ID
- 多维表格中具体数据表的唯一标识符
- 一个多维表格可以包含多个数据表，这个 ID 用于指定具体要操作哪个数据表
- 可以从数据表的 URL 或者 API 获取

为了确保博客页面的加载性能，实现了智能的图片处理机制：

1
# 图片压缩配置
2
MAX_SIZE = (800, 1200)  # 最大尺寸
3
WEBP_QUALITY = 85      # 初始质量
4
MAX_FILE_SIZE = 300 * 1024  # 目标大小上限

自动转换为现代的 WebP 格式
智能压缩算法：从85%质量开始，逐步降低直至满足大小要求
保留透明通道：自动检测和保持图片的透明度
渐进式压缩：在保证视觉质量的同时实现最优压缩比

2.数据同步#

同步过程分为以下几个：

（1）认证

1
def get_tenant_access_token():
2
    """获取飞书应用的 tenant_access_token"""
3
    url = "https://open.feishu.cn/open-apis/auth/v3/tenant_access_token/internal"
4
    headers = {
5
        "Content-Type": "application/json"
6
    }
7
    data = {
8
        "app_id": APP_ID,
9
        "app_secret": APP_SECRET
10
    }

通过飞书开放平台的 OAuth2 流程获取访问令牌，确保安全访问。

（2）获取多维表格中的记录

1
def get_bitable_records():
2
    """获取多维表格中的记录"""
3
    token = get_tenant_access_token()
4
    if not token:
5
        print("Failed to get access token")
6
        return None
7

8
    url = f"https://open.feishu.cn/open-apis/bitable/v1/apps/{BITABLE_ID}/tables/{TABLE_ID}/records"
9
    headers = {
10
        "Authorization": f"Bearer {token}",
11
        "Content-Type": "application/json"
12
    }
13

14
    response = requests.get(url, headers=headers)
15
    return response.json()

获取飞书多维表格中的表格记录

1
def download_image(url, token, save_dir):
2
    """下载图片并返回本地路径"""
3
    try:
4
        # 生成文件名（使用URL的哈希值）
5
        url_hash = hashlib.md5(url.encode()).hexdigest()
6
        filename = f"{url_hash}.webp"  # 使用webp格式
7
        local_path = os.path.join(save_dir, filename)
8

9
        # 如果文件已存在，直接返回路径
10
        if os.path.exists(local_path):
11
            print(f"Image already exists: {filename}")
12
            return os.path.join('/images/books', filename)
13

14
        # 下载图片
15
        headers = {"Authorization": f"Bearer {token}"}
16
        response = requests.get(url, headers=headers)
17
        response.raise_for_status()
18

19
        # 压缩图片
20
        compressed_data = compress_image(response.content)
21

22
        # 保存压缩后的图片
23
        with open(local_path, 'wb') as f:
24
            f.write(compressed_data)
25

26
        original_size = len(response.content) / 1024  # KB
27
        compressed_size = len(compressed_data) / 1024  # KB
28
        compression_ratio = (1 - compressed_size / original_size) * 100 if original_size > 0 else 0
29
        print(f"Downloaded: {filename} (Original: {original_size:.1f}KB, Compressed: {compressed_size:.1f}KB, Saved: {compression_ratio:.1f}%)")
30

31
        return os.path.join('/images/books', filename)
32
    except Exception as e:
33
        print(f"Error downloading image {url}: {str(e)}")
34
        return None

1
def process_records(records, token):
2
    """处理记录，下载图片并更新图片路径"""
3
    if not records or 'data' not in records or 'items' not in records['data']:
4
        return records
5

6
    # 确保图片目录存在
7
    save_dir = os.path.join(os.path.dirname(os.path.dirname(__file__)), 'public', 'images', 'books')
8
    os.makedirs(save_dir, exist_ok=True)
9

10
    # 处理每条记录
11
    for item in records['data']['items']:
12
        if '封面' in item['fields'] and item['fields']['封面']:
13
            covers = item['fields']['封面']
14
            new_covers = []
15
            for cover in covers:
16
                if 'url' in cover:
17
                    # 下载图片并获取本地路径
18
                    local_path = download_image(cover['url'], token, save_dir)
19
                    if local_path:
20
                        new_cover = cover.copy()
21
                        new_cover['local_path'] = local_path
22
                        new_covers.append(new_cover)
23
            if new_covers:
24
                item['fields']['封面'] = new_covers
25

26
    return records
27

28
def save_to_json(data):
29
    """将数据保存为 JSON 文件"""
30
    output_path = os.path.join(os.path.dirname(os.path.dirname(__file__)), 'public', 'data', 'books.json')
31

32
    # 添加更新时间
33
    data['last_updated'] = datetime.now().isoformat()
34

35
    with open(output_path, 'w', encoding='utf-8') as f:
36
        json.dump(data, f, ensure_ascii=False, indent=2)
37

38
    print(f"Data saved to {output_path}")

提取书籍信息
下载并优化封面图片
生成适用于静态站点的本地路径
将处理后的数据序列化为 JSON 格式
添加时间戳，便于追踪更新状态
保存到博客的 public/data 目录

（3）文件组织

处理后的资源按照类型分类存储：

图片资源：public/images/books/
数据文件：public/data/books.json

这种组织方式与 Astro 的静态资源处理完美契合，确保了资源的正确引用和加载。

2.静态博客书架页样式设计#

1
---
2
import MainGridLayout from '../layouts/MainGridLayout.astro';
3
import { i18n } from '../i18n/translation';
4
import I18nKey from '../i18n/i18nKey';
5

6
// Read and parse the books data
7
const response = await fetch(new URL('/data/books.json', Astro.url));
8
const booksData = await response.json();
9
// Filter books with reading progress "1"
10
const books = booksData.data.items.filter(book => book.fields['阅读进度'] === "1");
11

12
// Group books by category (领域)
13
const booksByCategory = books.reduce((acc, book) => {
14
  const category = book.fields['领域'] || '未分类';
15
  if (!acc[category]) {
16
    acc[category] = [];
17
  }
18
  acc[category].push(book);
19
  return acc;
20
}, {});
21

22
// Function to get cover URL
23
function getCoverUrl(book) {
24
  if (book.fields['封面']?.[0]) {
25
    // 使用本地路径
26
    return book.fields['封面'][0].local_path;
27
  }
28
  return null;
29
}
30
---
31

32
<MainGridLayout title={i18n(I18nKey.bookshelf)} description={i18n(I18nKey.bookshelf)}>
33
  <style>
34
    .custom-scrollbar::-webkit-scrollbar {
35
      width: 4px;
36
    }
37
    .custom-scrollbar::-webkit-scrollbar-track {
38
      background: transparent;
39
    }
40
    .custom-scrollbar::-webkit-scrollbar-thumb {
41
      background-color: rgba(255, 255, 255, 0.3);
42
      border-radius: 2px;
43
    }
44
    .custom-scrollbar::-webkit-scrollbar-thumb:hover {
45
      background-color: rgba(255, 255, 255, 0.5);
46
    }
47
  </style>
48
  <div class="flex w-full rounded-[var(--radius-large)] overflow-hidden relative">
49
    <div class="card-base z-10 px-6 py-6 relative w-full">
50
      {Object.entries(booksByCategory).map(([category, books]) => (
51
        <div class="mb-12">
52
          <h2 class="text-2xl font-bold mb-6 pb-2 border-b border-zinc-200 dark:border-zinc-800 text-[var(--primary)]">
53
            {category}
54
          </h2>
55
          <div class="grid grid-cols-2 sm:grid-cols-3 lg:grid-cols-4 xl:grid-cols-5 gap-6">
56
            {books.map((book) => (
57
              <div class="group relative flex flex-col">
58
                <div class="aspect-[3/4] overflow-hidden rounded-lg bg-zinc-100 dark:bg-zinc-900 shadow-md transition-all duration-300 group-hover:shadow-xl">
59
                  {getCoverUrl(book) ? (
60
                    <img
61
                      src={getCoverUrl(book)}
62
                      alt={book.fields['书名']}
63
                      class="h-full w-full object-cover transition-transform duration-300 group-hover:scale-105"
64
                    />
65
                  ) : (
66
                    <div class="flex h-full w-full items-center justify-center bg-zinc-100 dark:bg-zinc-900 p-4">
67
                      <span class="text-center text-sm text-[var(--text-2)]">{book.fields['书名']}</span>
68
                    </div>
69
                  )}
70
                  <div class="absolute inset-0 bg-gradient-to-t from-black/60 to-transparent opacity-0 transition-opacity duration-300 group-hover:opacity-100">
71
                    <div class="absolute bottom-0 left-0 right-0 p-4">
72
                      <h3 class="text-sm font-bold text-white mb-1 line-clamp-2">
73
                        {book.fields['书名']}
74
                      </h3>
75
                      {book.fields['作者']?.length > 0 && (
76
                        <p class="text-xs text-zinc-200 mb-2">
77
                          {book.fields['作者'].join(', ')}
78
                        </p>
79
                      )}
80
                    </div>
81
                  </div>
82
                </div>
83
                <div class="overlay absolute inset-0 bg-black/80 opacity-0 transition-opacity duration-300 rounded-lg invisible group-hover:visible group-hover:opacity-100 flex items-center justify-center overflow-hidden">
84
                  <div class="p-4 text-white h-full overflow-y-auto custom-scrollbar">
85
                    <h3 class="text-sm font-bold mb-2 sticky top-0 bg-black/80 py-2">{book.fields['书名']}</h3>
86
                    {book.fields['书评'] ? (
87
                      <>
88
                        <p class="text-sm text-zinc-100 mb-3">{book.fields['书评']}</p>
89
                        {book.fields['书籍简介'] && (
90
                          <div class="pt-3 border-t border-white/20">
91
                            <p class="text-xs text-zinc-400">
92
                              {book.fields['书籍简介']}
93
                            </p>
94
                          </div>
95
                        )}
96
                      </>
97
                    ) : (
98
                      <p class="text-xs text-zinc-300">{book.fields['书籍简介']}</p>
99
                    )}
100
                  </div>
101
                </div>
102
              </div>
103
            ))}
104
          </div>
105
        </div>
106
      ))}
107
    </div>
108
  </div>
109

110
  <!-- giscus评论 -->
111
  <div style="margin-top: 20px;"></div>
112
  <script src="https://giscus.app/client.js"
113
          data-repo="Lapis0x0/blog-discussion"
114
          data-repo-id="R_kgDONda6_g"
115
          data-category="Announcements"
116
          data-category-id="DIC_kwDONda6_s4ClN0D"
117
          data-mapping="pathname"
118
          data-strict="0"
119
          data-reactions-enabled="1"
120
          data-emit-metadata="0"
121
          data-input-position="bottom"
122
          data-theme="preferred_color_scheme"
123
          data-lang="zh-CN"
124
          crossorigin="anonymous"
125
          async>
126
  </script>
127
</MainGridLayout>
128

129
<style>
130
  .line-clamp-2 {
131
    display: -webkit-box;
132
    -webkit-line-clamp: 2;
133
    -webkit-box-orient: vertical;
134
    overflow: hidden;
135
  }
136

137
  .line-clamp-3 {
138
    display: -webkit-box;
139
    -webkit-line-clamp: 3;
140
    -webkit-box-orient: vertical;
141
    overflow: hidden;
142
  }
143

144
  .line-clamp-6 {
145
    display: -webkit-box;
146
    -webkit-line-clamp: 6;
147
    -webkit-box-orient: vertical;
148
    overflow: hidden;
149
  }
150
</style>

3.Github Action工作流#

设定为每周日从飞书那里拉取一次数据，更新书架页信息。

1
name: Update Books Data
2

3
on:
4
  schedule:
5
    - cron: '0 0 * * 0'  # 每周日 UTC 00:00 运行
6
  workflow_dispatch:  # 允许手动触发
7

8
jobs:
9
  update-books:
10
    runs-on: ubuntu-latest
11
    permissions:
12
      contents: write  # 明确设置写入权限
13

14
    steps:
15
    - uses: actions/checkout@v3
16
      with:
17
        token: ${{ secrets.GITHUB_TOKEN }}
18

19
    - name: Set up Python
20
      uses: actions/setup-python@v4
21
      with:
22
        python-version: '3.10'
23
        cache: 'pip'  # 启用pip缓存
24

25
    - name: Install dependencies
26
      run: |
27
        python -m pip install --upgrade pip
28
        pip install pillow requests  # 直接指定必要的依赖
29

30
    - name: Update books data
31
      env:
32
        FEISHU_APP_ID: ${{ secrets.FEISHU_APP_ID }}
33
        FEISHU_APP_SECRET: ${{ secrets.FEISHU_APP_SECRET }}
34
        FEISHU_BITABLE_ID: ${{ secrets.FEISHU_BITABLE_ID }}
35
        FEISHU_TABLE_ID: ${{ secrets.FEISHU_TABLE_ID }}
36
      run: |
37
        python scripts/test_feishu_bitable.py
38

39
    - name: Commit and push if changed
40
      run: |
41
        git config --local user.email "github-actions[bot]@users.noreply.github.com"
42
        git config --local user.name "github-actions[bot]"
43
        git add public/data/books.json public/images/books/*
44
        git diff --quiet && git diff --staged --quiet || (git commit -m "Update books data [skip ci]" && git push)

三、实际效果#

请访问此链接来体验