给博客写个本地管理 CLI

一、背景：静态博客的”改个东西好麻烦”#

Firefly 是 Astro 静态站点，内容（文章、动态、友链）都是在构建时生成进静态文件的。这意味着：

1. 它没有后台管理界面，想加一篇文章，得改 src/content/posts/ 里的 .md 源文件；
2. 改完必须重新构建 Docker 镜像（docker compose build），否则网站上看不到；
3. 友链更麻烦——它不是单独文件，而是写死在 src/config/friendsConfig.ts 的 TypeScript 数组里。

于是日常变成这样：在服务器上 vim 改文件 → 跑构建 → 等几分钟 → 验证。割裂感很强，写作体验也差。

我想要的是：在自己电脑上用顺手的编辑器写，写完一条命令推上去，可选自动重建。

二、这个工具能做什么#

blogmgr 是一个纯 Python、零依赖（只用标准库）的命令行工具，覆盖 Firefly 三种内容的管理：

核心能力：

• 本地写作：add 建好带 title/published 的空文章，edit 自动用记事本打开写正文。
• 一键同步：通过 SMB 网络共享把文件推到服务器（只增 / 改，不删）。
• 可选重建：rebuild 子命令可在服务器上跑 docker compose build && up -d（检测到 plink 时全自动）。
• 安全备份：改友链前会把原文件备份到本地 _backups/，绝不在服务器留临时文件。
• 交互模式：不带参数运行时进入持续可用的命令行（REPL），直接敲 add "标题"、sync、exit 即可连续操作，不必每次重复敲命令前缀。

三、特性#

• 零依赖：只用 Python 标准库，不用 pip install 任何东西，下载即用。
• 跨平台：Windows / macOS / Linux 都能跑（SMB 在三者都通用）。
• 本地真源：友链以本地 JSON 为真源，推送时只替换 TS 数组，完整保留文件里的其它逻辑（friendsPageConfig、getEnabledFriends 函数等）。
• 防呆设计：--dry-run 演练模式、覆盖前自动备份、按权重自动排序。

四、安装#

环境要求：

• Python 3.8 或以上（命令行能跑 python 或 python3）。
• 能访问博客项目的网络共享（如 \\<服务器IP>\opt\Firefly-master），也就是你服务器上挂载的那个目录。

把脚本和配置放进一个目录即可，blogmgr.py 是主程序，blogmgr.json 是配置：

1
{
2
  "local_posts": "你的本地文章目录",
3
  "remote_posts": "\\\\<服务器IP>\\opt\\Firefly-master\\src\\content\\posts",
4
  "local_dynamics": "你的本地动态目录",
5
  "remote_dynamics": "\\\\<服务器IP>\\opt\\Firefly-master\\src\\content\\dynamic",
6
  "local_friends": "你的本地友链目录",
7
  "remote_friends_file": "\\\\<服务器IP>\\opt\\Firefly-master\\src\\config\\friendsConfig.ts",
8
  "ssh_host": "<服务器IP>",
9
  "ssh_user": "<用户名>",
10
  "ssh_pass": "<密码>"
11
}

五、快速开始#

1
cd 工具目录
2
python blogmgr.py init          # 首次：建好本地目录
3

4
# 发一篇文章
5
python blogmgr.py add "我的第一篇文章" -d "简介" -t "技术,随笔"
6
python blogmgr.py edit "我的第一篇文章"   # 记事本打开写正文
7
python blogmgr.py sync                     # 推到服务器
8

9
# 发一条动态
10
python blogmgr.py dyn-add "今天天气不错"
11

12
# 加一条友链（首次先 pull 把现有友链拉下来）
13
python blogmgr.py friend-pull
14
python blogmgr.py friend-add "朋友博客" -u "https://example.com" -i "https://example.com/avatar.png" -d "描述" -w 5
15
python blogmgr.py friend-sync
16

17
# 让改动生效（重建镜像）
18
python blogmgr.py rebuild

六、命令一览#

文章

1
add / list / show / edit / delete / status / sync / pull

动态

1
dyn-add / dyn-list / dyn-show / dyn-edit / dyn-delete / dyn-status / dyn-sync / dyn-pull

友链

1
friend-pull / friend-add / friend-list / friend-edit / friend-delete / friend-status / friend-sync

通用

1
init / rebuild

每条命令都支持 -h 看帮助。sync / pull 及其动态版都带 --dry-run 可先演练；pull 类命令是从服务器 SMB 共享把内容拉回本地（同名同内容跳过、不同则覆盖、本地独有文件保留），适合换电脑或重新初始化时把线上内容搬下来。

七、友链是怎么被管理的（技术细节）#

这是工具里最”巧妙”也最容易出错的部分。友链不是文件，而是 friendsConfig.ts 里的一个数组：

1
export const friendsConfig: FriendLink[] = [
2
  { title: "..." , imgurl: "...", /* ... */ },
3
  // ...
4
];
5

6
// 获取启用的友链并进行排序
7
export const getEnabledFriends = (): FriendLink[] => { /* ... */ };

如果直接整文件覆盖，会丢掉 friendsPageConfig 和 getEnabledFriends 这些不能动的逻辑。所以工具的做法是：

1. 用正则 friendsConfig:\s*FriendLink\[\]\s*=\s*\[ 精确定位数组起点（注意 FriendLink[] 自带方括号，不能简单匹配第一个 [）；
2. 只替换数组体，保留 head（数组声明行）和 tail（从 ]; 到文件末尾）；
3. 本地每个友链一个 .json，推送时按 weight 降序排好，拼回数组。

核心代码就这么几段（全部来自标准库，无需第三方包）：

1
import re, json
2

3
def _find_array_span(text):
4
    """精确定位 friendsConfig 数组的起止下标，跳过 FriendLink[] 自带的方括号"""
5
    m = re.search(r'friendsConfig:\s*FriendLink\[\]\s*=\s*\[', text)
6
    if not m:
7
        return None
8
    b = m.end() - 1          # '[' 的下标
9
    depth = 0
10
    for k in range(b, len(text)):
11
        if text[k] == "[":
12
            depth += 1
13
        elif text[k] == "]":
14
            depth -= 1
15
            if depth == 0:
16
            return b, k
17
    return None
18

19
def split_objects(body):
20
    """按 {} 匹配切分对象块，字符串内的括号一律忽略"""
21
    objs, depth, start, in_str, esc = [], 0, None, False, False
22
    for i, c in enumerate(body):
23
        if in_str:
24
            if esc: esc = False
25
            elif c == "\\": esc = True
26
            elif c == '"': in_str = False
27
            continue
28
        if c == '"':
29
            in_str = True
30
        elif c == "{":
31
            if depth == 0:
32
                start = i
33
            depth += 1
34
        elif c == "}":
35
            depth -= 1
36
            if depth == 0 and start is not None:
37
                objs.append(body[start:i + 1])
38
                start = None
39
    return objs
40

41
def build_friends_ts(friends):
42
    """把本地友链 JSON 拼回 TS 对象数组，按 weight 降序已在外层排好"""
43
    blocks = []
44
    for d in friends:
45
        tags = "[" + ", ".join(f'"{t}"' for t in d.get("tags", [])) + "]"
46
        block = (
47
            "\t{\n"
48
            f"\t\ttitle: \"{d['title']}\",\n"
49
            f"\t\timgurl: \"{d.get('imgurl', '')}\",\n"
50
            f"\t\tdesc: \"{d.get('desc', '')}\",\n"
51
            f"\t\tsiteurl: \"{d.get('siteurl', '')}\",\n"
52
            f"\t\ttags: {tags},\n"
53
            f"\t\tweight: {d.get('weight', 5)},\n"
54
            f"\t\tenabled: {str(d.get('enabled', True)).lower()},\n"
55
            "\t},"
56
        )
57
        blocks.append(block)
58
    return "\n".join(blocks)

推送时先 split_objects 解析服务器现有数组、合并本地改动，再用 build_friends_ts 重新生成数组体，最后只替换 head 与 tail 之间的部分——文件里 friendsPageConfig、getEnabledFriends 等函数和类型声明原封不动。

上面这几段是原理摘录，不能单独保存运行。完整可运行的工具就是一个文件 blogmgr.py（约 400 行，纯标准库），把它连同 blogmgr.json（首次运行会自动生成）放在同一目录即可使用，上面这些函数都已包含在内。

八、部署 Firefly 踩过的坑（也是你会遇到的）#

写这个工具的过程中，我把 Firefly 在普通服务器上部署的坑基本踩了一遍，记录在这里，省得你重蹈覆辙：