七月流火

鬼谷子说

Fri, 02 Oct 2026 00:00:00 GMT

🌟 鬼谷子说#

鬼谷子说：
改命，靠选妻，
立威，靠沉默，
服众，靠果断，
上位，靠贵人，
守业，靠制衡，
破局，靠胆识，
安民，靠仁心，
远祸，靠藏锋，
成事，靠天时。
修身，靠克己，
用人，靠明察，
治乱，靠重典，
长久，靠民心，
知退，靠慧眼，
固本，靠勤俭。
保平安，靠示弱，
悟人性，靠吃亏，
久立身，靠后路，
定乾坤，靠决断，
平风波，靠从容，
识真伪，靠时间，
聚财富，靠周期，
修境界，靠苦难，
传家业，靠规矩，
交挚友，靠患难，
稳大局，靠分寸，
知天命，靠沉淀。

用 Docker 自建 iPTV：从启动到电视播放

Fri, 02 Oct 2026 00:00:00 GMT

为什么自建#

市面上的直播源经常失效、卡顿、夹带广告。自己用 Docker 跑一套源管理系统，可以把多个来源聚合成一个稳定的 M3U，随时在电视、手机、平板上订阅。

快速开始#

1
services:
2
  iptv:
3
    image: akiralereal/iptv:latest
4
    ports:
5
      - "1905:1905"
6
    volumes:
7
      - ./data:/app/data
8
    restart: unless-stopped

启动：

Terminal window

1
docker compose up -d

管理后台默认地址：

M3U：/interface.m3u
TXT：/txt
EPG：/playback.xml
后台：/admin

播放器适配#

播放器	格式
DIYP / 百川	TXT
TiviMate / 飞牛	标准 M3U
老设备	兼容版 `?relay=1`
更老设备	全代理版 `?relay=2`

提示：家里几天没人看会员频道也不会掉线，后台会自动续期。

下一步可以接入央视频、爱奇艺体育等来源，按需开启即可。

Firefly 一款清新美观的 Astro 博客主题模板

Fri, 02 Jan 1970 00:00:00 GMT

🌟 项目概述#

Firefly 是一款基于 Astro 框架和 Fuwari 模板开发的清新美观且现代化个人博客主题模板，专为技术爱好者和内容创作者设计。该主题融合了现代 Web 技术栈，提供了丰富的功能模块和高度可定制的界面，让您能够轻松打造出专业且美观的个人博客网站。

🖥️在线预览： Firefly - Demo site

📝Firefly使用文档： https://docs-firefly.cuteleaf.cn

⭐Firefly开源地址：https://github.com/CuteLeaf/Firefly

⭐Fuwari开源地址：https://github.com/saicaca/fuwari

CuteLeaf

Firefly

🍀Firefly, fresh and aesthetic Astro blog theme template.

✨A static blog template built with Astro.

—

MIT

Astro

Firefly

🚀 技术架构#

静态站点生成: 基于 Astro ，提供极快的加载速度和优秀的 SEO 优化
TypeScript 支持: 完整的类型安全，提升开发体验和代码质量
响应式设计: 使用 Tailwind CSS 构建，完美适配桌面端和移动端
组件化开发: 支持 Astro、Svelte 组件，灵活可扩展

📖 配置说明#

📚 详细配置文档: 查看 Firefly 使用文档获取完整的配置指南

Firefly 简单使用指南

Fri, 02 Jan 1970 00:00:00 GMT

这个博客模板是基于 Astro 构建的。对于本指南中未提及的内容，您可以在 Astro 文档中找到答案。

文章的 Front-matter#

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 会自动转换为小写

Astro 入门：10 分钟搭好你的第一个站点

Wed, 28 Oct 2026 00:00:00 GMT

为什么是 Astro#

Astro 是一个内容优先的静态站点生成器。它的几个特点很适合做技术博客：

默认零 JavaScript，页面加载极快
写文章只用 Markdown，不用碰框架
自带 SEO 支持
想加交互时，再用任意框架的”岛屿”组件

一句话：专心写内容，性能交给 Astro。

项目结构（你主要会碰这几处）#

1
src/
2
├─ content/posts/  ← 你的文章放这里（.md 文件，文件名就是网址）
3
├─ layouts/        ← 页面骨架（页头页脚、SEO）
4
├─ components/     ← 可复用的小组件（如导航栏）
5
├─ pages/          ← 路由（首页、分类页、文章页、关于、联系）
6
├─ lib/categories.ts ← 分类定义（唯一真源，改这里增减分类）
7
public/            ← 图片、字体等静态资源（原样拷贝）

最常用的三条命令#

Terminal window

1
npm install      # 第一次拉依赖
2
npm run dev      # 本地预览，改文件自动刷新（端口 4321）
3
npm run build    # 生成静态站点到 dist/

加一篇新文章只要三步#

在 src/content/posts/ 新建一个 .md 文件（文件名就是网址，用英文或拼音，例如 my-first.md）
顶部写好 frontmatter（标题、描述、日期、分类、标签）
下面直接写 Markdown 正文

1
---
2
title: "我的第一篇"
3
description: "随便写点什么"
4
published: 2026-06-01
5
category: "life"      # 分类 key：web / nas / docker / life
6
tags: ["随笔"]
7
---
8

9
正文从这里开始……

网址是怎么来的（很简单）#

你想去	网址
首页	`/`
网络汇总页	`/web/`
NAS 分类	`/nas/`
Docker 分类	`/docker/`
生活分类	`/life/`
某篇文章	`/分类/文件名/` （例如 `/docker/iptv-docker/`）
关于 / 联系	`/about/` `/contact/`

规则：文章 URL = /分类key/文件名/。分类 key 在 src/lib/categories.ts 里定义，想加分类就改那个文件。

就是这么简单。想深入可以看 Astro 官方文档。

上门网络服务随笔：那些踩过的坑

Thu, 22 Oct 2026 00:00:00 GMT

客户说”没网”，八成是路由器#

上门最常见的一句话是”网断了”。到现场一看，十次有六次是路由器死机或光猫被碰掉电，重启就好。真正运营商侧故障反而少。

提醒：先别急着报修，看一眼光猫的 LOS 灯——红灯才是真断纤。

“全屋 Wi-Fi 差”，往往是架构错#

很多家庭买三台”路由器”到处插，每台都开 DHCP，结果是双层 NAT、设备乱跳。正确的姿势是一台主路由 + 多个 AP。

提醒：买设备前先想拓扑，别被”买了三台更稳”误导。

“我要公网 IP”，但没说要干什么#

有客户开口就要公网 IP，细问才知道是想在外看家里摄像头。这种情况更安全的做法是上 VPN / 穿透，而不是把摄像头端口直接暴露公网。

提醒：能不暴露就不暴露，安全永远排在方便前面。

一句总结#

网络问题大多不是”设备不行”，而是”规划没做对”。先理清需求和拓扑，再谈花钱升级硬件。

飞牛 FnOS + Cloudflare Tunnel 内网穿透完整教程

Thu, 22 Oct 2026 00:00:00 GMT

飞牛 FnOS + Cloudflare Tunnel 内网穿透完整教程#

一、前置准备#

一个域名，已托管到 Cloudflare（NS 已切换）
飞牛 FnOS 已安装 Docker / Docker Compose
需要穿透的服务在 FnOS 上正常运行

二、Cloudflare 端配置#

1. 开通 Zero Trust#

登录 Cloudflare 后台，左侧点 Zero Trust
设置团队名称（随意），到付款页面选 Free 计划，完成开通

Free 计划支持 50 用户以内免费使用 Access，个人用完全够。如果当时跳过了套餐选择，后续在 Access → 应用程序页面会提示”选择计划”，点进去选 Free 即可。

2. 创建隧道#

Zero Trust 后台 → 左侧 Networks → Tunnels
点 Create a tunnel → 选 Cloudflared → 下一步
给隧道命名（比如 fnos-tunnel）→ 保存
安装方式选 Docker，复制页面给出的 token（后面要用）

三、FnOS 端部署 cloudflared#

关键：必须用 host 网络模式#

如果用默认 bridge 网络，容器里的 127.0.0.1 是容器自己，访问不到宿主机上的服务，会报 connection refused。

在 FnOS 上创建 docker-compose.yml：

1
version: '3'
2
services:
3
  cloudflared:
4
    image: cloudflare/cloudflared:latest
5
    container_name: cloudflared
6
    network_mode: host
7
    restart: unless-stopped
8
    command: tunnel --no-autoupdate run --token 这里替换成你的token

启动：

Terminal window

1
docker compose up -d

验证容器运行状态：

Terminal window

1
docker ps | grep cloudflared

确认网络模式是 host：

Terminal window

1
docker inspect cloudflared | grep NetworkMode

输出必须是 "NetworkMode": "host"。

回到 Cloudflare 隧道页面，等连接器状态变绿，点 Next。

四、配置公共主机名#

在隧道详情页 → Public Hostnames → Add a public hostname：

字段	填写说明
Subdomain	子域名前缀，比如 `nas`
Domain	选择你的域名
Path	留空
Type	`HTTP`
URL	`127.0.0.1:你的服务端口`

关键：URL 用 127.0.0.1，不要用本机局域网 IP#

ESXI 虚拟机内，程序访问本机网卡 IP（如 10.0.0.4:8080）会触发虚拟交换机回流拦截，导致超时。用 127.0.0.1 走本地回环，不走网卡，避开这个问题。

点 Save hostname 保存，配置立即生效，不用重启容器。

五、验证#

浏览器访问 https://子域名.你的域名，能正常打开页面即成功。

本地验证服务是否正常（FnOS SSH 执行）：

Terminal window

1
curl http://127.0.0.1:你的服务端口

能返回内容说明服务正常。

六、多服务配置#

在 Public Hostnames 里逐个添加，每个服务对应一个子域名：

子域名	URL
`nas`	`127.0.0.1:5666`（飞牛管理界面）
`music`	`127.0.0.1:8080`（音乐服务）
`download`	`127.0.0.1:9000`（下载服务）

每个都用 127.0.0.1:端口，host 网络模式下都能正常访问。

七、常见问题排查#

问题 1：502 Bad Gateway，日志报 `dial tcp 127.0.0.1:端口: connect: connection refused`#

原因：cloudflared 容器不是 host 网络模式。

解决：确认 docker-compose.yml 里有 network_mode: host，重建容器。

Terminal window

1
docker compose down && docker compose up -d

问题 2：502，日志报 `dial tcp 10.0.0.x:端口: i/o timeout`#

原因：URL 填了本机局域网 IP，ESXI 虚拟交换机拦截回流流量。

解决：隧道后台把 URL 改成 127.0.0.1:端口。

问题 3：502，日志报 `Host validation failed`#

原因：后端服务强制校验 Host 头。

解决：隧道后台编辑该域名 → Additional application settings → HTTP Host Header 填入后端服务认可的域名。

问题 4：查看 cloudflared 日志#

Terminal window

1
docker logs cloudflared --tail 50

日志里会明确写清楚连哪个地址失败，根据报错对应上面的问题处理。

八、安全加固：Cloudflare Access 身份验证#

给隧道服务加登录验证，只有你授权的人能访问，防止公网裸奔。

配置步骤#

进入 Zero Trust 后台 → 左侧 访问控制 → 应用程序
点 Add an application → 选 Self-hosted
填写：
- Application name：随意，比如 我的NAS
- Session duration：选 24 hours 或更久
- Application domain：选你的域名，子域名填你要保护的那个（比如 music）
点 Next
Policy name：随意，比如 允许我自己
Action：选 Allow
Include 规则里：
- 选 Email
- 填你的邮箱地址（只有这个邮箱能登录访问）
点 Next → 点 Add application 保存

效果#

以后访问受保护的子域名，会先跳转到 Cloudflare 登录页，输入你授权的邮箱，收验证码登录后才能进入服务。

多个服务#

每个子域名单独建一个 Application，分别保护。或者建一个 Application，domain 那里选 *.你的域名，一次性保护所有子域名。

九、其他安全建议#

措施	说明
不用飞牛默认端口	改管理界面默认端口，避免被扫
强密码	飞牛账号、各服务账号用强密码
不开不必要的服务	只穿透真正需要外网访问的
定期更新	cloudflared 镜像、FnOS 系统、各容器保持更新
配合 Access	敏感服务一定要加 Access 身份验证

十、配置速查表#

配置项	正确值	错误值
容器网络模式	`network_mode: host`	默认 bridge
后端服务地址	`http://127.0.0.1:端口`	`http://10.0.0.x:端口`
Host 校验服务	填 HTTP Host Header	留空
普通服务	Host Header 留空	乱填
Zero Trust 套餐	Free 计划	未选套餐

附：本次踩坑总结#

同虚拟机内不能用本机局域网 IP（ESXI 回流拦截），要用 127.0.0.1
cloudflared 容器必须 host 网络，否则容器里的 127.0.0.1 是容器自己，不是宿主机
后端服务校验 Host 头时，需要在隧道里配置 HTTP Host Header
Cloudflare Access 需要先选 Free 套餐才能使用

家庭影音中心：Jellyfin + NAS 搭建笔记

Thu, 22 Oct 2026 00:00:00 GMT

为什么选 Jellyfin#

Jellyfin 是开源免费的媒体服务器，没有 Plex 的会员墙，也不把元数据传到境外服务器。对在意隐私的家庭用户很合适。

在 NAS 上用 Docker 部署#

典型的 docker-compose 片段：

1
services:
2
  jellyfin:
3
    image: jellyfin/jellyfin:latest
4
    container_name: jellyfin
5
    network_mode: host
6
    volumes:
7
      - ./config:/config
8
      - /volume1/media:/media
9
    restart: unless-stopped

要点：

network_mode: host 在局域网内最简单，避免端口映射麻烦；
媒体目录建议按 /media/电影、/media/剧集 规范命名，刮削更准。

硬件解码#

4K 转码很吃 CPU。能开 Intel 核显 / NVIDIA 转码就开，否则宁可直出、让客户端自己解：

客户端支持直出时，服务端几乎零占用；
老 NAS 硬解不了，就把片源压成客户端能直接播的格式。

客户端#

设备	推荐
电视	官方 TV 版 / 盒子
iPhone / iPad	Jellyfin Mobile
浏览器	直接网页播放

整理好目录、首次扫描完成后，家里任何屏幕都能秒开你的影音库。

家庭网络规划：从光猫到全屋 Wi-Fi

Thu, 22 Oct 2026 00:00:00 GMT

三个角色先分清#

光猫：运营商给的，负责把光纤信号转成网络，多数也带路由和 Wi-Fi（但性能一般）。
主路由：网络的”大脑”，拨号、DHCP、防火墙、端口转发都在这里。
AP（接入点）：只负责把 Wi-Fi 信号铺开，不抢路由的活。

小户型一台好路由就够了；大户型/复式务必”主路由 + 多个 AP”的架构，而不是堆几台都当路由。

规划清单#

弱电点位：装修期在每个房间留网线到弱电箱，比后期用电力猫稳得多。
主路由位置：尽量放在房屋中心、高处、开放空间，别塞金属弱电箱里。
Wi-Fi 频段：2.4G 穿墙远、5G 速度快，IoT 设备建议单独分 2.4G。
VLAN / 隔离：摄像头、访客网络与内网隔离，提升安全性。

常见翻车点#

光猫和路由器都开了 DHCP → 内网 IP 乱套；
AP 当二级路由用 → 双层 NAT、端口转发失效；
把所有设备塞一个 2.4G → 智能家居一多就卡。

需要更细的拨号与多 WAN 配置，可参考本站《外地使用 WireGuard 客户端设置指南》里的组网思路。

NAS 私有化入门：家庭为什么需要一台 NAS

Thu, 22 Oct 2026 00:00:00 GMT

什么是 NAS#

NAS（Network Attached Storage，网络附加存储）本质上是一台常驻在局域网里的私有存储服务器。它和移动硬盘最大的区别是：7×24 小时在线、多设备共享、带系统与应用生态，而不是插在一台电脑上临时用。

对家庭来说，它通常承担三个角色：

数据保险箱：手机照片、电脑文档自动备份，避免手机丢了/硬盘坏了就全没了。
影音中心：把电影、剧集集中存放，电视、iPad、手机随时流式播放。
轻量私有云：在外面也能访问家里的文件，不依赖第三方网盘。

哪些人真的需要#

场景	建议
手机照片越积越多、怕丢	强烈建议
家里多台设备要共享文件	建议
只想存几部电影偶尔看	先用手边硬盘/盒子即可
完全不在意隐私、习惯用公有云	可暂缓

一句话：数据越多、设备越多、越在意隐私，NAS 的回报越高。

选购前的三个判断#

盘位：2 盘位够绝大多数家庭（一块存、一块冷备）；4 盘位留给影音库和 RAID。
平台：群晖/威联通开箱即用、生态成熟；飞牛/绿联性价比高、适合爱折腾；自己用旧电脑装开源系统也行。
功耗与噪音：放在客厅就要优先考虑静音型号，放弱电箱则看散热。

落地最小步骤#

插好硬盘、连网线到主路由；
初始化系统、建存储池；
开启手机/电脑自动备份；
需要外网访问再配穿透或 VPN，不要直接把管理端口暴露公网。

下一步可以看《家庭影音中心：Jellyfin + NAS 搭建笔记》，把存好的片子真正用起来。

用 Docker 部署你的第一个自托管服务

Thu, 22 Oct 2026 00:00:00 GMT

自托管是什么#

把原本用 SaaS（网盘、笔记、相册）的服务，自己用一台机器跑起来。好处是数据在自己手里、可定制；代价是要花一点维护精力。

为什么从 Docker 开始#

Docker 把服务连同依赖打包成”容器”，装错/卸干净都很容易，是新手自托管最稳的入口。

第一步：装 Docker#

在 Linux 上一行搞定：

Terminal window

1
curl -fsSL https://get.docker.com | sh

装完后跑 docker version 能看到客户端和服务端即成功。

第二步：跑第一个容器#

以网络工具 whoami 为例：

Terminal window

1
docker run -d -p 8080:80 --name my-first traefik/whoami

浏览器打开 http://<你的IP>:8080 就能看到容器返回的请求信息。

第三步：用 compose 管理#

单个命令跑的服务，久了会忘。写成 docker-compose.yml 才是正道：

1
services:
2
  whoami:
3
    image: traefik/whoami
4
    ports: ["8080:80"]
5
    restart: unless-stopped

docker compose up -d 启动，docker compose down 停止，清清楚楚。

新手建议顺序#

先跑通上面例子，理解”镜像/容器/端口”；
再上真正有用的：笔记、相册、影音；
最后才碰反向代理和内网穿透。

本站《家庭影音中心：Jellyfin + NAS 搭建笔记》就是一步实战。

群晖 Synology + Cloudflare Tunnel 内网穿透完整教程

Thu, 22 Oct 2026 00:00:00 GMT

一、前置准备#

一个域名，已托管到 Cloudflare（NS 已切换）
群晖 NAS 已安装 Container Manager（DSM 7.2+，旧版本叫 Docker）
需要穿透的服务在群晖上正常运行
群晖已开启 SSH（控制面板 → 终端机和 SNMP → 启用 SSH 服务）

二、Cloudflare 端配置#

1. 开通 Zero Trust#

登录 Cloudflare 后台，左侧点 Zero Trust
设置团队名称（随意），到付款页面选 Free 计划，完成开通

Free 计划支持 50 用户以内免费使用 Access，个人用完全够。

2. 创建隧道#

Zero Trust 后台 → 左侧 Networks → Tunnels
点 Create a tunnel → 选 Cloudflared → 下一步
给隧道命名（比如 synology-tunnel）→ 保存
安装方式选 Docker，复制页面给出的 token（后面要用）

三、群晖端部署 cloudflared#

关键：必须用 host 网络模式#

如果用默认 bridge 网络，容器里的 127.0.0.1 是容器自己，访问不到群晖宿主机上的服务，会报 connection refused。

提供两种部署方式，任选其一。

方式 A：SSH + docker-compose（推荐，最稳定）#

1. SSH 登录群晖#

Terminal window

1
ssh 你的群晖用户名@群晖IP

2. 创建 docker-compose.yml#

找一个你喜欢的目录，比如 /volume1/docker/cloudflared/：

Terminal window

1
mkdir -p /volume1/docker/cloudflared
2
cd /volume1/docker/cloudflared

创建 docker-compose.yml：

1
version: '3'
2
services:
3
  cloudflared:
4
    image: cloudflare/cloudflared:latest
5
    container_name: cloudflared
6
    network_mode: host
7
    restart: unless-stopped
8
    command: tunnel --no-autoupdate run --token 这里替换成你的token

3. 启动容器#

Terminal window

1
docker compose up -d

如果提示 docker compose 命令不存在，用 docker-compose up -d。

4. 验证#

Terminal window

1
docker ps | grep cloudflared

确认网络模式是 host：

Terminal window

1
docker inspect cloudflared | grep NetworkMode

输出必须是 "NetworkMode": "host"。

方式 B：Container Manager 图形界面#

适合不想用命令行的用户。

1. 打开 Container Manager#

群晖桌面 → 打开 Container Manager → 左侧 注册表 → 搜索 cloudflared → 选 cloudflare/cloudflared → 下载 → 标签选 latest。

2. 创建容器#

左侧容器 → 点新增 → 选择 cloudflare/cloudflared:latest 镜像 → 下一步。

3. 常规设置#

容器名称：cloudflared
勾选 启用自动重新启动

执行命令（命令栏）填入：

1
tunnel --no-autoupdate run --token 你的token

4. 网络设置（关键）#

勾选 使用与 Docker Host 相同的网络（即 host 网络模式）
不要用默认的 bridge 网络

5. 完成创建#

一路下一步，点完成启动容器。

6. 验证#

容器列表里看到 cloudflared 运行中，详情里网络模式显示 host。

回到 Cloudflare 隧道页面，等连接器状态变绿，点 Next。

四、配置公共主机名#

在隧道详情页 → Public Hostnames → Add a public hostname：

字段	填写说明
Subdomain	子域名前缀，比如 `nas`
Domain	选择你的域名
Path	留空
Type	`HTTP`
URL	`127.0.0.1:你的服务端口`

关键：URL 用 127.0.0.1，不要用群晖局域网 IP#

群晖虚拟机内（ESXI 环境），程序访问本机网卡 IP（如 10.0.0.3:5000）可能触发虚拟交换机回流拦截。用 127.0.0.1 走本地回环，不走网卡，最稳。

点 Save hostname 保存，配置立即生效，不用重启容器。

五、验证#

浏览器访问 https://子域名.你的域名，能正常打开页面即成功。

本地验证服务是否正常（群晖 SSH 执行）：

Terminal window

1
curl http://127.0.0.1:你的服务端口

能返回内容说明服务正常。

六、多服务配置#

在 Public Hostnames 里逐个添加，每个服务对应一个子域名：

子域名	URL	说明
`dsm`	`127.0.0.1:5000`	群晖 DSM 管理界面
`photo`	`127.0.0.1:80`	Synology Photos（如Web Station）
`music`	`127.0.0.1:8080`	音乐服务
`download`	`127.0.0.1:9000`	下载服务

每个都用 127.0.0.1:端口，host 网络模式下都能正常访问。

七、常见问题排查#

问题 1：502 Bad Gateway，日志报 `dial tcp 127.0.0.1:端口: connect: connection refused`#

原因：cloudflared 容器不是 host 网络模式。

解决：

docker-compose 方式：确认 docker-compose.yml 里有 network_mode: host，重建容器
Terminal window
```
1
docker compose down && docker compose up -d
```
图形界面方式：编辑容器 → 网络 → 勾选”使用与 Docker Host 相同的网络”

问题 2：502，日志报 `dial tcp 10.0.0.x:端口: i/o timeout`#

原因：URL 填了群晖局域网 IP，ESXI 虚拟交换机拦截回流流量。

解决：隧道后台把 URL 改成 127.0.0.1:端口。

问题 3：502，日志报 `Host validation failed`#

原因：后端服务强制校验 Host 头。

解决：隧道后台编辑该域名 → Additional application settings → HTTP Host Header 填入后端服务认可的域名。

问题 4：群晖 DSM 管理界面穿透后登录跳转回内网 IP#

原因：DSM 会强制跳转，需要配置 Host Header。

解决：隧道后台编辑 DSM 对应的域名 → Additional application settings → HTTP Host Header 填入你的外网域名（比如 dsm.你的域名）。

问题 5：查看 cloudflared 日志#

Terminal window

1
docker logs cloudflared --tail 50

图形界面用户：Container Manager → 容器 → 点 cloudflared → 日志。

日志里会明确写清楚连哪个地址失败，根据报错对应上面的问题处理。

八、安全加固：Cloudflare Access 身份验证#

给隧道服务加登录验证，只有你授权的人能访问，防止公网裸奔。

配置步骤#

进入 Zero Trust 后台 → 左侧 访问控制 → 应用程序
点 Add an application → 选 Self-hosted
填写：
- Application name：随意，比如 群晖DSM
- Session duration：选 24 hours 或更久
- Application domain：选你的域名，子域名填你要保护的那个（比如 dsm）
点 Next
Policy name：随意，比如 允许我自己
Action：选 Allow
Include 规则里：
- 选 Email
- 填你的邮箱地址（只有这个邮箱能登录访问）
点 Next → 点 Add application 保存

效果#

以后访问受保护的子域名，会先跳转到 Cloudflare 登录页，输入你授权的邮箱，收验证码登录后才能进入服务。

多个服务#

每个子域名单独建一个 Application，分别保护。或者建一个 Application，domain 那里选 *.你的域名，一次性保护所有子域名。

九、群晖特有注意事项#

事项	说明
DSM 端口	默认 HTTP 5000，HTTPS 5001，隧道用 HTTP 填 5000 即可
DSM 登录跳转	必须配置 HTTP Host Header 为外网域名，否则登录后跳内网
群晖防火墙	控制面板 → 安全性 → 防火墙，确保不拦截 cloudflared 出站（一般默认放行）
Container Manager vs Docker	DSM 7.2+ 叫 Container Manager，旧版本叫 Docker，操作基本一致
群晖反向代理	如果用了群晖自带的反向代理（控制面板 → 登录门户 → 高级 → 反向代理），隧道地址填反代端口即可
套件 Web 服务	群晖套件（如 Photo Station、Audio Station）的端口在套件设置里查看

十、其他安全建议#

措施	说明
改 DSM 默认端口	控制面板 → 登录门户 → 更改默认 5000/5001 端口
启用自动封锁	控制面板 → 安全性 → 自动封锁，防止暴力破解
强密码	群晖账号、各服务账号用强密码
不开不必要的服务	只穿透真正需要外网访问的
定期更新	cloudflared 镜像、DSM 系统、各套件保持更新
配合 Access	敏感服务（尤其是 DSM）一定要加 Access 身份验证
两步验证	群晖账号开启两步验证

十一、配置速查表#

配置项	正确值	错误值
容器网络模式	`network_mode: host` / 使用与 Docker Host 相同网络	默认 bridge
后端服务地址	`http://127.0.0.1:端口`	`http://10.0.0.x:端口`
DSM 管理界面	HTTP Host Header 填外网域名	留空（会跳转内网）
普通服务	Host Header 留空	乱填
Zero Trust 套餐	Free 计划	未选套餐

附：核心原理#

Cloudflare Tunnel 不需要公网 IP，原理是：

群晖上的 cloudflared 客户端主动向外连接 Cloudflare 全球节点
建立一条加密的反向隧道
外网用户访问你的域名 → Cloudflare → 隧道 → 群晖上的服务

全程不需要：

公网 IPv4
路由器端口映射
DMZ 主机
DDNS

只要群晖能正常上网就行。

未来五年（2026‑2031）电商趋势分析报告

Wed, 21 Oct 2026 00:00:00 GMT

这篇就是给你当模板用的。下面每一种语法都可以直接抄。

未来五年（2026–2031）电商核心趋势#

总基调：告别纯流量红利，从”低价走量”转向全域、AI驱动、即时履约、品牌化、合规化、出海多元增长；货架电商增速放缓，内容电商、即时零售、跨境DTC、私域复购成为增量主力。

一、技术层：AI 渗透全链路，重构生产、营销、客服、供应链#

1. 生成式 AI 成为商家标配工具#

前端：AI 主播、数字人直播、AI 短视频批量生成、AI 图文、智能试穿/试妆、商品 3D 建模；短剧、剧情种草、专业测评内容批量产出。
中端：AI 智能选品、文案、主图、标题、评价管理、智能客服、自动售后、智能投放，大幅降低中小商家人力成本。
后端：AI 预测销量、动态库存调度、智能分仓，柔性供应链普及。
约束：监管趋严，AI 内容真实性、虚假宣传、AI 刷单会重点管控，纯 AI 低质搬运内容流量会被限制。

2. 沉浸式交互（VR/AR/3D 商详）逐步落地#

大件家具、家电、家装、服饰、珠宝优先普及，线上”所见接近所得”，降低退货率；虚拟商品、数字藏品、数字服务电商持续扩容。

二、渠道格局：全域分层，单一平台很难做大盘#

渠道分工越来越清晰，全域经营是商家必修课：

渠道类型	代表平台	定位与趋势
传统货架电商	淘宝、京东、拼多多	增速放缓，主打搜索需求、囤货、比价、品牌官网阵地、稳定复购；大促玩法简化，直降、现货优先
内容电商	抖音、快手、小红书	种草第一入口，兴趣驱动、冲动转化；直播从达人带货转向品牌自播为主、专业垂类直播、溯源工厂直播
即时零售	美团闪购、淘鲜达、京东到家	增速最高赛道，30 分钟~2 小时送达，融入一刻钟便民圈；县城、乡镇是下沉增量市场
私域/小程序	企业微信、品牌小程序	沉淀用户、会员复购、高客单、降低平台佣金；直播、社群、会员体系打通
社区电商	各类社区团平台	回归理性，不再疯狂补贴，主打县域农产品、刚需日用品，依托自提点+本地供应链

一句话总结：货架解决”我要买什么”，内容解决”我想买点什么”，即时零售解决”我现在就要”，私域解决”反复找我买”。

三、供给与消费：国货崛起、品质优先、分层消费、绿色电商#

1. 低价内卷退潮，价值消费回归#

用户对单纯低价敏感度下降，更在意品质、售后、溯源、成分、口碑；平台流量权重向品质、服务、正品倾斜，“全网最低价”无序竞争被约束。白牌生存空间持续压缩，细分垂类国货品牌机会最大，国风、功能性、小众垂直品类持续增长。

2. 消费分层明显#

平价刚需：追求稳定性价比，供应链效率取胜；
品质升级：健康、母婴、家居、户外、个护、家电，愿意为专业、安全、售后付费；
情绪消费：IP、文创、非遗、文旅联动商品。

3. 绿色电商、可持续供应链成为硬性加分项#

简约包装、循环快递、低碳溯源、二手电商（循环电商）稳步增长；部分平台会设置绿色商品流量标签，品牌 ESG 成为海外与国内品牌的考核项。

4. 农村电商持续深化（数商兴农）#

农产品上行从散户直播走向产地仓、标准化品控、产地品牌；县域物流完善，生鲜产地直发、预制菜是重点品类。

四、跨境电商：多模式并行，从铺货走向品牌出海#

1. 平台卖家内卷加剧，DTC 独立站占比提升#

亚马逊、Temu、Shein 这类平台流量成本、合规风险持续走高；有能力的商家走独立站+社媒（TikTok、Ins）私域，做自有品牌溢价，不再单纯拼价格。

2. 海外仓是标配#

政策持续支持海外智慧仓、多式联运（中欧班列+跨境电商），本地化履约、本地化售后是竞争力核心；单纯直邮小包模式占比持续下滑。

3. 市场分化#

东南亚、拉美、中东是高增长新兴市场；欧美市场门槛高、合规严，适合做高客单品牌；同时进口跨境（国内消费者买海外好物）稳步扩容。

4. 合规红线越来越重#

税务、产品认证、数据合规、知识产权、本地化劳工规则，不合规账号风险极高；铺货模式慢慢被淘汰。

五、供应链与履约：柔性化、本地化、仓配一体化#

1. 本地仓前置、短链履约是竞争壁垒#

即时零售带动前置仓、门店仓普及；线上线下库存一盘货，统一会员、统一售后，O2O 深度融合。

2. 柔性供应链#

小单快反、按需生产，适配内容电商快速测款、爆品快速补单；C2M 反向定制（用户需求驱动工厂开发）在服饰、家居、小家电普及。

3. 物流：成本上行，效率竞争#

快递价格很难继续大幅下跌，比拼的是时效、破损率、售后上门服务；逆向物流（退货）体验成为转化短板，商家会重点优化。

六、监管与规则：全面合规，野蛮生长时代结束#

价格监管、虚假宣传、直播合规、达人财税、知识产权、数据安全、用户隐私保护持续收紧；
算法治理：平台推荐算法更透明，无序比价、流量垄断、大数据杀熟持续整治；
刷单、刷评、虚假直播、夸大宣传处罚力度加大，合规能力直接决定商家能不能活下去。

七、对不同角色的启示#

角色	核心建议
品牌方	放弃单一平台押注，搭建全域矩阵；优先做自播和私域沉淀，布局 DTC 独立站出海；产品力、品控、售后是长期护城河
中小卖家	避开红海标品价格战，深耕垂直细分赛道；善用 AI 降低运营成本；优先做复购型品类，不要只赚一次性流量钱
平台	重心从抢流量转向履约服务、供应链基建、品质治理；即时零售和跨境是核心增长曲线
服务商	AI 工具、SaaS、海外仓、合规财税、内容代运营、本地履约服务需求持续走高

风险提示#

居民消费复苏节奏存在不确定性，消费信心波动会影响可选品类；
国际地缘、海外贸易政策变化直接冲击跨境；
AI 工具同质化，单纯靠 AI 内容无法建立长期壁垒；
流量成本长期上行，没有复购能力的生意模型会越来越难。

OpenWrt 路由器折腾记

Wed, 21 Oct 2026 00:00:00 GMT

OpenWrt 路由器折腾记#

这是一篇示范文章，用来演示「文件名/标题用中文，但 URL 保持英文短横线」的写法。

为什么不用中文 URL#

中文路径在浏览器地址栏会被编码成 %E8%B7%AF%E7%94%B1%E5%99%A8 这种乱码，分享出去既丑又容易出错。用 slug: router-notes 一行就能锁定干净地址：/docker/router-notes/。

正文字随便写#

你只需要在 src/content/posts/ 下新建 .md 文件
顶部 --- 之间填写标题、分类、日期等元信息
改完保存，dev 服务器会自动刷新

提示：本文件就是「方法二」的标准示范—— 文件名用中文 OpenWrt 路由器折腾记.md（在文件夹里一眼能认出是哪篇），但 frontmatter 里加 slug: router-notes 锁定英文地址，URL 仍是 /docker/router-notes/。这样「看得懂的文件名」和「干净的中文 URL」两全其美。

我的第一篇博客文章

Sat, 09 Sep 2023 00:00:00 GMT

This is a sample English post. Astro builds the URL from the slug field in frontmatter:

slug: en/welcome → the page lives at /en/welcome/

To add more English posts, just drop a new .md file into src/content/docs/ and set slug: en/your-slug. The category comes from the category field (web / nas / docker / life).

Switch languages using the buttons in the top-right corner. Only the posts that exist in a given language will appear there.

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 切换。

在提醒框内使用（MDX 组件）#

::: code-group 和 ::: tip 等 Docusaurus 风格提醒框都使用 ::: 容器语法，而 micromark-directive 规定父子容器的冒号数必须不同，因此 ::: code-group 无法嵌套在 ::: tip 等提醒框内（整块会失效）。

这种情况改用 MDX 组件 TabGroup：MDX 组件不经过 ::: 指令解析，在提醒框内外都能正常使用，也方便日后扩展更多 UI 组件。把文章后缀改为 .mdx，从统一入口 @/components/firefly-mdx 引入（可一次引入多个组件）：

1
import { TabGroup } from "@/components/firefly-mdx";
2

3
:::tip
4

5
<TabGroup labels={["test.js", "test.py"]} client:load>
6
  ```js
7
  console.log(1)
8
  ```
9

10
  ```py
11
  print("hello world")
12
  ```
13
</TabGroup>
14

15
:::

展开收起

Tip

labels 数组给每个代码块声明标签，顺序一一对应
组件用 client:load 激活标签切换

Firefly 布局系统详解

Sat, 03 Jan 1970 00:00:00 GMT

📖 概述#

Firefly 提供了灵活的布局系统，允许您根据内容需求和个人喜好自定义博客的视觉呈现方式。布局系统主要包括侧边栏布局和文章列表布局两个维度，它们相互配合，共同决定了页面的整体结构。

本文将详细介绍 Firefly 的各种布局模式、它们的特点、使用场景，以及不同布局组合的效果。

左侧边栏+列表布局

右侧边栏+网格布局

左侧边栏+三列网格布局

双侧边栏+列表布局

双侧边栏+网格布局

双侧边栏+网格瀑布流布局

一、侧边栏布局系统#

侧边栏是博客页面的重要组成部分，用于展示导航、分类、标签、统计信息等辅助内容。Firefly 支持两种侧边栏布局模式。

1.1 单侧边栏模式#

左侧边栏 (position: “left”)#

左侧边栏布局

右侧边栏 (position: “right”)#

右侧边栏布局

特点#

侧边栏固定在页面其中一侧
文章阅读区域体验更佳，更宽敞
更加简约，没有那么紧凑

适用场景#

传统博客风格
强调导航和分类的博客
需要突出用户资料的个人博客
内容为主，辅助信息次之的场景

Tip

文章详情页显示哪几侧，由**各组件的 showOnPostPage（以及 hideOnNonPostPage）**决定：某一侧在当前页型下没有任何可见组件时，该列会自动收起，把空间让给内容栏。

如果想在文章页同时显示双侧边栏，把 position 设为 "both"，并给两侧组件配好 showOnPostPage 即可。

配置示例#

src/config/sidebarConfig.ts

1
export const sidebarLayoutConfig: SidebarLayoutConfig = {
2
  enable: true,
3
  position: "left", // 左侧边栏
4
};

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-layout-system

文件名重名时这种写法会失效，构建日志里会给出提示，改用完整文件路径即可，所以推荐直接修改 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)

Firefly 内置的专属 MDX UI 组件#

这里列出 Firefly 内置的 MDX UI 组件，方便在 MDX 文章中直接使用。

Tab分组：`TabGroup`#

用于创建可切换的标签页，方便在文章中展示不同语言或不同版本的代码等等。

1
<TabGroup labels={["test.js", "test.py"]} client:load>
2
  ```js
3
  console.log(1)
4
  ```
5

6
  ```py
7
  print("hello world")
8
  ```
9
</TabGroup>

test.jstest.py

1
console.log(1)

1
print("hello world")

时间线：`Timeline` / `TimelineItem`#

属性	必填	说明
`date`	否	时间标签，如 “2024-03-10”
`title`	否	条目标题
`type`	否	节点颜色，default 为主题色，其余对应提示框色板（tip / note / important / warning / caution）
`icon`	否	内置图标名，显示在圆点内：star / rocket / git / flag / book / heart / zap / bug / tag / calendar / code / edit
正文	否	`<TimelineItem>` 标签内的内容，支持 Markdown

1
<Timeline>
2
  <TimelineItem date="2026-08-16" title="新版本发布" icon="rocket">
3
    发布了全新版本，带来以下更新：
4

5
    - 新增时间线组件
6
    - 改进暗色主题
7

8
    正文里支持 **Markdown** 内容。
9
  </TimelineItem>
10
  <TimelineItem date="2025-11-02" title="站点上线" type="tip" icon="flag">
11
    欢迎来到我的博客。
12
  </TimelineItem>
13
  <TimelineItem date="2025-06-15" title="项目立项" type="note">
14
    开始规划 Firefly 主题。
15
  </TimelineItem>
16
</Timeline>

展开收起

2026-08-16
新版本发布
发布了全新版本，带来以下更新：
- 新增时间线组件
- 改进暗色主题
正文里支持 Markdown 内容。
2025-11-02
站点上线
欢迎来到我的博客。
2025-06-15
项目立项
开始规划 Firefly 主题。

步骤条：`Steps` / `StepItem`#

编号步骤条，适合教程、部署流程。编号自动生成，无需手动传序号。

属性	必填	说明
`title`	否	步骤标题
`type`	否	编号圆颜色，default 为主题色，其余对应提示框色板（tip / note / important / warning / caution）
`icon`	否	内置图标名，有图标时显示图标而非数字（star / rocket / git / flag / book / heart / zap / bug / tag / calendar / code / edit）
正文	否	`<StepItem>` 标签内的内容，支持 Markdown

1
<Steps>
2
  <StepItem title="安装依赖">
3
    运行 `pnpm install`。
4
  </StepItem>
5
  <StepItem title="启动开发服务器" type="tip" icon="rocket">
6
    运行 `pnpm dev`，打开 `localhost:4321`。
7
  </StepItem>
8
  <StepItem title="编写文章">
9
    在 `src/content/posts/` 新建 `.mdx` 文章。
10
  </StepItem>
11
</Steps>

安装依赖
运行 pnpm install。
启动开发服务器
运行 pnpm dev，打开 localhost:4321。
编写文章
在 src/content/posts/ 新建 .mdx 文章。

徽章：`Badge`#

内联彩色小徽章，可嵌在段落或标题里。

属性	必填	说明
`type`	否	default 为主题色，其余对应提示框色板（tip / note / important / warning / caution）

1
<Badge type="tip">提示</Badge> <Badge type="warning">注意</Badge>

新功能提示笔记重要注意危险

更多信息，请查看 MDX 文档

Markdown 扩展功能

Thu, 01 Jan 1970 00:00:00 GMT

GitHub 仓库卡片#

您可以添加链接到 GitHub 仓库的动态卡片，在页面加载时，仓库信息会从 GitHub API 获取。

CuteLeaf

Firefly

🍀Firefly, fresh and aesthetic Astro blog theme template.

—

MIT

Astro

使用代码 ::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 Mermaid 图表

Thu, 01 Jan 1970 00:00:00 GMT

Markdown 中 Mermaid 图表完整指南#

本文演示如何在 Markdown 文档中使用 Mermaid 创建各种复杂图表，包括流程图、时序图、ER 图、类图、状态图、XY 图、甘特图、思维导图等。

Mermaid 图表由 Merman 实现。Firefly 在 Astro 构建阶段生成亮色和深色两套静态 SVG，无需在浏览器中加载 Mermaid 渲染运行时。可以前往 Merman Playground 实时编辑语法并预览渲染结果。

流程图示例#

流程图非常适合表示流程或算法步骤。

是

否

选项 1

选项 2

选项 3

子过程详情

子步骤 1

子步骤 2

子步骤 3

开始

条件检查

处理步骤 1

处理步骤 2

另一个决策

结果 1

结果 2

结果 3

结束

是

否

选项 1

选项 2

选项 3

子过程详情

子步骤 1

子步骤 2

子步骤 3

开始

条件检查

处理步骤 1

处理步骤 2

另一个决策

结果 1

结果 2

结果 3

结束

时序图示例#

时序图显示对象之间随时间的交互。

数据库服务器网页应用用户数据库服务器网页应用用户alt[认证成功][认证失败]提交登录请求发送认证请求查询用户凭据返回用户数据返回认证结果显示欢迎页面请求用户数据获取用户偏好返回偏好设置返回用户数据加载个性化界面显示错误消息提示重新输入

ER 图示例#

ER 图（实体关系图）非常适合表示数据库结构。

writes

posts

has

belongs to

USER

int

string

username

string

datetime

created_at

ARTICLE

int

string

title

text

content

datetime

published

int

author_id

COMMENT

int

text

content

datetime

created_at

int

user_id

int

article_id

类图示例#

类图显示系统的静态结构，包括类、属性、方法及其关系。

写作

发表

拥有

属于

User

+String username

+String password

+String email

+Boolean active

+login()

+logout()

+updateProfile()

Article

+String title

+String content

+Date publishDate

+Boolean published

+publish()

+edit()

+delete()

Comment

+String content

+Date commentDate

+addComment()

+deleteComment()

状态图示例#

状态图显示对象在其生命周期中经历的状态序列。

提交

拒绝

批准

发布

归档

撤回

草稿

审核中

已批准

已归档

已发布

临时隐藏

恢复

活跃

隐藏

提交

拒绝

批准

发布

归档

撤回

草稿

审核中

已批准

已归档

已发布

临时隐藏

恢复

活跃

隐藏

XY 图示例#

XY 图表非常适合展示趋势和对比数据。

月度访问量趋势1月2月3月4月5月6月5000450040003500300025002000150010005000访问量

饼图示例#

饼图适合直观展示各部分在整体中的占比。

45%30%15%10%内容类型占比技术文章 [45]项目记录 [30]生活随笔 [15]其他 [10]

甘特图示例#

甘特图可以按时间轴展示项目阶段、任务依赖和当前进度。

07/0107/0307/0507/0707/0907/1107/1307/1507/17需求整理视觉设计功能实现内容迁移构建检查正式上线准备开发发布博客版本发布计划

思维导图示例#

思维导图适合梳理主题层级和知识结构。

Firefly

内容

技术文章

生活记录

体验

搜索

深色模式

图表

工程

Astro

Svelte

Merman

Firefly

内容

技术文章

生活记录

体验

搜索

深色模式

图表

工程

Astro

Svelte

Merman

时间线示例#

时间线用于按年份或阶段呈现项目的重要事件。

2024建立博客完成基础主题2025加入搜索与图库完善内容系统2026升级 Astro 7使用 Merman 渲染图表Firefly 演进时间线

用户旅程图示例#

用户旅程图能够描述用户在不同阶段的行为和体验评分。

读者

发现内容

发现内容读者

打开首页

打开首页读者

搜索主题

阅读文章

阅读文章读者

浏览正文

浏览正文读者

查看图表

继续探索

继续探索读者

查看相关文章

查看相关文章读者

分享文章

分享文章读者浏览文章的旅程

读者

发现内容

发现内容读者

打开首页

打开首页读者

搜索主题

阅读文章

阅读文章读者

浏览正文

浏览正文读者

查看图表

继续探索

继续探索读者

查看相关文章

查看相关文章读者

分享文章

分享文章读者浏览文章的旅程

Git 图示例#

Git 图可以清晰展示分支、提交和合并历史。

mainfeatureinitadd-diagramspolish-themesmerge-featurerelease

看板示例#

看板适合展示任务在不同工作阶段之间的分布。

待办

进行中

已完成

整理需求

准备示例

接入 Merman

服务端渲染

亮暗主题

待办

进行中

已完成

整理需求

准备示例

接入 Merman

服务端渲染

亮暗主题

Sankey 图示例#

Sankey 图通过连线宽度展示流量在不同节点之间的流向。

Home 1650Post list 1200Search 450Post detail 1220Related posts 260External shares 180

总结#

Mermaid 是在 Markdown 文档中创建各种类型图表的强大工具。本文演示了流程图、时序图、ER 图、类图、状态图、XY 图、饼图、甘特图、思维导图、时间线、用户旅程图、Git 图、看板和 Sankey 图。这些图表可以帮助您更清晰地表达复杂的概念、流程和数据结构。

要使用 Mermaid，只需在代码块中指定 mermaid 语言，并使用简洁的文本语法描述图表。图表会在构建时自动渲染为 SVG，无需客户端 JavaScript 加载。

可以前往 Merman Playground 尝试更多语法，再将图表代码粘贴到文章中。

Markdown PlantUML 图表

Thu, 01 Jan 1970 00:00:00 GMT

Markdown 中 PlantUML 图表指南#

PlantUML 是一种使用纯文本描述图表的工具。你只需要写一段结构化语法，就可以生成时序图、类图、用例图、活动图等常见工程图。

它特别适合写在技术博客和项目文档里：

图表和正文一起版本管理，便于协作与审阅
修改图只需要改文本，适合频繁迭代
能和 Markdown 无缝结合，保持文档统一

在 Firefly 中，plantuml 代码块会在构建阶段编码并生成服务器 SVG 地址，页面端再根据亮暗主题自动切换图源，并支持缩放、拖拽和全屏交互。

如果你想快速上手，可以记住这个最小模板：

活动图示例#

状态图示例#

用例图示例#

组件图示例#

部署图示例#

ER 图示例#

时序图示例（登录与刷新令牌）#

C4 风格容器图示例#

Markdown 教程

Thu, 01 Jan 1970 00:00:00 GMT

这是一个展示如何编写 Markdown 文件的示例。本文档汇总了核心语法与常见扩展（GFM）。

块级元素
- 段落与换行
- 标题
- 引用
- 列表
- 代码块
- 分割线
- 表格
内联元素
- 链接
- 强调
- 行内代码
- 图片
- 删除线
杂项
- 自动链接
- 反斜杠转义
内联 HTML

块级元素#

段落与换行#

段落#

HTML 标签：<p>

使用一个或多个空行分隔段落。（仅包含空格或制表符的行也视为空行。）

代码：

1
This will be
2
inline.
3

4
This is second paragraph.

预览：

This will be inline.

This is second paragraph.

换行#

HTML 标签：<br />

在行末添加两个或更多空格来产生换行。

代码：

1
This will be not
2
inline.

预览：

This will be not
inline.

标题#

Markdown 支持两种标题样式：Setext 与 atx。

Setext#

HTML 标签：<h1>，<h2>

使用等号 (=) 表示 <h1>、使用短横线 (-) 表示 <h2>，数量不限，作为“下划线”。

代码：

1
This is an H1
2
=============
3
This is an H2
4
-------------

预览：

This is an H1#

This is an H2#

atx#

HTML 标签：<h1>，<h2>，<h3>，<h4>，<h5>，<h6>

在行首使用 1-6 个井号 (#)，对应 <h1> 至 <h6>。

代码：

1
# This is an H1
2
## This is an H2
3
###### This is an H6

预览：

This is an H1#

This is an H2#

This is an H6#

可选：你可以在行尾“闭合” atx 标题。末尾的井号数量不必与开头一致。

代码：

1
# This is an H1 #
2
## This is an H2 ##
3
### This is an H3 ######

预览：

This is an H1#

This is an H2#

This is an H3#

引用#

HTML 标签：<blockquote>

Markdown 使用邮件风格的 > 作为引用符号。若手动换行并在每行前加 >，显示效果最佳。

代码：

1
> This is a blockquote with two paragraphs. Lorem ipsum dolor sit amet,
2
> consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus.
3
> Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus.
4
>
5
> Donec sit amet nisl. Aliquam semper ipsum sit amet velit. Suspendisse
6
> id sem consectetuer libero luctus adipiscing.

预览：

This is a blockquote with two paragraphs. Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus. Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus.
Donec sit amet nisl. Aliquam semper ipsum sit amet velit. Suspendisse id sem consectetuer libero luctus adipiscing.

Markdown 允许“偷懒”：在一个硬换行段落中，只在第一行前加 > 即可。

代码：

1
> This is a blockquote with two paragraphs. Lorem ipsum dolor sit amet,
2
consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus.
3
Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus.
4

5
> Donec sit amet nisl. Aliquam semper ipsum sit amet velit. Suspendisse
6
id sem consectetuer libero luctus adipiscing.

预览：

This is a blockquote with two paragraphs. Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus. Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus.

Donec sit amet nisl. Aliquam semper ipsum sit amet velit. Suspendisse id sem consectetuer libero luctus adipiscing.

引用可以嵌套（引用中的引用），通过增加 > 层级实现。

代码：

1
> This is the first level of quoting.
2
>
3
> > This is nested blockquote.
4
>
5
> Back to the first level.

预览：

This is the first level of quoting.
This is nested blockquote.
Back to the first level.

引用内可包含其他 Markdown 元素，包括标题、列表与代码块。

代码：

1
> ## This is a header.
2
>
3
> 1.   This is the first list item.
4
> 2.   This is the second list item.
5
>
6
> Here's some example code:
7
>
8
>     return shell_exec("echo $input | $markdown_script");

预览：

This is a header.#

This is the first list item.

This is the second list item.

Here’s some example code:
1
return shell_exec("echo $input | $markdown_script");

列表#

Markdown 支持有序（数字）与无序（圆点）列表。

无序列表#

HTML 标签：<ul>

无序列表可使用 星号 (*)、加号 (+) 或 短横线 (-)。

代码：

1
*   Red
2
*   Green
3
*   Blue

预览：

Red
Green
Blue

等价于：

代码：

1
+   Red
2
+   Green
3
+   Blue

或者：

代码：

1
-   Red
2
-   Green
3
-   Blue

有序列表#

HTML 标签：<ol>

有序列表使用数字加英文句点：

代码：

1
1.  Bird
2
2.  McHale
3
3.  Parish

预览：

Bird
McHale
Parish

注意：像下面这样可能会“意外触发”有序列表：

代码：

1
1986. What a great season.

预览：

What a great season.

你可以用反斜杠转义 (\) 句点：

代码：

1
1986\. What a great season.

预览：

1986. What a great season.

列表中的缩进内容#

列表项里的引用#

在列表项内放置引用，需要将 > 符号整体缩进：

代码：

1
*   A list item with a blockquote:
2

3
    > This is a blockquote
4
    > inside a list item.

预览：

A list item with a blockquote:

This is a blockquote inside a list item.

列表项里的代码块#

在列表项内放置代码块，需要缩进两层——8 个空格或两个 Tab：

代码：

1
*   A list item with a code block:
2

3
        <code goes here>

预览：

A list item with a code block:
```
1
<code goes here>
```

嵌套列表#

代码：

1
* A
2
  * A1
3
  * A2
4
* B
5
* C

预览：

A
- A1
- A2
B
C

代码块#

HTML 标签：<pre>

将代码块中的每行缩进至少4 个空格或1 个制表符。

代码：

1
This is a normal paragraph:
2

3
    This is a code block.

预览：

This is a normal paragraph:

1
This is a code block.

代码块会一直持续，直到遇到未缩进的行（或文末）。

在代码块内，与号 (&) 和尖括号 (< >) 会自动转为 HTML 实体。

代码：

1
    <div class="footer">
2
        &copy; 2004 Foo Corporation
3
    </div>

预览：

1
<div class="footer">
2
    &copy; 2004 Foo Corporation
3
</div>

下文的“围栏代码块”和“语法高亮”属于扩展语法，你也可以用它们来书写代码块。

围栏代码块#

使用成对的反引号围起来（如下所示），就不需要四空格缩进了。

代码：

1
Here's an example:
2

3
```
4
function test() {
5
  console.log("notice the blank line before this function?");
6
}
7
```

预览：

Here’s an example:

1
function test() {
2
  console.log("notice the blank line before this function?");
3
}

语法高亮#

在围栏代码块后添加可选的语言标识，即可启用语法高亮（参见支持语言列表）。

代码：

1
```ruby
2
require 'redcarpet'
3
markdown = Redcarpet.new("Hello World!")
4
puts markdown.to_html
5
```

预览：

1
require 'redcarpet'
2
markdown = Redcarpet.new("Hello World!")
3
puts markdown.to_html

分割线（水平线）#

HTML 标签：<hr /> 一行中放置三个或以上的短横线 (-)、星号 (*) 或下划线 (_)。符号之间允许有空格。

代码：

1
* * *
2
***
3
*****
4
- - -
5
---------------------------------------
6
___

预览：

表格#

HTML 标签：<table>

这是扩展语法。

用竖线 (|) 分隔列，用短横线 (-) 分隔表头，使用冒号 (:) 指定对齐方式。

两侧的竖线 (|) 与对齐可选。用于表头分隔时，每列至少需要 3 个短横线。

代码：

1
| Left | Center | Right |
2
|:-----|:------:|------:|
3
|aaa   |bbb     |ccc    |
4
|ddd   |eee     |fff    |
5

6
 A | B
7
---|---
8
123|456
9

10

11
A |B
12
--|--
13
12|45

预览：

Left	Center	Right
aaa	bbb	ccc
ddd	eee	fff

A	B
123	456

A	B
12	45

内联元素#

链接#

HTML 标签：<a>

Markdown 支持两种链接样式：行内链接与引用式链接。

行内链接#

行内链接格式：[文本](URL "标题")

标题可选。

代码：

1
This is [an example](http://example.com/ "Title") inline link.
2

3
[This link](http://example.net/) has no title attribute.

预览：

This is an example inline link.

This link has no title attribute.

如果引用同一站点的本地资源，可以使用相对路径：

代码：

1
See my [About](/about/) page for details.

预览：

See my About page for details.

引用式链接#

可以预定义链接引用。定义格式：[id]: URL "标题"

标题同样可选。引用时使用：[文本][id]

代码：

1
[id]: http://example.com/  "Optional Title Here"
2
This is [an example][id] reference-style link.

预览：

This is an example reference-style link.

说明：

方括号中包含链接标识（不区分大小写，可在左侧缩进最多三格空格）；
随后是冒号；
再跟一个或多个空格（或 tab）；
然后是链接 URL；
URL 可选地用尖括号包裹；
可选地跟随标题属性，用引号或圆括号包裹。

以下三种定义等价：

代码：

1
[foo]: http://example.com/  "Optional Title Here"
2
[foo]: http://example.com/  'Optional Title Here'
3
[foo]: http://example.com/  (Optional Title Here)
4
[foo]: <http://example.com/>  "Optional Title Here"

如果使用空的方括号，则链接文本本身会作为名称。

代码：

1
[Google]: http://google.com/
2
[Google][]

预览：

Google

强调#

HTML 标签：<em>，<strong>

Markdown 使用 星号 (*) 或 下划线 (_) 表示强调。一个分隔符对应 <em>；两个分隔符对应 <strong>。

代码：

1
*single asterisks*
2

3
_single underscores_
4

5
**double asterisks**
6

7
__double underscores__

预览：

single asterisks

single underscores

double asterisks

double underscores

但如果两侧有空格，则会被视作普通字符而非强调语法。

你可以使用反斜杠进行转义：

代码：

1
\*this text is surrounded by literal asterisks\*

预览：

*this text is surrounded by literal asterisks*

行内代码#

HTML 标签：<code>

用反引号 (`) 包裹。

代码：

1
Use the `printf()` function.

预览：

Use the printf() function.

若行内代码中需要包含反引号字符，可使用多重反引号作为定界符：

代码：

1
``There is a literal backtick (`) here.``

预览：

There is a literal backtick (`) here.

行内代码两侧的定界符允许包含空格（开头一个、结尾一个），方便在代码起始或结尾放置反引号字符：

代码：

1
A single backtick in a code span: `` ` ``
2

3
A backtick-delimited string in a code span: `` `foo` ``

预览：

A single backtick in a code span: `

A backtick-delimited string in a code span: `foo`

图片#

HTML 标签：<img />

Markdown 的图片语法与链接类似，支持行内与引用两种方式。

行内图片#

行内图片语法：![替代文本](URL "标题")

标题可选。

代码：

1
![Alt text](/path/to/img.jpg)
2

3
![Alt text](/path/to/img.jpg "Optional title")

预览：

Alt text

说明：

一个感叹号 !；
后接方括号，放置图片的替代文本；
再接圆括号，内含图片 URL/路径，及可选的标题（引号包裹）。

引用式图片#

引用式图片语法：![替代文本][id]

代码：

1
[img id]: https://s2.loli.net/2024/08/20/5fszgXeOxmL3Wdv.webp  "Optional title attribute"
2
![Alt text][img id]

预览：

Alt text

删除线#

HTML 标签：<del>

这是扩展语法。

GFM 增加了删除线语法。

代码：

1
~~Mistaken text.~~

预览：

Mistaken text.

杂项#

自动链接#

Markdown 支持一种便捷写法来创建“自动链接”（URL 与邮箱地址）：只需用尖括号将其包住即可。

代码：

1
<http://example.com/>
2

3
<address@example.com>

预览：

http://example.com/

address@example.com

GFM 会自动识别标准 URL 并转换为链接。

代码：

1
https://github.com/emn178/markdown

预览：

https://github.com/emn178/markdown

反斜杠转义#

Markdown 允许使用反斜杠来转义那些本用于 Markdown 语法的特殊字符，使其按字面显示。

代码：

1
\*literal asterisks\*

预览：

*literal asterisks*

以下字符可通过反斜杠转义以按字面量输出：

Code:

1
\   backslash
2
`   backtick
3
*   asterisk
4
_   underscore
5
{}  curly braces
6
[]  square brackets
7
()  parentheses
8
#   hash mark
9
+   plus sign
10
-   minus sign (hyphen)
11
.   dot
12
!   exclamation mark

内联 HTML#

对于 Markdown 语法未覆盖的标记，直接使用原生 HTML 即可。无需特别声明从 Markdown 切换到 HTML，直接写标签就行。

代码：

1
This is a regular paragraph.
2

3
<table>
4
    <tr>
5
        <td>Foo</td>
6
    </tr>
7
</table>
8

9
This is another regular paragraph.

预览：

This is a regular paragraph.

Foo

This is another regular paragraph.

请注意：在块级 HTML 标签内不会处理 Markdown 语法。

与块级标签不同，在行内级标签内会处理 Markdown 语法。

代码：

1
<span>**Work**</span>
2

3
<div>
4
    **No Work**
5
</div>

预览：

Work

**No Work**

***

在文章中嵌入视频

Thu, 01 Jan 1970 00:00:00 GMT

只需从 YouTube 或其他平台复制嵌入代码，然后将其粘贴到 markdown 文件中。

1
---
2
title: 在文章中嵌入视频
3
published: 2023-10-19
4
// ...
5
---
6

7
<iframe width="100%" height="468" src="https://www.youtube.com/embed/5gIf0_xpFPI?si=N1WTorLKL0uwLsU_" title="YouTube video player" frameborder="0" allowfullscreen></iframe>

七月流火

鬼谷子说

🌟 鬼谷子说#

用 Docker 自建 iPTV：从启动到电视播放

为什么自建#

快速开始#

播放器适配#

Firefly 一款清新美观的 Astro 博客主题模板

🌟 项目概述#

🚀 技术架构#

📖 配置说明#

Firefly 简单使用指南

文章的 Front-matter#

文章文件的放置位置#

自定义文章 URL (Slug)#

什么是 Slug？#

Slug 使用示例#

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

示例 2：自定义 Slug#

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

Slug 使用建议#

注意事项#

Astro 入门：10 分钟搭好你的第一个站点

为什么是 Astro#

项目结构（你主要会碰这几处）#

最常用的三条命令#

加一篇新文章只要三步#

网址是怎么来的（很简单）#

上门网络服务随笔：那些踩过的坑

客户说”没网”，八成是路由器#

“全屋 Wi-Fi 差”，往往是架构错#

“我要公网 IP”，但没说要干什么#

一句总结#

飞牛 FnOS + Cloudflare Tunnel 内网穿透完整教程

飞牛 FnOS + Cloudflare Tunnel 内网穿透完整教程#

一、前置准备#

二、Cloudflare 端配置#

1. 开通 Zero Trust#

2. 创建隧道#

三、FnOS 端部署 cloudflared#

关键：必须用 host 网络模式#

四、配置公共主机名#

关键：URL 用 127.0.0.1，不要用本机局域网 IP#

五、验证#

六、多服务配置#

七、常见问题排查#

问题 1：502 Bad Gateway，日志报 dial tcp 127.0.0.1:端口: connect: connection refused#

问题 2：502，日志报 dial tcp 10.0.0.x:端口: i/o timeout#

问题 3：502，日志报 Host validation failed#

问题 4：查看 cloudflared 日志#

八、安全加固：Cloudflare Access 身份验证#

配置步骤#

效果#

多个服务#

九、其他安全建议#

十、配置速查表#

附：本次踩坑总结#

家庭影音中心：Jellyfin + NAS 搭建笔记

为什么选 Jellyfin#

在 NAS 上用 Docker 部署#

硬件解码#

客户端#

家庭网络规划：从光猫到全屋 Wi-Fi

三个角色先分清#

规划清单#

常见翻车点#

NAS 私有化入门：家庭为什么需要一台 NAS

什么是 NAS#

哪些人真的需要#

选购前的三个判断#

落地最小步骤#

用 Docker 部署你的第一个自托管服务

自托管是什么#

为什么从 Docker 开始#

第一步：装 Docker#

第二步：跑第一个容器#

第三步：用 compose 管理#

新手建议顺序#

群晖 Synology + Cloudflare Tunnel 内网穿透完整教程

一、前置准备#

问题 1：502 Bad Gateway，日志报 `dial tcp 127.0.0.1:端口: connect: connection refused`#

问题 2：502，日志报 `dial tcp 10.0.0.x:端口: i/o timeout`#

问题 3：502，日志报 `Host validation failed`#

问题 1：502 Bad Gateway，日志报 `dial tcp 127.0.0.1:端口: connect: connection refused`#

问题 2：502，日志报 `dial tcp 10.0.0.x:端口: i/o timeout`#

问题 3：502，日志报 `Host validation failed`#