陌灬离的博客

1
---
2
title: 我的第一篇博客文章
3
published: 2023-09-09
4
description: 这是我新 Astro 博客的第一篇文章。
5
image: ./cover.jpg
6
tags: [前端, 开发]
7
category: 前端开发
8
draft: false
9
---

属性	描述
`title`	文章标题。
`published`	文章发布日期。
`updated`	文章更新日期。如果未设置，将默认使用发布日期。
`pinned`	是否将此文章置顶在文章列表顶部。
`description`	文章的简短描述。显示在首页上。
`image`	文章封面图片路径。 1. 以 `http://` 或 `https://` 开头：使用网络图片 2. 以 `/` 开头：`public` 目录中的图片 3. 不带任何前缀：相对于 markdown 文件的路径
`tags`	文章标签。
`category`	文章分类。
`lang`	文章语言代码（如 `zh-CN`）。仅当文章语言与站点默认语言不同时设置。
`licenseName`	文章内容的许可证名称。
`licenseUrl`	文章内容的许可证链接。
`author`	文章作者。
`sourceLink`	文章内容的来源链接或参考。
`draft`	如果这篇文章仍是草稿，则不会显示。
`comment`	是否启用此文章的评论功能。默认为 `true`。
`slug`	自定义文章 URL 路径。如果不设置，将使用文件名作为 URL。
`password`	文章密码。设置后文章内容将被 AES-256-GCM 加密，访客需输入密码才能查看。
`passwordHint`	密码提示。显示在密码输入框上方，帮助访客回忆密码，也可以不加。

文章文件的放置位置#

您的文章文件应放置在 src/content/posts/ 目录中。您也可以创建子目录来更好地组织您的文章和资源。

1
src/content/posts/
2
├── post-1.md
3
└── post-2/
4
    ├── cover.png
5
    └── index.md

自定义文章 URL (Slug)#

什么是 Slug？#

Slug 是文章 URL 路径的自定义部分。如果不设置 slug，系统将使用文件名作为 URL。

Slug 使用示例#

示例 1：使用文件名作为 URL#

1
---
2
title: 我的第一篇博客文章
3
published: 2023-09-09
4
---

文件：src/content/posts/my-first-blog-post.md

URL：/posts/my-first-blog-post

示例 2：自定义 Slug#

1
---
2
title: 我的第一篇博客文章
3
published: 2023-09-09
4
slug: hello-world
5
---

文件：src/content/posts/my-first-blog-post.md

URL：/posts/hello-world

示例 3：其他语言文件名使用Slug#

1
---
2
title: 如何使用 Firefly 博客主题
3
published: 2023-09-09
4
slug: how-to-use-firefly-blog-theme
5
---

文件：src/content/posts/如何使用Firefly博客主题.md

URL：/posts/how-to-use-firefly-blog-theme

Slug 使用建议#

使用英文和连字符：my-awesome-post 而不是 my awesome post
保持简洁：避免过长的 slug
具有描述性：让 URL 能够反映文章内容
避免特殊字符：只使用字母、数字和连字符
保持一致性：在整个博客中使用相似的命名模式

注意事项#

Slug 一旦设置并发布，建议不要随意更改，以免影响 SEO 和已存在的链接
如果多个文章使用相同的 slug，后面的文章会覆盖前面的
Slug 会自动转换为小写

博客填坑记：放弃 Git Submodule，拥抱正确的上游同步姿势

Wed, 14 Jan 2026 00:00:00 GMT

前言#

最近在使用 Firefly 主题搭建个人博客时，为了能持续获取原作者的更新，我最初在 AI 的建议下尝试使用了 git submodule（子模块）来管理我的文章目录。

结果，当我试图同步上游代码（Upstream）时，灾难发生了……

遇到的问题#

同步时，VS Code 疯狂报错，终端提示 fatal: not removing 'src/content/posts' recursively，而且文件列表中出现了一个诡异的 posts~HEAD 红色冲突，删都删不掉。

同时，启动项目时还遇到了 Cannot find module 'rehype-callouts' 的报错。

经过一番折腾（和高人指点），我终于明白：对于个人博客这种“魔改+写作”并行的项目，使用 Git Submodule 是过度设计，更是给自己挖坑。

为什么 Submodule 是个坑？#

双向修改的噩梦：子模块的设计初衷是“只读引用”。但我需要频繁修改 posts 里的文章，这导致 Git 无法判断版本，产生了“游离指针”和嵌套仓库冲突。
操作繁琐：每次更新都需要在两个仓库里分别提交，极易出错。
配置残留：即使删除了文件夹，.gitmodules 和 .git 隐藏目录依然会导致 Git 索引错乱。

解决方案：彻底移除子模块#

如果你也遇到了 warning: adding embedded git repository 或者 posts~HEAD 无法消除的问题，可以照着我的步骤“外科手术”一下：

1. 清理隐藏的 .git 文件夹#

问题的根源在于 src/content/posts 文件夹里藏了一个 .git 文件夹。需要强制删除它：

Terminal window

1
# 在终端执行（确保路径正确）
2
rm -rf src/content/posts/.git
3
# 或者在 Windows PowerShell 下：
4
Remove-Item -Path "src\content\posts\.git" -Recurse -Force

2. 清除 Git 缓存索引#

告诉 Git 忘记这个文件夹之前的“特殊身份”：

Terminal window

1
git rm -r --cached src/content/posts

3. 删除配置文件#

一定要把项目根目录下的 .gitmodules 文件删掉，这是子模块的“户口本”，不删会一直报错。

4. 重新添加为普通文件#

现在，把文章目录当做普通的文件夹加回来：

Terminal window

1
git add src/content/posts/*
2
git add .
3
git commit -m "彻底移除子模块，转为普通文件夹管理"

正确的工作流：如何优雅地同步上游#

填完坑后，我总结了一套标准同步流程（SOP）。以后获取原作者更新，只需要照着这个做，再也不怕覆盖文章了。

第一步：保护现场#

在同步前，永远先提交自己手头的修改：

Terminal window

1
git add .
2
git commit -m "同步前备份我的修改"

第二步：拉取并合并#

Terminal window

1
git fetch upstream
2
git merge upstream/master
3
# 注意：如果作者分支是 main，则用 upstream/main

第三步：处理冲突（关键）#

合并时，VS Code 左侧的“源代码管理”通常会出现冲突列表。

对于文章和配置文件 (config.ts)：毫不犹豫选择 “采用当前更改 (Accept Current Change)”，保留自己的。
对于系统代码：通常选择 “采用传入的更改 (Accept Incoming Change)”，使用作者的新功能。

Img

第四步：安装新依赖#

如果启动时报错缺包，是因为作者加了新插件。执行一行命令即可解决：

Terminal window

1
pnpm install
2
# 或者 npm install

总结#

折腾这一通，虽然走了弯路，但也彻底搞懂了 Git 的合并逻辑。对于博客这种项目，Upstream Merge（上游合并） 才是正道，Submodule 还是留给大型项目组件化去用吧。

希望这篇避坑指南能帮到同样在使用 Astro 博客模板的朋友们！

Firefly博客部署：Git Submodule方案完整指南

Wed, 31 Dec 2025 00:00:00 GMT

Firefly 博客搭建全流程指南(Git Submodule 方案)#

一、为什么选择 Git Submodule 方案?#

在开始搭建之前,先了解一下这套方案的核心优势。

1. 文章库(Posts)绝对安全#

当你执行 git merge upstream/main(同步上游)时:

完全不会冲突: Git 知道 src/content/posts 是一个子模块(Submodule),它在主库里只是一行”版本号指引”,上游作者无论怎么修改他自己的示例文章,都绝对碰不到你私有仓库里的文章
唯一的变化: 如果上游作者修改了 src/content/posts 这个文件夹的名称(比如改成 src/content/articles),你才需要动一下。但这种改动在成熟的框架里极少发生

2. 配置文件(Config)手动决策#

这是你唯一需要花 1 分钟”动脑子”的地方。当你执行同步命令时:

Terminal window

1
git fetch upstream
2
git merge upstream/main

如果没有冲突: Git 会自动合并
如果有冲突(通常在 src/config.ts): VS Code 会变红,显示”合并冲突”,你会看到类似这样的代码:

1
<<<<<<< HEAD (你的代码)
2
title: "陌离的博客",
3
=======
4
title: "Firefly Demo",
5
>>>>>>> upstream/main (作者的代码)

操作: 你只需要点击 VS Code 顶部的 “Accept Current Change”(保留我的更改),或者手动删掉作者的那几行,保留你自己的配置即可。

3. 上游增加新功能自动获得#

如果上游作者在 src/config.ts 里新增了一个功能配置(比如新增了评论系统设置):

Git 会很聪明地把这一行加进来
你只需要在合并完后,去填一下这个新配置的值就行了

二、Fork Firefly 仓库#

首先前往 https://github.com/CuteLeaf/Firefly 博客主页,点击右上角的 Fork 按钮到自己账号下。

Fork仓库

Repository name 和 Description 直接按照默认的即可,也可以自行修改,然后点击 Create fork。

到这里你就已经 Fork 完成了,有了代码,后面就可以部署到 Vercel 上面。但现在我们还需要创建一个新的仓库,专门用来写文章。

三、创建内容仓库#

我们现在开始创建内容仓库:

登录 GitHub,点击右上角的 New repository
仓库名称建议: my-blog-posts(可自定义)
重要: 必须选择 Private(私有),这样可以保护你的草稿和未发布内容
不要勾选 “Initialize this repository with a README”
点击 Create repository

创建仓库

四、迁移现有文章(Fuwari 用户专用,可选)#

由于 Firefly 是 Secondary development based on Fuwari,我本来用的是 Fuwari 博客,也是 Astro 框架,所以迁移起来不需要改太多东西。不需要迁移的可以跳过这一节。

迁移步骤#

先小范围测试: 首先我先复制了一两个我原来 Fuwari 博客的文章到 Firefly 下面,发现能正常显示,于是便开始大规模迁移。

注意: 不要一来就将全部内容复制到 Firefly 下面,要是报错了就难搞了。
准备目录结构: 我在 H 盘创建了一个专门存放博客的目录 H:\博客专用,然后:

Terminal window

1
# 克隆自己 Fork 的 Firefly(不是原仓库)
2
git clone https://github.com/moli721/Firefly.git
3

4
# 新建 posts 文件夹,专门存放文章
5
mkdir posts

这样做的好处是<以后只需要去> H:\博客专用\posts 修改文章,然后推送到 GitHub,再让 moli721/Firefly.git 拉取子模块就行。git merge upstream/main(同步上游)时不会冲突。

保留示例文章: 先把 H:\博客专用\Firefly\src\content\posts 复制到我的 H:\博客专用\posts 下面,这样做的好处是保留了原来 Firefly 博客的一些样例和基本格式,以后可以对照。
迁移旧文章: 最后一步就是将 H:\代码\fuwari博客\fuwari-moli721\src\content\posts 下的博客复制到 H:\博客专用\posts 下面直接迁移。

整理示例文章#

迁移后,我让 Claude Code 把原来 Firefly 的示例文章放在 examples 目录下(手动迁移也行)。

示例文章整理

修复 Frontmatter 格式#

但是后来也发现 Firefly 的 frontmatter 顺序和 Fuwari 的有些不一样,然后还有些补充。对于强迫症的我不会允许这里不一样,由于文章数量很多,这里不推荐手动修改,直接让 Claude Code 帮你干活,狠狠鞭策 AI!

Terminal window

1
# 让 Claude Code 帮你批量检查和修复
2
# 1. 打开文章目录
3
# 2. 告诉 Claude: "firefly的frontmatter顺序和fuwari的有些不一样,帮我检查所有文章的 Frontmatter,修复格式问题"
4
# 3. Claude 会自动扫描并修复所有文章

到这里,博客文章基本迁移完成了。

五、推送文章到 GitHub#

下面将 posts 目录推送到 GitHub:

Terminal window展开收起

1
# 进入文章目录
2
cd H:\博客专用\posts
3

4
# 初始化 Git 仓库
5
git init
6

7
# 添加所有文章文件
8
git add .
9

10
# 提交到本地仓库
11
git commit -m "Initial posts backup from Fuwari"
12

13
# 设置主分支名称
14
git branch -M main
15

16
# 关联远程仓库(替换为你的用户名)
17
git remote add origin https://github.com/moli721/my-blog-posts.git

展开收起

注意: 这里应该换成你自己的用户名和仓库名: git remote add origin https://github.com/你的用户名/my-blog-posts.git

Terminal window

1
# 推送到 GitHub
2
git push -u origin main

六、配置子模块(关键步骤)#

下一步就是配置子模块了。这是整个流程中最关键的一步,我们将通过 Git Submodule 把文章仓库”挂载”到框架中。

1. 删除 Firefly 自带的示例文章#

Terminal window

1
# 确保在 Firefly 根目录下
2
cd H:\博客专用\Firefly
3

4
# 注意: 是 posts(复数)
5
git rm -r src/content/posts

2. 挂载你的私有文章库#

Terminal window

1
# 将你的文章仓库作为子模块添加(替换为你的用户名)
2
git submodule add https://github.com/你的用户名/my-blog-posts.git src/content/posts

3. 安装依赖并启动项目#

重要提示: Firefly 框架的作者强制要求必须使用 pnpm。这是因为 pnpm 速度更快、节省磁盘空间,且能有效避免依赖冲突。如果你执行 npm install,会被内置的校验脚本 only-allow pnpm 拦截。用 npm install 会报错,作者亲身体验!

安装 pnpm(全局安装)#

如果你的电脑还没有安装 pnpm,先用 npm 安装它:

Terminal window

1
npm install -g pnpm

安装完成后,可以输入 pnpm -v 验证是否成功,你应该能看到版本号(如 9.x 或 10.x)。

使用 pnpm 安装依赖#

Terminal window

1
# 安装项目依赖
2
pnpm install

你会发现 pnpm 的安装速度非常快,它会自动处理好所有依赖关系。

启动开发服务器#

Terminal window

1
# 启动本地预览
2
pnpm dev

现在打开浏览器访问 http://localhost:4321,你应该能看到你的博客了!

如果这里出现报错: 就看报错提示解决吧,没有报错就提交子模块。

4. 提交子模块配置#

Terminal window

1
# 添加所有更改
2
git add .
3

4
# 提交到本地
5
git commit -m "chore: link posts submodule"
6

7
# 推送到你的 GitHub 仓库
8
git push origin main

七、部署到 Vercel(重要配置)#

下一步就是部署到 Vercel。

由于使用了私有子模块,Vercel 默认没有权限访问你的文章仓库,需要额外配置。否则即使你的 Firefly 项目下面的 src\content\posts 下面有文章,部署出来的项目也会一篇文章都没有,全是空的。

在询问 Gemini 和 Claude 后,找到了解决方案。

1. 修改 vercel.json#

解决方案: 删除 vercel.json 中的 installCommand 行。

这里我们需要修改原项目的 vercel.json,将其修改为以下内容,然后提交到项目里:

1
{
2
  "buildCommand": "pnpm build",
3
  "outputDirectory": "dist",
4
  "framework": "astro",
5
  "headers": [
6
    {
7
      "source": "/(.*)",
8
      "headers": [
9
        {
10
          "key": "X-Content-Type-Options",
11
          "value": "nosniff"
12
        },
13
        {
14
          "key": "X-Frame-Options",
15
          "value": "DENY"
16
        },
17
        {
18
          "key": "X-XSS-Protection",
19
          "value": "1; mode=block"
20
        },
21
        {
22
          "key": "Referrer-Policy",
23
          "value": "strict-origin-when-cross-origin"
24
        }
25
      ]
26
    },
27
    {
28
      "source": "/_astro/(.*)",
29
      "headers": [
30
        {
31
          "key": "Cache-Control",
32
          "value": "public, max-age=31536000, immutable"
33
        }
34
      ]
35
    }
36
  ],
37
  "cleanUrls": true
38
}

展开收起

2. 确保 .gitmodules 使用绝对路径#

然后确保 .gitmodules 使用绝对路径(没改过的不用改,我是因为之前改过)。

原因: 不能用相对路径,在某些环境下好用,但在 Vercel 这种特定的构建容器里会产生歧义。

在本地打开 .gitmodules,将 URL 改回完整的 HTTPS 地址:

Terminal window

1
[submodule "src/content/posts"]
2
  path = src/content/posts
3
  url = https://github.com/moli721/my-blog-posts.git

提交并推送到 GitHub:

Terminal window

1
git add .gitmodules
2
git commit -m "chore: restore absolute URL for submodule"
3
git push origin main

3. 创建 GitHub “经典” Token(Classic Token)#

之前用的 Fine-grained Token(细粒度令牌)虽然安全,但有可能会报错。我试过了,搜索发现它目前对子模块的支持非常差,经常报 403 Write access 错误。我们换成最稳的 Classic Token。

生成 Token#

去 GitHub Settings → Developer settings(在最下面) → Personal access tokens → Tokens (classic)
点击 Generate new token (classic)
Note 填 Vercel-Firefly
Expiration 选 No expiration(或者你喜欢的时长)
重要: 勾选整个 repo 权限
生成后,复制这个以 ghp_ 开头的字符串(只显示一次,记下来)

生成Token

4. 在 Vercel 配置环境变量#

然后前往 Vercel 填写相关信息。

步骤 1: 添加环境变量#

在 Vercel 项目 Settings → Environment Variables 里,添加一个变量:

Key: BLOG_TOKEN
Value: 填入你刚才复制的 ghp_... 令牌

配置环境变量

步骤 2: 配置 Install Command#

去 Settings → Build and Deployment → Install Command。

确保 Override 开启,填入这行代码(避开 403 错误):

Terminal window

1
git config --global url."https://moli721:$BLOG_TOKEN@github.com/".insteadOf "https://github.com/" && git submodule update --init --recursive && pnpm install

注意: 将 moli721 替换为你的 GitHub 用户名。

配置Install Command

5. 重新部署(Redeploy)#

回到 Deployments,找最近一次失败的,点 … 选 Redeploy。

八、大功告成!#

到这里就完全搭建完成了!

部署成功

九、日常使用工作流程#

配置完成后,日常写作和发布的流程非常简单。记住核心原则:改文章去 posts 目录,预览和部署在 Firefly 目录。

1. 日常写文章#

在独立的 posts 目录工作:

Terminal window

1
# 进入文章目录
2
cd H:\博客专用\posts
3

4
# 创建或编辑文章
5
# 注意:必须添加完整的 frontmatter(见下方示例)
6

7
# 提交到文章仓库
8
git add .
9
git commit -m "feat: 新增文章《xxx》"
10
git push origin main

⚠️ 重要提醒: 每篇文章必须包含 frontmatter,否则 Firefly 会报错!

基本 frontmatter 模板:

1
---
2
title: 文章标题
3
published: 2025-12-31
4
description: 文章简介
5
tags: [标签1, 标签2]
6
category: 分类名称
7
draft: false
8
---
9

10
# 文章标题
11

12
文章内容...

可选字段:

1
---
2
title: 文章标题
3
published: 2025-12-31
4
pinned: true              # 添加这行可以置顶文章
5
description: 文章简介
6
image: "./FILES/xxx.png"  # 添加封面图
7
tags: [标签1, 标签2]
8
category: 分类名称
9
draft: false
10
---

2. 本地预览博客#

在 Firefly 目录更新子模块并预览:

Terminal window

1
# 进入 Firefly 目录
2
cd H:\博客专用\Firefly
3

4
# 拉取最新文章
5
git submodule update --remote src/content/posts
6

7
# 本地预览
8
pnpm dev

打开浏览器访问 http://localhost:4321 查看效果。

3. 部署到 Vercel#

确认预览无误后,提交子模块更新:

Terminal window

1
# 在 Firefly 目录下
2
cd H:\博客专用\Firefly
3

4
# 提交子模块引用更新
5
git add src/content/posts
6
git commit -m "chore: update posts to latest version"
7

8
# 推送到 GitHub(Firefly 使用 master 分支)
9
git push origin master

推送后,Vercel 会自动触发部署,大约 1-2 分钟后你的博客就更新了!

十、同步上游更新(Merge Upstream)#

当 Firefly 官方仓库有新功能或 bug 修复时,你需要同步这些更新。得益于 Submodule 方案,这个过程非常安全和可控。

为什么 Submodule 方案同步更新超安全?#

文章库绝对安全: src/content/posts 是子模块,上游无法修改你的私有文章仓库
配置冲突可控: 只有 src/config/ 目录可能冲突,且可以手动选择保留哪个版本
新功能自动获得: 上游新增的代码功能会自动合并,无需手动复制

1. 添加上游仓库(首次执行)#

如果你是第一次同步,需要先添加上游仓库:

Terminal window

1
# 进入 Firefly 目录
2
cd H:\博客专用\Firefly
3

4
# 添加官方仓库为上游(upstream)
5
git remote add upstream https://github.com/CuteLeaf/Firefly.git
6

7
# 验证是否添加成功
8
git remote -v
9
# 应该看到:
10
# origin    https://github.com/你的用户名/Firefly.git (你的 fork)
11
# upstream  https://github.com/CuteLeaf/Firefly.git (官方仓库)

2. 备份配置文件(强烈推荐)#

在合并前,先备份你的个人配置:

Terminal window

1
# 创建带时间戳的备份目录
2
mkdir ../firefly-config-backup-$(date +%Y%m%d-%H%M%S)
3

4
# 备份配置文件和自定义资源
5
cp -r src/config ../firefly-config-backup-*/
6
cp -r public/assets/images ../firefly-config-backup-*/images

Windows PowerShell 用户:

Terminal window

1
# 使用 PowerShell 创建备份
2
$timestamp = Get-Date -Format "yyyyMMdd-HHmmss"
3
New-Item -ItemType Directory -Path "..\firefly-config-backup-$timestamp"
4
Copy-Item -Recurse src/config "..\firefly-config-backup-$timestamp\"
5
Copy-Item -Recurse public/assets/images "..\firefly-config-backup-$timestamp\images"

3. 获取上游更新并检查状态#

Terminal window展开收起

1
# 获取上游最新代码(不会修改本地文件)
2
git fetch upstream
3

4
# 检查有哪些新提交
5
git log HEAD..upstream/master --oneline
6
# 这会显示上游的新提交列表,例如:
7
# a1b2c3d feat: 新增暗色模式切换功能
8
# e4f5g6h fix: 修复移动端导航栏问题
9
# i7j8k9l docs: 更新配置文件注释
10

11
# 查看具体改动的文件统计
12
git diff HEAD..upstream/master --stat
13
# 这会显示哪些文件被修改,例如:
14
# src/config/siteConfig.ts          | 15 ++++---
15
# src/components/Navbar.astro       | 42 +++++++++++-------
16
# package.json                      |  3 +-

展开收起

⚠️ 重点关注: 如果 git diff --stat 显示 src/config/ 目录有修改,说明可能会有配置冲突。

4. 手动合并(推荐方式)#

使用 --no-commit --no-ff 参数可以让你在提交前检查合并结果:

Terminal window

1
# 执行合并,但不自动提交
2
git merge upstream/master --no-commit --no-ff

可能的三种情况:

情况 A: 自动合并成功(无冲突)#

Terminal window

1
# 终端显示:
2
Automatic merge went well; stopped before committing as requested

这说明没有冲突!检查改动后直接提交即可:

Terminal window

1
# 查看改动
2
git status
3

4
# 测试运行
5
pnpm dev
6

7
# 确认无误后提交
8
git commit -m "merge: 同步上游更新 $(git log upstream/master -1 --format='%h %s')"

情况 B: 有冲突(通常在配置文件)#

Terminal window

1
# 终端显示:
2
CONFLICT (content): Merge conflict in src/config/siteConfig.ts
3
Automatic merge failed; fix conflicts and then commit the result.

解决步骤:

打开 VS Code 查看冲突文件(通常在 src/config/ 目录):

1
<<<<<<< HEAD (你的版本)
2
title: "陌灬离的博客",
3
navbar: {
4
  logo: "/assets/images/mylogo.svg",
5
  title: "𝓜𝓞𝓵𝓲"
6
},
7
=======
8
title: "Firefly",
9
navbar: {
10
  logo: "/assets/images/logo.svg",
11
  title: "Firefly"
12
},
13
>>>>>>> upstream/master (上游版本)

手动选择保留哪个版本:
- 点击 VS Code 顶部的 “Accept Current Change”(保留你的)
- 或点击 “Accept Incoming Change”(使用上游的)
- 或点击 “Accept Both Changes”(保留两者,手动整合)
处理配置文件建议:
- src/config/siteConfig.ts: 保留你的个人信息(标题、描述、链接等)
- src/config/commentConfig.ts: 保留你的评论系统配置(Twikoo/Giscus)
- src/config/profileConfig.ts: 保留你的个人资料
- 新增的配置项: 接受上游的默认值,稍后根据需要修改
恢复自定义资源(如果被删除):

Terminal window

1
# 检查自定义图片是否存在
2
ls public/assets/images/
3

4
# 如果图片被删除,从备份恢复
5
cp ../firefly-config-backup-*/images/* public/assets/images/

标记冲突已解决:

Terminal window

1
# 添加已解决的文件
2
git add .
3

4
# 检查状态
5
git status

测试运行:

Terminal window

1
pnpm dev
2
# 在浏览器访问 http://localhost:4321 检查
3
# 重点检查: 导航栏、个人资料、评论系统、文章列表

提交合并:

Terminal window

1
git commit -m "merge: 合并上游更新,保留个人配置"

情况 C: Submodule 冲突(极少见)#

如果 src/content/posts 显示冲突:

src/content/posts

1
# 查看冲突
2
git status
3
# 保留你的子模块版本
4
git checkout --ours src/content/posts
5

6
# 添加到暂存区
7
git add src/content/posts
8

9
# 继续提交
10
git commit -m "merge: 同步上游更新,保留文章子模块"

5. 推送并部署#

Terminal window

1
# 推送到你的 GitHub 仓库
2
git push origin master
3

4
# Vercel 会自动部署,等待 1-2 分钟即可

6. 验证部署#

访问你的 Vercel 部署地址,检查:

✅ 博客能正常访问
✅ 文章列表完整
✅ 个人配置(标题、头像、评论系统)正确
✅ 新功能正常工作

🤖 给 AI 助手的状态摘要模板#

如果你在同步过程中需要切换 AI 对话,或者让新的 AI 助手帮你继续,可以复制以下模板并填入实际信息:

1
## Firefly 博客上游同步状态摘要
2

3
**项目信息**:
4
- 主项目: [你的GitHub用户名]/Firefly (fork from CuteLeaf/Firefly)
5
- 文章仓库: [你的GitHub用户名]/my-blog-posts (私有,通过 Git Submodule 挂载到 `src/content/posts`)
6
- 本地路径: `H:\博客专用\Firefly`
7
- Posts 路径: `H:\博客专用\posts`
8

9
**个性化配置**:
10
- 博客标题: [你的博客标题]
11
- 导航栏 Logo: `/assets/images/[你的logo文件名]`
12
- 评论系统: [Twikoo/Giscus/其他] + 配置地址
13
- 自定义图片: [列出你的自定义图片文件名]
14
- Bangumi UID: [你的番组计划ID,如有]
15

16
**当前同步状态**:
17
- [ ] 已执行 `git fetch upstream`
18
- [ ] 已检查 `git log HEAD..upstream/master` (发现 X 个新提交)
19
- [ ] 已备份配置文件到: `../firefly-config-backup-[时间戳]/`
20
- [ ] 已执行 `git merge upstream/master --no-commit --no-ff`
21
- [ ] 冲突状态: [无冲突 / 有冲突在以下文件: xxx]
22
- [ ] 已解决冲突并测试(`pnpm dev` 正常运行)
23
- [ ] 已提交合并
24

25
**冲突解决策略** (如有):
26
- `src/config/siteConfig.ts`: 保留我的个人信息,接受新增配置项的默认值
27
- `src/config/commentConfig.ts`: 完全保留我的配置(`git checkout --ours`)
28
- `src/config/profileConfig.ts`: 完全保留我的配置
29
- 自定义图片: 如被删除则从备份恢复
30

31
**待办事项**:
32
- [ ] 继续解决剩余冲突
33
- [ ] 本地测试通过
34
- [ ] 提交并推送
35
- [ ] 验证 Vercel 部署
36

37
**备注**: [其他重要信息或遇到的问题]

展开收起

使用方法: 复制上面的模板,填入你的实际信息,然后粘贴给新的 AI 对话。AI 会根据这个摘要快速理解你的状态并继续帮助你。

常见问题#

Q1: 多久同步一次上游? A: 建议每 1-2 个月检查一次,或者当你在 GitHub 看到上游有重大更新时。

Q2: 如果不小心把自定义配置覆盖了怎么办? A: 这就是为什么我们要先备份!从 ../firefly-config-backup-*/ 恢复即可。

Q3: 能直接用 git pull upstream master 吗? A: 不推荐。pull = fetch + merge,会自动提交。使用 --no-commit 可以先检查再提交,更安全。

Q4: Submodule 同步会影响我的文章吗? A: 不会!src/content/posts 指向你的私有仓库,上游无法修改。最多只是子模块引用的 commit ID 可能冲突,用 git checkout --ours 保留你的版本即可。

参考资源#

祝你的博客之旅顺利! 🎉

Clawcloud部署AList完整指南

Mon, 14 Apr 2025 00:00:00 GMT

前言#

在这个云服务遍地开花的时代，找到一个真正适合个人使用的免费云平台着实不易。最近我发现了 Clawcloud 这个宝藏平台，不仅提供了慷慨的免费额度，更难得的是无需信用卡即可使用 —— 这对于我们这些热衷于探索新技术却预算有限的开发者来说，简直是最好的礼物。

作为一名经常需要管理各种文件的开发者，我一直在寻找一个可以稳定运行 AList 的平台。通过深入研究和实践，我发现 Clawcloud 完美符合这个需求。它不仅提供了新用户 5 美元的初始额度，对于拥有超过半年历史的 GitHub 用户，更有每月持续的 5 美元赠送额度，这让长期运行变得非常经济实惠。

在这篇文章中，我将详细分享我的部署经验，包括平台特性、资源定价、部署流程以及一些常见的坑。无论你是想搭建个人网盘，还是在寻找免费的容器部署方案，相信这篇教程都能给你带来启发。

💡 小贴士：虽然 Clawcloud 采用按量计费模式，但通过合理配置，完全可以在免费额度内稳定运行你的服务！

平台介绍与准备工作#

Clawcloud 平台特点#

新用户注册即赠送 5 美元额度（当月有效）
绑定 GitHub 账号（注册超过 180 天）可每月获得 5 美元赠额
免费计划无需绑定信用卡
采用按量计费模式（Pay as you go）

资源定价表#

资源类型	按月计费	按小时计费	其他计费方式
CPU	$4/vCPU/月	$0.005556/vCPU/小时	-
RAM	$2/GB/月	$0.002778/GB/小时	-
Storage	$0.12/GB/月	$0.000352/GB/小时	-
Network	$0.05/GB	-	0.00005/MB或0.00005/MB 或 0.00005/MB或0.05/GB

部署前准备#

注册时间超过 180 天的 GitHub 账号（用于登录 Clawcloud Run）
Cloudflare 账号（用于创建隧道）

部署原理#

在开始具体的部署步骤之前，让我们先了解整个系统的工作原理，这将帮助你更好地理解配置过程。

为什么需要 Cloudflare 隧道？#

Clawcloud 上部署的 AList 是一个内网服务，外部网络无法直接访问。为了使服务能够被外部访问，我们需要使用 Cloudflare 隧道来建立一个安全的连接通道。

工作流程#

内网服务
- AList 部署在 Clawcloud 内部
- 获得内网地址：alist-xxx.ns-xxx.svc.cluster.local:5244
隧道建立
- 在 Cloudflare 创建隧道并获取 Token
- 配置 CNAME 记录（如：alist-cf.moli721.xyz）作为隧道入口
- 在 Clawcloud 部署 cloudflared 客户端维持隧道连接
- 设置公共主机名（如：alist.moli721.xyz）作为访问入口

请求流程

1
用户访问 alist.moli721.xyz
2
       ↓
3
Cloudflare 处理请求
4
       ↓
5
通过已建立的隧道转发
6
       ↓
7
cloudflared 客户端接收请求
8
       ↓
9
转发至 AList 内网服务

关键组件说明#

cloudflared 客户端：运行在 Clawcloud 上的隧道客户端，负责维持隧道连接和请求转发
CNAME 记录：用于注册隧道连接点，使 Cloudflare 能够找到正确的隧道
公共主机名：用户实际访问的域名，通过隧道将请求转发到内部服务

AList 部署步骤#

1. 创建 AList 应用#

访问 Clawcloud 官网并注册账号
进入控制台，找到 App Store 中的 AList
Img
配置管理员账号
- 选择 USERNAME 为 admin
- 设置你的管理员密码
- 点击右上角 Deploy App 并确认
  Img

⚠️ 注意：请务必记住设置的管理员密码，这将用于后续登录 AList 管理面板

应用配置优化
- 点击 Details 后进入 Update 界面
- 取消勾选 Enable Internet Access
- 将 /opt/alist/data 存储容量调整至 10G
- 点击右上角 Update 并确认
  Img

2. 配置 Cloudflare 隧道#

2.1 创建隧道应用#

在 AppLauchpad 中点击 Create App
填写基本信息：
- Application Name: cloudflare
- Image Name: cloudflare/cloudflared
- Usage: 0.1CPU 64M
- Network: 勾选 Enable Internet Access
  Img

2.2 配置域名解析#

点击 custom domain，复制 CNAME 值
在 Cloudflare 添加 CNAME 记录
- 名称：自定义（如：alist-cf）
- 目标：粘贴刚才复制的 CNAME 值
  Img

💡 CNAME 的作用：CNAME（Canonical Name）记录是一种 DNS 记录，它能够将一个域名指向另一个域名。在这里，我们使用 CNAME 将我们自定义的域名（如：alist-cf.你的域名.com）指向 Cloudflare 的隧道服务器，这样就能通过我们自己的域名访问 AList 服务了。

2.3 获取隧道 Token#

进入 Cloudflare Zero Trust 概述
导航至：网络 -> Tunnels
创建新隧道
Img
复制隧道 Token
Img

2.4 完成隧道配置#

配置隧道命令
- 在 Command 输入框中填写：cloudflared tunnel --no-autoupdate run --token 你的token
- 点击右上角 Deploy Application
- 确认后点击 Yes 完成创建
配置公共主机名
- 进入隧道详情页面
- 选择”公共主机名”选项
- 点击编辑按钮
  Img
配置内网地址
- 在 URL 字段中填写 AList 的内网地址
- 内网地址格式：alist-[随机字符].ns-[随机字符].svc.cluster.local:5244
- 注意：需要删除地址前面的 http:// 或 https:// 前缀
- 参考下图进行配置：
  Img

⚠️ 重要提示：

确保填写的是 AList 的内网地址，而不是 Cloudflare 的地址

Token 示例：如果你看到类似 cloudflared.exe service install eyJhIjoiODY3Y2JlZWMzNWNkNWRmMzZhYTJlMjhmYzgxxxxxxxxxxxxx 的内容，只需提取 token 部分即可

完整的命令格式应该是：cloudflared tunnel --no-autoupdate run --token eyJhIjoiODY3Y2JlZWMzNWNkNWRmMzZhYTJlMjhmYzgxxxxxxxxxxxxx

内网地址示例：如果你看到 http://alist-wwfvezps.ns-d9vkx1tq.svc.cluster.local:5244，请只保留 alist-wwfvezps.ns-d9vkx1tq.svc.cluster.local:5244 部分

至此，AList 的部署和配置就全部完成了！你现在可以通过配置的域名访问你的 AList 服务了。

补充说明#

应用卸载方法#

如需卸载应用，可在 App Store 的 My Apps 标签中找到对应应用，点击右上角 Uninstall 即可。

常见问题解答#

CNAME 记录的作用：用于将你的自定义域名指向 Cloudflare 的隧道服务
内网地址注意事项：配置时请使用 AList 的内网地址，而非 Cloudflare 的地址

原教程参考：https://linux.do/t/topic/557711

从零开始：在Cloudflare上部署Cookie共享与影视站实战指南

Sun, 13 Apr 2025 00:00:00 GMT

前言#

Cloudflare作为一个强大的云平台，不仅可以帮助我们部署网站，还能实现很多有趣的功能。今天，我将介绍如何在Cloudflare上部署两个实用的项目：

Cookie-share：一个支持跨设备账号切换的工具
LibreTV：一个私人影视站

让我们一起来看看如何快速部署这两个项目！

第一部分：Cookie共享服务部署#

准备工作#

在开始部署之前，我们需要：

一个 Cloudflare 账号
浏览器安装油猴插件（Tampermonkey）
项目源码：cookie-share

部署步骤#

1. 创建 Cloudflare Worker#

首先，我们需要在 Cloudflare 上创建一个 Worker 来运行我们的服务：

登录 Cloudflare，进入 Workers 和 Pages 界面
点击创建应用程序
Img
选择 “Hello World” 模板，为你的 Worker 取一个名字（这里我们使用 cookie-share）
Img

2. 配置环境变量和 KV 存储#

为了确保服务正常运行，我们需要设置以下配置：

创建 KV 命名空间
- 在 Cloudflare Workers 界面找到 KV 选项
- 创建一个新的命名空间（例如：cookie-share-kv）
  Img
设置环境变量
- ADMIN_PASSWORD：管理员密码，用于访问管理接口
- PATH_SECRET：安全密钥，用于防止暴力破解
- COOKIE_STORE：绑定 KV 命名空间
  Img

3. 部署 Worker 代码#

复制 worker.js 的内容
在 Worker 编辑界面中粘贴代码
点击”部署”按钮

注意：请确保在部署代码之前已经正确配置了环境变量和 KV 存储，否则会报错！

4. 配置油猴脚本#

为了使 cookie-share 正常工作，我们需要正确配置油猴脚本的权限：

将配置模式改为高级：
Img
添加 cookie 权限并保存：
Img

使用示例：ChatGPT 账号切换#

让我们以 ChatGPT 为例，演示如何使用 cookie-share：

配置服务地址和密钥：
Img
- Worker URL 格式：https://你的域名/PATH_SECRET
- 例如：如果你的 PATH_SECRET 是 “abcdef”，则填写 https://cookie.moli721.xyz/abcdef
切换账号：
Img

Cookie共享安全提示#

为了确保你的账号安全，请注意：

设置足够复杂的 ADMIN_PASSWORD 和 PATH_SECRET
不要将这些密钥分享给不信任的人
定期更换密钥
及时清理不需要的 cookie 数据

第二部分：LibreTV 私人影视站部署#

相比Cookie共享服务，LibreTV的部署过程要简单得多。让我们来看看如何快速搭建一个私人影视站。

部署步骤#

Fork项目首先前往LibreTV项目地址，将项目fork到自己的GitHub账号下：
Img
使用Cloudflare Pages部署
- 进入Cloudflare的Workers和Pages界面
- 选择Pages选项，点击”连接到Git”
  Img
选择仓库并完成部署
- 选择刚刚fork的LibreTV仓库
- Cloudflare会自动完成部署过程
  Img

部署完成后，你就可以访问自己的私人影视站了：

Img

结语#

通过本教程，我们成功在Cloudflare上部署了两个实用的项目：

Cookie共享服务：帮助你在不同设备间轻松切换账号
私人影视站：随时随地观看你喜欢的影视内容

这两个项目都充分利用了Cloudflare的免费资源，不需要额外的服务器成本。希望这个教程对你有帮助！

PikPak会员获取与配置方案

Thu, 03 Apr 2025 00:00:00 GMT

免费获取PikPak会员的完整教程#

本教程将带您一步步实现免费获取PikPak会员资格。整个过程简单易懂，即使是技术小白也能轻松完成。

一、准备工作#

首先，我们需要获取一个开源项目来帮助我们实现自动邀请功能。前往GitHub上的这个项目： https://github.com/Bear-biscuit/Pikpak-Auto-Invitation

将项目克隆到本地后，安装相关依赖并运行：

1
git clone https://github.com/Bear-biscuit/Pikpak-Auto-Invitation
2
pip install -r requirements.txt
3
python run.py

这里我就不详细演示了。

二、获取临时邮箱#

为了完成邀请注册流程，我们需要使用临时邮箱。这里推荐使用闪邮箱： https://shanyouxiang.com/

Img

进入网站后，您可以选择购买登录账号或邮箱卡。邮箱卡支持API调用，而我选择的是直接购买账号。购买完成后，我们就可以开始下一步操作了。

三、注册PikPak账号#

现在，前往我们刚才运行的项目页面，找到注册账号的界面：

首先需要填写您刚购买的邮箱和PikPak邀请码
PikPak邀请码获取方法：打开PikPak应用，点击左下角的”引荐奖励计划”

Img

进入后点击”邀请码”即可复制您的专属邀请码。

填写完成后点击”注册”按钮

Img

注意：如果滑块验证码验证失败，可以多尝试几次，直到成功为止。

Img

四、获取验证码并完成注册#

点击”获取验证码”后，我们需要查看邮箱获取验证码。有两种方式：

前往Outlook官网登录查看
使用项目提供的第二个页面（推荐）：输入您的邮箱账号和密码

Img

获取验证码后，将其复制到注册页面，点击”完成注册”：

Img

注册成功后，系统会自动生成一个JSON文件，并将账号信息保存在”历史账号”中：

Img

五、激活会员资格#

最后一步，我们需要激活刚注册的账号：

前往”账号一键活跃”界面
选择您刚才使用的账号
从纸鸢佬的导航页获取密钥
执行激活操作

Img

完成以上步骤后，您就成功获得了7天的PikPak会员时长！

Img

参考资源#

更多详细信息可参考：https://linux.do/t/topic/528654

如何在Clash中手动添加规则以直连特定网站

Tue, 25 Mar 2025 00:00:00 GMT

博客文章：如何在 Clash 中手动添加规则以直连特定网站#

前言#

最近在使用 Clash 代理时，我遇到一个问题：开启代理后，访问某些网站时会被拒绝进入。仔细一想，可能是这些网站检测到我的流量走了代理节点，不允许通过代理访问。为了解决这个问题，我决定手动在 Clash 配置中添加规则，让这些网站的流量直连（不走代理）。在这个过程中，我还对 ruleProviders（规则集）产生了好奇——它是什么？谁提供的？怎么用？跟自己写的规则有什么区别？接下来，我将把疑问和解决过程记录下来，分享给大家。

问题背景#

我在 Clash 中订阅了一个代理配置，节点运行正常，但访问下面两个网址时却出了问题：

http://10.17.8.18/a79.htm?userip=10.21.246.78&wlanacname=&wlanacip=10.17.4.1&usermac=f3feecd18354f7cc87b23ed50cb58a7871db97133f303b3b
https://new.clivia.fun/

打开代理后，这些网站要么加载失败，要么直接提示无法访问。原因很可能是网站要求流量必须直连，而不是通过代理节点。为了正常访问，我需要调整 Clash 的规则，让这些网址的流量绕过代理，走直连模式。

解决方法：手动添加直连规则#

在 Clash 中，流量的路由是通过 rules（规则）来控制的。Clash 会从上到下依次检查规则列表，找到第一个匹配的规则，然后根据规则指定的策略（比如 DIRECT 表示直连，PROXY 表示走代理）处理流量。

为了让特定网站直连，我需要在规则列表的开头添加直连规则，确保这些流量优先匹配到 DIRECT 策略。

针对内网 IP 地址#

第一个网址的域名部分是一个内网 IP 地址 10.17.8.18，我可以用 IP-CIDR 规则来匹配它：

1
- IP-CIDR,10.17.8.18/32,DIRECT

IP-CIDR：匹配 IP 地址范围的规则。
10.17.8.18/32：精确匹配单个 IP 地址（/32 表示子网掩码，只包含这一个 IP）。
DIRECT：表示直连，不走代理。

针对域名#

第二个网址是 new.clivia.fun，我可以用 DOMAIN 规则来精确匹配它：

1
- DOMAIN,new.clivia.fun,DIRECT

DOMAIN：匹配完整域名的规则。
new.clivia.fun：目标域名。
DIRECT：直连策略。

修改后的规则列表#

我在 Clash 配置文件中，将这两条规则添加到 rules 数组的开头，确保它们优先于其他规则被匹配：

1
config["rules"] = [
2
    "IP-CIDR,10.17.8.18/32,DIRECT",
3
    "DOMAIN,new.clivia.fun,DIRECT",
4
    // 其他原有规则...
5
];

保存配置后重启 Clash，问题解决了！这两个网址的流量不再走代理，访问恢复正常。

未来如何添加更多直连网址#

如果以后还有其他网站需要直连，只需按照类似方法，在 rules 开头添加新规则。Clash 支持多种规则类型，比如：

单个 IP 地址：IP-CIDR,<IP地址>/32,DIRECT
单个域名：DOMAIN,<域名>,DIRECT
域名关键字：DOMAIN-KEYWORD,<关键字>,DIRECT（匹配包含关键字的域名）
域名后缀：DOMAIN-SUFFIX,<域名后缀>,DIRECT（匹配某后缀的所有域名）

例如，想让 example.com 直连：

1
- DOMAIN,example.com,DIRECT

关于 `ruleProviders` 的疑问解答#

在研究规则时，我注意到配置文件中还有一个 ruleProviders 的部分，这是什么呢？下面我来详细解释。

`ruleProviders` 是什么？#

简单来说，ruleProviders 是 Clash 中用于从外部获取规则集的功能。这些规则集通常是一些预定义的规则文件，由第三方或开源社区提供和维护，包含大量规则，能应对更广泛的场景，比如屏蔽广告、处理局域网流量等。

`ruleProviders` 的配置示例#

我的配置文件中有这样的内容：

1
"ruleProviders": {
2
    "LocalAreaNetwork": {
3
        "type": "http",
4
        "format": "yaml",
5
        "interval": 86400,
6
        "behavior": "classical",
7
        "url": "https://raw.githubusercontent.com/tnnevol/ACL4SSR/refs/heads/master/ClashVerge/dist/clash-rules/acl4ssr-online-full/LocalAreaNetwork.txt",
8
        "path": "./ruleset/tnnevol/LocalAreaNetwork.yaml"
9
    },
10
    "BanAD": {
11
        "type": "http",
12
        "format": "yaml",
13
        "interval": 86400,
14
        "behavior": "classical",
15
        "url": "https://raw.githubusercontent.com/tnnevol/ACL4SSR/refs/heads/master/ClashVerge/dist/clash-rules/acl4ssr-online-full/BanAD.txt",
16
        "path": "./ruleset/tnnevol/BanAD.yaml"
17
    }
18
}

展开收起

url：规则集的下载地址，Clash 会定期从这里获取最新的规则文件。
path：规则文件下载后保存的本地路径，Clash 从这里加载规则。
interval：更新间隔（单位秒，这里是 86400 秒，即 24 小时）。
type 和 format：指定规则来源类型（HTTP）和格式（YAML）。

谁提供的？#

这些规则集通常由开源社区或 Clash 用户维护，比如 GitHub 上的项目（如上面的 tnnevol/ACL4SSR）。它们是公开的，任何人都可以使用或贡献规则。

怎么调用？#

在 rules 中，可以通过 RULE-SET 关键字引用这些规则集。例如：

1
- RULE-SET,LocalAreaNetwork,DIRECT
2
- RULE-SET,BanAD,REJECT

RULE-SET：表示引用一个外部规则集。
LocalAreaNetwork：规则集的名称，对应 ruleProviders 中的键名。
DIRECT 或 REJECT：应用到匹配流量的策略（直连或拒绝）。

这表示：

匹配 LocalAreaNetwork 规则集的流量（通常是局域网地址）走直连。
匹配 BanAD 规则集的流量（广告域名）被拒绝连接。

跟自己写的规则有什么区别？#

手动添加的规则：
- 由我自己编写，针对特定需求（比如让某个网站直连）。
- 数量少，维护简单，但功能有限。
ruleProviders 的规则集：
- 由他人提供，规则数量多，覆盖面广（比如广告屏蔽、局域网优化）。
- 通过网络动态更新，省去手动调整的麻烦，但不够灵活。

简单来说，手动规则适合个性化需求，而 ruleProviders 更适合通用场景。

总结#

通过手动添加 IP-CIDR 和 DOMAIN 规则，我成功让特定网站的流量直连，解决了访问受阻的问题。同时，我也搞清楚了 ruleProviders 的作用：它通过外部规则集扩展了 Clash 的功能，让流量管理更省心。

希望这篇文章能帮到有类似困惑的朋友！如果你也遇到网站访问问题，不妨试试手动添加规则，或者利用 ruleProviders 优化你的 Clash 配置。

附录：Clash 规则优先级#

Clash 的规则是从上到下匹配的，顺序很重要：

靠前的规则优先匹配：所以直连规则要放在开头。
默认规则放最后：比如 MATCH,PROXY，作为”兜底”策略处理未匹配的流量。

HuggingFace Spaces部署API服务完整指南

Mon, 24 Mar 2025 00:00:00 GMT

引言#

在当今的开发环境中，拥有自己的API服务已经成为许多项目的必要条件。然而，传统的API部署往往需要服务器资源和相关费用，对于个人开发者或小型项目来说可能是一笔不小的开支。幸运的是，Hugging Face Spaces提供了一个绝佳的解决方案，让我们能够零成本地部署和管理自己的API服务。

Hugging Face Spaces的优势#

使用Hugging Face Spaces部署API有以下几个显著优势：

完全免费：无需支付任何服务器或云服务费用
操作简单：通过图形界面即可完成部署，无需复杂的命令行操作
可靠性高：由Hugging Face提供的稳定基础设施支持
易于分享：每个Space都有唯一的URL，方便与他人共享
社区支持：可以利用Hugging Face庞大的社区资源和已有项目

什么是2api？#

2api（也称为”逆向API”）是一种通过逆向工程将官方网页版服务转换为API形式的技术。以AI服务为例，官方网页对话通常比直接使用官方API更经济实惠，特别是对于大量对话需求的用户。通过2api，你可以将这些网页服务包装成标准API接口，然后接入到自己的程序或网站中，从而大幅降低使用成本。

简单来说，2api让你能够以更低的成本获得与官方API相似的功能，特别适合那些需要频繁调用API但预算有限的开发者和项目。

优秀的2api项目推荐#

以下是两个值得参考的2api项目，你可以基于它们快速部署自己的API服务：

免责声明#

本文推荐的项目仅供学习和研究使用。如果项目所有者认为不应公开分享这些链接，请联系我删除。使用这些项目时，请确保遵守相关服务的使用条款和法律法规。

部署你自己的2api服务#

下面我们将以q2waepnilm为例，详细介绍如何在Hugging Face Spaces上部署自己的2api服务。

步骤一：复制现有Space#

首先，打开上面推荐的q2waepnilm项目链接，在页面右上角找到”Duplicate this Space”按钮，点击将其复制到你自己的账户下。

Img

步骤二：配置基本参数#

复制完成后，你需要填写一些基本配置信息：

API_KEY：这是你将来调用API时需要使用的密钥，可以自定义设置
ACCOUNT_TOKENS：你的账户授权令牌，用于身份验证
API_PREFIX：服务的路径前缀

Img

关于API_PREFIX的说明：

这是你API的路径前缀
不填则为空（例如：http://localhost:3000）
如果填写”/api”，则访问地址为：http://localhost:3000/api

步骤三：确保Space可公开访问#

重要提示：确保将你的Space设置为public（公开），否则将无法获取”Embed this space”选项，也就无法获得直接URL进行API调用。

我的配置示例如下图所示：

Img

步骤四：获取API访问地址#

现在，进入你创建好的Space，点击右上角的”Embed this space”选项：

Img

在弹出的窗口中，你将看到”Direct URL”，这就是你的API服务地址。之后，你可以通过这个URL结合之前设置的API_KEY来调用你的API服务。

管理你的Space#

为了更好地管理你的API服务，你可以通过点击右上角的”Setting”按钮进入设置页面，在这里你可以找到以下重要选项：

Restart this Space：重启你的服务，当遇到问题时可以尝试
Factory rebuild：根据原作者的更新来更新你的项目，确保你始终使用最新版本，避免因不更新导致服务不可用
Change Space visibility：修改空间的可见性（public或private）。注意：如果改为private，你将无法获得Direct URL，也就无法直接调用API

继续下拉页面，你还能找到”Variables and secrets”选项，这里可以修改之前设置的变量和密钥：

Img

总结#

通过Hugging Face Spaces，我们可以轻松实现零成本的API部署。整个过程简单直观，即使是技术小白也能快速上手。你只需要：

复制一个现有的2api项目
配置必要的参数
确保设置为public可见性
获取API访问地址
根据需要管理你的Space

这种方式不仅节省了服务器成本，还大大简化了API部署的技术门槛。希望这篇指南能帮助你快速搭建自己的API服务，为你的项目开发提供便利。

如果你在部署过程中遇到任何问题，可以查阅Hugging Face的官方文档或在社区中寻求帮助。祝你API部署顺利！

Cloudflare域名迁移实战：从us.kg到.xyz

Fri, 21 Mar 2025 00:00:00 GMT

适用范围说明#

本文主要面向已经在 Cloudflare 上成功搭建了服务（如临时邮箱、图床等）的用户，重点讲解如何将这些现有服务从一个域名迁移到另一个域名。文章不涉及服务的初始搭建和配置过程，而是专注于域名变更时的迁移操作。如果你正在寻找如何从零开始搭建这些服务的教程，可能需要参考其他资料。

背景介绍#

:loudspeaker: 重要通知：US.KG 暂停服务及迁移至 DPDNS.ORG

最近我使用的免费 us.kg 域名突然宣布暂停服务，导致我在 Cloudflare 上搭建的临时邮箱和 PicGo 图床都不能用了。作为学生，我不想放弃已经搭建好的服务，所以决定研究如何将所有 Cloudflare 相关服务（DNS 解析、页面规则、WAF 配置等）迁移到新购买的 .xyz 域名上，同时尽量保证服务的连续性。

Cloudflare 的架构设计比较合理，使得这种迁移操作相对简单。下面我将分享我的迁移经验，希望能帮助遇到类似情况的朋友们。

Cloudflare Workers 与域名的关系#

首先需要明确一点：Cloudflare 中的 Worker 是独立于域名管理的。这意味着即使域名失效，你的 Worker 代码和配置仍然存在。你可以通过【域和路由】功能直接添加或删除域名，而不必担心域名变更会导致 Worker 丢失。

这一特性为我们的迁移工作提供了便利，接下来让我们分别看看如何迁移临时邮箱服务和 PicGo 图床。

临时邮箱服务迁移#

临时邮箱服务通常分为前端和后端两部分，我们需要分别处理。

1. 后端迁移#

首先，访问 Cloudflare Workers 后端设置，将服务地址替换为新域名：

Img

同时，需要更新相关环境变量，确保它们指向新域名：

Img

完成上述更改后，还有一个关键步骤：配置邮箱转发功能。这对于临时邮箱服务的正常运行至关重要：

Img

然后确保启用电子邮箱路由：

Img

注意：如果不启用电子邮箱路由，临时邮箱将无法接收邮件，这是服务正常运行的必要条件。

2. 前端迁移#

前端修改不了，因为前端代码通常会硬编码后端 API 的域名。以我的情况为例，原前端固定调用 https://apimail.molii721.us.kg/ 作为后端接口。

由于无法直接修改已部署前端的 API 请求地址，我们需要重新生成并部署前端代码：

访问临时邮箱文档网站：https://temp-mail-docs.awsl.uk/zh/guide/ui/pages
根据新域名重新生成前端代码：

Img

生成代码后，前往 Cloudflare 的 Workers 和 Pages 面板，创建新的 Pages 项目并部署前端代码。

完成这些步骤后，临时邮箱服务就成功迁移到新域名了。

3. 后续版本更新#

迁移完成后，随着项目的迭代，你可能需要更新临时邮箱服务。好消息是，数据库和环境变量等配置无需改动，只需更新后端和前端代码即可。

Img

如上图所示，需要更新的是 Worker 后端代码和 Pages 前端代码，下面分别介绍更新方法。

更新后端代码#

前往 Cloudflare 控制台，进入 Workers 和 Pages 页面，找到你的后端 Worker 项目，点击进入后选择右上方的 编辑代码：

Img

下载最新的 worker.js 代码。你可以访问 https://temp-mail-docs.awsl.uk/zh/guide/ui/worker.html 查看文档说明，或直接点击 https://github.com/dreamhunter2333/cloudflare_temp_email/releases/latest/download/worker.js 下载最新版本。
在编辑器中，先删除原有的 worker.js 文件，然后上传刚下载的新版本，点击部署即可完成后端更新：

Img

更新前端代码#

由于前端代码中硬编码了后端 API 域名，更新前端时需要重新生成代码包。

访问 https://temp-mail-docs.awsl.uk/zh/guide/ui/pages.html ，填写你的域名信息并下载生成的前端代码（具体操作与前文迁移部分相同，此处不再赘述）：

Img

回到 Cloudflare 的 Workers 和 Pages 页面，找到之前部署的前端 Pages 项目并点击进入，选择右上角的 创建部署：
将下载好的前端代码包直接拖入上传区域，点击 保存并部署，等待部署完成即可：
Img

Img

更新完成后，可以在项目详情页看到版本号的变化。以我的项目为例，已从 v1.0.0 成功更新到 v1.2.1。

PicGo 图床迁移#

相比临时邮箱，PicGo 图床的迁移要简单得多，因为它主要依赖于 Cloudflare R2 存储桶，而 R2 存储桶是独立于域名的服务。

迁移步骤如下：

前往 Cloudflare R2 存储桶设置，为存储桶添加新域名的自定义域：

Img

修改 PicGo 客户端中的相关设置，将域名更新为新域名：

Img

由于其他配置（如访问密钥、存储桶名称等）保持不变，只需更新这两处即可完成 PicGo 图床的迁移。

总结#

通过以上步骤，我成功将临时邮箱和 PicGo 图床从 us.kg 域名迁移到了新的 .xyz 域名。整个过程比预想的顺利，主要是因为 Cloudflare 服务的模块化设计。

一开始看到域名失效的通知时有些担心，但实际操作后发现，只要理清各个服务组件之间的关系，迁移过程并不复杂。希望这篇经验分享能帮助到其他遇到类似情况的朋友们。

Spaceship域名购买与Cloudflare托管配置

Fri, 21 Mar 2025 00:00:00 GMT

Spaceship域名购买与Cloudflare托管完全指南#

在建立个人网站或项目时，选择合适的域名注册商和DNS托管服务至关重要。本文将详细介绍如何在Spaceship购买域名，并将其托管到Cloudflare的完整流程。

为什么选择Spaceship？#

在众多域名注册商中，Spaceship具有以下明显优势：

价格便宜，相比其他知名域名注册商更具性价比
不需要经过域名备案，节省了大量时间和繁琐流程
可以通过国内的支付宝支付，交易更加便捷安全

为什么选择Cloudflare托管？#

将域名托管到Cloudflare有诸多好处：

免费的DNS管理服务，操作界面简洁直观
提供免费的CDN加速和DDoS防护，提升网站访问速度和安全性
灵活的DNS记录管理，支持各种记录类型
提供SSL证书，让您的网站支持HTTPS
强大的缓存功能和页面规则，优化网站性能

Spaceship域名购买流程#

第一步：搜索并选择域名#

首先我们前往Spaceship官网登录后，点击Domains选项，在搜索框中输入你想要的域名。

Img

第二步：完成支付#

在选择好域名后，进入支付环节。我选择的是使用支付宝支付，只需按照提示填写好支付信息并绑定支付宝即可。绑定成功后，就可以直接完成支付流程。

第三步：确认购买成功#

购买完成后，我们可以前往Domain Manager查看已购买的域名状态和信息。

Img

Cloudflare域名托管流程#

第一步：添加域名到Cloudflare#

下一步是将域名托管到Cloudflare。首先，前往Cloudflare主页，点击”添加站点”或”添加域”按钮。

Img

第二步：输入域名信息#

在弹出的页面中输入你刚刚在Spaceship购买的域名，然后按照Cloudflare的指引完成初始设置。

第三步：更换名称服务器#

Cloudflare会提供其名称服务器信息，你需要将Spaceship中的默认名称服务器替换为Cloudflare提供的名称服务器。

Img

第四步：在Spaceship中更新DNS设置#

回到Spaceship的控制面板，找到你的域名管理页面，更新名称服务器设置。

Img

第五步：等待DNS生效#

更新名称服务器后，需要等待一段时间让DNS变更生效。通常这个过程需要几分钟到几小时不等。你可以在Cloudflare控制面板查看状态，直到显示域名已成功激活。

Img

将域名绑定到Vercel#

完成Cloudflare托管设置后，如果你使用Vercel部署你的网站或应用，还需要将域名绑定到Vercel项目。这样，访问者就可以通过你的自定义域名访问Vercel上托管的内容。

第一步：进入Vercel项目设置#

首先，登录Vercel账户并进入你的项目仪表板。在左侧导航栏中找到并点击”Domains”选项。

Img

第二步：添加自定义域名#

在Domains页面中，点击”Add”按钮开始添加你的自定义域名。

Img

第三步：配置Vercel授权#

按照Vercel的指引，输入你的域名并完成验证步骤。Vercel会提供必要的DNS记录，你需要确保这些记录已在Cloudflare中正确配置。

Img

第四步：验证域名绑定#

添加完成后，Vercel会自动检查DNS配置是否正确。这个过程可能需要几分钟到几小时不等。一旦验证成功，你的域名就会显示为”Valid”状态，此时访问者就可以通过你的自定义域名访问你的Vercel项目了。

通过以上步骤，你已经成功完成了从Spaceship购买域名，到Cloudflare托管，再到Vercel绑定的全流程配置。现在，你的网站已经拥有了专业的自定义域名，并且同时享受着Cloudflare的安全保护和Vercel的高性能托管服务。

CherryStudio导出话题至Notion配置教程

Mon, 03 Mar 2025 00:00:00 GMT

本文将详细介绍如何将 CherryStudio 中的话题导出到 Notion 数据库。整个过程分为 Notion 端的准备工作和 CherryStudio 的配置两个部分，让我们一步步来完成这个设置。

Notion 端准备工作#

第一步：创建 Notion 数据库#

首先，我们需要在 Notion 中新建一个数据库，用于存储导出的话题：

Img

第二步：获取数据库 ID#

创建数据库后，我们需要获取数据库 ID。点击右上角的”分享”按钮，然后点击”拷贝视图链接”：

Img

复制的链接格式类似：https://www.notion.so/1ab97cff34xxxx6cf2960491ccb3?v=1ab97cffxxxxc7000cbf2a3c2d&pvs=4

其中问号前面的字符串 1ab97cff34xxxx6cf2960491ccb3 就是我们需要的数据库 ID。

第三步：创建和配置 Integration#

接下来，我们需要创建一个 Notion Integration 并获取密钥：

进入 Notion 的集成管理界面：
Img
设置相应的权限（使用默认权限即可）：
Img

在这里，你会看到 Internal Integration Secret，这就是我们后面需要填入 CherryStudio 的 Notion 密钥。

第四步：连接数据库与 Integration#

这一步非常重要 —— 我们需要将刚创建的 Integration 与数据库关联起来：

Img

CherryStudio 配置#

现在我们已经完成了 Notion 端的准备工作，接下来配置 CherryStudio：

在 CherryStudio 中填入以下 Notion 配置信息：
Img
确认页面标题字段名与 Notion 数据库中的字段对应：
Img

测试连接#

完成配置后，我们可以检查连接是否成功：

Img

如果显示连接成功，就可以开始导出话题到 Notion 了：

Img

最后，我们可以在 Notion 中查看导出的内容：

Img

至此，我们就完成了 CherryStudio 导出话题至 Notion 的全部配置过程。你现在可以方便地将 CherryStudio 中的话题同步到 Notion 数据库中了。

Alist+Webdav数据同步配置指南

Thu, 27 Feb 2025 00:00:00 GMT

在日常使用中,我们经常需要在不同设备之间同步和备份数据。Alist 作为一个强大的文件列表程序,结合 Webdav 协议,可以为我们提供一个便捷的数据同步解决方案。本文将详细介绍如何配置和使用 Alist + Webdav 来实现数据同步。

参考资源#

在开始配置之前,这里提供一些有用的参考资源:

Alist 官方的 Webdav 配置指南: https://alist.nn.ci/zh/guide/webdav.html
视频教程参考推荐: https://www.bilibili.com/video/BV16g4y1d7kM/?spm_id_from=333.337.search-card.all.click&vd_source=e03b7988550b29e55118b7d8e6cab3c

官方文档中提供了详细的配置说明:

Img

配置步骤#

1. 创建专用账户#

首先,我们需要在 Alist 管理界面创建一个专门用于 Webdav 管理的用户账户:

Img

2. 设置用户权限#

创建专用账户后，我们需要进行详细的权限配置。这一步对于确保数据安全和使用便利性都很重要。

基础配置#

设置用户名和密码
- 请使用安全性较高的密码
- 这里设置的用户名和密码将用于 Webdav 登录
配置挂载路径
- 挂载路径决定了用户可访问的范围
- 例如：设置为 /sync 则用户只能访问该目录及其子目录
- 建议：根据实际需求设置独立的同步目录，避免暴露其他文件

Img

权限详细说明#

基础访问权限：

隐藏：允许查看隐藏的文件夹
无需密码访问：可以直接访问设置了密码的文件夹

文件操作权限：

创建目录或上传：允许新建文件夹和上传文件
重命名：允许重命名文件和文件夹
移动：允许移动文件位置
复制：允许复制文件
删除：允许删除文件

高级功能权限：

添加离线下载任务：允许创建离线下载任务
Webdav 读取/管理：允许通过 Webdav 协议读取/管理文件
FTP 读取/管理：允许通过 FTP 协议读取/管理文件

权限配置建议#

个人使用场景：
- 建议开启所有文件操作权限
- Webdav 读取和管理权限必须开启
- 其他权限可按需开启
共享使用场景：
- 建议限制删除和移动权限
- 可以开启创建目录和上传权限
- 根据需求限制重命名权限
安全性建议：
- 定期检查和更新权限设置
- 对重要数据所在目录进行单独权限控制
- 建议只开启必要的协议权限（如只用 Webdav 就无需开启 FTP）

3. 客户端配置与使用#

完成 Alist 端的配置后，我们就可以在各类支持 Webdav 协议的软件中进行配置使用了。这里以常见的文件管理器为例：

在客户端中添加网络位置或远程存储：
Img
填写连接信息：

服务器地址：http(s)://your-alist-domain/dav/
用户名：之前创建的专用账户用户名
密码：对应的账户密码

连接成功后，你就可以像使用本地文件夹一样操作 Alist 网盘了：
Img

提示：

确保服务器地址使用完整的 URL，包含 http/https 前缀
地址末尾的 /dav/ 不要遗漏
如果连接失败，请检查用户权限是否正确设置

总结与进阶使用#

至此，我们已经完成了 Alist + Webdav 的基础配置。这套方案不仅完全免费，而且具有以下优势：

支持 Windows、Mac、Linux 等各类平台
可以挂载为本地磁盘，使用体验流畅
支持多用户管理，权限可细粒度控制
可配合第三方软件实现自动备份

对于想要搭建私有云盘又不想花钱的朋友来说，这绝对是一个值得尝试的解决方案。只要按照本文的步骤配置，很快就能享受到便捷的跨设备数据同步服务了。

Clash配置文件完全解析：从订阅到规则分流

Sun, 16 Feb 2025 00:00:00 GMT

文件引用自：https://linux.do/t/topic/424805/17

点击查看完整配置文件

1
// 国内DNS服务器
2
const domesticNameservers = [
3
  "https://223.5.5.5/dns-query", // 阿里DoH
4
  "https://doh.pub/dns-query" // 腾讯DoH，因腾讯云即将关闭免费版IP访问，故用域名
5
];
6
// 国外DNS服务器
7
const foreignNameservers = [
8
  // "https://8.8.4.4/dns-query#ecs=1.1.1.1/24&ecs-override=true", // GoogleDNS
9
  "https://1.1.1.1/dns-query", // CloudflareDNS
10
  // "https://208.67.222.222/dns-query#ecs=1.1.1.1/24&ecs-override=true", // OpenDNS
11
  "https://9.9.9.9/dns-query" //Quad9DNS
12
];
13
// DNS配置
14
const dnsConfig = {
15
  "enable": true,
16
  "listen": "0.0.0.0:1053",
17
  "ipv6": true,
18
  "use-system-hosts": false,
19
  "cache-algorithm": "arc",
20
  "enhanced-mode": "fake-ip",
21
  "fake-ip-range": "198.18.0.1/16",
22
  "fake-ip-filter": [
23
    // 本地主机/设备
24
    "+.lan",
25
    "+.local",
26
    // // Windows网络出现小地球图标
27
    // "+.msftconnecttest.com",
28
    // "+.msftncsi.com",
29
    // QQ快速登录检测失败
30
    "localhost.ptlogin2.qq.com",
31
    "localhost.sec.qq.com",
32
    // 微信快速登录检测失败
33
    "localhost.work.weixin.qq.com"
34
  ],
35
  "default-nameserver": ["https://223.5.5.5/dns-query"],
36
  "nameserver": [...foreignNameservers],
37
  "nameserver-policy": {
38
    "geosite:private,cn": domesticNameservers
39
  }
40
};
41
//分地区
42

43

44
// 规则集通用配置
45
const ruleProviderCommon = {
46
  "type": "http",
47
  "format": "yaml",
48
  "interval": 86400
49
};
50
// 规则集配置
51
const ruleProviders = {
52
  "reject": {
53
    ...ruleProviderCommon,
54
    "behavior": "domain",
55
    "url": "https://fastly.jsdelivr.net/gh/Loyalsoldier/clash-rules@release/reject.txt",
56
    "path": "./ruleset/loyalsoldier/reject.yaml"
57
  },
58
  "icloud": {
59
    ...ruleProviderCommon,
60
    "behavior": "domain",
61
    "url": "https://fastly.jsdelivr.net/gh/Loyalsoldier/clash-rules@release/icloud.txt",
62
    "path": "./ruleset/loyalsoldier/icloud.yaml"
63
  },
64
  "apple": {
65
    ...ruleProviderCommon,
66
    "behavior": "domain",
67
    "url": "https://fastly.jsdelivr.net/gh/Loyalsoldier/clash-rules@release/apple.txt",
68
    "path": "./ruleset/loyalsoldier/apple.yaml"
69
  },
70
  "google": {
71
    ...ruleProviderCommon,
72
    "behavior": "domain",
73
    "url": "https://fastly.jsdelivr.net/gh/Loyalsoldier/clash-rules@release/google.txt",
74
    "path": "./ruleset/loyalsoldier/google.yaml"
75
  },
76
  "telegramcidr": {
77
    ...ruleProviderCommon,
78
    "behavior": "ipcidr",
79
    "url": "https://fastly.jsdelivr.net/gh/Loyalsoldier/clash-rules@release/telegramcidr.txt",
80
    "path": "./ruleset/loyalsoldier/telegramcidr.yaml"
81
  },
82
  "cncidr": {
83
    ...ruleProviderCommon,
84
    "behavior": "ipcidr",
85
    "url": "https://fastly.jsdelivr.net/gh/Loyalsoldier/clash-rules@release/cncidr.txt",
86
    "path": "./ruleset/loyalsoldier/cncidr.yaml"
87
  },
88
  "lancidr": {
89
    ...ruleProviderCommon,
90
    "behavior": "ipcidr",
91
    "url": "https://fastly.jsdelivr.net/gh/Loyalsoldier/clash-rules@release/lancidr.txt",
92
    "path": "./ruleset/loyalsoldier/lancidr.yaml"
93
  },
94
  "applications": {
95
    ...ruleProviderCommon,
96
    "behavior": "classical",
97
    "url": "https://fastly.jsdelivr.net/gh/Loyalsoldier/clash-rules@release/applications.txt",
98
    "path": "./ruleset/loyalsoldier/applications.yaml"
99
  },
100
  "openai": {
101
    ...ruleProviderCommon,
102
    "behavior": "classical",
103
    "url": "https://fastly.jsdelivr.net/gh/blackmatrix7/ios_rule_script@master/rule/Clash/OpenAI/OpenAI.yaml",
104
    "path": "./ruleset/blackmatrix7/openai.yaml"
105
  },
106
  "ehentai": {
107
    ...ruleProviderCommon,
108
    "behavior": "classical",
109
    "url": "https://fastly.jsdelivr.net/gh/v2fly/domain-list-community@master/data/ehentai",
110
    "path": "./ruleset/v2fly/ehentai.yaml"
111
  },
112
  "microsoft": {
113
    ...ruleProviderCommon,
114
    "behavior": "classical",
115
    "url": "https://fastly.jsdelivr.net/gh/v2fly/domain-list-community@master/data/microsoft",
116
    "path": "./ruleset/v2fly/microsoft.yaml"
117
  },
118
  "bing": {
119
    ...ruleProviderCommon,
120
    "behavior": "classical",
121
    "url": "https://fastly.jsdelivr.net/gh/v2fly/domain-list-community@master/data/bing",
122
    "path": "./ruleset/v2fly/bing.yaml"
123
  },
124
  "onedrive": {
125
    ...ruleProviderCommon,
126
    "behavior": "classical",
127
    "url": "https://fastly.jsdelivr.net/gh/v2fly/domain-list-community@master/data/onedrive",
128
    "path": "./ruleset/v2fly/onedrive.yaml"
129
  },
130
  "youtube": {
131
    ...ruleProviderCommon,
132
    "behavior": "classical",
133
    "url": "https://fastly.jsdelivr.net/gh/v2fly/domain-list-community@master/data/youtube",
134
    "path": "./ruleset/v2fly/youtube.yaml"
135
  },
136
  "netflix": {
137
    ...ruleProviderCommon,
138
    "behavior": "classical",
139
    "url": "https://fastly.jsdelivr.net/gh/v2fly/domain-list-community@master/data/netflix",
140
    "path": "./ruleset/v2fly/netflix.yaml"
141
  },
142
  "abema": {
143
    ...ruleProviderCommon,
144
    "behavior": "classical",
145
    "url": "https://fastly.jsdelivr.net/gh/v2fly/domain-list-community@master/data/abema",
146
    "path": "./ruleset/v2fly/abema.yaml"
147
  },
148
  "bahamut": {
149
    ...ruleProviderCommon,
150
    "behavior": "classical",
151
    "url": "https://fastly.jsdelivr.net/gh/v2fly/domain-list-community@master/data/bahamut",
152
    "path": "./ruleset/v2fly/bahamut.yaml"
153
  },
154
  "steam": {
155
    ...ruleProviderCommon,
156
    "behavior": "classical",
157
    "url": "https://fastly.jsdelivr.net/gh/v2fly/domain-list-community@master/data/steam",
158
    "path": "./ruleset/v2fly/steam.yaml"
159
  },
160
  "proxy": {
161
    ...ruleProviderCommon,
162
    "behavior": "domain",
163
    "url": "https://fastly.jsdelivr.net/gh/Loyalsoldier/clash-rules@release/proxy.txt",
164
    "path": "./ruleset/loyalsoldier/proxy.yaml"
165
  },
166
  "direct": {
167
    ...ruleProviderCommon,
168
    "behavior": "domain",
169
    "url": "https://fastly.jsdelivr.net/gh/Loyalsoldier/clash-rules@release/direct.txt",
170
    "path": "./ruleset/loyalsoldier/direct.yaml"
171
  },
172
  "private": {
173
    ...ruleProviderCommon,
174
    "behavior": "domain",
175
    "url": "https://fastly.jsdelivr.net/gh/Loyalsoldier/clash-rules@release/private.txt",
176
    "path": "./ruleset/loyalsoldier/private.yaml"
177
  },
178
  "gfw": {
179
    ...ruleProviderCommon,
180
    "behavior": "domain",
181
    "url": "https://fastly.jsdelivr.net/gh/Loyalsoldier/clash-rules@release/gfw.txt",
182
    "path": "./ruleset/loyalsoldier/gfw.yaml"
183
  },
184
  "tld-not-cn": {
185
    ...ruleProviderCommon,
186
    "behavior": "domain",
187
    "url": "https://fastly.jsdelivr.net/gh/Loyalsoldier/clash-rules@release/tld-not-cn.txt",
188
    "path": "./ruleset/loyalsoldier/tld-not-cn.yaml"
189
  },
190
};
191
// 规则
192
const rules = [
193
  // 额外自定义规则       //在此添加你想要的规则
194
  "PROCESS-NAME,steam.exe,🎮 Steam",
195
  "DOMAIN,v2.ixlmo.net,🔗 Global Direct",
196
  // 自定义规则
197
  "DOMAIN-SUFFIX,googleapis.cn,⚙️ Node Select", // Google服务
198
  "DOMAIN-SUFFIX,gstatic.com,⚙️ Node Select", // Google静态资源
199
  "DOMAIN-SUFFIX,xn--ngstr-lra8j.com,⚙️ Node Select", // Google Play下载服务
200
  "DOMAIN-SUFFIX,github.io,⚙️ Node Select", // Github Pages
201
  "DOMAIN,v2rayse.com,⚙️ Node Select", // V2rayse节点工具
202
  //Bilibili 港澳台
203
  "DOMAIN,p-bstarstatic.akamaized.net,📺 BilibiliHMT",
204
  "DOMAIN,p.bstarstatic.com,📺 BilibiliHMT",
205
  "DOMAIN,upos-bstar-mirrorakam.akamaized.net,📺 BilibiliHMT",
206
  "DOMAIN,upos-bstar1-mirrorakam.akamaized.net,📺 BilibiliHMT",
207
  "DOMAIN,upos-hz-mirrorakam.akamaized.net,📺 BilibiliHMT",
208
  // blackmatrix7 规则集
209
  "RULE-SET,openai,💸 ChatGPT",
210
  // Loyalsoldier 规则集
211
  "RULE-SET,applications,🔗 Global Direct",
212
  "RULE-SET,private,🔗 Global Direct",
213
  "RULE-SET,reject,🥰 AdBlock",
214
  "RULE-SET,icloud,🍎 iCloud",
215
  "RULE-SET,apple,🍎 Apple",
216
  "RULE-SET,google,📢 Google",
217
  "RULE-SET,telegramcidr,📲 Telegram,no-resolve",
218
  "RULE-SET,ehentai,🐼 E-Hentai,no-resolve",
219
  "RULE-SET,microsoft,Ⓜ️ Microsoft,no-resolve",
220
  "RULE-SET,bing,Ⓜ️ Bing,no-resolve",
221
  "RULE-SET,onedrive,Ⓜ️ Onedrive,no-resolve",
222
  "RULE-SET,youtube,📹 Youtube,no-resolve",
223
  "RULE-SET,netflix,🎥 Netflix,no-resolve",
224
  "RULE-SET,bahamut,📺 Bahamut,no-resolve",
225
  "RULE-SET,abema,📺 Abema,no-resolve",
226
  "RULE-SET,steam,🎮 Steam,no-resolve",
227
  "RULE-SET,proxy,⚙️ Node Select",
228
  "RULE-SET,gfw,⚙️ Node Select",
229
  "RULE-SET,tld-not-cn,⚙️ Node Select",
230
  "RULE-SET,direct,🔗 Global Direct",
231
  "RULE-SET,lancidr,🔗 Global Direct,no-resolve",
232
  "RULE-SET,cncidr,🔗 Global Direct,no-resolve",
233
  // 其他规则
234
  "GEOIP,LAN,🔗 Global Direct,no-resolve",
235
  "GEOIP,CN,🔗 Global Direct,no-resolve",
236
  "MATCH,🐟 Others"
237
];
238
// 代理组通用配置
239
const groupBaseOption = {
240
  "interval": 300,
241
  "timeout": 3000,
242
  "url": "https://www.google.com/generate_204",
243
  "lazy": true,
244
  "max-failed-times": 3,
245
  "hidden": false
246
};
247

248
// 程序入口
249
function main(config) {
250
  const proxyCount = config?.proxies?.length ?? 0;
251
  const proxyProviderCount =
252
    typeof config?.["proxy-providers"] === "object" ? Object.keys(config["proxy-providers"]).length : 0;
253
  if (proxyCount === 0 && proxyProviderCount === 0) {
254
    throw new Error("配置文件中未找到任何代理");
255
  }
256

257
  // 覆盖原配置中DNS配置
258
  config["dns"] = dnsConfig;
259

260
  // 覆盖原配置中的代理组
261
  config["proxy-groups"] = [
262
    {
263
      ...groupBaseOption,
264
      "name": "⚙️ Node Select",
265
      "type": "select",
266
      "proxies": ["♻️ Latency Tuning", "🚑 Fallback", "⚖️ Load Balance(Hashing)", "☁️ Load Balance(Round Robin)", "🇭🇰Hong Kong", "🇯🇵Japan", "🇰🇷Korea", "🇸🇬Singapore", "🇨🇳Taiwan", "🇺🇸United States", "🇬🇧United Kingdom"],
267
      "include-all": true,
268
      "icon": "https://fastly.jsdelivr.net/gh/clash-verge-rev/clash-verge-rev.github.io@main/docs/assets/icons/adjust.svg"
269
    },
270
    {
271
      ...groupBaseOption,
272
      "name": "♻️ Latency Tuning",
273
      "type": "url-test",
274
      "tolerance": 50,
275
      "include-all": true,
276
      "icon": "https://fastly.jsdelivr.net/gh/clash-verge-rev/clash-verge-rev.github.io@main/docs/assets/icons/speed.svg"
277
    },
278
    {
279
      ...groupBaseOption,
280
      "name": "🚑 Fallback",
281
      "type": "fallback",
282
      "include-all": true,
283
      "icon": "https://fastly.jsdelivr.net/gh/clash-verge-rev/clash-verge-rev.github.io@main/docs/assets/icons/ambulance.svg"
284
    },
285
    {
286
      ...groupBaseOption,
287
      "name": "⚖️ Load Balance(Hashing)",
288
      "type": "load-balance",
289
      "strategy": "consistent-hashing",
290
      "include-all": true,
291
      "icon": "https://fastly.jsdelivr.net/gh/clash-verge-rev/clash-verge-rev.github.io@main/docs/assets/icons/merry_go.svg"
292
    },
293
    {
294
      ...groupBaseOption,
295
      "name": "☁️ Load Balance(Round Robin)",
296
      "type": "load-balance",
297
      "strategy": "round-robin",
298
      "include-all": true,
299
      "icon": "https://fastly.jsdelivr.net/gh/clash-verge-rev/clash-verge-rev.github.io@main/docs/assets/icons/balance.svg"
300
    },
301
    {
302
      ...groupBaseOption,
303
      "name": "🇭🇰Hong Kong",
304
      "type": "select",
305
      "include-all": true,
306
      "filter": "(?i)港|🇭🇰|hk|hongkong|hong kong",
307
      "icon": "https://fastly.jsdelivr.net/gh/clash-verge-rev/clash-verge-rev.github.io@main/docs/assets/icons/flags/hk.svg"
308
    },
309
    {
310
      ...groupBaseOption,
311
      "name": "🇯🇵Japan",
312
      "type": "select",
313
      "include-all": true,
314
      "filter": "(?i)日本|🇯🇵|jp|japan",
315
      "icon": "https://fastly.jsdelivr.net/gh/clash-verge-rev/clash-verge-rev.github.io@main/docs/assets/icons/flags/jp.svg"
316
    },
317
    {
318
      ...groupBaseOption,
319
      "name": "🇰🇷Korea",
320
      "type": "select",
321
      "include-all": true,
322
      "filter": "(?i)韩|🇰🇷|kr|korea",
323
      "icon": "https://fastly.jsdelivr.net/gh/clash-verge-rev/clash-verge-rev.github.io@main/docs/assets/icons/flags/kr.svg"
324
    },
325
    {
326
      ...groupBaseOption,
327
      "name": "🇸🇬Singapore",
328
      "type": "select",
329
      "include-all": true,
330
      "filter": "(?i)新加坡|🇸🇬|sg|singapore",
331
      "icon": "https://fastly.jsdelivr.net/gh/clash-verge-rev/clash-verge-rev.github.io@main/docs/assets/icons/flags/sg.svg"
332
    },
333
    {
334
      ...groupBaseOption,
335
      "name": "🇨🇳Taiwan",
336
      "type": "select",
337
      "include-all": true,
338
      "filter": "(?i)台湾|🇹🇼|tw|taiwan|tai wan",
339
      "icon": "https://fastly.jsdelivr.net/gh/clash-verge-rev/clash-verge-rev.github.io@main/docs/assets/icons/flags/cn.svg"
340
    },
341
    {
342
      ...groupBaseOption,
343
      "name": "🇺🇸United States",
344
      "type": "select",
345
      "include-all": true,
346
      "filter": "(?i)美|🇺🇸|us|united state|america",
347
      "icon": "https://fastly.jsdelivr.net/gh/clash-verge-rev/clash-verge-rev.github.io@main/docs/assets/icons/flags/us.svg"
348
    },
349
    {
350
      ...groupBaseOption,
351
      "name": "🇬🇧United Kingdom",
352
      "type": "select",
353
      "include-all": true,
354
      "filter": "(?i)英|🇬🇧|uk|united kingdom|great britain",
355
      "icon": "https://fastly.jsdelivr.net/gh/clash-verge-rev/clash-verge-rev.github.io@main/docs/assets/icons/flags/gb.svg"
356
    },
357
    {
358
      ...groupBaseOption,
359
      "name": "📢 Google",
360
      "type": "select",
361
      "proxies": ["⚙️ Node Select", "♻️ Latency Tuning", "🚑 Fallback", "⚖️ Load Balance(Hashing)", "☁️ Load Balance(Round Robin)", "🔗 Global Direct", "🇭🇰Hong Kong", "🇯🇵Japan", "🇰🇷Korea", "🇸🇬Singapore", "🇨🇳Taiwan", "🇺🇸United States", "🇬🇧United Kingdom"],
362
      "include-all": true,
363
      "icon": "https://fastly.jsdelivr.net/gh/clash-verge-rev/clash-verge-rev.github.io@main/docs/assets/icons/google.svg"
364
    },
365
    {
366
      ...groupBaseOption,
367
      "name": "📲 Telegram",
368
      "type": "select",
369
      "proxies": ["⚙️ Node Select", "♻️ Latency Tuning", "🚑 Fallback", "⚖️ Load Balance(Hashing)", "☁️ Load Balance(Round Robin)", "🔗 Global Direct", "🇭🇰Hong Kong", "🇯🇵Japan", "🇰🇷Korea", "🇸🇬Singapore", "🇨🇳Taiwan", "🇺🇸United States", "🇬🇧United Kingdom"],
370
      "include-all": true,
371
      "icon": "https://fastly.jsdelivr.net/gh/clash-verge-rev/clash-verge-rev.github.io@main/docs/assets/icons/telegram.svg"
372
    },
373
    {
374
    ...groupBaseOption,
375
      "name": "🐼 E-Hentai",
376
      "type": "select",
377
      "proxies": ["⚙️ Node Select", "♻️ Latency Tuning", "🚑 Fallback", "⚖️ Load Balance(Hashing)", "☁️ Load Balance(Round Robin)", "🔗 Global Direct", "🇭🇰Hong Kong", "🇯🇵Japan", "🇰🇷Korea", "🇸🇬Singapore", "🇨🇳Taiwan", "🇺🇸United States", "🇬🇧United Kingdom"],
378
      "include-all": true,
379
      "icon": "https://e-hentai.org/favicon.ico"
380
    },
381
    {
382
    ...groupBaseOption,
383
      "name": "Ⓜ️ Microsoft",
384
      "type": "select",
385
      "proxies": ["⚙️ Node Select", "♻️ Latency Tuning", "🚑 Fallback", "⚖️ Load Balance(Hashing)", "☁️ Load Balance(Round Robin)", "🔗 Global Direct", "🇭🇰Hong Kong", "🇯🇵Japan", "🇰🇷Korea", "🇸🇬Singapore", "🇨🇳Taiwan", "🇺🇸United States", "🇬🇧United Kingdom"],
386
      "include-all": true,
387
      "icon": "https://fastly.jsdelivr.net/gh/clash-verge-rev/clash-verge-rev.github.io@main/docs/assets/icons/microsoft.svg"
388
    },
389
    {
390
    ...groupBaseOption,
391
      "name": "Ⓜ️ Bing",
392
      "type": "select",
393
      "proxies": ["⚙️ Node Select", "♻️ Latency Tuning", "🚑 Fallback", "⚖️ Load Balance(Hashing)", "☁️ Load Balance(Round Robin)", "🔗 Global Direct", "🇭🇰Hong Kong", "🇯🇵Japan", "🇰🇷Korea", "🇸🇬Singapore", "🇨🇳Taiwan", "🇺🇸United States", "🇬🇧United Kingdom"],
394
      "include-all": true,
395
      "icon": "https://fastly.jsdelivr.net/gh/clash-verge-rev/clash-verge-rev.github.io@main/docs/assets/icons/bing.svg"
396
    },
397
    {
398
    ...groupBaseOption,
399
      "name": "Ⓜ️ Onedrive",
400
      "type": "select",
401
      "proxies": ["⚙️ Node Select", "♻️ Latency Tuning", "🚑 Fallback", "⚖️ Load Balance(Hashing)", "☁️ Load Balance(Round Robin)", "🔗 Global Direct", "🇭🇰Hong Kong", "🇯🇵Japan", "🇰🇷Korea", "🇸🇬Singapore", "🇨🇳Taiwan", "🇺🇸United States", "🇬🇧United Kingdom"],
402
      "include-all": true,
403
      "icon": "https://fastly.jsdelivr.net/gh/clash-verge-rev/clash-verge-rev.github.io@main/docs/assets/icons/microsoft.svg"
404
    },
405
    {
406
    ...groupBaseOption,
407
      "name": "📹 Youtube",
408
      "type": "select",
409
      "proxies": ["⚙️ Node Select", "♻️ Latency Tuning", "🚑 Fallback", "⚖️ Load Balance(Hashing)", "☁️ Load Balance(Round Robin)", "🔗 Global Direct", "🇭🇰Hong Kong", "🇯🇵Japan", "🇰🇷Korea", "🇸🇬Singapore", "🇨🇳Taiwan", "🇺🇸United States", "🇬🇧United Kingdom"],
410
      "include-all": true,
411
      "icon": "https://fastly.jsdelivr.net/gh/clash-verge-rev/clash-verge-rev.github.io@main/docs/assets/icons/youtube.svg"
412
    },
413
    {
414
    ...groupBaseOption,
415
      "name": "🎥 Netflix",
416
      "type": "select",
417
      "proxies": ["⚙️ Node Select", "♻️ Latency Tuning", "🚑 Fallback", "⚖️ Load Balance(Hashing)", "☁️ Load Balance(Round Robin)", "🔗 Global Direct", "🇭🇰Hong Kong", "🇯🇵Japan", "🇰🇷Korea", "🇸🇬Singapore", "🇨🇳Taiwan", "🇺🇸United States", "🇬🇧United Kingdom"],
418
      "include-all": true,
419
      "icon": "https://fastly.jsdelivr.net/gh/clash-verge-rev/clash-verge-rev.github.io@main/docs/assets/icons/netflix.svg"
420
    },
421
    {
422
    ...groupBaseOption,
423
      "name": "📺 Bahamut",
424
      "type": "select",
425
      "proxies": ["⚙️ Node Select", "♻️ Latency Tuning", "🚑 Fallback", "⚖️ Load Balance(Hashing)", "☁️ Load Balance(Round Robin)", "🔗 Global Direct", "🇭🇰Hong Kong", "🇯🇵Japan", "🇰🇷Korea", "🇸🇬Singapore", "🇨🇳Taiwan", "🇺🇸United States", "🇬🇧United Kingdom"],
426
      "include-all": true,
427
      "icon": "https://www.gamer.com.tw/favicon.ico"
428
    },
429
    {
430
    ...groupBaseOption,
431
      "name": "📺 Abema",
432
      "type": "select",
433
      "proxies": ["⚙️ Node Select", "♻️ Latency Tuning", "🚑 Fallback", "⚖️ Load Balance(Hashing)", "☁️ Load Balance(Round Robin)", "🔗 Global Direct", "🇭🇰Hong Kong", "🇯🇵Japan", "🇰🇷Korea", "🇸🇬Singapore", "🇨🇳Taiwan", "🇺🇸United States", "🇬🇧United Kingdom"],
434
      "include-all": true,
435
      "icon": "https://abema.tv/favicon.ico"
436
    },
437
    {
438
    ...groupBaseOption,
439
      "name": "📺 BilibiliHMT",
440
      "type": "select",
441
      "proxies": ["⚙️ Node Select", "♻️ Latency Tuning", "🚑 Fallback", "⚖️ Load Balance(Hashing)", "☁️ Load Balance(Round Robin)", "🔗 Global Direct", "🇭🇰Hong Kong", "🇯🇵Japan", "🇰🇷Korea", "🇸🇬Singapore", "🇨🇳Taiwan", "🇺🇸United States", "🇬🇧United Kingdom"],
442
      "include-all": true,
443
      "icon": "https://bilibili.com/favicon.ico"
444
    },
445
    {
446
    ...groupBaseOption,
447
      "name": "🎮 Steam",
448
      "type": "select",
449
      "proxies": ["🔗 Global Direct", "⚙️ Node Select", "♻️ Latency Tuning", "🚑 Fallback", "⚖️ Load Balance(Hashing)", "☁️ Load Balance(Round Robin)", "🇭🇰Hong Kong", "🇯🇵Japan", "🇰🇷Korea", "🇸🇬Singapore", "🇨🇳Taiwan", "🇺🇸United States", "🇬🇧United Kingdom"],
450
      "include-all": true,
451
      "icon": "https://fastly.jsdelivr.net/gh/clash-verge-rev/clash-verge-rev.github.io@main/docs/assets/icons/steam.svg"
452
    },
453
    {
454
      ...groupBaseOption,
455
      "url": "https://chatgpt.com",
456
      "expected-status": "200",
457
      "name": "💸 ChatGPT",
458
      "type": "select",
459
      "proxies": ["⚙️ Node Select", "♻️ Latency Tuning", "🚑 Fallback", "⚖️ Load Balance(Hashing)", "☁️ Load Balance(Round Robin)", "🔗 Global Direct", "🇭🇰Hong Kong", "🇯🇵Japan", "🇰🇷Korea", "🇸🇬Singapore", "🇨🇳Taiwan", "🇺🇸United States", "🇬🇧United Kingdom"],
460
      "include-all": true,
461
      "exclude-filter": "(?i)港|hk|hongkong|hong kong|俄|ru|russia|澳|macao",
462
      "icon": "https://fastly.jsdelivr.net/gh/clash-verge-rev/clash-verge-rev.github.io@main/docs/assets/icons/chatgpt.svg"
463
    },
464
    {
465
      ...groupBaseOption,
466
      "name": "🍎 iCloud",
467
      "type": "select",
468
      "proxies": ["⚙️ Node Select", "🔗 Global Direct", "♻️ Latency Tuning", "🚑 Fallback", "⚖️ Load Balance(Hashing)", "☁️ Load Balance(Round Robin)", "🇭🇰Hong Kong", "🇯🇵Japan", "🇰🇷Korea", "🇸🇬Singapore", "🇨🇳Taiwan", "🇺🇸United States", "🇬🇧United Kingdom"],
469
      "include-all": true,
470
      "icon": "https://fastly.jsdelivr.net/gh/clash-verge-rev/clash-verge-rev.github.io@main/docs/assets/icons/apple.svg"
471
    },
472
    {
473
      ...groupBaseOption,
474
      "name": "🍎 Apple",
475
      "type": "select",
476
      "proxies": ["⚙️ Node Select", "♻️ Latency Tuning", "🚑 Fallback", "⚖️ Load Balance(Hashing)", "☁️ Load Balance(Round Robin)", "🔗 Global Direct", "🇭🇰Hong Kong", "🇯🇵Japan", "🇰🇷Korea", "🇸🇬Singapore", "🇨🇳Taiwan", "🇺🇸United States", "🇬🇧United Kingdom"],
477
      "include-all": true,
478
      "icon": "https://fastly.jsdelivr.net/gh/clash-verge-rev/clash-verge-rev.github.io@main/docs/assets/icons/apple.svg"
479
    },
480
    {
481
      ...groupBaseOption,
482
      "name": "🥰 AdBlock",
483
      "type": "select",
484
      "proxies": ["REJECT", "DIRECT"],
485
      "icon": "https://fastly.jsdelivr.net/gh/clash-verge-rev/clash-verge-rev.github.io@main/docs/assets/icons/bug.svg"
486
    },
487
    {
488
      ...groupBaseOption,
489
      "name": "🔗 Global Direct",
490
      "type": "select",
491
      "proxies": ["DIRECT", "⚙️ Node Select", "♻️ Latency Tuning", "🚑 Fallback", "⚖️ Load Balance(Hashing)", "☁️ Load Balance(Round Robin)", "🇭🇰Hong Kong", "🇯🇵Japan", "🇰🇷Korea", "🇸🇬Singapore", "🇨🇳Taiwan", "🇺🇸United States", "🇬🇧United Kingdom"],
492
      "include-all": true,
493
      "icon": "https://fastly.jsdelivr.net/gh/clash-verge-rev/clash-verge-rev.github.io@main/docs/assets/icons/link.svg"
494
    },
495
    {
496
      ...groupBaseOption,
497
      "name": "❌ Global Reject",
498
      "type": "select",
499
      "proxies": ["REJECT", "DIRECT"],
500
      "icon": "https://fastly.jsdelivr.net/gh/clash-verge-rev/clash-verge-rev.github.io@main/docs/assets/icons/block.svg"
501
    },
502
    {
503
      ...groupBaseOption,
504
      "name": "🐬 Custom Direct",
505
      "type": "select",
506
      "proxies": ["🔗 Global Direct", "⚙️ Node Select", "♻️ Latency Tuning", "🚑 Fallback", "⚖️ Load Balance(Hashing)", "☁️ Load Balance(Round Robin)", "🇭🇰Hong Kong", "🇯🇵Japan", "🇰🇷Korea", "🇸🇬Singapore", "🇨🇳Taiwan", "🇺🇸United States", "🇬🇧United Kingdom"],
507
      "icon": "https://fastly.jsdelivr.net/gh/clash-verge-rev/clash-verge-rev.github.io@main/docs/assets/icons/unknown.svg"
508
    },
509
    {
510
      ...groupBaseOption,
511
      "name": "🐳 Custom Proxy",
512
      "type": "select",
513
      "include-all": true,
514
      "proxies": ["⚙️ Node Select", "♻️ Latency Tuning", "🚑 Fallback", "⚖️ Load Balance(Hashing)", "☁️ Load Balance(Round Robin)", "🔗 Global Direct", "🇭🇰Hong Kong", "🇯🇵Japan", "🇰🇷Korea", "🇸🇬Singapore", "🇨🇳Taiwan", "🇺🇸United States", "🇬🇧United Kingdom"],
515
      "icon": "https://fastly.jsdelivr.net/gh/clash-verge-rev/clash-verge-rev.github.io@main/docs/assets/icons/openwrt.svg"
516
    },
517
    {
518
      ...groupBaseOption,
519
      "name": "🐟 Others",
520
      "type": "select",
521
      "proxies": ["⚙️ Node Select", "♻️ Latency Tuning", "🚑 Fallback", "⚖️ Load Balance(Hashing)", "☁️ Load Balance(Round Robin)", "🔗 Global Direct", "🇭🇰Hong Kong", "🇯🇵Japan", "🇰🇷Korea", "🇸🇬Singapore", "🇨🇳Taiwan", "🇺🇸United States", "🇬🇧United Kingdom"],
522
      "include-all": true,
523
      "icon": "https://fastly.jsdelivr.net/gh/clash-verge-rev/clash-verge-rev.github.io@main/docs/assets/icons/fish.svg"
524
    }
525
  ];
526

527
  // 覆盖原配置中的规则
528
  config["rule-providers"] = ruleProviders;
529
  config["rules"] = rules;
530
  config["proxies"].forEach(proxy => {
531
    // 为每个节点设置 udp = true
532
    proxy.udp = true
533
  })
534
  // 返回修改后的配置
535
  return config;
536
}

展开收起

你是否好奇过,当你点击一个 YouTube 视频时,数据包是如何通过代理服务器传输的?或者为什么有时候某些网站特别慢,而换个节点就变快了?这篇文章将为你揭开 Clash 配置文件的神秘面纱,用最通俗的语言解释它是如何工作的。

我们会按照以下顺序,循序渐进地了解整个过程:

配置文件是什么,它在整个代理过程中扮演什么角色
如何从订阅链接获取可用的代理服务器
DNS 配置如何帮助你更快地访问网站
规则如何决定你的访问请求走什么路径
代理组是如何管理和分发节点的
实际案例<访问> YouTube 的全过程

Clash 配置文件详解：从订阅节点到转发 YouTube 流量#

想象一下,配置文件就像是一本”说明书”,它告诉 Clash 该如何处理你的网络请求<该用哪个服务器>、要不要加速、是否要绕过某些网站等。本文将带你一步步理解这本”说明书”的内容,让你明白当你浏览网页时,数据包是如何被智能处理的。

1. 配置文件整体介绍#

如果把 Clash 比作一个快递公司,那么这份配置文件就是快递分拣的规则手册。它告诉快递员(Clash)：

这个包裹(网络请求)要送到哪里
用什么路线最快(代理节点)
特殊包裹要如何处理(规则)
在哪些情况下需要绕路(分流)

这份配置文件使用 JavaScript 编写,主要完成以下工作:

检查你是否有可用的快递员(代理节点)
设置导航系统(DNS 配置)
制定派送路线(规则集和规则)
组建快递小组(代理组)
确保所有快递员都能处理特殊包裹(UDP 设置)

2. 如何获取订阅链接中的节点#

订阅链接就像是一份快递员名单,里面包含了所有可以帮你送货的快递员信息(服务器地址、端口等)。当你在 Clash 中输入这个链接时,它会自动解析出所有可用的快递员。

让我们看看配置文件是如何处理这个名单的:

1
const proxyCount = config?.proxies?.length ?? 0;
2
const proxyProviderCount = typeof config?.["proxy-providers"] === "object" ? Object.keys(config["proxy-providers"]).length : 0;
3
if (proxyCount === 0 && proxyProviderCount === 0) {
4
  throw new Error("配置文件中未找到任何代理");
5
}

这段代码就是在检查:

是否有直接可用的快递员(proxies)
是否有可以联系到的快递公司(proxy-providers)
如果两个都没有,就报错说”没有找到快递员”

当你导入订阅链接后,这些节点会被自动分配到不同的快递小组中(代理组)。配置文件中的 include-all: true 表示所有快递员都可以加入对应的小组。

3. DNS 配置与网站识别：以 YouTube 为例#

DNS 是什么？#

DNS（域名解析系统）就像是互联网世界的”导航地图”。当你想访问一个网站时，DNS 会告诉你这个网站具体在哪里（IP地址）。

为什么需要特别配置 DNS？#

想象你要寄两个包裹：

一个寄往北京（国内网站）
一个寄往纽约（国外网站）

你会发现：

问国内快递员北京地址 → 准确快速
问国内快递员纽约地址 → 可能不准确或找不到

所以我们需要：

国内地址 → 问国内快递员
国外地址 → 问国际快递员

DNS 配置示例#

1
dns:
2
  enable: true
3
  enhanced-mode: "fake-ip"
4
  nameserver: # 国内 DNS 服务器
5
    - https://dns.alidns.com/dns-query # 阿里 DNS
6
    - https://doh.pub/dns-query        # DNSPod DNS
7

8
  fallback: # 国外 DNS 服务器
9
    - https://1.1.1.1/dns-query        # Cloudflare DNS
10
    - https://9.9.9.9/dns-query        # Quad9 DNS
11

12
  fallback-filter: # 识别规则
13
    geoip: true    # 使用地理位置数据库
14
    ipcidr:        # IP 地址范围
15
      - 240.0.0.0/4

展开收起

如何识别国内外网站？#

以访问 YouTube 为例，让我们看看完整的识别和解析过程：

域名规则匹配

1
rules:
2
  - DOMAIN-SUFFIX,youtube.com,📹 Youtube
3
  - DOMAIN-SUFFIX,googlevideo.com,📹 Youtube

Clash 发现访问的是 youtube.com
匹配到上述规则，确定是 YouTube 服务

规则集验证

1
rule-providers:
2
  youtube:
3
    type: http
4
    behavior: domain
5
    url: "https://raw.githubusercontent.com/Loyalsoldier/clash-rules/release/youtube.txt"

查询规则集确认这是 YouTube 相关域名
规则集中包含了完整的 YouTube 域名列表

GeoSite 数据库查询

1
rules:
2
  - GEOSITE,youtube,📹 Youtube

通过 GeoSite 数据库再次确认
数据库显示这是国外网站

选择合适的 DNS

因为确定是国外网站
使用 fallback 中的国外 DNS（1.1.1.1 或 9.9.9.9）
避免使用可能被污染的国内 DNS

实际工作流程#

当你在浏览器输入 youtube.com 时：

请求捕获
- Clash 截获访问请求
- 提取域名 youtube.com
网站识别
- 通过规则匹配识别为 YouTube
- 确定是国外网站
- 需要使用代理访问
DNS 解析
- 自动切换到国外 DNS（如 Cloudflare 1.1.1.1）
- 获取 YouTube 的真实 IP 地址
- 避免 DNS 污染问题
建立连接
- 使用解析到的 IP 地址
- 通过选定的代理节点访问

这样的设计确保了：

国内网站用国内 DNS → 访问更快
国外网站用国外 DNS → 解析更准确
自动识别和切换 → 体验更流畅

就像有两个导航系统：

国内导航 → 熟悉国内的路
国外导航 → 了解国外的路
系统自动选择合适的导航 → 永远不会迷路

4. 规则集和规则：如何让 Clash 知道该走哪条路#

想象一下，Clash 就像一个智能的交通指挥官，需要知道不同的网站该走什么路。规则集就是他手中的”指挥手册”，告诉他该如何分配这些网络流量。

规则集是什么？#

简单来说，规则集就是一个清单，告诉 Clash：

哪些网站需要代理（比如 YouTube、Google）
哪些网站直接访问（比如淘宝、百度）
每个网站该使用什么样的连接方式

就像快递公司的分拣指南：

国内包裹走普通快递
国际包裹走国际快递
特殊物品走特殊渠道

规则集是如何工作的？#

配置文件通过 ruleProviders 来管理这些规则集：

1
// 以 YouTube 为例
2
"RULE-SET,youtube,📹 Youtube,no-resolve"

这行配置的意思是：

发现 YouTube 相关的网址
交给 ”📹 Youtube” 这个代理组处理
不需要额外的地址解析（no-resolve）

为什么要这样设计？#

这种设计有几个好处：

自动更新
- 规则集会定期从网上下载最新版本
- 就像导航软件会更新最新的路况信息
模块化管理
- 不同类型的网站有不同的规则集
- 就像快递公司对不同类型的包裹有不同的处理方式
便于维护
- 规则变化时只需更新规则集
- 用户不需要手动修改配置

实际工作流程#

当你访问 YouTube 时：

识别网站
- Clash 看到你访问的是 youtube.com
- 查找规则集，发现这是 YouTube 相关网站
选择路线
- 根据规则找到对应的代理组（📹 Youtube）
- 在代理组中选择合适的节点
建立连接
- 通过选定的节点访问 YouTube
- 确保视频能够流畅播放

就像快递系统：

收到包裹（网络请求）
查看目的地（网站域名）
选择合适的快递员（代理节点）
送达目的地（访问网站）

5. 代理组：Clash 的智能调度系统#

代理组就像是不同的快递小组，每个小组都有自己的特长：

手动选择组（select 类型）
- 自己选择想用的节点
- 就像指定特定的快递员
自动测速组（url-test 类型）
- 自动选择最快的节点
- 就像系统自动分配最空闲的快递员
故障转移组（fallback 类型）
- 当前节点出问题自动换下一个
- 就像快递员请假有替补上岗
负载均衡组（load-balance 类型）
- 在多个节点之间分配流量
- 就像多个快递员合作送同一个区域

每个代理组都可以设置：

包含哪些节点（proxies）
是否包含所有节点（include-all）
使用什么策略（type）

这样的设计确保了：

网络访问稳定可靠
自动选择最佳路线
出现问题能够自动处理

6. 流量转发全过程：当你点开 YouTube 视频时发生了什么？#

让我们通过实际的配置代码，一步步看看当你访问 YouTube 时，Clash 是如何工作的。

第一步：DNS 解析#

首先看看 DNS 配置:

1
// 国外DNS服务器
2
const foreignNameservers = [
3
"https://1.1.1.1/dns-query", // CloudflareDNS
4
"https://9.9.9.9/dns-query" // Quad9DNS
5
];

当你输入 youtube.com 时:

Clash 捕获到这个域名
发现是国外网站，使用 foreignNameservers
通过 CloudflareDNS 或 Quad9DNS 解析出真实 IP

这就像在国外找房子，要问当地的人才知道准确地址。

第二步：规则匹配#

看看 YouTube 的规则配置:

1
{
2
...groupBaseOption,
3
"name": "📹 Youtube",
4
"type": "select",
5
"proxies": ["⚙️ Node Select", "♻️ Latency Tuning", "🚑 Fallback", "⚖️ Load Balance(Hashing)", "☁️ Load Balance(Round Robin)", "🔗 Global Direct", "🇭🇰Hong Kong", "🇯🇵Japan", "🇰🇷Korea", "🇸🇬Singapore", "🇨🇳Taiwan", "🇺🇸United States", "🇬🇧United Kingdom"],
6
"include-all": true,
7
"icon": "https://fastly.jsdelivr.net/gh/clash-verge-rev/clash-verge-rev.github.io@main/docs/assets/icons/youtube.svg"
8
}

节点选择过程:

可以手动选择特定地区节点
或使用自动策略:
- ♻️ 自动选择延迟最低的节点
- 🚑 当前节点故障自动切换
- ⚖️ 在多个节点间平衡分配

就像有多个快递员，可以:

指定特定快递员送货
让系统自动选择最快的
或者多个快递员轮流送

第四步：流量转发#

最后看看节点配置:

1
config["proxies"].forEach(proxy => {
2
// 为每个节点设置 udp = true
3
proxy.udp = true
4
})

转发过程:

选定节点后，建立连接
开启 UDP 支持，确保视频流畅
通过节点访问 YouTube 服务器
将视频数据返回给你

就像快递员:

拿到包裹（你的请求）
选择最佳路线（代理节点）
送到目的地（YouTube 服务器）
把货物（视频数据）带回来

整个过程总结#

当你想看 YouTube 视频时:

输入网址 → DNS 解析获取真实地址
规则匹配 → 确定使用 YouTube 代理组
代理选择 → 找到最适合的节点
流量转发 → 通过节点访问视频

所有这些都是自动完成的，你只需要:

打开浏览器
输入 YouTube 网址
享受流畅的视频体验

这就是一个优秀的代理配置系统应该做到的：把复杂的事情变得简单，让用户专注于使用体验。

总结#

整个配置文件的作用可以归纳为：

检查是否正确导入了订阅节点（这些节点保存于 config.proxies 或 proxy-providers 中）。
配置 DNS，确保国内外域名解析走不同的服务器，增强解析准确性和绕过污染。
定义规则集以及具体规则，将各类网站（如 Google、YouTube、Netflix 等）按类别匹配到不同的代理组。
定义代理组，通过手动选择、自动检测、负载均衡等策略，把所有订阅的节点分组，用户（或者规则）选择合适的节点。
在访问 YouTube 时，Clash 通过 DNS 解析、规则匹配、模块化代理组选择，将数据流量转发到一个经过挑选的节点上，实现无障碍访问。

通过这份配置文件，你不仅学会了如何导入和使用订阅链接中的节点，还能根据实际需要制定不同的规则和代理组，实现对流量的智能分流。希望这篇文章能帮助你更好地理解和使用 Clash 的配置。

Cloudflare R2免费图床部署与PicGo配置

Wed, 12 Feb 2025 00:00:00 GMT

Cloudflare R2 + PicGo搭建免费图床教程#

为什么选择Cloudflare R2作为图床？#

Cloudflare R2是一个对象存储服务，类似于阿里云OSS或AWS S3，但它提供了更慷慨的免费额度：

每月10GB免费存储空间
每月100万次免费请求
无限制的出站流量
全球CDN加速

配合PicGo这款优秀的图片上传工具，我们可以搭建一个稳定、高速且完全免费的图床服务。

前期准备#

在开始搭建之前，我们需要准备以下几个必要条件：

Cloudflare账号：访问 https://dash.cloudflare.com/ 注册
PayPal账号：用于验证身份并开通Cloudflare R2服务，访问 https://www.paypal.com/ 注册
PicGo软件：图片上传管理工具，从 https://github.com/molunerfinn/picgo/releases下载
Img
根据你的系统自行选择下载，这里我下载的是这个版本的。

PayPal账号设置详解#

由于Cloudflare R2需要PayPal验证，这里详细说明PayPal账号的注册和验证流程。

1. 基础账号注册#

使用常用邮箱（支持国内邮箱如QQ邮箱）
填写手机号码（支持国内手机号）
填写个人信息和地址（建议与身份证信息保持一致）

2. 绑定银行卡#

按照页面提示填写卡片信息
关于安全码（CVV）：
- 如果你的卡片没有安全码，可以不填或填写任意3位数字
  Img
完成卡片激活流程（支持银联兼容的Visa卡）

3. 关联银行账户#

这一步可能会遇到地址验证错误，参考以下解决方案：https://tieba.baidu.com/p/7226505581?pid=137908119220&cid=0#137908119220

填写银行信息时注意以下格式：

Img

银行名称：使用英文全称，如建设银行填写”CHINA CONSTRUCTION BANK CORPORATION”
SWIFT代码：使用分行代码，如深圳建设银行使用”PCBCCNBJSZX”
地址：可以留空
账号：填写银行卡号（去掉空格）

开通Cloudflare R2服务#

完成PayPal验证后，就可以开通Cloudflare R2服务了。注意事项：

必须使用PayPal支付方式（选择左上角的PayPal选项）
如果开通失败导致账户被限制：
- 需要上传身份证正反面照片
- 提供身份证上的地址信息（可以直接将地址部分截图框起来提供）

至此，所有准备工作就完成了。接下来我们就可以开始配置R2存储桶和PicGo工具，打造自己的免费图床服务了。

配置Cloudflare R2服务#

这部分的配置过程，我是参考了这篇Cloudflare R2 + PicGo 免费图床教程。不过我还是决定把自己的配置过程记录下来，一方面是给自己留个备忘，另一方面也是记录下我踩过的一些坑，希望能帮到遇到类似问题的朋友。

1. 创建R2存储桶#

首先，我们需要创建一个R2存储桶来存储图片：

进入Cloudflare控制面板的R2服务
创建新的存储桶（注意：存储桶名称必须使用小写字母）
Img

2. 配置自定义域名#

为了更好地管理和访问图片，我们需要配置自定义域名：

在R2控制面板中添加自定义域名
输入已注册的域名或子域名
Img
在本例中，我使用了picgo作为子域名，因为这个图床主要用于PicGo服务。选择子域名时，你可以根据实际需求进行命名，只需遵循以下规则：

使用子域名时，通常没有严格的限制，可以根据需求使用任意的英文、数字组合。常见的子域名类型包括：

www：这是最常见的子域名，通常用于指向网站的主页面。例如：www.molii722.us.kg。

blog：用于博客或文章发布的子域名。例如：blog.molii722.us.kg。

shop：通常用于电商网站的子域名。例如：shop.molii722.us.kg。

mail：用于邮件服务的子域名。例如：mail.molii722.us.kg。

support：用于客户支持页面的子域名。例如：support.molii722.us.kg。

api：用于 API 服务的子域名。例如：api.molii722.us.kg。

admin：用于管理后台的子域名。例如：admin.molii722.us.kg。

理论上，您可以创建任意子域名，只要符合以下规则：

长度通常限制在 1 到 63 个字符之间。

只能包含字母、数字和连字符（-），但不能以连字符开头或结尾。

只能使用 ASCII 字符集。

可以根据网站的功能和组织结构自由选择子域名的命名。

配置完成后，你会看到域名状态显示为”活动”：

Img

此时，你的图片可以通过自定义域名和R2.dev域名两种方式访问。你可以通过面板直接上传图片测试：

Img

至此，作为简单图床已经能正常使用了，但是需要在 CF 面板上传和查看链接，比较麻烦，可以使用 R2 API 结合 PicGo 来进行上传和管理图片，还能快捷复制图片链接。

3. 配置PicGo上传工具#

虽然可以直接通过Cloudflare面板上传图片，但使用PicGo可以让上传过程更加便捷。让我们来配置PicGo：

首先创建API令牌：
- 进入API令牌管理页面
  Img
- 点击”创建API令牌”
  Img
- 按照图示配置权限
  Img
配置PicGo：
- 在PicGo中安装S3插件
  Img
- 将R2配置信息填入Amazon S3设置中
  Img

配置完成后，你就可以通过PicGo轻松上传图片了：

Img

安全性#

我们可以配置相关规则来确保只有来自授权网站的请求可以访问资源。

配置WAF规则限制访问：
- 进入WAF配置页面
  Img
- 创建规则，限制只允许特定域名访问
  Img
配置本地访问白名单：
- 添加本地IP到白名单
  Img
- 可以通过CMD运行ipconfig查看本地IP IP填写你本地的IP，可以打开CMD，输入ipconfig查看，如果不行，可以点击之前设置的规则，看看有哪些IP被阻止了。
  Img
  
  Img

扩展功能与使用技巧#

1. 编辑器集成#

Typora配置#

点击”文件” -> “偏好设置” -> “图像”
按照下图配置PicGo设置：
Img

YankNote配置#

点击左下角的”设置” -> “图片”
按照下图配置：
Img
配置完成后，当你从粘贴板粘贴图片到YankNote时，图片会自动上传到图床。

2. 常见问题解决方案#

图片上传速度慢#

解决方案：在PicGo的Amazon S3插件中配置代理

Img

详细说明请参考：cloudflare r2 +picgo 上传图片经常失败

图片显示异常#

问题：在笔记软件中上传图片后不显示，复制markdown到网页显示”This XML file does not appear to have any style information associated with it”

解决方案：配置自定义输出URL模板

Img

详细说明：【求助】关于在笔记软件中上传 Picgo 图床的问题

3. PicGo进阶使用技巧#

自定义上传路径#

配置格式：{year}/{month}/{fileName}.{extName}

支持的变量：year、month、fileName、extName等
注意：{fileName}.{extName}等同于{fullName}
详细配置说明：https://github.com/wayjam/picgo-plugin-s3?tab=readme-ov-file#%E8%87%AA%E5%AE%9A%E4%B9%89%E8%BE%93%E5%87%BA-url-%E6%A8%A1%E6%9D%BFoutputurlpattern

批量图片迁移#

Typora批量迁移#

点击”格式” -> “图像” -> “上传所有本地图片”
等待上传完成

YankNote批量迁移#

点击左下角的”工具”
选择”上传所有图片”（注意：仅会上传当前文档中的图片）
Img

Cloudflare Workers临时邮箱部署指南

Wed, 12 Feb 2025 00:00:00 GMT

在这个教程中，我将介绍如何使用Cloudflare Workers搭建一个属于自己的临时邮箱服务。本文是基于以下教程的实践总结和知识扩展：

原始教程：https://linux.do/t/topic/316819/1
官方教程：https://temp-mail-docs.awsl.uk/zh/guide/ui/d1.html

虽然上述教程已经提供了详细的步骤说明，但我想通过这篇文章记录一些重要的知识点和实践经验，以便日后查阅。

系统架构概述#

在开始之前，让我们先了解一下这个临时邮箱服务的主要组成部分：

后端服务：基于Cloudflare Workers的无服务器函数
数据存储：使用D1数据库和KV存储
前端界面：用于用户交互的Web界面
邮件转发：处理邮件路由的规则配置

搭建步骤#

1. 配置后端服务#

首先需要创建D1数据库，它将作为Cloudflare Workers的后端存储。Cloudflare Workers是一个让无服务器函数尽可能接近最终用户运行的平台。当收到特定类型的请求时，这些代码会被自动执行。

2. 环境变量配置#

需要设置一系列环境变量来控制服务的行为。详细配置说明可以参考：https://temp-mail-docs.awsl.uk/zh/guide/worker-vars

例如用户环境变量包括：

USER_DEFAULT_ROLE：新用户的默认角色（启用邮件验证时有效）
ADMIN_USER_ROLE：管理员角色配置
USER_ROLES：用户角色JSON配置
DISABLE_ANONYMOUS_USER_CREATE_EMAIL：控制匿名用户创建邮箱的权限
NO_LIMIT_SEND_ROLE：可以无限制发送邮件的角色（如vip/admin）

3. 存储系统配置#

在这个系统中，我们需要同时使用D1数据库和KV存储，它们各自有不同的用途：

D1数据库#

D1是基于SQLite的关系型数据库，主要用于：

存储结构化数据（用户信息、邮件内容等）
处理需要复杂查询的数据
确保数据一致性

KV存储#

KV提供键值对存储，适用于：

缓存和会话管理
需要快速访问的临时数据
分布式存储场景

两者结合使用的优势：

可以根据数据特性选择合适的存储方式
优化性能和资源使用
提供更灵活的数据处理方案

注意：配置时必须遵守以下命名规则：

D1 Database的绑定名称必须为”DB”
KV的绑定名称必须为”KV”

4. 域名配置#

配置API服务域名（我使用的是apimail.molii721.us.kg）
设置邮件转发规则，将发往molii721.us.kg的邮件转发到对应的Workers

5. 前端部署#

访问 https://temp-mail-docs.awsl.uk/zh/guide/ui/pages 生成前端代码
下载frontend.zip并部署
配置前端访问域名（我使用的是mail.molii721.us.kg）

系统使用和管理#

管理员功能#

通过访问 https://mail.molii721.us.kg/admin 可以：

创建和管理用户
Img
设置用户角色
Img
配置邮件自动清理
Img
设置邮件发送配额
Img
管理邮箱地址（如删除nidreiger@molii721.us.kg等地址）
Img

用户使用说明#

支持匿名用户创建临时邮箱（注意：关闭浏览器或清除cookie后会丢失）
注册用户可以更好地管理和保存邮箱
不同角色的用户有不同的权限和限制

至此，你就拥有了一个功能完整的临时邮箱服务！

Nonebot2插件开发踩坑笔记：代理设置与文件处理

Mon, 10 Feb 2025 00:00:00 GMT

Nonebot2 插件踩坑笔记：代理设置与文件处理#

引言#

在 Nonebot2 插件开发中，网络请求和文件处理是两个常见的痛点。最近在维护插件时，遇到了几个典型问题：httpx 代理设置改变、图片发送失败等。本文将分享这些问题的解决方案，希望能帮助大家少走弯路。

一、httpx 代理设置更新#

1. 问题起因#

最近很多使用 httpx.AsyncClient 的插件突然报错：

1
AsyncClient.__init__() got an unexpected keyword argument 'proxies'

这是因为 httpx 库更新后改变了代理设置的方式。让我们看看如何修复这个问题。

2. 实际案例分析#

2.1 nonebot_plugin_cp_broadcast插件的更新#

更新前：

1
async def req_get(url: URLTypes, proxies: Optional[ProxiesTypes] = None) -> str:
2
    async with AsyncClient(proxies=proxies) as client:
3
        r: Response = await client.get(url)
4
    return r.content.decode("utf-8")

更新后：

1
async def req_get(url: URLTypes, proxies: Optional[ProxiesTypes] = None) -> str:
2
    try:
3
        transport = AsyncHTTPTransport(proxy=proxies["http"] if proxies else None)
4
        async with AsyncClient(transport=transport) as client:
5
            resp = await client.get(url)
6
            resp.raise_for_status()
7
            return resp.text
8
    except Exception as e:
9
        logger.error(f"请求失败: {e}")
10
        return ""

2.2 nonebot_plugin_picstatus 插件的更新#

更新前：

1
@bg_provider()
2
async def loli():
3
    async with AsyncClient(
4
        follow_redirects=True,
5
        proxies=config.proxy,
6
        timeout=config.ps_req_timeout,
7
    ) as cli:
8
        return resp_to_bg_data(
9
            (await cli.get("https://www.loliapi.com/acg/pe/")).raise_for_status(),
10
        )

更新后：

1
@bg_provider()
2
async def loli():
3
    transport = AsyncHTTPTransport(proxy=config.proxy if config.proxy else None)
4
    async with AsyncClient(
5
        transport=transport,
6
        follow_redirects=True,
7
        timeout=config.ps_req_timeout
8
    ) as cli:
9
        resp = await cli.get("https://www.loliapi.com/acg/pe/")
10
        resp.raise_for_status()
11
        return resp_to_bg_data(resp)

二、nonebot-plugin-nai3 插件踩坑实录#

1. 遇到的问题#

在开发过程中遇到了两个主要问题：

1
# 问题一：代理设置错误
2
httpx.ProxyError: 代理连接失败
3

4
# 问题二：图片发送失败
5
ActionFailed(retcode=1200, message='文件名解析失败')

2. 解决过程#

2.1 代理问题修复#

1
# 更新前
2
proxies = {"http://": nai3_config.nai3_proxy}
3

4
# 更新后
5
proxies = {
6
    "http://": nai3_config.nai3_proxy,
7
    "https://": nai3_config.nai3_proxy
8
}
9
transport = AsyncHTTPTransport(proxy=proxies["https://"] if proxies else None)

2.2 图片发送问题#

尝试了多种方案：

直接路径（失败）：

1
await nai3.send(MessageSegment.image(f"file:///{temp_path}"))

相对路径（失败）：

1
await nai3.send(MessageSegment.image("./data/nai3/temp.png"))

Base64 方案（成功）：

1
import base64
2
with open(temp_path, "rb") as f:
3
    image_data = f.read()
4
    base64_str = base64.b64encode(image_data).decode()
5
await nai3.send(
6
    f"种子: {seed}\n" + MessageSegment.image(f"base64://{base64_str}"),
7
    at_sender=True
8
)

三、最佳实践与解决方案#

1. 代理设置通用模板#

1
from httpx import AsyncClient, AsyncHTTPTransport
2
from typing import Optional
3

4
async def make_request(url: str, proxy: Optional[str] = None):
5
    transport = AsyncHTTPTransport(proxy=proxy if proxy else None)
6
    try:
7
        async with AsyncClient(transport=transport) as client:
8
            resp = await client.get(url)
9
            resp.raise_for_status()
10
            return resp.text
11
    except Exception as e:
12
        logger.error(f"请求失败: {e}")
13
        return None

2. 图片发送最佳实践#

1
async def send_image(bot, event, image_path: str):
2
    try:
3
        # 首先尝试直接发送
4
        await bot.send(event, MessageSegment.image(f"file:///{image_path}"))
5
    except Exception as e:
6
        logger.debug(f"直接发送失败: {e}")
7
        # 失败则使用 base64
8
        try:
9
            with open(image_path, "rb") as f:
10
                base64_str = base64.b64encode(f.read()).decode()
11
            await bot.send(event, MessageSegment.image(f"base64://{base64_str}"))
12
        except Exception as e:
13
            logger.error(f"图片发送完全失败: {e}")
14
            raise

3. 错误处理与日志记录#

1
try:
2
    # 网络请求
3
    transport = AsyncHTTPTransport(proxy=proxy if proxy else None)
4
    async with AsyncClient(transport=transport) as client:
5
        resp = await client.get(url)
6
        resp.raise_for_status()
7

8
    # 文件处理
9
    with open(temp_path, "wb") as f:
10
        f.write(resp.content)
11

12
    # 消息发送
13
    await send_image(bot, event, temp_path)
14

15
except httpx.HTTPError as e:
16
    logger.error(f"HTTP 请求失败: {e}")
17
except IOError as e:
18
    logger.error(f"文件操作失败: {e}")
19
except ActionFailed as e:
20
    logger.error(f"消息发送失败: {e}")
21
except Exception as e:
22
    logger.error(f"未知错误: {e}")

展开收起

4. 文件权限检查#

Terminal window

1
$ ls -la /opt/mybot/data/nai3
2
total 592
3
drwxr-xr-x 2 root root   4096 Feb 10 02:04 .
4
drwxr-xr-x 7 root root   4096 Feb  9 04:38 ..
5
-rwxr-xr-x 1 root root     35 Feb  9 03:13 black_data.json
6
-rwxr-xr-x 1 root root 591515 Feb 10 03:43 temp.png

权限说明：

drwxr-xr-x: 目录权限，所有者可读写执行，其他用户可读执行
-rwxr-xr-x: 文件权限，所有者可读写执行，其他用户可读执行

四、经验总结#

1. 代理设置注意事项#

使用新版 AsyncHTTPTransport
同时配置 http 和 https
检查代理地址格式
做好错误处理

2. 图片处理要点#

优先使用 base64 方式
检查文件权限
做好异常处理
添加详细日志

3. 调试技巧#

使用详细的日志记录
分步骤排查问题
准备多个备选方案
注意检查文件权限

五、常见问题解答#

Q: 为什么要更改代理设置方式？ A: 新的方式提供了更好的灵活性和可控性，允许更细粒度的传输层配置。
Q: 为什么图片发送会失败？ A: 可能是路径解析问题、权限问题或 go-cqhttp 的限制，使用 base64 方式最可靠。
Q: 代理设置要注意什么？ A: 需要同时设置 http 和 https，使用新版的 AsyncHTTPTransport 方式。
Q: 如何调试文件权限问题？ A: 使用 ls -la 命令查看详细权限，确保运行用户有正确的读写权限。

结语#

通过这些实际案例的分享，我们看到了在 Nonebot2 插件开发中常见的一些问题和解决方案。良好的错误处理和日志记录是排查问题的关键，而使用正确的代理设置和文件处理方式则是避免问题的基础。

希望这篇文章能帮助大家在开发过程中少走弯路。如果你有任何问题或经验分享，欢迎在评论区讨论！

参考资料#

Nonebot2 QQ机器人Linux环境部署指南

Sun, 09 Feb 2025 00:00:00 GMT

Linux 环境下的 Nonebot2 QQ机器人搭建指南#

本文是 Nonebot2 教程系列的 Linux 篇，主要介绍如何在 Linux 系统上配置和部署 QQ 机器人。

一、框架安装#

1. 安装 NapCat#

推荐使用 Docker 方式安装 NapCat，具体步骤请参考官方文档。安装完成后，按照框架接入指南完成配置。

2. 环境迁移准备#

如果你已在本地环境调试好机器人，可以通过复制以下文件到服务器来快速部署：

src 文件夹
pyproject.toml
poetry.lock

二、Python 环境配置#

在 Ubuntu 系统上安装 Python 3.10.11 的详细步骤：

1. 系统更新#

先更新一下包管理器的包列表，确保系统是最新的：

Terminal window

1
sudo apt update

2. 安装必要依赖#

安装编译 Python 需要的一些工具和库：

Terminal window

1
sudo apt install -y software-properties-common
2
sudo apt install -y build-essential libssl-dev zlib1g-dev libbz2-dev \
3
libreadline-dev libsqlite3-dev wget curl llvm libncurses5-dev libncursesw5-dev \
4
libffi-dev liblzma-dev python3-openssl git

3. 添加 Python PPA#

使用 Python 官方的 PPA 仓库来安装特定版本的 Python：

Terminal window

1
sudo add-apt-repository ppa:deadsnakes/ppa
2
sudo apt update

4. 安装 Python 3.10#

安装 Python 3.10.12：

Terminal window

1
sudo apt install python3.10

5. 配置 pip#

安装 Python 包管理工具 pip：

Terminal window

1
sudo apt install python3.10-distutils
2
wget https://bootstrap.pypa.io/get-pip.py
3
sudo python3.10 get-pip.py

6. 验证安装#

最后，检查 Python 版本，确保安装成功：

Terminal window

1
python3.10 --version

💡 如果显示 Python 3.10.11，则表示安装成功。

三、项目依赖管理#

完成 Python 安装后，需要创建项目结构并安装依赖：

创建 Nonebot 项目目录
复制之前准备的文件到相应位置
创建并激活虚拟环境
使用 Poetry 安装依赖

⚠️ 如果在安装依赖时遇到超时问题，可以考虑配置代理。

四、配置网络代理#

1. 安装和配置 Clash#

推荐参考详细教程配置 Clash 代理。配置完成后，可以使用以下命令控制 Clash：

Terminal window

1
systemctl start clash # 启动代理
2
systemctl stop clash # 停止代理

2. 代理相关命令#

Terminal window

1
查看当前代理设置
2
echo $http_proxy
3
echo $https_proxy
4

5
临时关闭代理
6
unset http_proxy https_proxy all_proxy

3. SSL 错误解决#

如果遇到 SSL 错误：error:0a000126:ssl routines::unexpected eof while reading，可以参考这篇文章解决。

常见问题与解决方案#

Poetry 安装超时
- 配置国内镜像源
- 使用代理
- 增加超时时间
依赖安装失败
- 检查 Python 版本兼容性
- 确认系统依赖是否完整
- 查看错误日志定位具体问题
网络连接问题
- 验证代理配置
- 检查防火墙设置
- 确认端口是否开放

🔍 遇到问题时，建议先查看 Nonebot2 的官方文档和问题解答。

Docker容器网络互联：ERR_CONNECTION_REFUSED排查记录

Sat, 08 Feb 2025 00:00:00 GMT

Docker容器网络互联：踩坑记录与解决方案#

📝 这是一份来自真实项目的踩坑笔记，记录了在使用Docker时遇到的网络问题及其解决方案。通过两个具体实例，帮助你理解和解决容器间的网络通信问题。

本文将通过两个实际案例来说明这些问题：

🔌 案例一：napcat反向WebSocket连接失败
🔗 案例二：newapi容器无法访问cursor-to-openai服务

一、背景简介#

在使用 Docker 部署多个服务时，经常会遇到容器之间的网络隔离问题。不同的容器可能运行在不同的 Docker 网络中，容器内的 127.0.0.1 指向的是各自的内部环境，而不是宿主机或其它容器。这篇日记记录了我在部署 napcat（用于反向 WebSocket 连接）和 newapi（测试 HTTP 接口）时遇到的问题，以及如何排查和解决这些问题。

二、Docker 网络基础#

1. Docker 默认网络类型#

bridge 网络
- 如果你没有指定网络，Docker 默认会将容器连接到名为 bridge 的网络中。
- 容器可以通过 IP 通信，但默认无法通过容器名称互相访问。
用户自定义网络
- 你可以使用命令 docker network create <network_name> 创建自定义网络（例如 baota_net）。
- 在自定义网络中，容器间可以通过名称相互解析，非常方便。

2. 查看 Docker 网络信息#

查看所有网络

Terminal window

1
docker network ls

输出示例：

1
NETWORK ID     NAME        DRIVER    SCOPE
2
487f8520966a   baota_net   bridge    local
3
d2758aac9ad7   bridge      bridge    local
4
e93f7b6bb2da   host        host      local
5
2817ff9e258d   none        null      local

查看某个网络的详细信息
比如查看 baota_net 网络：
Terminal window
```
1
docker network inspect baota_net
```
这会显示该网络的子网、网关以及当前有哪些容器连接到这个网络，并显示它们的 IP 地址。

快速查看所有容器的网络

Terminal window

1
docker ps --format "{{.Names}} -> {{.Networks}}"

例如，我得到的结果是：

1
napcat -> bridge
2
cursor-to-openai -> bridge
3
newapi_by2f_new-api_1 -> baota_net
4
newapi_by2f_redis_1 -> baota_net
5
newapi_by2f_mysql_1 -> baota_net
6
alist_7b4p_alist_7b4p_1 -> baota_net

表示：

部分容器（napcat、cursor-to-openai）运行在默认的 bridge 网络中；
其他容器运行在自定义的 baota_net 网络中。

3. 关于主机网络接口#

在 ifconfig 输出中你看到的 ens17 是宿主机上的网卡名称，它通常代表真实的网络接口（在本例中 IP 为 172.16.0.24）。这与 Docker 默认使用的 docker0 或其他桥接网络不同。我们在容器之间或容器与宿主机之间通信时，经常需要用到宿主机的实际 IP 地址。

三、实例分析#

例子1：napcat 反向 WebSocket 连接失败#

问题描述：#

在 napcat 的反向代理配置中设置了目标地址为 ws://127.0.0.1:8080/onebot/v11/ws。
日志显示错误：connect ECONNREFUSED 127.0.0.1:8080。

原因分析：#

napcat 运行在 Docker 容器中，容器内的 127.0.0.1 指向的是 napcat 自己，而不是宿主机上的 NoneBot 服务。
NoneBot 服务运行在宿主机或其他网络中，因而无法从 napcat 的容器内通过 127.0.0.1 访问。

解决方案：#

使用宿主机 IP 地址
根据 ifconfig，宿主机 IP 是 172.16.0.24，因此修改反向代理地址为：
```
1
ws://172.16.0.24:8080/onebot/v11/ws
```
这样 napcat 容器就能通过宿主机网络正确连接到 NoneBot 服务。
或者使用 host.docker.internal
如果 Docker 版本支持，在 napcat 容器启动时添加映射：
Terminal window
```
1
docker run --add-host=host.docker.internal:host-gateway ...
```
然后配置反向代理地址为：
```
1
ws://host.docker.internal:8080/onebot/v11/ws
```

例子2：newapi 容器测试配置失败#

问题描述：#

newapi 容器尝试访问 cursor-to-openai 服务时，填写 http://127.0.0.1:3010 导致连接超时（i/o timeout）。
cursor-to-openai 运行在 bridge 网络中，并通过端口映射将 3010 暴露给宿主机。

原因分析：#

在 newapi 容器中，127.0.0.1 指的是 newapi 自己，而 cursor-to-openai 服务运行在另外一个容器中。
使用宿主机 IP（例如 172.16.0.24:3010）也不一定能成功，因为 newapi 容器与宿主机之间可能存在路由或网络隔离问题。

解决方案：#

让两个容器处于同一网络
将 cursor-to-openai 容器加入到 newapi 容器所在的网络（比如都加入 baota_net）。操作命令：
Terminal window
```
1
docker network connect baota_net cursor-to-openai
```
然后，在 newapi 中通过容器名直接访问：
```
1
http://cursor-to-openai:3010/v1/chat/completions
```
这种方法让容器之间直接通信，避免了跨网络或通过宿主机访问时出现的超时问题。
使用宿主机地址并配置 host.docker.internal
如果不方便让容器处于同一网络，可以在 newapi 容器启动时添加：
Terminal window
```
1
--add-host=host.docker.internal:host-gateway
```
然后在 newapi 中使用：
```
1
http://host.docker.internal:3010/v1/chat/completions
```
这种方式让 newapi 通过特殊域名访问宿主机映射的服务端口。

四、总结与经验分享#

Docker 网络知识点
- Docker 默认会创建多个网络，如 bridge、host、none，以及你手动创建的自定义网络（如 baota_net）。
- 容器的 127.0.0.1 只指向自身，不同容器间不能用它直接通信。
如何查看和管理网络
- 使用 docker network ls 列出所有网络。
- 使用 docker network inspect <network> 查看详细信息，包括连接的容器及其 IP。
- 使用 docker ps --format "{{.Names}} -> {{.Networks}}" 快速查看各容器所在网络。
跨容器通信技巧
- 尽量让需要互联的容器加入同一自定义网络，便于使用容器名通信。
- 如果必须通过宿主机访问，使用宿主机实际 IP 或配置 host.docker.internal，并注意防火墙和路由问题。
实例教训
- napcat 反向连接失败：原来使用 127.0.0.1 错误理解了容器内的网络环境，正确的方法是使用宿主机 IP 或 host.docker.internal。
- newapi 配置失败：通过调整容器网络，将服务容器加入同一网络，成功解决了超时问题。

Ngrok与TailwindCSS配置使用记录

Sat, 08 Feb 2025 00:00:00 GMT

我的踩坑日记#

一、Ngrok 的使用#

在开发过程中，我需要将本地服务映射到公网，借助 Ngrok 实现内网穿透真是解了燃眉之急。具体步骤如下：

下载安装
打开 Ngrok Windows 下载页面，选择与你系统匹配的最新版本进行下载。下载后根据官方文档完成基本配置。
使用命令映射端口
配置完成后，在命令行中输入
```
1
ngrok http <你的服务端口>
```
这样就能将本地服务端口通过 Ngrok 映射到公网，非常方便。

小贴士： 在配置过程中，可能会遇到认证或端口映射问题，查阅官网文档或相关社区讨论往往能帮助你快速解决问题。

二、tailwindcss 的项目创建与配置#

使用 tailwindcss 进行前端样式开发也经历了一些摸索，这里整理了几种常用的项目创建方式和配置注意事项：

项目创建方式
我常用的有两种方法：
- 使用 Vite 创建项目：
  执行命令：
```
1
npm create vite@latest
```
  然后根据提示选择你需要的框架（React、Vue 等）。
- 直接使用各框架的创建工具：
  - Vue 项目：npm create vue@latest
  - React 项目：npx create-next-app@latest
tailwindcss 的配置
- 如果你使用的是 Vite 项目，可以参考 TailwindCSS 使用 Vite 安装文档来进行配置。注意，这里的文档基于最新的 tailwindcss-v4 配置。
- 坑点提示：
  - 如果在配置过程中出现问题，比如提示需要安装 Microsoft 的一些运行文件，可以参考 TailwindCSS GitHub 讨论的相关说明。
  - tailwindcss-v4 下直接运行 npx tailwindcss init 可能会报错，因为这是 v3 的命令。详细的配置步骤建议参考 v3 版的安装指南。
- 对于其他框架的项目，请参照 TailwindCSS 官方框架指南进行相应配置。
推荐实践
综合经验，我建议：
- 使用 Vite 快速创建项目，体验轻量高效。
- 采用 pnpm 来安装依赖包，这样更节省磁盘空间且安装速度快。
- 根据最新的 tailwindcss-v4 配置文件进行调整，确保使用的是最新功能和最佳实践。

宝塔面板Docker应用配置指南

Fri, 07 Feb 2025 00:00:00 GMT

宝塔面板是一款简单好用的服务器运维管理工具，它提供了可视化的界面来管理服务器，大大简化了服务器运维的难度。本文将详细介绍如何在宝塔面板中配置和使用Docker，帮助你轻松部署各种应用。

如果你想要更直观地了解配置过程，可以参考这个视频教程： https://www.bilibili.com/video/BV1JT421y7pS/?spm_id_from=333.1007.top_right_bar_window_history.content.click&vd_source=e03b7d988550b29e55118b7d8e6cab3c

安装宝塔面板#

首先访问宝塔面板的官方下载页面：https://www.bt.cn/new/download.html
在安装界面填写相关信息：
Img
点击”立即安装”，等待5~10分钟左右完成安装

安装完成后，你会看到如下界面：

Img

复制面板访问地址，输入用户名和密码即可登录管理界面。

重要提示：在使用宝塔面板之前，请确保已经在服务器安全组或防火墙中放行了面板访问端口。本文后续提到的所有端口同样需要确保已放行，否则将无法正常访问相关服务。

配置Docker环境#

在宝塔面板左侧边栏找到Docker选项并安装（如果未安装，系统会提示你进行安装）
为了提升镜像下载速度，建议配置国内镜像源。参考这篇文章，在终端执行以下命令：

Terminal window展开收起

1
sudo mkdir -p /etc/docker
2
sudo tee /etc/docker/daemon.json <<-'EOF'
3
{
4
    "registry-mirrors": [
5
        "https://do.nark.eu.org",
6
        "https://dc.j8.work",
7
        "https://docker.m.daocloud.io",
8
        "https://dockerproxy.com",
9
        "https://docker.mirrors.ustc.edu.cn",
10
        "https://docker.nju.edu.cn"
11
    ]
12
}
13
EOF
14
sudo systemctl daemon-reload
15
sudo systemctl restart docker

展开收起

配置完成后，你可以看到镜像源已经添加成功：

Img

创建Docker容器#

在Docker管理界面中，你可以通过命令行方式创建容器：

Img

只需将Docker运行命令复制到命令输入框，点击”执行命令”即可完成容器创建。

Cursor API代理服务紧急修复方案

Mon, 03 Feb 2025 00:00:00 GMT

最近在网上看到不少小伙伴吐槽说 Cursor 又用不了了。是的，你没看错，又双叒叕更新了！这次 Cursor 加强了对临时邮箱的封禁力度，导致不少公益站点纷纷阵亡，惨烈程度堪比团灭…😱

如果你正在使用我之前那篇《搭建个人 API 代理站点》的教程，可能已经发现 CursorAPI 配置出现了空回复的问题。别担心！这篇文章就是来解决这个烦恼的。

最后#

这就是和 Cursor 的对抗进行时。它更新一次，换个方案继续就好。要是之后又有变化，有时间的话我会更新解决方案。

Cursor Pro自动化工具配置与使用

Sun, 26 Jan 2025 00:00:00 GMT

前言#

Cursor Pro是一款强大的自动化工具，本文将详细介绍其安装配置流程以及使用过程中的一些重要概念。通过本教程，你将能够快速上手并充分利用这个工具。

准备工作#

在开始配置之前，我们需要准备以下内容：

CloudFlare账号及已配置的域名
一个可用的接收邮箱
Cursor Pro安装包

安装配置步骤#

1. 下载安装#

首先访问Relases页面，根据你的操作系统下载对应的安装包。解压后你会看到两个主要文件：

logs文件夹
CursorPro.exe
Img

2. 环境配置#

从cursor-auto-free项目下载.env.example文件
打开CloudFlare控制面板，进入你的域名管理界面
Img
按照下图所示配置Catch-all地址
Img
将.env.example重命名为.env，并按照下图示例填写配置信息
Img

3. 启动运行#

完成配置后，右键点击CursorPro.exe，选择”以管理员身份运行”即可启动程序。

工作原理解析#

Catch-all邮件地址机制#

Catch-all地址（通配符邮箱）是CloudFlare提供的一项强大功能，它的工作流程如下：

配置包含两个关键选项：
- 操作：发送电子邮件
- 目标位置：实际接收邮件的地址
所有发送到xxx@你的域名的邮件都会：
- 首先经过CloudFlare邮箱服务器
- 然后转发到你设置的目标邮箱
这样可以有效隐藏你的实际邮箱地址，外部只能看到CloudFlare的邮箱服务

工作流程图示：

Img

常见问题解决#

如果你遇到machine_id限制的问题，可以通过以下步骤解决：

关闭Cursor程序
使用cursor_machine_id工具修改机器码
如果问题仍然存在，可以尝试卸载Cursor后重新执行脚本

参考资料#

详细教程请参考：https://cursor-auto-free-doc.vercel.app/

Deepseek-V3+CoT思维链+RAG知识库配置指南

Sun, 26 Jan 2025 00:00:00 GMT

现在是构建强大 AI 的最佳时机！

Deepseek V3 正式发布，不仅成本低，效果还超棒！ V3 模型在训练时融入了 R1 的推理能力，虽然它本身不是专门的推理模型，但在执行 CoT（Chain-of-Thought）任务时表现非常出色。更厉害的是，Deepseek 还支持 Prompt 缓存功能，即使 CoT 的系统提示词很长，缓存后实际消耗的成本也不会太高，性价比直接拉满！

与此同时，Cherry Studio 也推出了基于 RAG（Retrieval-Augmented Generation）的知识库，实用性直接升级，简直是 AI 开发者的福音！

话不多说，赶紧动手开干吧！

第一步：注册 Deepseek API 和 Siliconflow#

注册 Deepseek API 访问 Deepseek 平台，注册账号并获取 API 密钥。 Deepseek-V3 模型成本低、效果好，是构建 AI 的首选工具！
Img
注册 Siliconflow 访问 Siliconflow 登录页面，使用统一登录系统注册账号。 Siliconflow 提供的 Embedding 模型（如 Pro/BAAI/bge-m3）效果非常棒，适合用于知识库构建。
Img

第二步：下载并配置 Cherry Studio#

下载 Cherry Studio 前往 Cherry Studio GitHub 页面，下载最新版本。
导入对话模型 打开 Cherry Studio，点击”设置”，选择”导入模型”。官方示例中已经提供了 Deepseek 模型的配置，直接导入即可。
导入 Embedding 模型 在 Cherry Studio 中，选择”知识库”功能，导入 Siliconflow 提供的 Embedding 模型（如 Pro/BAAI/bge-m3）。知识库功能是 0.9.1 版本的新亮点，实用性超强！
Img
也可点击管理添加模型
Img

第三步：配置 CoT Prompt#

新建助理 在 Cherry Studio 中，点击”新建助理”，进入配置页面。
添加 CoT Prompt 在助理的 Prompt 设置中，粘贴你的 CoT（Chain-of-Thought）提示词。 Deepseek 支持 Prompt 缓存，即使提示词较长，也不会增加太多成本，性价比超高！
Img

我们可以对比一下有思维链和没有思维链的回复。有思维链：

Img

没有思维链：

Img

可以看到思维链会展示思考过程同时更加针对性的进行回复

第四步：知识库教程#

在 Cherry Studio 中，知识库功能是 0.9.1 版本的重要更新之一。通过知识库，你可以将外部数据（如文档、API 文档等）与 AI 模型结合，提升问答和推理的准确性。以下是配置知识库的详细步骤：

1. 导入 Embedding 模型#

在 Cherry Studio 中，点击”知识库”功能，选择”导入模型”。推荐使用 Siliconflow 提供的 Embedding 模型（如 Pro/BAAI/bge-m3），效果非常出色。

Img

2. 配置知识库数据源#

将你的文档或数据文件（如 Markdown、JSON 等）上传到知识库中。Cherry Studio 支持多种文件格式，确保数据源的多样性和实用性。

操作步骤：
1. 点击”知识库”功能，选择”上传数据”。
2. 选择文件并上传，系统会自动解析文件内容并生成索引。

3. 优化知识库检索#

通过调整 Embedding 模型的参数和检索策略，可以进一步提升知识库的检索效果。例如，设置合适的相似度阈值，确保返回的结果既准确又相关。

建议：
- 调整相似度阈值：根据实际需求，设置一个合理的阈值，避免返回过多无关结果。
- 优化检索策略：结合上下文信息，提升检索的精准度。

4. 测试知识库功能#

在 Cherry Studio 中新建一个助理，配置其使用知识库功能。通过输入问题，测试知识库的检索和回答能力，确保其满足你的需求。

Img

调整模型温度：
- 温度越低，模型的逻辑和数学能力越强，适合需要精确回答的场景。
- 温度越高，模型的创造力和艺术能力越强，适合需要创意输出的场景。
- 注意：温度设置并非越低越好，过低可能导致模型对基本知识的理解不足。
本地部署模型：如果你希望本地部署模型，可以使用 ollama。下载后运行以下命令即可：
Terminal window
```
1
ollama pull momic-embed-text
```
其他配置与前面步骤一致。

5. 持续更新知识库#

知识库的效果依赖于数据的质量和时效性。定期更新知识库中的数据源，确保其始终与最新信息同步。

建议：
- 定期检查数据源，删除过时或无效的内容。
- 添加新的数据源，确保知识库的覆盖范围不断扩大。

6. 启用知识库的效果#

启用知识库后，AI 能够引用知识库中的内容，大大增强其注意力和检索能力。

Img

对应的流程图（AI生成）：

Img

小贴士#

知识库教程：如果对知识库配置有疑问，可以参考 Cherry Studio 官方教程。
模型选择：Deepseek-V3 和 Siliconflow 的 Embedding 模型搭配使用，效果非常出色，强烈推荐！

话不多说，赶紧动手试试吧！

参考资源#

[长期更新] Cherry Studio 使用指南与讨论汇总 https://linux.do/t/topic/327630
- 汇集了关于 Cherry Studio 的最新教程、使用技巧和社区讨论，适合想要深入学习的朋友。
Deepseek-V3 + CoT 思维链 + RAG 知识库：打造超强 AI 问答系统 https://linux.do/t/topic/316186
- 详细介绍了如何结合 Deepseek-V3、CoT 思维链和 RAG 知识库，构建一个高效、精准的 AI 问答系统，适合进阶用户参考。

【新手必读】酒馆(Silly Tavern)零基础入门指南

Sat, 25 Jan 2025 00:00:00 GMT

酒馆基本知识了解#

详细知识可以参考酒馆入门（必修）

本文将按照使用顺序，详细介绍酒馆(Silly Tavern)的基础配置流程和使用技巧。

1. API连接配置#

API连接是使用酒馆的第一步，位于上方第二个位置（插头图标）。必须正确配置API才能开始对话。

配置步骤：#

填写代理地址（填写中转商对应的）
填写API密钥（可从中转商令牌位置获得）
选择模型名称
点击连接测试

常见问题：

连接失败时，检查网络连接和API密钥是否正确
确保选择的模型与API密钥匹配
如果使用代理，确保代理地址正确

API连接界面

2. 预设导入与配置#

完成API连接后，需要配置对话预设。预设位于上方第一个位置，用于定制对话风格和内容。

配置步骤：#

点击预设图标
选择或导入预设文件
调整基础设置
保存配置

基础设置建议：

推荐开启流式传输
其他选项可保持默认
根据需要调整其他预设响应设置

预设界面

预设设置

3. 正则表达式配置#

正则表达式用于精确控制AI的响应触发条件。

基础正则示例：#

1
# 基础匹配
2
.*关键词.*      - 匹配包含"关键词"的文本
3
^开头$         - 精确匹配"开头"这个词
4
[选项1|选项2]   - 匹配多个选项之一

Img

这里可以看到，输出内容不会包含思维链的内容，只包含正文内容。这个就是正则其中之一的作用，可以隐藏一些用户不需要看到的但是ai会输出的内容。

第二个就是针对于世界书。可以参考我的生图世界书,生成了

1
<image>image###1girl, fox_ears, brown_hair, green_eyes, red_tips, chinese_clothes, cloud_pattern, shoulder_cutout, standing, afternoon_sunlight, handfan, covering_mouth, smiling, indoors, tea_cup, fox_tail, jewelry###</image>

的提示词，然后会显示一个生成图片的功能，这个是通过油猴插件生成的，具体可以查看进阶部分。

4. 角色卡导入与配置#

完成基础设置后，可以开始配置角色卡。

配置步骤：#

点击角色管理图标
选择导入角色卡
填写或修改角色信息
保存配置

角色卡内容：

角色名称：角色的名字
背景故事：角色的历史和经历
性格特征：个性和行为模式
能力和技能：特殊能力说明
外貌描述：外观特征描述

Img

比如我这里导入成功之后，此角色卡将会添加在右侧角色栏里面

Img

点击此角色卡，会弹出提示，点击是导入其世界书

Img

角色卡可以前往类脑角色卡专区自行获取

5. 世界书配置#

世界书是角色所在世界的设定集，用于构建完整的对话环境。

配置步骤：#

点击世界书图标
创建或导入世界书
填写世界设定
设置权重和触发条件
保存配置

基本结构：

历史背景：世界观设定
地理信息：场景描述
文化设定：风俗习惯
规则系统：世界运作规则

绿灯： 表示只有在触发关键词的时候才会加载这段预设。

蓝灯： 表示只有在，然后一般要改变位置也就是@D这个的深度表示权重，0十分重要，一般就填0-4以内的，可以提升ai的注意力（前提是ai已经理解了这部分世界书） 格式用键值对：使用这种格式，或者yaml等格式，这种方式由于在训练ai的时候，相比于自然语言，ai能更加理解这种方式，这样能提高ai的注意力

Img

我个人使用的预设以及配套正则 https://sillytavern-stage-girls-dog.readthedocs.io/tool_and_experience/misc/main.html

6. 进阶功能#

文生图功能#

提供多种实现方式：

油猴插件方案(推荐)
- 详细教程
- 这是我的相关配置
  Img
- 正面提示词：
```
1
best quality, amazing,quality, very aesthetic,absurdres, smea,
```
- 负面提示词：
```
1
Blurred genital area, mosaic painted genital area, obstructed genital area,Black stripe,lowres, bad anatomy, bad hands, text, error, missing fingers, extra digit, fewer digits, cropped, worst quality, low quality, normal quality, jpeg artifacts, signature, watermark, username, blurry, bad feet
```
- 文生图世界书以及正则 https://discord.com/channels/1134557553011998840/1268179293070950501/1331659754229202974 最终版不需要正则，在前面几个版本，为了适配油猴插件生图还需要添加两个正则，将生图标签《换成###。
  Img
本地部署方案
- SD安装教程
- ComfyUI教程
其他方案
- DC-小画师

7. 使用建议#

配置顺序
- 先完成API连接
- 设置基础预设
- 配置正则规则
- 导入角色和世界观
优化建议
- 定期更新配置
- 保存成功设置
- 参考社区经验
注意事项
- 定期备份数据
- 关注版本更新
- 保持设置统一

详细知识可以参考酒馆入门（必修）

ZeroTier实现手机远程访问SillyTavern配置指南

Wed, 22 Jan 2025 00:00:00 GMT

前言#

想在外面也能用手机访问电脑上的酒馆(Silly Tavern)吗?今天我们就来介绍一个简单好用的解决方案 - ZeroTier。

ZeroTier是什么?#

ZeroTier 是一个强大的虚拟局域网工具,它可以让不同地方的设备组成一个虚拟局域网,就像这些设备都在同一个网络中一样。它的优点包括:

🚀 无需公网IP
🔧 无需复杂的路由器设置
🛡️ 安全可靠的连接
🌐 跨平台支持
💻 简单易用

具体操作步骤#

1. 下载安装#

首先我们需要在电脑和手机上都安装 ZeroTier:

电脑端:

访问 ZeroTier官网
下载对应系统的版本(Windows用户选择Microsoft Windows)
下载界面

手机端:

访问 Android下载链接
安装后打开设置(Settings)
开启移动数据权限(Allow mobile data),否则可能无法正常连接

2. 创建网络#

注册并登录 ZeroTier 官网后,点击 “Create A Network” 创建新网络:
创建网络按钮
进入新创建的网络后:
- 复制网络ID(后面要用)
- 在Settings中修改name(网络名称)和description(描述)
- 将网络类型设为private(私有网络)
  网络设置界面

3. 手机端配置#

打开手机上的ZeroTier应用,点击”Add Network”,输入刚才复制的网络ID:
添加网络
添加完成后,点击右侧的开关启动连接:
启动连接
此时设备会显示等待认证状态,我们需要去官网进行认证:
等待认证
在官网找到新加入的设备,点击勾选进行认证。认证成功后会显示绿色的勾:
认证成功
这时候可以点击”Edit”给设备起个好记的名字,比如”我的手机”
回到手机,重新连接网络,当状态显示”Connected”时就表示连接成功了:
连接成功

💡 小贴士:

每张图都展示了具体的操作界面,建议对照着图片操作

注意保存好网络ID,这是连接的重要凭证

设备名称建议设置得容易识别,方便后续管理

4. 电脑端配置#

右键点击任务栏的ZeroTier图标
选择”Join Network”
输入网络ID并确认

5. 配置酒馆#

找到Silly Tavern的配置文件(config.yaml)
修改相关网络设置
酒馆配置

6. 开始使用#

现在,你可以在手机浏览器中输入:

1
http://[ZeroTier分配的IP]:8000

就能访问电脑上的酒馆了!

🌟 小贴士:

确保两个设备都连接到了同一个ZeroTier网络

记得保存好网络ID

如果连接不上,检查一下设备是否已通过认证

建议给设备起个容易识别的名字

现在,你可以在外面也能随时访问自己的酒馆了,是不是很方便呢? 😊

Nonebot2 QQ机器人部署实战（1）：环境配置

Tue, 21 Jan 2025 00:00:00 GMT

QQ机器人搭建教程：基于 Nonebot2 框架#

随着QQ机器人技术的发展，我们现在有了更好的选择。本教程将介绍如何使用最新的 QQNT 框架搭建你的机器人。

环境准备#

Python环境#

推荐使用 Python 3.10 版本
⚠️ 注意：暂不建议使用 Python 3.12，可能存在兼容性问题

框架选择#

目前主流的 QQ 机器人框架有：

LLOneBot（推荐）：新一代 QQNT 框架
NapcatBot：基于 QQNT 的另一个选择
go-cqhttp（已过时）：不再推荐使用

为了更好的理解和搭建Nonebot2，我们先来看一下Nonebot2的消息处理流程图：

Nonebot2消息处理流程图

项目创建与配置#

1. 安装项目管理工具#

首先，我们需要安装 pipx。它是一个专门用于安装和运行 Python 应用的工具，能够避免全局依赖冲突。

Terminal window

1
# 安装 pipx
2
python -m pip install --user pipx
3

4
# 将 pipx 添加到环境变量
5
python -m pipx ensurepath

💡 小贴士：使用 pipx 安装工具可以避免污染全局 Python 环境

2. 安装 Nonebot2 脚手架#

nb-cli 是 Nonebot2 官方提供的命令行工具，它能帮助我们：

快速创建项目
管理项目配置
安装和管理插件
启动和调试机器人

Terminal window

1
pipx install nb-cli

⚠️ 安装完成后，可以使用 nb --version 检查是否安装成功

3. 创建 Nonebot2 项目#

使用 nb-cli 创建新项目：

Terminal window

1
nb create

在创建过程中，你需要回答一系列配置问题。以下是每个选项的详细说明：

Terminal window展开收起

1
[?] 项目名称: mybot
2
    # 设置你的项目名称，建议使用小写字母
3

4
[?] 要使用哪些适配器? OneBot V11 (OneBot V11 协议)
5
    # OneBot V11 是最常用的协议，支持 LLOneBot
6

7
[?] 要使用哪些驱动器? FastAPI (FastAPI 驱动器)
8
    # FastAPI 提供高性能的异步支持
9

10
[?] 请输入插件存储位置: 2) 在 "src" 文件夹中
11
    # 推荐选择 src 目录，便于管理
12

13
[?] 立即安装依赖? y
14
    # 自动安装必要的依赖包
15

16
[?] 创建虚拟环境? y
17
    # 创建独立的项目环境
18

19
[?] 要使用哪些内置插件? echo
20
    # echo 插件用于测试机器人是否正常工作

展开收起

创建完成后，你会看到以下提示：

Terminal window

1
在 mybot\.venv 中创建虚拟环境...
2
完成!
3

4
使用 poetry 或 pdm 等依赖管理工具添加以下包:
5
  nonebot-adapter-onebot nonebot2[fastapi]
6

7
运行以下命令来启动你的机器人:
8
  cd mybot
9
  nb run --reload

4. 项目目录结构#

创建完成后，你的项目结构应该是这样的：

1
mybot/
2
├── .env                # 环境配置文件
3
├── .gitignore         # Git 忽略文件
4
├── bot.py             # 机器人入口文件
5
├── pyproject.toml     # 项目依赖配置
6
└── src/               # 源代码目录
7
    └── plugins/       # 插件目录

5. 启动项目#

Terminal window

1
# 进入项目目录
2
cd mybot
3

4
# 启动机器人（开发模式）
5
nb run --reload

当你看到如下界面，说明 Nonebot2 已经成功启动：

Nonebot2启动成功

🔍 启动参数说明：

--reload：开发模式，代码修改后自动重载

--port 8080：指定端口（默认 8080）

--host 0.0.0.0：允许外部访问

6. 常见问题#

如果遇到依赖安装失败：

Terminal window

1
# 手动安装核心依赖
2
pip install nonebot2[fastapi]
3
pip install nonebot-adapter-onebot

端口被占用：

Terminal window

1
# 修改 .env 文件中的端口配置
2
DRIVER=fastapi
3
HOST=127.0.0.1
4
PORT=8081  # 改为其他未被占用的端口

找不到 nb 命令：

Terminal window

1
# 检查 PATH 环境变量
2
echo $PATH
3

4
# 重新安装 nb-cli
5
pipx reinstall nb-cli

🌟 提示：创建项目后，建议先测试 echo 插件，确保基础功能正常，再进行后续配置。

7. 配置 LLOneBot#

LLOneBot 是一个 LiteLoaderQQNT 插件，它实现了 OneBot V11 协议，让我们能够通过 Nonebot2 开发 QQ 机器人。

LLOneBot

Waiting for api.github.com...

00K

Waiting...

安装步骤：

下载并安装 QQNT 客户端
使用一键安装脚本安装 LLOneBot：
- 访问 LLOneBot 安装脚本
- 按照说明进行安装
- 运行配置向导

配置 LLOneBot：

登录 QQ 后，打开 QQNT 左下角的设置
找到 LLOneBot 设置选项
配置反向 WebSocket：
LLOneBot配置
- 第一个地址用于连接 Nonebot2（默认端口 8080）
- 第二个地址可用于其他服务（如 Koishi）

当你看到以下日志时，说明连接成功：

1
[INFO] nonebot | OneBot V11 | Bot XXXXXXXXXX connected

连接成功

8. 测试机器人#

让我们来测试内置的 echo 插件：

在 QQ 中发送：@机器人 echo 你好
机器人会回复：你好
Echo测试

🎉 恭喜！如果机器人正确回复了消息，说明你的 QQ 机器人已经搭建成功了！

接下来，你可以开始开发自己的插件，让机器人拥有更多有趣的功能。

Nonebot2——QQ机器人搭建教程（2）：插件开发实战

Tue, 21 Jan 2025 00:00:00 GMT

Nonebot2 插件开发教程 - 零基础入门#

一、创建你的第一个插件#

让我们从最简单的开始 - 创建一个能说”你好”的插件。

首先使用 nb-cli 创建插件:

Terminal window

1
nb plugin create

创建插件

这会在 plugins 目录下创建如下结构:

1
plugins/
2
└── hello/              # 插件目录
3
    ├── __init__.py    # 插件主文件
4
    └── config.py      # 配置文件

让我们来看看这个最基础的插件代码:

1
from nonebot import on_command                        # 导入命令处理器
2
from nonebot.adapters.onebot.v11 import Bot, Event   # 导入机器人和事件对象
3
from nonebot.plugin import PluginMetadata            # 导入插件元数据
4

5
# 定义插件元信息
6
__plugin_meta__ = PluginMetadata(
7
    name="示例插件",           # 插件名称
8
    description="这是一个示例插件", # 插件描述
9
    usage="@机器人 hello"      # 使用方法
10
)
11

12
# 注册一个命令处理器
13
hello = on_command(
14
    "hello",           # 命令名称
15
    priority=10        # 优先级(数字越小优先级越高)
16
)
17

18
# 编写命令处理函数
19
@hello.handle()  # 使用装饰器注册处理函数
20
async def hello_handler(bot: Bot, event: Event):
21
    await hello.finish("你好！我是你的机器人助手～")

展开收起

运行效果:

运行效果

代码解析#

导入必要模块
- on_command: 用于注册命令
- Bot: 机器人对象,用于调用QQ API
- Event: 事件对象,包含消息内容等信息
- PluginMetadata: 用于定义插件信息

定义插件元数据

1
__plugin_meta__ = PluginMetadata(
2
    name="示例插件",          # 插件名称
3
    description="示例描述",    # 插件描述
4
    usage="使用说明"          # 使用方法
5
)

这些信息会在帮助系统中显示

注册命令处理器
```
1
hello = on_command("hello")
```
- 当用户发送 /hello 时会触发这个命令
- 默认命令前缀是 /
- 可以通过配置更改前缀
编写处理函数
```
1
@hello.handle()
2
async def hello_handler(bot: Bot, event: Event):
3
    await hello.finish("回复消息")
```
- 使用 @handle() 装饰器注册处理函数
- 函数必须是异步的(async)
- finish() 会发送消息并结束处理

💡 小贴士:

命令名称对大小写敏感

可以设置多个命令别名

处理函数可以获取更多信息(如发送者QQ号)

可以发送更复杂的消息(如图片)

通过这个简单的例子,我们了解了插件的基本结构。接下来,让我们看看如何开发更实用的功能…

二、模块导入与配置系统#

2.1 常用模块导入#

1
# 1. 核心功能模块
2
from nonebot import on_command, on_shell_command  # 命令注册
3
from nonebot.plugin import PluginMetadata, require  # 插件元数据和依赖
4
from nonebot.rule import ArgumentParser  # 命令参数解析
5
from nonebot.log import logger  # 日志记录
6

7
# 2. 适配器模块
8
from nonebot.adapters.onebot.v11 import (
9
    Bot,                # 机器人对象
10
    Event,             # 事件基类
11
    MessageEvent,      # 消息事件
12
    GroupMessageEvent, # 群消息事件
13
    PrivateMessageEvent,# 私聊消息事件
14
    Message,           # 消息类
15
    MessageSegment,    # 消息段
16
)
17

18
# 3. 权限控制模块
19
from nonebot.permission import (
20
    SUPERUSER,         # 超级用户
21
    GROUP_ADMIN,       # 群管理员
22
    GROUP_OWNER,       # 群主
23
)
24

25
# 组合权限
26
ADMIN = SUPERUSER | GROUP_ADMIN | GROUP_OWNER  # 超管或群管理或群主

展开收起

💡 提示：

按功能分类导入模块,便于管理

使用 from xxx import (...) 可以一次导入多个内容

权限可以用 | 组合

2.2 配置系统详解#

Nonebot2 提供了两种配置方式,让我们详细了解一下:

2.2.1 全局配置#

全局配置适用于整个机器人的通用设置:

1
from nonebot import get_driver
2

3
# 1. 获取全局配置（.env文件）
4
global_config = get_driver().config
5

6
# 2. 使用全局配置
7
HOST = global_config.host        # 机器人服务器地址
8
PORT = global_config.port        # 服务器端口
9
SUPERUSERS = global_config.superusers  # 超级用户列表
10
COMMAND_START = global_config.command_start  # 命令前缀

💡 全局配置说明:

通过 get_driver().config 获取

适合存放机器人级别的配置

所有插件都可以访问

通常在 .env 文件中设置

2.2.2 插件配置#

插件配置用于单个插件的专属设置:

定义配置类 (config.py)

1
from pydantic import BaseModel, Extra
2

3
class Config(BaseModel, extra=Extra.ignore):
4
    """AI绘图插件配置"""
5
    # API设置
6
    api_key: str         # API密钥(必填,无默认值)
7
    api_url: str = ""    # API地址(选填,有默认值)
8

9
    # 功能设置
10
    daily_limit: int = 10      # 每日使用次数
11
    save_image: bool = False   # 是否保存图片
12

13
    # 高级设置
14
    proxy: str = None    # 代理地址
15
    timeout: int = 60    # 超时时间(秒)

展开收起

使用插件配置 (init.py)

1
from nonebot import get_plugin_config
2
from .config import Config  # 从同目录导入
3

4
# 获取插件配置
5
plugin_config = get_plugin_config(Config)
6

7
# 使用配置
8
if not plugin_config.api_key:
9
    logger.error("未设置API密钥!")
10

11
daily_limit = plugin_config.daily_limit
12
save_image = plugin_config.save_image

2.2.3 配置优先级机制#

当同一个配置项在多个地方定义时,会按照优先级从高到低加载:

1
# 1. 最高优先级: 环境变量
2
# 在系统中设置
3
export API_KEY="env_key_123"
4

5
# 2. 次高优先级: .env文件
6
# .env
7
API_KEY=env_file_key_456
8
DAILY_LIMIT=20
9

10
# 3. 最低优先级: 配置类默认值
11
class Config(BaseModel):
12
    api_key: str = "default_key_789"
13
    daily_limit: int = 10

实际运行时:

1
from nonebot import get_plugin_config
2
from .config import Config
3

4
plugin_config = get_plugin_config(Config)
5

6
# 如果环境变量存在,使用环境变量的值
7
print(plugin_config.api_key)  # 输出: env_key_123
8

9
# 如果环境变量不存在,但.env文件有配置,使用.env的值
10
print(plugin_config.daily_limit)  # 输出: 20
11

12
# 如果环境变量和.env都没有,使用默认值
13
print(plugin_config.timeout)  # 输出: 60(默认值)

💡 优先级说明:

环境变量 > .env文件 > 默认值

高优先级的值会覆盖低优先级的值

如果高优先级没有设置,会继续查找低优先级

如果都没有设置且没有默认值,会报错

这种机制的好处:

可以在不修改代码的情况下覆盖配置
敏感信息可以通过环境变量注入
.env文件便于管理常用配置
默认值保证基础功能可用

三、事件处理系统#

3.1 注册事件处理器#

Nonebot2 提供了多种事件处理器:

1
# 1. 命令处理器(最常用)
2
cmd = on_command(
3
    "命令名",                # 命令名称
4
    aliases={"别名1", "别名2"},  # 命令别名
5
    priority=10,            # 优先级(数字越小优先级越高)
6
    block=True,             # 是否阻止事件传递
7
    permission=ADMIN        # 权限控制
8
)
9

10
# 2. shell命令处理器(适合复杂参数)
11
draw = on_shell_command(
12
    "draw",                # 命令名
13
    parser=draw_parser,    # 参数解析器
14
    priority=10
15
)
16

17
# 3. 关键词处理器
18
kw = on_keyword({"你好", "hello"})  # 触发关键词
19

20
# 4. 正则处理器
21
rex = on_regex(r"\d+")             # 匹配数字

展开收起

3.2 命令参数解析#

在使用 on_shell_command 时,我们常常需要处理复杂的命令参数。这时就需要用到 ArgumentParser:

1
from nonebot.rule import ArgumentParser
2

3
# 创建命令解析器
4
draw_parser = ArgumentParser(description="AI绘图命令")
5

6
# 1. 添加位置参数(必填)
7
draw_parser.add_argument(
8
    "prompt",           # 参数名
9
    nargs="*",         # 参数个数(*表示任意多个)
10
    help="绘图提示词",   # 参数说明
11
    type=str           # 参数类型
12
)
13

14
# 2. 添加可选参数
15
draw_parser.add_argument(
16
    "-n", "--negative",  # 参数别名
17
    nargs="*",          # 参数个数
18
    help="负面提示词",    # 参数说明
19
    type=str,           # 参数类型
20
    dest="negative"      # 存储变量名
21
)
22

23
# 3. 添加开关参数
24
draw_parser.add_argument(
25
    "--r18",           # 参数名
26
    action="store_true", # 存在即为True
27
    help="是否开启R18"   # 参数说明
28
)

展开收起

参数类型说明:

位置参数
- 不带 - 的参数
- 按位置顺序填写
- 不指定 default 时为必填
- 例: /draw 猫娘
可选参数
- 以 - 或 -- 开头
- 可以不按顺序
- 可以设置默认值
- 例: /draw 猫娘 -n 低画质
开关参数
- 不需要值的参数
- 存在即为True
- 例: /draw 猫娘 --r18

使用示例:

1
@draw.handle()
2
async def handle_draw(bot: Bot, event: MessageEvent, args: Namespace):
3
    # 获取参数值
4
    prompt = " ".join(args.prompt) if args.prompt else ""  # 提示词
5
    negative = " ".join(args.negative) if args.negative else ""  # 负面词
6
    is_r18 = args.r18  # 是否R18
7

8
    await draw.send(
9
        f"收到绘图请求:\n"
10
        f"提示词: {prompt}\n"
11
        f"负面词: {negative}\n"
12
        f"R18: {'是' if is_r18 else '否'}"
13
    )

命令示例:

Terminal window

1
/draw 猫娘 可爱                  # 基础用法
2
/draw 猫娘 -n 低画质 --r18       # 完整参数
3
/draw                          # 无参数(会报错)

💡 提示:

nargs="*" 表示参数可以有多个值

type=str 指定参数类型(str/int/float等)

dest 指定参数在 Namespace 中的变量名

必填参数没有默认值时,不填会报错

使用 help 说明参数用途

3.3 消息发送#

Nonebot2 提供了多种消息发送方式:

1
# 1. 基础消息发送
2
await cmd.send("普通文本")                     # 发送文本
3
await cmd.send("你好!", at_sender=True)       # @发送者
4
await cmd.finish("结束处理")                   # 发送并结束处理
5

6
# 2. 复杂消息发送
7
from nonebot.adapters.onebot.v11 import MessageSegment
8

9
# 发送图片
10
await cmd.send(MessageSegment.image("图片路径"))
11

12
# 发送表情
13
await cmd.send(MessageSegment.face(1))
14

15
# 发送@
16
await cmd.send(MessageSegment.at(user_id))
17

18
# 组合消息
19
msg = (
20
    MessageSegment.text("结果：\n") +
21
    MessageSegment.image("result.png") +
22
    MessageSegment.at(user_id)
23
)
24
await cmd.send(msg)
25

26
# 3. 合并转发消息(群聊)
27
msgs = []
28
for text in message_list:
29
    msgs.append({
30
        "type": "node",
31
        "data": {
32
            "name": "机器人",
33
            "uin": bot.self_id,
34
            "content": text
35
        }
36
    })
37
await bot.call_api(
38
    "send_group_forward_msg",
39
    group_id=event.group_id,
40
    messages=msgs
41
)

展开收起

3.4 权限控制#

1
# 1. 基础权限
2
SUPERUSER         # 超级用户
3
GROUP_ADMIN       # 群管理员
4
GROUP_OWNER       # 群主
5

6
# 2. 组合权限
7
ADMIN = SUPERUSER | GROUP_ADMIN | GROUP_OWNER  # 超管或群管理
8

9
# 3. 使用权限
10
cmd = on_command("admin", permission=ADMIN)
11

12
# 4. 手动检查权限
13
if event.get_user_id() in bot.config.superusers:
14
    await cmd.finish("您是超级用户!")
15

16
if isinstance(event, GroupMessageEvent):
17
    if event.sender.role in ["admin", "owner"]:
18
        await cmd.finish("您是群管理!")

展开收起

3.5 异常处理#

1
@cmd.handle()
2
async def handler(bot: Bot, event: MessageEvent):
3
    try:
4
        # 处理逻辑...
5
        result = await some_api()
6

7
    except NetworkError:
8
        # 网络错误
9
        logger.error("网络错误")
10
        await cmd.finish("网络错误,请稍后再试!")
11

12
    except ApiError as e:
13
        # API错误
14
        logger.error(f"API错误: {e}")
15
        await cmd.finish("处理失败,请检查参数!")
16

17
    except Exception as e:
18
        # 其他错误
19
        logger.exception(f"未知错误: {e}")
20
        await cmd.finish("发生未知错误!")

展开收起

💡 提示:

合理使用日志记录错误

给用户友好的错误提示

避免直接暴露错误细节

重要操作要有异常处理

通过以上内容,我们掌握了:

如何注册各类事件处理器
如何获取事件信息
如何发送各种消息
如何进行权限控制
如何处理异常

接下来让我们通过实战案例来运用这些知识…

四、实战示例 - AI绘图插件#

让我们通过开发一个 AI 绘图插件,来实践前面学到的知识。这个插件可以:

通过命令生成 AI 图片
支持自定义提示词
有冷却和次数限制
支持黑名单管理

4.1 插件结构#

首先创建插件目录:

1
plugins/
2
└── nonebot_plugin_nai3/
3
    ├── __init__.py    # 主要逻辑
4
    ├── config.py      # 配置文件
5
    └── utils.py       # 工具函数

4.2 定义配置#

在 config.py 中设置插件配置:

1
from pydantic import BaseModel
2
from nonebot import get_plugin_config
3

4
class Config(BaseModel):
5
    """插件配置类"""
6
    # API设置
7
    nai3_token: str = ""        # API密钥
8
    nai3_proxy: str = None      # 代理地址
9

10
    # 使用限制
11
    nai3_limit: int = 10        # 每人每天次数
12
    nai3_cd_group: int = 30     # 群冷却时间(秒)
13
    nai3_cd_user: int = 300     # 用户冷却时间(秒)
14

15
    # 其他设置
16
    nai3_r18: bool = False      # 是否允许R18
17
    nai3_save: bool = False     # 是否保存图片
18

19
# 获取配置
20
plugin_config = get_plugin_config(Config)

展开收起

💡 知识点:

使用 BaseModel 定义配置类

给配置项添加类型注解

设置合理的默认值

用 get_plugin_config 获取配置

4.3 注册命令#

在 __init__.py 中注册命令:

1
from nonebot import on_shell_command
2
from nonebot.rule import ArgumentParser
3
from nonebot.permission import SUPERUSER, GROUP_ADMIN, GROUP_OWNER
4

5
# 1. 创建命令解析器
6
parser = ArgumentParser(description='AI绘图')
7
parser.add_argument("prompt", help="提示词")     # 必填参数
8
parser.add_argument("-n", "--negative", help="负面词")  # 可选参数
9

10
# 2. 注册命令
11
draw = on_shell_command(
12
    "draw",              # 命令名
13
    parser=parser,       # 参数解析器
14
    priority=10          # 优先级
15
)
16

17
# 3. 注册管理命令
18
ADMIN = SUPERUSER | GROUP_ADMIN | GROUP_OWNER  # 组合权限

展开收起

💡 知识点:

on_shell_command 支持复杂参数

ArgumentParser 用于解析参数

可以组合多个权限

优先级越小越优先处理

4.4 命令处理机制#

在 Nonebot2 中,命令处理是最核心的功能之一。让我们详细了解如何处理不同类型的命令:

4.4.1 基础命令处理#

1
# 1. 简单命令处理
2
help_cmd = on_command("帮助")
3

4
@help_cmd.handle()
5
async def _(event: MessageEvent):
6
    await help_cmd.finish("这是帮助信息")

💡 知识点:

on_command 用于注册简单命令

通过装饰器处理命令

使用 finish 发送消息并结束处理

4.4.2 可选参数处理#

在 ArgumentParser 中,可选参数(Optional Arguments)的处理方式如下:

1
# 1. 注册可选参数
2
parser = ArgumentParser(description='AI绘图')
3
parser.add_argument(
4
    "-n", "--negative",     # 短格式和长格式
5
    nargs="*",             # 参数个数(*表示任意多个)
6
    help="负面提示词",      # 参数说明
7
    type=str,             # 参数类型
8
    default=None,         # 默认值
9
    dest="negative"       # 存储的变量名
10
)
11

12
parser.add_argument(
13
    "-r", "--resolution",  # 分辨率参数
14
    choices=["pc", "mb", "sq"],  # 限制可选值
15
    default="mb",         # 默认值
16
    help="画布比例"        # 参数说明
17
)
18

19
# 2. 处理参数
20
@draw.handle()
21
async def handle_draw(args: Namespace):
22
    # 获取参数值
23
    negative = args.negative  # 通过dest指定的名称访问
24
    resolution = args.resolution
25

26
    # 处理分辨率
27
    if resolution == "mb":
28
        width, height = 832, 1216  # 手机比例
29
    elif resolution == "pc":
30
        width, height = 1216, 832  # 电脑比例
31
    else:
32
        width = height = 1024      # 正方形

展开收起

💡 可选参数说明:
参数格式:

短格式: -n, -r (单个横杠)

长格式: --negative, --resolution (双横杠)

参数配置:

nargs="*": 可以接收多个值

choices: 限制可选值范围

default: 设置默认值

dest: 指定存储变量名
使用示例:
Terminal window
1
/draw 猫娘 -n 低画质 模糊     # negative=["低画质", "模糊"]
2
/draw 猫娘 --negative 低画质  # 同上,使用长格式
3
/draw 猫娘 -r pc            # resolution="pc"
4
/draw 猫娘                  # 使用默认值

4.4.3 参数处理最佳实践#

设置默认值

1
parser.add_argument("-n", default="bad quality")  # 不填时使用默认值

限制参数范围

1
parser.add_argument("-s", type=float, choices=[1.0, 2.0, 3.0])  # 限制可选值

参数验证

1
@draw.handle()
2
async def _(args: Namespace):
3
    if args.scale < 1.0 or args.scale > 10.0:
4
        await draw.finish("参数范围错误!")

🌟 开发建议:

合理设置默认值,避免None判断

使用choices限制参数范围

添加参数验证保证安全

给出友好的错误提示

文档说明参数用法

4.5 使用示例#

有了上面的处理机制,我们的插件就可以支持以下命令格式:

基础命令

Terminal window

1
/draw 猫娘 可爱          # 空格分隔的多个提示词
2
/draw 猫娘 -n 低画质     # 指定负面词
3
/draw 猫娘 -r pc        # 指定图片比例

管理命令

Terminal window

1
/draw_black 添加用户123   # 不带空格也可以
2
/draw_black 添加 用户 123 # 带空格也可以

🌟 开发建议:

简单命令用 on_command

复杂参数用 ArgumentParser

灵活命令用字符串处理

根据需求选择合适方式

做好参数验证和异常处理

五、常见问题#

命令不触发

检查命令前缀(默认 /)
检查权限设置
检查优先级是否被其他插件覆盖

发送消息失败

检查是否触发风控
确认消息格式正确
路径使用绝对路径

配置不生效

检查配置文件格式
确认配置加载正确
重启机器人

🌟 进阶提示:

合理使用日志记录问题

善用调试工具

查看官方文档获取更多信息

总结#

编写 Nonebot2 插件的主要步骤和关键知识点:

1. 创建插件目录#

1
plugins/
2
└── nonebot_plugin_nai3/
3
    ├── __init__.py    # 主要逻辑
4
    ├── config.py      # 配置文件
5
    └── utils.py       # 工具函数

💡 知识点:

插件命名规范: nonebot_plugin_xxx

目录结构划分

模块化组织代码

2. 定义配置#

1
class Config(BaseModel):
2
    api_key: str
3
    daily_limit: int = 10

💡 知识点:

使用 BaseModel 定义配置类

全局配置 vs 插件配置

配置优先级机制

环境变量加载

配置命名规范

3. 注册命令#

1
draw = on_shell_command("draw", parser=parser)
2
admin = on_command("admin", permission=ADMIN)

💡 知识点:

命令注册方式

参数解析器使用

命令别名设置

优先级控制

权限设置

4. 处理事件#

1
@draw.handle()
2
async def handle_draw(event: MessageEvent):
3
    user_id = event.user_id
4
    message = event.get_message()

💡 知识点:

事件处理装饰器

事件类型判断

消息内容获取

参数解析处理

异步处理机制

5. 发送消息#

1
await bot.send(event, "文本消息")
2
await bot.send(event, MessageSegment.image(path))

💡 知识点:

消息发送方式

MessageSegment 使用

合并转发消息

消息构建方法

定时发送消息

6. 权限控制#

1
ADMIN = SUPERUSER | GROUP_ADMIN | GROUP_OWNER

💡 知识点:

权限等级设置

权限组合使用

权限检查方法

自定义权限

权限继承关系

7. 异常处理#

1
try:
2
    await process()
3
except NetworkError:
4
    await bot.send("网络错误")

💡 知识点:

异常类型定义

错误日志记录

异常捕获处理

用户友好提示

错误恢复机制

🌟 开发建议:

先规划好功能再动手

做好配置的规范定义

合理组织代码结构

加强异常处理

编写清晰的文档

注意代码复用

保持良好的注释

参考资料:

Alist网盘挂载系统部署指南

Mon, 20 Jan 2025 00:00:00 GMT

Alist 网盘挂载教程：打造你的云端文件管理系统#

前期准备#

一台可以访问公网的服务器或云电脑（Windows/Linux 均可）
需要挂载的网盘账号信息（支持多种网盘类型）

快速开始#

1. 获取 Alist#

访问 Alist 官方仓库

AlistGo

alist

Waiting for api.github.com...

00K

Waiting...

在 Releases 页面下载最新版本
选择适合你系统的安装包
💡 小贴士：Windows 用户选择 alist-windows-amd64.zip，解压后即可使用

2. 启动 Alist#

解压下载的安装包
在文件夹地址栏输入 powershell 并回车
执行启动命令：
Terminal window
```
1
./alist.exe server
```
⚠️ 重要提示：首次启动时系统会自动生成管理员账号和密码，请务必保存好

3. 开始使用#

浏览器访问 http://localhost:5244
使用生成的管理员账号登录
🔑 默认管理员用户名：admin

4. 配置外部访问#

如果需要外网访问，需要在服务器控制面板开放端口：

服务器端口配置

配置说明：

内部端口：填写 5244（Alist 默认端口）
外部端口：可以保持相同，或设置其他未被占用的端口，这会开启一个外网访问的端口，这个端口用于访问Alist 之后访问地址就是http://ip:外部端口就可以访问到Alist了

添加网盘存储#

基础配置#

进入后台的”存储管理”
点击右上角的”添加”按钮
选择要挂载的网盘类型
填写配置信息
存储管理界面

添加存储界面

配置项说明#

🔍 重要参数解释：

驱动：选择网盘类型

挂载路径：网盘在 Alist 中的访问路径

序号：决定网盘显示顺序

缓存过期时间：文件列表的缓存时间

WebDAV 策略：WebDAV 访问方式

下载代理URL：用于加速下载

启用签名：文件防盗链保护

Cookie：网盘登录凭证

根目录ID：网盘根目录标识

夸克网盘配置实例#

选择”夸克网盘”驱动
填写关键信息：
- 挂载路径：/夸克网盘（可自定义）
- Cookie：从网页版获取
  Cookie 获取
- 根目录 ID：可选配置
  根目录配置

💡 获取 Cookie 技巧：

登录夸克网盘网页版

按 F12 打开开发者工具

切换到 Network 标签页

刷新页面，在请求中找到 Cookie 信息

配置完成后，可以在主页看到挂载的网盘：

挂载成功界面

PikPak 网盘配置实例#

🔍 PikPak 网盘的配置虽然和夸克网盘类似，但在获取登录凭证时有些特别之处。

基础配置#

选择”PikPak 网盘”驱动
填写基本信息：
- 挂载路径：/PikPak（可自定义）
- 其他带 * 号的必填项

获取 refresh_token#

由于 PikPak 最新的登录机制变更，我们需要特别的方式来获取 refresh_token：

简单方法：
💡 推荐使用在线工具获取：PikPak Token 获取工具
- 访问工具网站
- 输入账号密码
- 直接获取 refresh_token

参考详细教程：PikPak登录接口，配合 Alist 使用

⚠️ 注意事项：

refresh_token 有效期较长，但不是永久的

建议保存好获取到的 token

如果挂载失败，优先检查 token 是否过期

配置完成后，就可以像使用其他网盘一样访问你的 PikPak 文件了。

进阶功能配置#

访问密码保护
自定义访问端口
WebDAV 服务配置
文件在线预览
离线下载功能

常见问题解决#

服务无法启动
- 检查端口占用情况
- 确认管理员权限
- 查看运行日志
网盘连接失败
- 验证配置信息准确性
- 检查 Cookie 有效期
- 确认网络连接状态

使用小贴士#

定期备份系统配置
及时更新到最新版本
妥善保存管理凭据
合理设置缓存时间

GitHub Copilot学生认证申请指南

Sat, 18 Jan 2025 00:00:00 GMT

Copilot学生包白嫖教程#

白嫖前提#

前提是在校学生，且有学校邮箱，当然也得有Github账户
前往学信网下载教育部学籍在线验证报告
将报告转换成英文版本，这是我使用的是插件沉浸式翻译中的一个功能

具体流程#

设置Github个人信息 来到 https://github.com/settings/profile 界面补充个人信息主要填写 Name(和报告英文版本一致)、Bio，最后Update profile

获取教育邮箱 一般直接去网上搜索学校名字+邮箱系统即可，具体账号密码学校应该会提示你，登录进去之后是管理界面，之后copilot会发送邮件通知你

准备教育部学籍在线验证报告 前往学信网登录之后，选择在线验证报告之后即可免费下载，接着将PDF导入沉浸式翻译，修改元素为英文的即可

申请GitHub Student Developer Pack 申请地址

Img

首先勾选学校邮箱 .edu.cn 后会自动填写 the name of school，然后写一段理由，Continue

接着来到上传图片界面，上传刚才翻译好的英文学籍报告即可，这一步要关闭代理，同时要同意验证地理位置

Img

上传好之后，正常就会出现这个界面

Img

接着学校邮箱就会收到通过的邮件，如图

Img

根据信息一个一个修改即可，比如第二个双重信息验证，可以去Google下一个插件完成之后，继续发送，成功之后会显示

Img

这个时候权益还没到账，我这里过了五天，权益到账了，Approve会变成蓝色

Img

说明权益到账了，现在就可以去插件市场下载Copilot插件免费使用了

Fuwari博客部署：从Fork到上线完整流程

Sat, 18 Jan 2025 00:00:00 GMT

Fuwari+Vercel博客搭建教程#

搭建前准备#

在开始搭建博客之前，我们需要准备以下工具和环境：

基本思维能力：遇到问题时，建议按照以下顺序解决h:\代码\fuwari博客\fuwari-moli721\src\content\spec\about.md$0：
- 先自己思考分析问题
- 善用搜索引擎（Google、必应等）
- 尝试询问 AI 助手（ChatGPT、Claude 等）
- 实在解决不了再去论坛或社区提问
Git：版本控制工具，用于管理代码和与 GitHub 交互
- 下载地址：Git 官网
- 新手也可以选择使用图形界面的 GitHub Desktop，但个人建议还是学习使用命令行，长远来看更实用
Node.js：JavaScript 运行环境
- 下载地址：Node.js 官网
- Fuwari 是基于 Node.js 开发的，所以这是必需品
- 建议选择 LTS（长期支持）版本
GitHub 账号：
- 用于存储博客源代码
- 也方便进行版本管理和多设备同步
Vercel 账号：
- 用于部署和托管博客
- 提供免费的静态网站托管服务
- 可以直接用 GitHub 账号登录
Markdown 编辑器：推荐使用 YankNote
- 界面清爽，功能强大
- 支持实时预览
- 功能丰富，支持代码高亮、数学公式、流程图、思维导图等
- 当然你也可以选择其他编辑器，如 Typora、VS Code 等
Markdown 基础知识：
- Markdown 是一种轻量级标记语言
- 用于编写结构化文档
- 语法简单易学
- 可以参考 Markdown 官方教程快速入门

有了这些准备，我们就可以开始搭建属于自己的博客了！

开始搭建#

打开Fuwari，点击右上角的fork，然后点击Create fork，将Fuwari项目fork到自己的GitHub账号下
在本地选择一个文件夹，使用Git，输入以下命令：

Terminal window

1
git clone https://github.com/你的GitHub账号/fuwari.git

进入项目目录，首先，全局安装pnpm：npm install -g pnpm（如果npm国内拉取过慢，请尝试cnpm：npm install -g cnpm），然后安装依赖，输入以下命令：

Terminal window

1
pnpm install
2
pnpm add sharp

安装完成后，输入以下命令：

Terminal window

1
pnpm dev

在浏览器中打开http://localhost:4321，就可以看到博客的预览页面了
Img

到这里，博客就已经搭建完成了，接下来，我们需要配置博客

基础配置修改#

首先，我们需要打开 src/config.ts 文件来个性化你的博客。这个文件包含了博客的核心配置信息：

配置文件位置

基本信息设置#

博客标题设置
- title：设置你的博客主标题
- subtitle：设置博客副标题（可选）。这两个会在首页组合显示为”主标题 - 副标题”的形式
界面设置
- lang：设置博客的显示语言
  - 支持的语言包括：英文(en)、简体中文(zh_CN)、繁体中文(zh_TW)、日语(ja)、韩语(ko)等
- themeColor：设置博客的主题色
  - 你可以点击博客右上角的调色板图标，选择喜欢的颜色，然后填写对应的数值
    主题色设置

图片和链接配置#

网站装饰
- banner.src：设置网站顶部的横幅图片（支持 http/https 链接）
- favicon.src：设置网站图标，就是浏览器标签页显示的小图标（支持 http/https 链接）
- links：设置导航栏上的友情链接
个人信息
- avatar：设置你的头像
- name：填写你的名字
- bio：设置个性签名，会显示在头像和名字的下方

导航栏和社交链接#

网站有两个主要的链接区域：

NavBarConfig：配置导航栏的链接
ProfileConfig：配置个人资料区域的社交媒体链接
导航设置示例

图标设置#

Fuwari 内置了多种图标库支持：fa6-brands、fa6-regular、fa6-solid 和 material-symbols。

设置图标的步骤：

访问 Iconify 网站
搜索你想要的图标（比如 “bilibili”）
复制图标的完整名称（如 fa6-brands:bilibili）
粘贴到配置文件的 icon 字段中

图标设置示例

提示：图标库已通过 @iconify-json/fa6-brands 预装，你可以直接使用，无需额外安装。

这里附上我的配置文件，供大家参考：

1
import type {
2
  LicenseConfig,
3
  NavBarConfig,
4
  ProfileConfig,
5
  SiteConfig,
6
} from './types/config'
7
import { LinkPreset } from './types/config'
8

9
export const siteConfig: SiteConfig = {
10
  title: '陌灬离的博客',
11
  subtitle: '心之所向',
12
  lang: 'zh_CN',         // 'en', 'zh_CN', 'zh_TW', 'ja', 'ko', 'es', 'th'
13
  themeColor: {
14
    hue: 112,         // Default hue for the theme color, from 0 to 360. e.g. red: 0, teal: 200, cyan: 250, pink: 345
15
    fixed: false,     // Hide the theme color picker for visitors
16
  },
17
  banner: {
18
    enable: true,
19
    src: 'assets/images/demo-banner.png',   // Relative to the /src directory. Relative to the /public directory if it starts with '/'
20
    position: 'center',      // Equivalent to object-position, only supports 'top', 'center', 'bottom'. 'center' by default
21
    credit: {
22
      enable: false,         // Display the credit text of the banner image
23
      text: '',              // Credit text to be displayed
24
      url: ''                // (Optional) URL link to the original artwork or artist's page
25
    }
26
  },
27
  toc: {
28
    enable: true,           // Display the table of contents on the right side of the post
29
    depth: 2                // Maximum heading depth to show in the table, from 1 to 3
30
  },
31
  favicon: [    // Leave this array empty to use the default favicon
32
    // {
33
    //   src: '/favicon/icon.png',    // Path of the favicon, relative to the /public directory
34
    //   theme: 'light',              // (Optional) Either 'light' or 'dark', set only if you have different favicons for light and dark mode
35
    //   sizes: '32x32',              // (Optional) Size of the favicon, set only if you have favicons of different sizes
36
    // }
37
  ]
38
}
39

40
export const navBarConfig: NavBarConfig = {
41
  links: [
42
    LinkPreset.Home,
43
    LinkPreset.Archive,
44
    LinkPreset.About,
45
    {
46
      name: 'GitHub',
47
      url: 'https://github.com/saicaca/fuwari',     // Internal links should not include the base path, as it is automatically added
48
      external: true,                               // Show an external link icon and will open in a new tab
49
    },
50
  ],
51
}
52

53
export const profileConfig: ProfileConfig = {
54
  avatar: 'assets/images/avatar.jpg',  // Relative to the /src directory. Relative to the /public directory if it starts with '/'
55
  name: '陌灬离',
56
  bio: 'A long way to go./还差的远！',
57
  links: [
58
    {
59
      name: 'Twitter',
60
      icon: 'fa6-brands:twitter',       // Visit https://icones.js.org/ for icon codes
61
      // You will need to install the corresponding icon set if it's not already included
62
      // `pnpm add @iconify-json/<icon-set-name>`
63
      url: 'https://twitter.com',
64
    },
65
    {
66
      name: 'Steam',
67
      icon: 'fa6-brands:steam',
68
      url: 'https://store.steampowered.com',
69
    },
70
    {
71
      name: 'GitHub',
72
      icon: 'fa6-brands:github',
73
      url: 'https://github.com/moli721',
74
    },
75
    {
76
      name: 'Bilibili',
77
      icon: 'fa6-brands:bilibili',
78
      url: 'https://space.bilibili.com/1920382429?spm_id_from=333.1007.0.0',
79
    },
80
  ],
81
}
82

83
export const licenseConfig: LicenseConfig = {
84
  enable: true,
85
  name: 'CC BY-NC-SA 4.0',
86
  url: 'https://creativecommons.org/licenses/by-nc-sa/4.0/',
87
}

展开收起

博客内容管理：开始创作你的第一篇文章#

创建新文章#

打开终端，在项目根目录下执行以下命令来创建新文章：
Terminal window
```
1
pnpm new-post "你的文章标题"
```
执行后，系统会在 src/content/posts 目录下自动生成一个新的 .md 文件。

文章配置说明#

当你用 YankNote 打开新创建的文章，会看到文件头部有这样一段配置信息：

1
title: xxx
2
published: 2024-10-14
3
description: ''
4
image: ''
5
tags: []
6
category: ''
7
draft: false
8
lang: ''

让我们来了解每个字段的含义：

title：文章标题
published：发布日期
description：文章简介，会显示在文章列表中
image：文章封面图片
- 如果使用本地图片，需要以 ./ 开头
- 例如：./assets/images/cover.webp
tags：文章标签，可以添加多个
- 例如：['教程', '博客', 'Fuwari']
category：文章分类
draft：是否为草稿（true/false）
lang：文章语言（可选）

图片处理神器：YankNote 的使用技巧#

很多人会问：“用 Markdown 写作很好，但处理图片是不是很麻烦？” 别担心！YankNote 为我们提供了超简单的图片处理方案。

设置步骤：#

创建专属工作区
- 点击 YankNote 左下角的设置图标
- 将 posts 文件夹添加为独立仓库
- 设置完成后，可以用 Alt + 数字键 快速切换
  仓库设置
- 比如我的 Fuwari 博客在第 5 个仓库，按 Alt + 5 就能快速切换
配置图片存储
- 点击仓库旁边的图片设置
- 将图片存储路径设置为：./FILES/{docBasename}.assets
- 这样做的好处是：
  - 所有图片会自动存放在 FILES 文件夹下
  - 使用相对路径引用图片，方便管理
  - 复制粘贴图片时会自动完成存储和引用

开始写作#

现在，你可以：

直接使用 Ctrl + V 粘贴图片
使用标准的 Markdown 语法写作
实时预览文章效果

有了这些设置，你就可以像使用普通文本编辑器一样流畅地创作博客文章了！

博客部署#

注册好vercel账号后进入控制台，点击New Project
Img
点击Import，选择GitHub，然后选择你的GitHub账号，点击Import
Img
选择你的GitHub账号下的fuwari项目，点击Import
Img
点击Deploy，等待一分钟左右部署完成，部署完成后，点击Visit，就可以访问你的博客了

至此，你的博客就已经部署完成了

随后你只需要在本地编辑好博客内容，然后推送到GitHub（使用git push命令，这里我就不详细介绍了），Vercel就会自动部署你的博客，你就可以在浏览器中访问你的博客了

Oh My Posh+Clink终端美化配置指南

Sat, 18 Jan 2025 00:00:00 GMT

ohmyposh+clink终端美化教程#

配置过程可参考开源免费软件分享0031——oh-my-posh+clink

详细对于终端的配置可以查看官方文档

Img

针对在cmd中’oh-my-posh’ 不是内部或外部命令,也不是可运行的程序或批处理文件。

可以使用绝对路径的配置

Terminal window

1
-- 初始化 oh-my-posh 并指定主题
2
local oh_my_posh = io.popen([[H:/workspaces/terminalbeauty/oh-my-posh/bin/oh-my-posh.exe init cmd --config "H:/workspaces/terminalbeauty/oh-my-posh/themes/atomic.omp.json"]]):read("*a")
3
load(oh_my_posh)()

后面的--config是主题配置，详细路径在H:\workspaces\terminalbeauty\oh-my-posh\themes，在官方文档里面也同时有效果预览：https://ohmyposh.dev/docs/themes

Img

使用的字体：JetBrainsMonoNerdFont-Italic 在我计算机位置："H:\workspaces\terminalbeauty\JetBrainsMono\JetBrainsMonoNerdFont-Italic.ttf"

同时可以修改cursor/vscode中的终端配置

首先ctrl + shift + p打开命令面板，搜索工作区
Img
有两种修改方式，一种是修改terminal下面的setting.jsons
Img

Img
也可以修改font
Img

升级你的 Windows 终端：Starship + Clink 完全指南

Sat, 18 Jan 2025 00:00:00 GMT

初识starship及clink#

Starship和Clink是两个工具，常用于提升Windows命令提示符（cmd.exe）的用户体验和功能。

Starship#

Starship是一个跨平台的命令行提示符，旨在提供快速、可定制的提示信息。它支持多种shell，包括Bash、Zsh、Fish、PowerShell等。Starship的特点包括：

快速和轻量: Starship设计为快速启动，并且不会显著影响命令行的响应时间。
美观的提示: 它可以显示Git状态、Python虚拟环境、Node.js版本等信息，帮助开发者更好地了解当前环境。
高度可定制: 用户可以通过配置文件（通常是TOML格式）自定义提示符的外观和行为。

Clink#

Clink是一个增强Windows命令提示符的工具，它通过添加GNU Readline库的功能，提供更丰富的命令行编辑、自动补全和历史记录功能。Clink的特点包括：

命令行增强: Clink使得cmd.exe具有更强大的命令行编辑功能，例如行编辑、历史搜索和命令补全。
脚本支持: Clink支持Lua脚本，可以让用户自定义命令提示符和其他功能。
与Starship结合使用: Clink可以与Starship集成，使得用户能够在cmd.exe中使用Starship的美观提示符。

如何结合使用Starship和Clink#

安装Clink: 首先，需要通过包管理器（如Scoop或Winget）安装Clink。
配置Starship: 创建一个名为starship.lua的文件，并将Starship的初始化代码添加到该文件中。这个文件需要放在Clink的脚本目录中。
启动Clink: 启动cmd.exe时，Clink会加载这个Lua脚本，从而使Starship的提示符在cmd.exe中生效。

通过结合使用Starship和Clink，用户可以在Windows命令提示符中获得一个更加美观和功能丰富的命令行体验。

在windows下安装软件及其环境#

步骤 1. 安装 Starship#

scoop install starship直接利用scoop包管理工具安装starship

步骤 2. 设置您的 shell 以使用 Starship#

配置你的终端来初始化 starship。请从下面列表选择你的终端：

Cmd

您需要使用 Clink (v1.2.30+) 与 Cmd. 在路径 %LocalAppData%\clink\starship.lua 下创建文件，输入以下内容
Terminal window
```
1
load(io.popen('starship init cmd'):read("*a"))()
```
安装Clink，我下载到了H:\workspaces\clink,运行 clink.bat 文件以安装Clink。
PowerShell

将以下内容添加到您 PowerShell 配置文件的末尾（通过运行 $PROFILE 来获取配置文件的路径）
Terminal window
```
1
Invoke-Expression (&starship init powershell)
```

配置#

在~/.config路径下新建starship.toml配置文件即可。

问题#

找不到%LocalAppData%\clink\starship.lua#

创建 Starship 配置文件

打开文件资源管理器<在windows文件资源管理器的地址栏中输入> %LocalAppData% 并按 Enter。这将打开 C:\Users\<你的用户名>\AppData\Local 目录。
查找或创建 clink 文件夹<在> Local 目录中，查找 clink 文件夹。如果它不存在，你可以手动创建一个：右键单击空白区域，选择“新建” -> “文件夹”，命名为 clink。
创建 starship.lua 文件<在> clink 文件夹中，右键单击并选择“新建” -> “文本文档”，然后将其重命名为 starship.lua。确保文件扩展名为 .lua，而不是 .txt。

编辑 starship.lua 文件:

使用文本编辑器（如记事本或 Visual Studio Code）打开 starship.lua 文件。

输入以下内容：

1
load(io.popen('starship init cmd'):read("*a"))()

保存并关闭文件。

PS C:\Users\xxx> $PROFILE C:\Users\xxx\Documents\WindowsPowerShell\Microsoft.PowerShell_profile.ps1 但是实际我电脑上找不到这个路径是怎么回事#

如果你在运行 $PROFILE 命令后发现路径 C:\Users\xxx\Documents\WindowsPowerShell\Microsoft.PowerShell_profile.ps1 不存在，这可能是因为该文件尚未创建。PowerShell的配置文件并不会自动存在，你需要手动创建它。以下是详细的步骤：

创建 PowerShell 配置文件#

打开 PowerShell:
- 在开始菜单中搜索 “PowerShell”，然后打开 Windows PowerShell。
查看 $PROFILE 路径:
- 输入以下命令以确认 $PROFILE 的路径：
  Terminal window
```
1
$PROFILE
```
创建文件夹:
- 如果路径中提到的 WindowsPowerShell 文件夹不存在，你需要手动创建它。使用以下命令创建文件夹：
  Terminal window
```
1
New-Item -ItemType Directory -Path "$HOME\Documents\WindowsPowerShell" -Force
```
创建配置文件:
- 使用以下命令创建配置文件：
  Terminal window
```
1
New-Item -ItemType File -Path $PROFILE -Force
```
编辑配置文件:
- 使用文本编辑器（如 Notepad）打开配置文件：
  Terminal window
```
1
notepad $PROFILE
```
- 在打开的 Notepad 中，你可以添加你希望在每次启动 PowerShell 时执行的命令，例如：
  Terminal window
```
1
# 示例: 初始化 Starship 提示符
2
Invoke-Expression (&starship init powershell)
```
保存并关闭 Notepad:
- 保存更改并关闭 Notepad。

验证配置#

重新启动 PowerShell:
- 关闭并重新打开 PowerShell。
检查 Starship 是否正常工作:
- 如果你在配置文件中添加了 Starship 的初始化命令，你应该能看到 Starship 提示符。

注意事项#

文件和文件夹的创建: 如果你在创建文件或文件夹时遇到任何权限问题，确保你以管理员身份运行 PowerShell。
PowerShell 版本: 确保你使用的是 Windows PowerShell，而不是 PowerShell Core（7.x）。两者的配置文件路径可能不同。

通过这些步骤，你应该能够成功创建和配置 PowerShell 的配置文件，并在每次启动 PowerShell 时自动运行你指定的命令。

以后可以在everything中输入starship.toml找到该文件

在vscode不显示图标的问题#

starship doesn’t show icons in vscode terminal #2818

最后通过下载Hask font字体基本得到解决，参考Windows 11和vscode终端美化

Img

可能是nerdfont版本不太对，改下icon即可，

这里我修改的是windows中的e70f这个图标

在Cursor显示问题#

下载Cursor后，由于没有配置文件，字体还是使用的是默认字体，此时我们可以输入ctrl + shift + p打开命令界面，继续输入settings，选择打开工作区设置（JSON）在此JSON文件中，配置字体，如："terminal.integrated.fontFamily": "'Hasklug Nerd Font'",

保存即可正常显示图标。

模板#

这里我使用的是官网的Gruvbox Rainbow Preset配置

同时我对一下几个地方进行修改

修改truncation_length = 100将截断长度改为100，否则如果你文件夹名称长度太长，前面会看不到

Img
修改python版本显示格式

format = '[$virtualenv]($style)[[ $symbol( $version) ](fg:color_fg0 bg:color_blue)]($style)'

使其有显示虚拟环境的功能

Img

Cursor API代理服务部署完整指南

Sat, 18 Jan 2025 00:00:00 GMT

从零开始：搭建个人 API 代理服务完全指南#

本文结合理论知识和实战经验，详细介绍如何搭建一个稳定可用的 API 代理服务，包含完整的故障排除指南。

方案概述#

本教程提供两种部署方案，分别适合不同的使用场景：

直连模式
- 特点：配置简单，快速部署
- 适用：个人使用或临时测试
- 原理：直接使用 Cursor 隧道，填写 Cookie 即可
One API 模式（推荐）
- 特点：功能完整，管理便捷
- 适用：公益站点或多账号管理
- 优势：
  - 支持批量管理多个账号
  - 提供令牌分发和使用统计
  - 可用作”收菜模式”
  - 带有完整的管理界面

💡 选择建议：

个人临时使用 → 选择直连模式

长期运营或多人使用 → 选择 One API 模式

本教程会详细介绍这两种模式的配置方法，你可以根据实际需求选择合适的方案

前期准备#

在开始动手之前，请确保已准备以下工具：

Cursor API 程序包：下载地址
Img
ngrok 内网穿透工具：用于创建网络隧道
One API 管理程序：用于统一管理 API 接口

核心概念详解#

在开始实操之前，让我们先理解几个关键概念，这将帮助你更好地理解整个搭建过程：

1. Cursor API 代理服务#

本质：一个将 Cursor 编辑器 AI 能力转换为标准 OpenAI API 格式的接口服务
工作原理：
- 在本地端口运行（默认3000端口）
- 接收标准 OpenAI API 格式的请求
- 转换并调用 Cursor AI 能力
- 返回处理结果
应用价值：让 Cursor 的 AI 能力可以被更多应用程序调用，极大扩展了使用场景

2. 网络隧道服务#

本质：创建一个安全的网络通道，将本地服务暴露到公网
实现方式：主要通过 ngrok 工具实现
核心功能：
- 内网穿透实现远程访问
- 提供临时公网域名
- 支持 HTTPS 加密
- 实时流量监控

3. One API 管理平台#

定位：API 接口的统一管理和分发平台
主要功能：
- 集中管理多个 API 端点
- 令牌管理和访问控制
- 使用量统计和监控
- 负载均衡和故障转移

方案一：直连模式配置#

第一步：配置网络环境#

配置 ngrok 首先访问 ngrok官网获取配置信息:
Img
设置 Authtoken
Terminal window
```
1
# 在命令行中执行
2
ngrok config add-authtoken <你的token>
```
Img

💡 提示：Authtoken 的作用是将 ngrok 账户与本地配置绑定，获取更多功能权限（如自定义域名、流量统计等）

第二步：配置 Cursor API 服务#

运行 cur代理.bat（默认使用 3000 端口）
如遇端口冲突，可修改端口：
```
1
// 在 src/index.js 中修改
2
const port = 3002  // 换成未被占用的端口
```
端口占用示例
⚠️ 注意：
- 建议使用 3000-5000 范围内的端口
- 记得保存修改后的端口号
- 确保新端口未被占用
示例：我这里使用 3002 端口（因为 3000 端口已被占用）
Img

第三步：配置访问凭证#

获取 Cursor 中的 WorkosCursorSessionToken：
Img
填写配置信息：
Img

看到 API connection successful! 提示就表示配置成功了！

注意：示例中的端点 http://localhost:3010/v1 是本地测试地址，实际使用时要换成你的 Cursor API 端口

第四步：启用远程访问#

运行 开启cur隧道.bat 启动 ngrok 隧道：
Img
使用生成的公网地址作为端点（如果无法访问，可以尝试在地址后添加 /v1）

方案二：One API 模式配置#

前两步的配置与直连模式相同（配置 ngrok 和启动 Cursor API），从第三步开始有所不同。

第三步：配置 One API 服务#

运行 打开Oneapi.bat（默认端口 3333）
Img
启动 One API 隧道
访问管理界面（本地访问 3333 端口）：
Img
默认登录信息：
- 账号：root
- 密码：123456

第四步：填写OneAPI信息并完成配置#

第四步：完成 One API 配置#

获取 WorkosCursorSession：
- 可以手动获取
- 也可以使用 CursorRegister 自动创建账号
配置 API 渠道：
Img
测试渠道连接：
Img
启用远程访问：
- 运行 开启one api隧道.bat
- 使用生成的公网地址作为端点
- 在令牌管理中创建并使用 API 密钥：
  令牌

🌟 配置成功的标志：

测试返回 200 状态码

服务状态显示正常

可以正常收发消息

提示 Status check bypassed 但测试返回 200 也是正常的

批量账号管理（可选）#

如果需要管理多个账号：

使用 CursorRegister 批量创建多个账号
收集所有账号的 WorkosCursorSession
通过 One API 统一管理这些账号
设置负载均衡和故障转移策略

常见问题与解决方案#

1. 连接问题#

状态检查提示：遇到 Status check bypassed 不用担心，只要测试返回 200 就是正常的
404错误：检查端口配置和服务运行状态
空回复：确保 cookie 格式正确（使用 %3A 而非双冒号）

2. 进阶功能：批量账号配置#

使用 CursorRegister 自动创建账号
批量获取 WorkosCursorSession
通过 One API 统一管理

参考资源#

博客分类哲学：从混乱到有序的知识管理之路

Mon, 13 Jan 2025 00:00:00 GMT

博客分类哲学#

核心价值观：面向恢复 (Recovery-Oriented) “我不记录我知道的，我只记录我将会忘记的。“

三大公理#

1. 意图优先 (Intent First)#

分类不按”技术栈”分（那会过时），按”我当下的动作意图”分（这是永恒的）。

为什么？

❌ 技术栈分类：React、Docker、Linux → 5年后过时
✅ 意图分类：部署、配置、学习、排查 → 永远有效

2. 上下文快照 (Context Snapshot)#

一篇好文章必须能在6个月后，让我无需查阅Google，直接复现环境。

检验标准：

✅ 包含完整的依赖版本
✅ 包含环境变量配置
✅ 包含验证步骤
✅ 包含常见报错和解决方案

3. 最小认知负荷 (Minimal Cognitive Load)#

拒绝废话。多用代码块、多用截图锚点、多用列表。能Copy绝不手打。

执行原则：

用代码块代替文字描述
用截图标注代替长篇解释
用列表代替段落
用命令代替步骤说明

理论基础#

参考框架：Diátaxis - 技术文档的系统性分类方法论

Diátaxis将技术内容分为4个象限：

Learning-oriented（学习导向）- 帮你理解概念
Task-oriented（任务导向）- 帮你完成目标
Information-oriented（信息导向）- 帮你快速查找
Understanding-oriented（理解导向）- 帮你深入原理

我的修正：在此基础上增加”避坑排查”（从-1到0），因为这是技术博客的核心价值。

文章分类体系（5个）#

🏗️ 部署搭建 (Build & Deploy)#

定义：从0到1，把一个完整的系统跑起来

适用场景：

你拿着一个崭新的VPS，想把博客部署上去
老板让你搭一个新的监控系统，你一脸懵逼
看到GitHub上一个很酷的项目，想在本地跑起来
刚买了一台NAS，想搭建自己的私有云
需要从零开始配置一个Docker化的开发环境

判断标准：完成后有一个完整的、可以访问的系统

核心要素：

环境依赖清单（操作系统、软件版本、端口要求）
完整的配置文件（Docker Compose、Nginx Config）
详细的部署步骤（一步一步跟着做）
验证方法（怎么确认部署成功）
常见问题（部署过程可能遇到的坑）

文章举例：

Firefly博客部署：从Fork到上线完整流程
Nonebot2 QQ机器人部署实战
使用HuggingFace Spaces部署免费API服务

🛠️ 工具配置 (Tools & Config)#

定义：从1到100，让某个工具变得更好用

适用场景：

你的终端太丑了，想美化一下
每次用Clash都要手动改规则，想自动化
看到别人的VSCode配置很炫，想照着配
刚装了新电脑，需要快速恢复开发环境
想用某个软件但官方文档全是英文看不懂
听说某个工具很好用，想快速上手试试

判断标准：完成后某个工具的使用体验显著提升

核心要素：

工具介绍（这是什么，解决什么问题）
安装方法（一条命令搞定）
核心配置（贴出配置文件）
使用技巧（最常用的5个功能）
注意事项（容易踩的坑）

文章举例：

Starship终端美化：3分钟配置指南
酒馆(SillyTavern)快速配置与使用
Clash规则自定义：手动添加直连站点

📝 学习笔记 (Study & Notes)#

定义：从不懂到懂，记录知识的内化过程

适用场景：

学React Hooks，看官方文档一头雾水，需要自己的理解
面试前复习算法，需要整理常见题型和解法
读了一本技术书，想记录核心要点和代码示例
某个技术的原理很复杂，需要用自己的话解释清楚
看了很多文章都讲不清楚，自己研究后总结出来
工作中遇到的技术细节，想系统地整理成知识体系

判断标准：侧重理解和记录，而非纯粹的操作步骤

核心要素：

概念介绍（用最简单的话解释）
原理解析（为什么这么设计）
代码示例（可运行的完整代码）
个人理解（我是怎么理解的）
参考资料（哪些文章讲得好）

文章举例：

React Hooks深入理解：useEffect的执行时机
Clash配置文件完全解析：从订阅到规则
Git Submodule工作机制详解

🚑 避坑排查 (Fix & Debug)#

定义：从-1到0，修复让人抓狂的错误

适用场景：

Docker容器起不来，报ERR_CONNECTION_REFUSED
Vercel部署失败，提示Submodule 403 Forbidden
代码在本地能跑，推到服务器就报错
某个配置改了就炸，但不知道哪里错了
Google搜了半天都是垃圾答案，自己折腾了3小时终于解决
半年后又遇到同样的错误，但完全不记得怎么解决的

判断标准：有明确的报错信息，需要排查和修复

核心要素：

问题现象（详细描述，贴报错截图）
完整报错信息（原始错误日志）
排查过程（尝试了哪些方法）
最终解决方案（详细步骤）
原因分析（为什么会出错）
预防措施（怎么避免再次踩坑）

标题要求：必须包含错误码或错误关键词

文章举例：

Docker容器无法访问宿主机：ERR_CONNECTION_REFUSED解决
Vercel部署失败：Submodule 403 Forbidden完全修复
Nonebot2启动报错：端口被占用问题排查

⚡ 速查脚本 (Snippets & Ops)#

定义：纯记忆片段，不需要理解，复制粘贴就行

适用场景：

每次用Git Submodule都要Google命令
需要查端口占用但总是记不住命令
想用正则匹配但语法老是忘
发布博客文章有固定流程，需要一个checklist
经常要配置Nginx但每次都要翻文档
有些命令很长很复杂，不想每次都手打

判断标准：不需要理解原理，只需要快速查到并使用

核心要素：

使用场景（什么时候需要）
命令/代码（直接可复制的）
参数说明（每个参数是什么意思）
示例（真实的使用案例）

文章举例：

Git Submodule常用命令速查表
Linux端口占用排查命令集合
Firefly博客发布文章标准流程
常用正则表达式速查手册

标签系统#

核心原则#

分类看动作，标签看属性

分类（Category）：回答”我在做什么？”
- 我在部署一个系统 → 部署搭建
- 我在配置一个工具 → 工具配置
- 我在学习一个技术 → 学习笔记
标签（Tags）：回答”内容是什么性质？”
- 这是免费的 → 免费、白嫖
- 这很复杂 → 进阶
- 这很基础 → 新手友好

关键修正：白嫖/免费是标签，不是分类#

错误示范：

1
title: HuggingFace免费部署API全流程
2
category: 白嫖攻略  # ❌ "白嫖"是属性，不是动作

正确示范：

1
title: HuggingFace Spaces部署API服务
2
category: 部署搭建  # ✅ 动作：我在部署
3
tags: ['API', 'HuggingFace', '免费', '部署']  # ✅ 属性：这是免费的

标签分类#

4类标签：

技术栈：Docker、React、Python、Linux
平台工具：Vercel、Cloudflare、HuggingFace、GitHub
内容属性：免费、白嫖、进阶、新手友好、付费
核心对象：博客、机器人、API、网盘、终端

标签数量：最少3个，最多6个，平均4-5个

标签示例：

1
# 部署搭建 + 免费资源
2
tags: ['API', 'HuggingFace', '免费', '部署', '白嫖']
3

4
# 工具配置 + 终端美化
5
tags: ['Starship', '终端', '美化', '效率工具', '新手友好']
6

7
# 学习笔记 + 进阶内容
8
tags: ['React', 'Hooks', '前端', '学习', '进阶']
9

10
# 避坑排查
11
tags: ['Docker', '网络', '排查', '错误修复']
12

13
# 速查脚本
14
tags: ['Git', 'Submodule', '命令', '速查']

写作规范#

标题设计#

基本原则：

说清楚”干什么”，不要模糊
避坑类必须包含错误码
去掉”白嫖”、“免费”等词（用标签标注）

标题模板：

部署搭建类
- [技术/项目] + 部署/搭建 + [关键特性]
- 示例：Firefly博客部署：Git Submodule方案
工具配置类
- [工具名] + 配置/美化/使用 + [核心功能]
- 示例：Starship终端美化：10分钟配置指南
学习笔记类
- [技术] + 学习笔记/深入理解/完全解析
- 示例：React Hooks深入理解：useEffect执行时机
避坑排查类
- [场景描述] + : + [错误码/错误关键词] + 解决/修复
- 示例：Docker容器无法访问宿主机：ERR_CONNECTION_REFUSED解决
速查脚本类
- [技术/工具] + 常用命令/速查表/操作手册
- 示例：Git Submodule常用命令速查表

语言风格#

✅ 推荐：

说人话：这样做会报错 > 此操作可能导致异常
用”我”：我遇到这个问题时... > 笔者在实践中发现...
口语化：搞定 > 完成配置
承认不足：我也不知道为什么，但这样能解决

❌ 避免：

AI式夸张：震撼登场、深度解析、全网最全
过度铺垁：在当今的技术环境中...
假装客观：通过本文的学习，相信读者能够...
长篇废话：直接上代码和截图

视觉要求#

必须有：

关键步骤的清晰截图（用红框标注重点）
代码块标注语言类型
重要提示用引用块
命令可一键复制

可选：

emoji标注（💡提示 / ⚠️注意 / ✅成功 / ❌错误）
表格对比（多方案选择时）
流程图（复杂流程时）

禁止：

纯文字长篇大论
模糊不清的截图
无关的装饰性图片
没有语法高亮的代码块

Frontmatter模板#

基础模板#

1
---
2
title: 具体的标题，说清楚干什么
3
published: YYYY-MM-DD
4
description: 一句话说清楚这篇文章解决什么问题（不超过80字）
5
image: "./FILES/文章目录/封面图.png"
6
tags: ['标签1', '标签2', '标签3', '标签4']
7
category: 分类名称
8
draft: false
9
---

分类值（5个）#

1
category: 部署搭建    # 🏗️ Build & Deploy
2
category: 工具配置    # 🛠️ Tools & Config
3
category: 学习笔记    # 📝 Study & Notes
4
category: 避坑排查    # 🚑 Fix & Debug
5
category: 速查脚本    # ⚡ Snippets & Ops

完整示例#

示例1：免费部署（白嫖作为标签）

1
---
2
title: HuggingFace Spaces部署API服务
3
published: 2025-03-24
4
description: 使用HuggingFace Spaces免费部署API服务的完整流程，包含配置和验证
5
image: "./FILES/HF-API-Deploy/cover.png"
6
tags: ['API', 'HuggingFace', '免费', '部署', '白嫖']
7
category: 部署搭建
8
draft: false
9
---

示例2：避坑排查（包含错误码）

1
---
2
title: Docker容器无法访问宿主机：ERR_CONNECTION_REFUSED解决
3
published: 2025-01-08
4
description: Docker容器访问宿主机服务报ERR_CONNECTION_REFUSED的完整排查和解决方案
5
image: "./FILES/Docker-Network-Error/cover.png"
6
tags: ['Docker', '网络', '排查', '错误修复']
7
category: 避坑排查
8
draft: false
9
---

示例3：工具配置（资源获取）

1
---
2
title: PikPak会员获取与配置
3
published: 2025-04-03
4
description: PikPak会员获取方案及客户端配置使用教程
5
image: "./FILES/PikPak-Setup/cover.png"
6
tags: ['PikPak', '会员', '免费', '网盘', '白嫖']
7
category: 工具配置
8
draft: false
9
---

分类决策树#

当你不确定文章应该归入哪个分类时，按以下流程判断：

1
开始写作
2
  ↓
3
有报错信息？
4
  ├─ 是 → 🚑 避坑排查
5
  └─ 否 ↓
6

7
纯粹是命令/配置片段？
8
  ├─ 是 → ⚡ 速查脚本
9
  └─ 否 ↓
10

11
侧重理解和学习？
12
  ├─ 是 → 📝 学习笔记
13
  └─ 否 ↓
14

15
完成后有完整系统能运行？
16
  ├─ 是 → 🏗️ 部署搭建
17
  └─ 否 → 🛠️ 工具配置

展开收起

分类对比#

分类	核心动作	起点→终点	判断标准	占比
部署搭建	造系统	0 → 1	完成后有完整可访问的系统	40%
工具配置	调工具	1 → 100	完成后某个工具显著变好用	25%
学习笔记	学知识	不懂 → 懂	侧重理解记录非纯操作	15%
避坑排查	修问题	-1 → 0	有报错信息需要修复	15%
速查脚本	查命令	忘记 → 找到	复制粘贴不需要理解	5%

发布检查清单#

Frontmatter检查：

title清晰具体，避坑类包含错误码
description一句话说清楚干什么
category选择正确（5个分类之一）
tags合理（3-6个，包含内容属性标签）
image路径正确

内容质量检查：

关键步骤有清晰截图
代码块有语法高亮
没有AI式夸张表达
没有长篇废话
外部链接有效

上下文完整性检查（核心）：

包含完整的环境依赖
包含详细的配置步骤
包含验证方法
包含常见问题解答
6个月后能无痛复现

理论参考#

Diátaxis Framework
- 技术文档的系统性分类方法论
- 作者：Daniele Procida
- 将内容分为：Tutorials, How-to guides, Reference, Explanation
酷壳（CoolShell）
- 陈皓的技术博客
- 13个分类，740篇文章
- 实战验证的分类策略
廖雪峰官方网站
- 教程型博客的成功范例
- 特点：零起点、完整示例、可跟做

版本：v5.0（哲学版）更新：2026-01-13

核心改进：

✅ 建立三大公理体系
✅ 基于Diátaxis框架设计
✅ 丰富适用场景描述
✅ 增加分类决策树
✅ 强化上下文完整性要求

安知鱼主题Hexo博客搭建与Vercel部署指南

Mon, 30 Dec 2024 00:00:00 GMT

安知鱼主题 Hexo 博客搭建与 Vercel 部署全攻略#

最近把博客换成了安知鱼主题，折腾了一圈，把这套最稳的搭建流程记下来。希望能帮后来人少走弯路。

一、环境准备与初始化#

首先，确保你的电脑里有 Node.js（推荐 v18+）。

安装 Hexo 全局脚手架：
Terminal window
```
1
npm install hexo-cli -g
```

找个干净的目录，初始化项目：

Terminal window

1
hexo init anzhiyu-blog
2
cd anzhiyu-blog
3
yarn install  # 建议统一用 yarn，速度快且稳

二、安装安知鱼主题#

安知鱼支持多种安装方式，这里建议选插件化安装，以后更新主题只要一行命令。

安装主题核心：
Terminal window
```
1
yarn add hexo-theme-anzhiyu
```
应用主题： 打开根目录的 _config.yml，把 theme 改成 anzhiyu。
配置文件备份： 为了方便自定义样式，建议把主题的配置拷到根目录：
Terminal window
```
1
cp -rf ./themes/anzhiyu/_config.yml ./_config.anzhiyu.yml
```

三、避坑：解决 ERR_REQUIRE_ESM 冲突#

这是最关键的一步。 现在的 Node 环境下跑 hexo generate 经常会报 strip-ansi 相关的红字错误，因为依赖库版本打架了。

解决方案： 在 package.json 里手动加上 resolutions（Yarn）或 overrides（npm）来强行锁版本：

1
"resolutions": {
2
  "strip-ansi": "6.0.1",
3
  "ansi-regex": "5.0.1"
4
}

改完后，执行以下命令重装依赖：

Terminal window

1
Remove-Item -Recurse -Force node_modules  # 删掉旧的
2
yarn install                              # 重新洗牌

四、补齐必备插件#

安知鱼主题是用 Pug 和 Stylus 写的，Hexo 默认不带，必须手动装上：

Terminal window

1
yarn add hexo-renderer-pug hexo-renderer-stylus

注：如果 npm 慢，直接用 cnpm 或者换淘宝源，别死磕。

五、关联 GitHub 仓库#

在 GitHub 上新建仓库，名字随便起，但不要勾选初始化 README。
终端执行：
Terminal window
```
1
git init
2
git add .
3
git commit -m "Initial commit"
4
git branch -M main
5
git remote add origin https://github.com/你的用户名/仓库名.git
6
git push -u origin main
```
注意： 如果你之前是用 git clone 下的主题，记得删掉 themes/anzhiyu 里的 .git 隐藏文件夹，不然主题代码传不上去。

六、部署至 Vercel#

登录 Vercel，Import 你刚传上去的仓库。
Framework Preset 选 Hexo。
关键点：在 Settings -> General 里的 Install Command，一定要手动开启并填入 yarn install 或 npm install。
点击 Deploy。看到漫天烟花就代表成了。

七、日常怎么玩？#

写新文章：hexo new "我的第一篇博客"，然后去 source/_posts 找 md 文件改就行。
本地看效果：hexo clean && hexo s，浏览器看 localhost:4000。
云端同步：本地改爽了直接 git push，Vercel 会自动帮你重新编译上线，完全不用手动传文件。

最后多说一句： 改配置的时候，_config.yml 里的冒号后面必须有空格，这种低级错误能让你白忙活半天。祝大家都能顺利跑起来！

补充建议：#

关于 Git Clone：你在正文里提到了 git clone 主题，但我建议你在教程中统一推荐 npm/yarn 安装模式。因为克隆模式如果不删子仓库的 .git，新手大概率会遇到 Vercel 部署出来是白屏的问题。
代码块格式：确保你在博客发布时，Markdown 的代码块语法正确（比如用 json 或 bash 指明语言），这样高亮才好看。
图片干货：如果可以，顺手截一张 Vercel 的配置图贴上去，效果更直观。

Firefly 代码块示例

Sat, 03 Jan 1970 00:00:00 GMT

在这里，我们将探索如何使用 Expressive Code 展示代码块。提供的示例基于官方文档，您可以参考以获取更多详细信息。

表达性代码#

语法高亮#

语法高亮

常规语法高亮#

1
console.log('此代码有语法高亮!')

渲染 ANSI 转义序列#

Terminal window展开收起

1
Standard ANSI colors:
2
- Dimmed:      Black  Red  Green  Yellow  Blue  Magenta  Cyan  White 
3
- Foreground:  Black  Red  Green  Yellow  Blue  Magenta  Cyan  White 
4
- Background:  Black  Red  Green  Yellow  Blue  Magenta  Cyan  White 
5
- Reversed:    Black  Red  Green  Yellow  Blue  Magenta  Cyan  White 
6

7
8-bit colors (showing colors 160-171 as an example):
8
- Dimmed:      160  161  162  163  164  165  166  167  168  169  170  171 
9
- Foreground:  160  161  162  163  164  165  166  167  168  169  170  171 
10
- Background:  160  161  162  163  164  165  166  167  168  169  170  171 
11
- Reversed:    160  161  162  163  164  165  166  167  168  169  170  171 
12

13
24-bit colors (full RGB):
14
- Dimmed:      ForestGreen - RGB(34,139,34)  RebeccaPurple - RGB(102,51,153) 
15
- Foreground:  ForestGreen - RGB(34,139,34)  RebeccaPurple - RGB(102,51,153) 
16
- Background:  ForestGreen - RGB(34,139,34)  RebeccaPurple - RGB(102,51,153) 
17
- Reversed:    ForestGreen - RGB(34,139,34)  RebeccaPurple - RGB(102,51,153) 
18

19
Font styles:
20
- Default
21
- Bold
22
- Dimmed
23
- Italic
24
- Underline
25
- Reversed
26
- Strikethrough

展开收起

编辑器和终端框架#

编辑器和终端框架

代码编辑器框架#

my-test-file.js

1
console.log('标题属性示例')

src/content/index.html

1
<div>文件名注释示例</div>

终端框架#

Terminal window

1
echo "此终端框架没有标题"

PowerShell 终端示例

1
Write-Output "这个有标题!"

覆盖框架类型#

1
echo "看，没有框架!"

PowerShell Profile.ps1

1
# 如果不覆盖，这将是一个终端框架
2
function Watch-Tail { Get-Content -Tail 20 -Wait $args }
3
New-Alias tail Watch-Tail

文本和行标记#

文本和行标记

标记整行和行范围#

1
// 第1行 - 通过行号定位
2
// 第2行
3
// 第3行
4
// 第4行 - 通过行号定位
5
// 第5行
6
// 第6行
7
// 第7行 - 通过范围 "7-8" 定位
8
// 第8行 - 通过范围 "7-8" 定位

选择行标记类型 (mark, ins, del)#

line-markers.js

1
function demo() {
2
  console.log('此行标记为已删除')
3
  // 此行和下一行标记为已插入
4
  console.log('这是第二个插入行')
5

6
  return '此行使用中性默认标记类型'
7
}

为行标记添加标签#

labeled-line-markers.jsx

1
<button
2
  role="button"
3
  {...props}
4
  value={value}
5
  className={buttonClassName}
6
  disabled={disabled}
7
  active={active}
8
>
9
  {children &&
10
    !active &&
11
    (typeof children === 'string' ? <span>{children}</span> : children)}
12
</button>

在单独行上添加长标签#

labeled-line-markers.jsx展开收起

1
<button
2
  role="button"
3
  {...props}
4

5
  value={value}
6
  className={buttonClassName}
7

8
  disabled={disabled}
9
  active={active}
10
>
11

12
  {children &&
13
    !active &&
14
    (typeof children === 'string' ? <span>{children}</span> : children)}
15
</button>

展开收起

使用类似 diff 的语法#

1
此行将标记为已插入
2
此行将标记为已删除
3
这是常规行

1
--- a/README.md
2
+++ b/README.md
3
@@ -1,3 +1,4 @@
4
+this is an actual diff file
5
-all contents will remain unmodified
6
 no whitespace will be removed either

结合语法高亮和类似 diff 的语法#

1
function thisIsJavaScript() {
2
  // 整个块都会以 JavaScript 高亮显示，
3
  // 并且我们仍然可以为其添加 diff 标记！
4
  console.log('要删除的旧代码')
5
  console.log('新的闪亮代码！')
6
}

标记行内的单独文本#

1
function demo() {
2
  // 标记行内的任何给定文本
3
  return '支持给定文本的多个匹配项';
4
}

正则表达式#

1
console.log('单词 yes 和 yep 将被标记。')

转义正斜杠#

Terminal window

1
echo "Test" > /home/test.txt

选择内联标记类型 (mark, ins, del)#

1
function demo() {
2
  console.log('这些是插入和删除的标记类型');
3
  // return 语句使用默认标记类型
4
  return true;
5
}

自动换行#

自动换行

为每个块配置自动换行#

1
// 启用换行的示例
2
function getLongString() {
3
  return '这是一个非常长的字符串，除非容器极宽，否则很可能无法适应可用空间'
4
}

1
// wrap=false 的示例
2
function getLongString() {
3
  return '这是一个非常长的字符串，除非容器极宽，否则很可能无法适应可用空间'
4
}

配置换行的缩进#

1
// preserveIndent 示例（默认启用）
2
function getLongString() {
3
  return '这是一个非常长的字符串，除非容器极宽，否则很可能无法适应可用空间'
4
}

1
// preserveIndent=false 的示例
2
function getLongString() {
3
  return '这是一个非常长的字符串，除非容器极宽，否则很可能无法适应可用空间'
4
}

可折叠部分#

可折叠部分


5 collapsed lines
1
// 所有这些样板设置代码将被折叠
2
import { someBoilerplateEngine } from '@example/some-boilerplate'
3
import { evenMoreBoilerplate } from '@example/even-more-boilerplate'
4

5
const engine = someBoilerplateEngine(evenMoreBoilerplate())
6

7
// 这部分代码默认可见
8
engine.doSomething(1, 2, 3, calcFn)
9

10
function calcFn() {
11
  // 您可以有多个折叠部分
3 collapsed lines
12
  const a = 1
13
  const b = 2
14
  const c = a + b
15

16
  // 这将保持可见
17
  console.log(`计算结果: ${a} + ${b} = ${c}`)
18
  return c
19
}
20

4 collapsed lines
21
// 直到块末尾的所有代码将再次被折叠
22
engine.closeConnection()
23
engine.freeMemory()
24
engine.shutdown({ reason: '示例样板代码结束' })

展开收起

行号#

行号

为每个块显示行号#

1
// 此代码块将显示行号
2
console.log('来自第2行的问候!')
3
console.log('我在第3行')

// 此块禁用行号
console.log('你好?')
console.log('抱歉，你知道我在第几行吗?')

更改起始行号#

5
console.log('来自第5行的问候!')
6
console.log('我在第6行')

Tab 代码块#

由 rehype-code-group 提供，语法与 VitePress 代码组一致：用 ::: code-group labels=[...] 包裹多个代码块，即可合并成一组标签页。

Note

labels=[...] 中的标签按顺序对应组内的代码块，用英文逗号分隔；::: 与 code-group 之间的空格不能省略。

基本用法#

1
::: code-group labels=[code.js, code.py, code.html]
2

3
```js
4
export function greet(name) {
5
  return `Hello, ${name}!`;
6
}
7
```
8

9
```py
10
def greet(name):
11
    return f"Hello, {name}!"
12
```
13

14
```html
15
<p>Hello, world!</p>
16
```
17

18
:::

展开收起

渲染效果：

code.jscode.pycode.html

1
export function greet(name) {
2
  return `Hello, ${name}!`;
3
}

1
def greet(name):
2
    return f"Hello, {name}!"

1
<p>Hello, world!</p>

标签中使用 Emoji#

标签支持 emoji 短代码，构建时会自动转换成 emoji：

1
::: code-group labels=[:package: npm, :package: pnpm, :yarn: yarn]

📦 npm📦 pnpm🧶 yarn

Terminal window

1
npm create astro@latest

Terminal window

1
pnpm create astro@latest

Terminal window

1
yarn create astro

与其他代码块特性组合#

组内仍是普通的 Expressive Code 代码块，标题、行号、行标记、折叠、终端框架等特性都可以照常使用。

配置文件终端折叠

astro.config.mjs

1
export default {
2
  theme: "firefly",
3
  codeGroup: true,
4
};

部署

1
pnpm build && pnpm preview


3 collapsed lines
1
// 这三行默认折叠
2
import { a } from "a";
3
import { b } from "b";
4

5
console.log(a, b);

不止是代码块#

标签页内可以放任意内容，例如文字、列表或图片：

说明列表

这是一段普通的段落内容。

列表项一
列表项二

Tip

标签栏在构建期生成，默认展开第一项；支持鼠标点击与键盘 ← / → / Home / End 切换。

Firefly 布局系统详解

Sat, 03 Jan 1970 00:00:00 GMT

📖 概述#

Firefly 提供了灵活的布局系统，允许您根据内容需求和个人喜好自定义博客的视觉呈现方式。布局系统主要包括侧边栏布局和文章列表布局两个维度，它们相互配合，共同决定了页面的整体结构。

本文将详细介绍 Firefly 的各种布局模式、它们的特点、使用场景，以及不同布局组合的效果。

左侧边栏+列表布局

右侧边栏+网格布局

左侧边栏+三列网格布局

双侧边栏+列表布局

双侧边栏+网格布局

双侧边栏+网格瀑布流布局

一、侧边栏布局系统#

侧边栏是博客页面的重要组成部分，用于展示导航、分类、标签、统计信息等辅助内容。Firefly 支持两种侧边栏布局模式。

1.1 单侧边栏模式#

左侧边栏 (position: “left”)#

左侧边栏布局

右侧边栏 (position: “right”)#

右侧边栏布局

特点#

侧边栏固定在页面其中一侧
文章阅读区域体验更佳，更宽敞
更加简约，没有那么紧凑

适用场景#

传统博客风格
强调导航和分类的博客
需要突出用户资料的个人博客
内容为主，辅助信息次之的场景

Tip

可以通过showBothSidebarsOnPostPage配置是否在文章详情页显示双侧边栏

当position为left或right时开启此项后，文章详情页将显示双侧边栏，主页等其他页面保持单侧边栏

适用在只想用单侧栏，但在文章详情页想用对侧栏的目录等组件的场景

配置示例#

src/config/sidebarConfig.ts

1
export const sidebarLayoutConfig: SidebarLayoutConfig = {
2
  enable: true,
3
  position: "left", // 左侧边栏
4
  showBothSidebarsOnPostPage: true, // 是否在文章详情页显示双侧边栏
5
};

1.2 双侧边栏模式 (position: “both”)#

特点#

左右两侧同时存在侧边栏
主内容区域位于中间
最大化利用屏幕空间
可以展示更多辅助信息
适合宽屏显示器

布局结构#

双侧边栏+列表布局

双侧边栏+网格布局

适用场景#

宽屏桌面端浏览
信息密集型博客
需要展示大量辅助内容
专业性强的技术博客

配置示例#

src/config/sidebarConfig.ts

1
export const sidebarLayoutConfig: SidebarLayoutConfig = {
2
  enable: true,
3
  position: "both", // 双侧边栏

二、文章列表布局系统#

文章列表是博客首页和归档页的核心内容，Firefly 提供两种展示方式，并支持多种网格配置。

2.1 列表模式 (defaultMode: “list”)#

特点#

单列纵向排列
显示文章封面图，可配置在左侧或右侧
展示更多文章摘要
适合深度阅读

列表布局结构#

列表模式布局

封面位置#

列表模式的封面图默认在卡片右侧，可以通过 coverPosition 改到左侧。改到左侧后，标题前的主题色竖线会自动隐藏（它是贴着卡片左边缘的设计），腾出的间距留给正文。

网格模式的封面固定在卡片顶部，不受这项配置影响。

优点#

✅ 视觉冲击力强，封面图吸引眼球
✅ 可以展示更多文章信息（摘要、标签等）
✅ 适合图片内容丰富的博客
✅ 移动端友好，单列更易阅读
✅ 兼容所有侧边栏配置（单侧、双侧）

配置示例#

src/config/siteConfig.ts

1
export const siteConfig: SiteConfig = {
2
  postListLayout: {
3
    defaultMode: "list",    // 列表模式
4
    coverPosition: "right", // 封面图位置："right" 右侧，"left" 左侧
5
  },
6
};

2.2 网格模式 (defaultMode: “grid”)#

特点#

自适应列数，根据浏览器宽度自动调整
紧凑布局，信息密度高
适合快速浏览

自适应网格#

网格模式通过 columnWidth 配置卡片的最小宽度（单位 px），浏览器会根据容器可用宽度自动计算能容纳多少列。

网格布局

配置示例#

src/config/siteConfig.ts

1
export const siteConfig: SiteConfig = {
2
  postListLayout: {
3
    defaultMode: "grid",
4
    grid: {
5
      masonry: true,      // 开启瀑布流
6
      columnWidth: 320,   // 卡片最小宽度(px)，浏览器自动计算列数
7
    },
8
  },
9
};

2.3 瀑布流布局 (Masonry)#

Firefly 的网格模式内置了智能瀑布流布局支持，解决了网格布局中因图文混合文章导致的卡片高度不一致导致的空白问题。

瀑布流布局

智能排版：自动将卡片放置到最短的列，最大化利用垂直空间。
消除空白：通过绝对定位精确计算每个卡片的位置，让卡片紧贴上方卡片，消除垂直方向的空白间隙。
自适应列数：瀑布流同样根据 columnWidth 和容器宽度动态计算列数，无需固定配置。
配置灵活：您可以在 siteConfig.ts 中通过 postListLayout.grid.masonry 选项自由开启或关闭此功能。

三、布局组合指南#

Firefly 允许您自由组合侧边栏和文章列表布局。以下是各种组合的效果说明。

侧边栏模式	文章列表模式	推荐度	适用场景
单侧边栏	列表模式	⭐⭐⭐⭐⭐	摄影、设计、生活类博客，强调图片和沉浸感
单侧边栏	网格模式	⭐⭐⭐⭐⭐	技术、笔记类博客，平衡阅读与检索效率
双侧边栏	列表模式	⭐⭐⭐⭐⭐	需要展示大量侧边栏信息的站点
双侧边栏	网格模式	⭐⭐⭐⭐⭐	极客风格，追求最高信息密度

四、响应式布局行为#

Firefly 的布局系统具有智能的响应式设计，会根据屏幕尺寸自动调整。

为了保证最佳阅读体验，系统会在屏幕变窄时自动调整布局：

网格列数自动减少：网格模式的列数由 columnWidth 和容器宽度自动决定，屏幕越窄列数越少。
列表模式 -> 网格模式：当屏幕宽度小于 380px（超小屏设备）时，列表模式会自动切换为网格模式，以保证卡片内容的可读性。
双侧边栏 -> 单侧边栏：当屏幕宽度小于 1280px 时，会根据tabletSidebar配置显示单侧边栏，隐藏其中一个侧边栏，文章目录导航会切换成浮动目录导航。

五、常见问题#

Q1: 如何调整网格列数？#

A: 通过 columnWidth 配置卡片最小宽度即可。值越小，同等宽度下列数越多；值越大，列数越少。浏览器会自动根据可用宽度计算最佳列数。

六、总结#

Firefly 的布局系统给予了您更大的自由度，您都可以通过简单的配置实现。

我们建议您根据自己的内容类型和目标读者的设备偏好，尝试不同的组合，找到最适合您的博客形态。

Firefly Wiki Link 内部链接示例

Sat, 03 Jan 1970 00:00:00 GMT

Firefly 支持在 Markdown、MDX 文章中使用 Obsidian 风格的 Wiki Link 内部链接。链接目标填写文章的 slug 或文件路径，都不需要包含扩展名，具体匹配规则见下文「链接目标的三种写法」。

文章链接卡片#

[[slug]] 单独成段时，会自动读取目标文章的标题、描述、发布时间、分类、标签和封面，渲染为链接卡片：

1
[[firefly]]
2

3
[[guide/index]]
4

5
[[markdown-extended]]

Firefly 一款清新美观的 Astro 博客主题模板

Firefly 是一款基于 Astro 框架和 Fuwari 模板开发的清新美观且现代化个人博客主题模板，专为技术爱好者和内容创作者设计。该主题融合了现代 Web 技术栈，提供了丰富的功能模块和高度可定制的界面，让您能够轻松打造出专业且美观的个人博客网站。

1970-01-02文章示例#Markdown#Firefly#博客#主题#模板

Firefly 简单使用指南

如何使用 Firefly 博客模板。

1970-01-02博客指南#Firefly#博客#Markdown#指南

Markdown 扩展功能

了解 Firefly 中的 Markdown 功能

1970-01-01文章示例#演示#示例#Markdown#Firefly

行内链接#

[[slug]] 出现在正文中间时，渲染为普通链接，链接文字自动使用目标文章的标题

1
请参阅 [[firefly]] 了解主题特性。

请参阅 Firefly 一款清新美观的 Astro 博客主题模板了解主题特性。

自定义显示标题#

在 | 后填写链接的显示文字。行内链接会用它替换文章标题；单独成段时依然渲染为卡片，卡片标题使用自定义文字，描述、时间、分类、标签和封面仍然读取目标文章：

1
请参阅 [[firefly|主题介绍]] 了解主题特性。
2

3
[[firefly|Firefly 主题介绍]]

请参阅主题介绍了解主题特性。

Firefly 主题介绍

1970-01-02文章示例#Markdown#Firefly#博客#主题#模板

一个例外：如果 | 后的文字只是把链接目标又抄了一遍（[[guide/index|index]]），会被当作无效别名忽略，仍然显示文章标题。Obsidian 在插入的链接时会自动补上这样的别名，避免笔记里显示一长串路径，这个例外就是为它准备的。

链接目标的三种写法#

用 Obsidian 管理文章时，把 src/content/posts 目录本身作为 Obsidian 仓库（vault）打开。下文提到的「仓库根目录」都指这个目录，它正好也是 Firefly 解析链接路径的起点。

链接目标按以下顺序匹配：

写法	示例	在 Obsidian 中
frontmatter 的 `slug`	`[[firefly-wiki-link]]`	✗ 不支持
文件路径（相对仓库根目录）	`[[guide/firefly-layout-system]]`	✓ 需改设置（推荐）
裸文件名（仓库内唯一时）	`[[firefly-layout-system]]`	✓ 默认即是

第一种：slug#

slug 写法在 Obsidian 中不支持，slug 是 Firefly 自己的概念，Obsidian 不读取 frontmatter 里的 slug，所以按 slug 写的链接在 Obsidian 里既不会自动补全，也点不动，只有构建出的站点上能正常跳转。如果你主要在 Obsidian 里写作，用下面两种写法。

第二种：文件路径（推荐）#

文件路径写法需要改 Obsidian 设置，在 设置 → 文件与链接 → 链接 → 内部链接类型 中选择基于仓库根目录的绝对路径，Obsidian 插入的链接才会带上目录：

1
[[guide/firefly-layout-system|firefly-layout-system]]

Firefly 布局系统详解

深入了解 Firefly 的布局系统，包括侧边栏布局（左侧/双侧）和文章列表布局（列表/网格），以及自适应网格列数。

1970-01-03博客指南#Firefly#布局#博客#指南

因为仓库根目录就是 src/content/posts，Obsidian 写出的这个路径和 Firefly 需要的路径完全一致，不需要任何额外转换。

上面这行末尾的 |firefly-layout-system 是 Obsidian 自动补的别名，Firefly 会忽略它，卡片标题仍然取文章的 title，除非你把它修改和文件名不一致，才会变成你修改后的别名。

内部链接类型下拉框里的基于当前笔记的相对路径只在同目录内可用：它给同目录文章生成的是裸文件名，能正常匹配；但跨目录时会生成 ../ 前缀，Firefly 无法解析，链接会按原文显示。

第三种：裸文件名#

「内部链接类型」的默认值就是尽可能简短的形式：只要文件名在整个仓库里唯一，Obsidian 插入的链接就只有文件名，不带目录。这种写法不需要改任何设置，效果和写完整路径完全一致：

1
[[firefly-layout-system]]

Firefly 布局系统详解

深入了解 Firefly 的布局系统，包括侧边栏布局（左侧/双侧）和文章列表布局（列表/网格），以及自适应网格列数。

1970-01-03博客指南#Firefly#布局#博客#指南

文件名重名时这种写法会失效，构建日志里会给出提示，改用完整文件路径即可，所以推荐直接修改 Obsidian 内部链接类型设置为基于仓库根目录的绝对路径，使用第二种文件路径写法，一劳永逸

链接到其他文章的标题#

在文章 slug 后添加 #标题。带标题锚点的链接始终渲染为普通链接：

查看代码块语法高亮

Firefly 布局系统详解#相关链接

1
[[code-examples#语法高亮|查看代码块语法高亮]]
2

3
[[guide/firefly-layout-system#相关链接|firefly-layout-system]]

标题锚点使用与页面标题相同的 slug 规则，因此中文、空格和大小写都会按页面实际生成的 ID 处理。

链接到本页标题#

省略文章 slug，只填写标题即可链接到当前文章：

跳转到本页目标

1
[[#本页目标|跳转到本页目标]]

本页目标#

这是本页 Wiki Link 指向的标题。

不支持附件嵌入#

附件嵌入语法目前不会被转换，会按原文显示：

![[image.png]]

行内代码和代码块中的 [[firefly]] 也不会被转换。

Firefly 文章加密

Fri, 02 Jan 1970 00:00:00 GMT

这是一篇密码保护的示例文章，用于演示文章加密功能。

KaTeX 数学公式示例

Fri, 02 Jan 1970 00:00:00 GMT

本文展示了 Firefly 主题对 KaTeX 数学公式的渲染支持。

行内公式 (Inline)#

行内公式使用单个 $ 符号包裹。

例如：欧拉公式 eiπ+1=0e^{i\pi} + 1 = 0eiπ+1=0 是数学中最优美的公式之一。

质能方程 E=mc2E = mc^2E=mc2 也是家喻户晓。

块级公式 (Block)#

块级公式使用两个 $$ 符号包裹，会居中显示。

∫−∞∞e−x2dx=π\int_{-\infty}^{\infty} e^{-x^2} dx = \sqrt{\pi}∫−∞∞e−x2dx=πx=−b±b2−4ac2ax = \frac{-b \pm \sqrt{b^2 - 4ac}}{2a}x=2a−b±b2−4ac

复杂示例#

矩阵 (Matrices)#

(abcd)(αβγδ)=(aα+bγaβ+bδcα+dγcβ+dδ)\begin{pmatrix} a & b \\ c & d \end{pmatrix} \begin{pmatrix} \alpha & \beta \\ \gamma & \delta \end{pmatrix} = \begin{pmatrix} a\alpha + b\gamma & a\beta + b\delta \\ c\alpha + d\gamma & c\beta + d\delta \end{pmatrix}(acbd)(αγβδ)=(aα+bγcα+dγaβ+bδcβ+dδ)

极限与求和 (Limits and Sums)#

∑n=1∞1n2=π26\sum_{n=1}^{\infty} \frac{1}{n^2} = \frac{\pi^2}{6}n=1∑∞n21=6π2lim⁡x→0sin⁡xx=1\lim_{x \to 0} \frac{\sin x}{x} = 1x→0limxsinx=1

麦克斯韦方程组 (Maxwell’s Equations)#

∇⋅E=ρε0∇⋅B=0∇×E=−∂B∂t∇×B=μ0J+μ0ε0∂E∂t\begin{aligned} \nabla \cdot \mathbf{E} &= \frac{\rho}{\varepsilon_0} \\ \nabla \cdot \mathbf{B} &= 0 \\ \nabla \times \mathbf{E} &= -\frac{\partial \mathbf{B}}{\partial t} \\ \nabla \times \mathbf{B} &= \mu_0\mathbf{J} + \mu_0\varepsilon_0\frac{\partial \mathbf{E}}{\partial t} \end{aligned}∇⋅E∇⋅B∇×E∇×B=ε0ρ=0=−∂t∂B=μ0J+μ0ε0∂t∂E

化学方程式 (Chemical Equations)#

\ceCH4+2O2−>CO2+2H2O\ce{CH4 + 2O2 -> CO2 + 2H2O}\ceCH4+2O2−>CO2+2H2O

符号	代码	渲染结果
Alpha	`\alpha`	α\alphaα
Beta	`\beta`	β\betaβ
Gamma	`\Gamma`	Γ\GammaΓ
Pi	`\pi`	π\piπ
Infinity	`\infty`	∞\infty∞
Right Arrow	`\rightarrow`	→\rightarrow→
Partial	`\partial`	∂\partial∂

MDX 格式文章示例

Fri, 02 Jan 1970 00:00:00 GMT

Tip

Firefly 支持 MDX 和 Markdown 两种类型的文章，你可以在文章中混合使用两种格式，如果没有特别复杂内容和需求，推荐使用 Markdown 格式就够了。

Markdown 和 MDX 的区别#

Markdown (MD) 是一种轻量级标记语言，允许用户使用纯文本格式编写文档，然后将其转换为格式化的HTML。它因其简洁易用的语法而广受欢迎，特别适合编写文档和博客文章。
MDX 是一种扩展了 Markdown 语法的格式，允许在 Markdown 文档中无缝地插入 JSX 代码。通过 MDX，用户可以在文档中嵌入 React 组件，从而实现更丰富的交互性和动态性。

特性	Markdown	MDX
基础语法	支持 (CommonMark)	支持 (CommonMark)
HTML 标签	支持	支持 (作为 JSX)
组件导入	不支持	支持 (import)
动态数据	不支持	支持 (JS 表达式)
样式定制	有限 (class/style)	灵活 (className/CSS-in-JS)

使用组件#

这是一个图标组件：

1
import { Icon } from 'astro-icon/components'
2

3
<div class="flex items-center gap-2 my-4">
4
  <Icon name="fa7-solid:rocket" class="text-4xl text-red-500" />
5
  <span>火箭发射！</span>
6
</div>

火箭发射！

使用 JSX#

你也可以直接写 HTML/JSX：

1
<div className="p-4 bg-blue-100 dark:bg-blue-900 rounded-lg my-4">
2
  这是一个自定义样式的 div 块，使用了 Tailwind CSS 类。
3
</div>

这是一个自定义样式的 div 块，使用了 Tailwind CSS 类。

简单的变量导出#

1
export const year = new Date().getFullYear()
2

3
今年是 {year} 年。

今年是 2026 年。

更多信息，请查看 MDX 文档

Markdown 扩展功能

Thu, 01 Jan 1970 00:00:00 GMT

GitHub 仓库卡片#

您可以添加链接到 GitHub 仓库的动态卡片，在页面加载时，仓库信息会从 GitHub API 获取。

CuteLeaf

Firefly

Waiting for api.github.com...

00K

Waiting...

使用代码 ::github{repo="CuteLeaf/Firefly"} 创建 GitHub 仓库卡片。

1
::github{repo="CuteLeaf/Firefly"}

提醒框(Admonitions)配置#

Firefly 采用了 rehype-callouts 插件，支持了四种风格的提醒框主题：GitHub、Obsidian、VitePress 和 Docusaurus。您可以在 src/config/siteConfig.ts 中进行配置：

src/config/siteConfig.ts

1
export const siteConfig: SiteConfig = {
2
  // ...
3
  rehypeCallouts: {
4
    // 选项: "github" | "obsidian" | "vitepress" | "docusaurus"
5
    theme: "github",
6
  },
7
  // ...
8
};

注意：更改配置后需要重启开发服务器才能生效。

以下是各个主题支持的类型列表，每个主题风格和语法不同，可根据喜好选择。

1. GitHub 主题风格#

这是 GitHub 官方支持的 5 种基本类型。

GitHub

基本语法

1
> [!NOTE] NOTE
2
> 突出显示用户应该考虑的信息。
3

4
> [!TIP] TIP
5
> 可选信息，帮助用户更成功。
6

7
> [!IMPORTANT] IMPORTANT
8
> 用户成功所必需的关键信息。
9

10
> [!WARNING] WARNING
11
> 关键内容，需要立即注意。
12

13
> [!CAUTION] CAUTION
14
> 行动的负面潜在后果。
15

16
> [!NOTE] 自定义标题
17
> 这是一个带有自定义标题的示例。

展开收起

2. Obsidian 主题风格#

Obsidian 风格支持非常丰富的类型和别名。

点击展开 Obsidian 语法列表

1
> [!NOTE] NOTE
2
> 通用的笔记块。
3

4
> [!ABSTRACT] ABSTRACT
5
> 文章的摘要。
6

7
> [!SUMMARY] SUMMARY
8
> 文章的总结（同 Abstract）。
9

10
> [!TLDR] TLDR
11
> 太长不看（同 Abstract）。
12

13
> [!INFO] INFO
14
> 提供额外信息。
15

16
> [!TODO] TODO
17
> 需要完成的事项。
18

19
> [!TIP] TIP
20
> 实用技巧或提示。
21

22
> [!HINT] HINT
23
> 暗示（同 Tip）。
24

25
> [!IMPORTANT] IMPORTANT
26
> 重要信息（Obsidian 风格通常使用类似的图标）。
27

28
> [!SUCCESS] SUCCESS
29
> 操作成功。
30

31
> [!CHECK] CHECK
32
> 检查通过（同 Success）。
33

34
> [!DONE] DONE
35
> 已完成（同 Success）。
36

37
> [!QUESTION] QUESTION
38
> 提出问题。
39

40
> [!HELP] HELP
41
> 寻求帮助（同 Question）。
42

43
> [!FAQ] FAQ
44
> 常见问题（同 Question）。
45

46
> [!WARNING] WARNING
47
> 警告信息。
48

49
> [!CAUTION] CAUTION
50
> 注意事项（同 Warning）。
51

52
> [!ATTENTION] ATTENTION
53
> 引起注意（同 Warning）。
54

55
> [!FAILURE] FAILURE
56
> 操作失败。
57

58
> [!FAIL] FAIL
59
> 失败（同 Failure）。
60

61
> [!MISSING] MISSING
62
> 缺失内容（同 Failure）。
63

64
> [!DANGER] DANGER
65
> 危险操作警告。
66

67
> [!ERROR] ERROR
68
> 错误信息（同 Danger）。
69

70
> [!BUG] BUG
71
> 报告软件缺陷。
72

73
> [!EXAMPLE] EXAMPLE
74
> 展示一个例子。
75

76
> [!QUOTE] QUOTE
77
> 引用一段话。
78

79
> [!CITE] CITE
80
> 引证（同 Quote）。
81

82
> [!NOTE] 自定义标题
83
> 这是一个带有自定义标题的示例。

展开收起

Obsidian

3. VitePress 主题风格#

VitePress 风格提供了一套现代化的、扁平的默认样式。目前仅包含与 GitHub 一致的 5 种 基础类型。

点击展开 VitePress 语法列表

1
> [!NOTE] NOTE
2
> 对应 GitHub 的 Note。
3

4
> [!TIP] TIP
5
> 对应 GitHub 的 Tip。
6

7
> [!IMPORTANT] IMPORTANT
8
> 对应 GitHub 的 Important。
9

10
> [!WARNING] WARNING
11
> 对应 GitHub 的 Warning。
12

13
> [!CAUTION] CAUTION
14
> 对应 GitHub 的 Caution。
15

16
> [!TIP] 自定义标题
17
> VitePress 风格同样支持自定义标题。

展开收起

VitePress

4. Docusaurus 主题风格#

Docusaurus 风格提供了一套现代化的提醒框样式，支持 5 种类型。

点击展开 Docusaurus 语法列表

支持以下类型的提醒框：note tip info warning danger

1
:::note
2
突出显示用户应该考虑的信息，即使在快速浏览时也是如此。
3
:::
4

5
:::tip
6
可选信息，帮助用户更成功。
7
:::
8

9
:::info
10
一般信息。
11
:::
12

13
:::warning
14
由于潜在风险需要用户立即注意的关键内容。
15
:::
16

17
:::danger
18
行动的负面潜在后果。
19
:::
20

21
:::tip[自定义标题]
22
可选信息，帮助用户更成功。
23
:::

展开收起

Docusaurus

剧透#

您可以为文本添加剧透。文本也支持 Markdown 语法。

内容被隐藏了哈哈！

1
内容 :spoiler[被隐藏了 **哈哈**]！

图片画廊网格 (Image Grid)#

您可以使用 [grid] 和 [/grid] 标签将多张图片纵向并排展示。这对于展示照片画廊或对比图非常有用。系统会自动根据包裹在其中的图片数量（最多支持并排展示4张）以响应式网格进行布局。

自动补齐图片高度： 同一排中如果有高度、大小或者比例不一的图片，会像「九宫格画廊相册」一样自动撑满。较短或不协调的图片会自动使用 object-cover 进行完美中心裁剪补充视野。图片边框水平彻底对齐无缝隙，但被裁剪后，只有点击图片通过灯箱才能查看完整图片，所以建议尽量避免使用长宽比例不一致的图片在同一排中。

图注恒定底端对齐： 不论上面的图片长宽如何变化，在同一行的所有图像解释文字（图注）都会对标到一条完美的水平基线上了。

示例图片一

示例图片二

基本语法

1
[grid]
2
![示例图片一](./images/firefly1.avif)
3
![示例图片二](./images/firefly2.avif)
4
![示例图片二](./images/firefly3.avif)
5
[/grid]

Markdown PlantUML 图表

Thu, 01 Jan 1970 00:00:00 GMT

Markdown 中 PlantUML 图表指南#

PlantUML 是一种使用纯文本描述图表的工具。你只需要写一段结构化语法，就可以生成时序图、类图、用例图、活动图等常见工程图。

它特别适合写在技术博客和项目文档里：

图表和正文一起版本管理，便于协作与审阅
修改图只需要改文本，适合频繁迭代
能和 Markdown 无缝结合，保持文档统一

在 Firefly 中，plantuml 代码块会在构建阶段编码并生成服务器 SVG 地址，页面端再根据亮暗主题自动切换图源，并支持缩放、拖拽和全屏交互。