网站前端#

后端#

部署和管理#

macOS 管理应用#

Firefly Admin 是真正的 macOS 原生应用，不是网页套壳：

• Swift 6、SwiftUI、最低支持 macOS 14。
• NavigationSplitView 三栏导航，使用原生 Form、List、Table、Sheet 和 Toolbar。
• MVVM 结构，网络层使用 URLSession + Codable。
• 登录令牌和本地草稿密钥放在 macOS Keychain。
• OSLog 记录网络和发布状态。
• WKWebView 显示线上预览、草稿预览和手机/平板尺寸预览。

第一次部署做了什么#

1. 备份原有博客和 Nginx 配置。
2. 在服务器安装 Node.js 和固定版本的 pnpm。
3. 上传源码并执行 pnpm install --frozen-lockfile。
4. 执行检查和生产构建，把 dist/ 放到网站目录。
5. 配置 Nginx 和 HTTPS。
6. 用浏览器检查首页、文章、RSS、站点地图和 404 页面。

Nginx 当前指向 firefly-managed/current，发布时只切换这个软链接。新构建失败时，线上软链接不变，原网站继续运行。

6.1 创建项目并获取公开连接信息#

在 Supabase Dashboard 创建项目，记录：

• Project URL，例如 https://<project-ref>.supabase.co。
• Publishable key（旧项目可能叫 anon public key）。

应用连接时使用项目根 URL，不要把 /rest/v1/ 拼到 URL 末尾。Publishable key 可以放在网站和 Mac 应用中；Secret key、service role key 和数据库密码只能放在服务器端。

6.2 初始化表和 Storage#

初始 SQL 位于：

1
supabase/schema.sql
2
supabase/config-versions.sql
3
supabase/migrations/

在新项目上应按文件名顺序执行迁移，或使用已经登录并绑定项目的 Supabase CLI。生产环境不要把一份已经执行过的旧 SQL 再次当成新迁移执行。

主要数据包括：

• profiles：用户公开资料。
• blog_comments：文章评论。
• user_files：用户文件元数据。
• site_settings：兼容旧版本的网站设置。
• site_config_versions、草稿和审计表：配置版本、发布和操作记录。
• content_*：文章、动态、项目、内容版本、发布任务和发布事件。
• site_assets：网站公开资源元数据。
• content-assets：内容草稿使用的私有附件桶。

6.3 设置管理员#

管理员角色放在 Supabase Auth 的 app_metadata 中，普通用户不能自己修改：

1
update auth.users
2
set raw_app_meta_data =
3
  coalesce(raw_app_meta_data, '{}'::jsonb) || '{"role":"admin"}'::jsonb
4
where email = '你的管理员邮箱';

修改角色后退出应用并重新登录。GitHub 登录需要在 Supabase Authentication 中启用 GitHub provider，并加入应用的回调地址 firefly-admin://auth/callback。

可以直接发布后生效的配置#

• 网站标题、描述和导航标题。
• 主题色、浅色/深色/跟随系统模式。
• 壁纸地址、遮罩和毛玻璃相关运行时设置。
• 首页横幅文字、公告和个人资料。
• 侧边栏布局、已构建页面开关。
• 友链、打赏信息。
• 评论区域开关。

发布后仍需要重建的配置#

• 字体下载、字体子集化和代码字体。
• 新增或修改 Astro 路由、Markdown/MDX、Content Collections。
• Mermaid、PlantUML、代码高亮主题等构建插件。
• RSS、站点地图、Pagefind 搜索索引和 SEO/OG 静态资源。
• 需要新增模板或组件才能支持的功能。
• 视频地址及标记为构建项的播放器配置。相关迁移和新版 admin-assets 已部署；循环开关可在新版网站运行时生效。

每个配置字段在应用中会标记“运行时生效”或“需要重建”。

本地重新构建应用#

在仓库根目录运行：

1
cd /Users/nightwind/aiWork/firefly/Firefly
2
pnpm admin:manifest
3
bash FireflyAdmin/scripts/build-app.sh
4
codesign --verify --deep --strict "FireflyAdmin/build/Firefly Admin.app"

pnpm admin:manifest 用于刷新配置 Schema 和默认值，修改配置定义时需要执行；只修改 Swift 界面时通常不需要刷新它。构建脚本会自动生成并打包原项目的 About、友链说明和留言板说明，供首次接入使用。

编译完成不等于日常应用已更新。 先按 Command-Q 退出旧应用，保留旧应用副本，再复制新应用到固定安装位置。复制命令见 部署手册中的应用更新步骤。之后仍从 /Users/nightwind/Applications/Firefly Admin.app 启动，避免误开其他旧副本。

本轮使用 Command Line Tools，原生编译与签名校验通过；没有完整 Xcode，不能记为 xcodebuild 通过。完整 Xcode 可用时，也可以打开 FireflyAdmin/FireflyAdmin.xcodeproj，选择实际的 FireflyAdmin scheme。个人本机使用临时签名；对外分发才需要另行安排 Developer ID 签名、公证和更新机制。

重新编译后，macOS 可能再次要求读取原钥匙串。请在系统弹窗中自行允许，不要发送密码，也不要删除钥匙串或本地草稿来绕过提示。

登录和连接#

1. 打开应用的“连接设置”。
2. 输入 Supabase 项目根 URL 和 Publishable/anon key。
3. 使用邮箱登录，或使用 GitHub OAuth 登录。
4. 确认账号的角色显示为管理员。
5. 线上预览地址填写 https://bytefun.site；本地预览可填写 http://localhost:4321。

令牌保存在 Keychain；本地内容草稿使用加密文件保存，密钥也在 Keychain，并按项目、站点和账号隔离。

图片壁纸#

打开“壁纸与毛玻璃”：

• 选择横幅、全屏、透明覆盖或纯色背景模式。
• 设置桌面和移动端壁纸 URL。
• 调整遮罩、顶栏透明和模糊强度。
• 保存并发布配置。

图片 URL 可以从“资源管理”上传后直接复制，也可以使用已有公开 URL。清空 URL 会回到源码默认壁纸。

视频壁纸#

视频壁纸需要三个条件：

1. 在“资源管理”上传合法的视频资源并得到 URL。
2. 在“壁纸与毛玻璃”中打开视频开关并选择视频 URL。
3. 如果字段标记“需要重建”，发布配置后提交一次网站重建。

当前生产项目已部署视频迁移和新版 admin-assets。视频使用“获取上传凭证 → 直接上传 Storage → 校验登记”的流程，视频字节不再经过 Edge Function。32 MiB MP4 已完成真实上传验收，约 59 秒后成功登记；进度传完还需等待登记完成。

应用、数据库和存储桶已取消额外写死的视频上限，但当前 Supabase Free 项目全局上限仍为 50 MiB。更大文件可以使用其他服务的 HTTPS 视频直链，或自行升级套餐后同步调整项目限制与服务端能力值；没有自动购买升级。

• 网站访客：点击顶栏视频图标展开二级菜单，选择“循环播放”“播放 / 暂停”。图标本身只展开菜单，页面底部没有控制按钮。
• 站长默认设置：在应用“壁纸与毛玻璃 → 循环播放视频”设置并发布。访客在菜单中修改只影响自己的当前播放。
• 修改视频地址后按字段提示发布并重建；只上传文件不会自动替换网站壁纸。

播放失败时检查视频 URL 能否直接打开、编码是否被浏览器支持，以及开关和地址是否已发布到本次构建。

调色板#

网站右上角调色板入口由“调色板与显示”控制。若网站看不到入口，先确认入口开关已发布；若修改的是构建字段，再提交重建任务。

新建文章或动态#

1. 打开左侧“文章管理”或“动态内容”。
2. 点击“新建”或按 Command + N。
3. 填写标题、slug、摘要、正文、日期、分类、标签、封面和 SEO 信息。
4. 使用“插入”菜单添加标题、粗体、链接、列表、代码块或表格。
5. 点击“保存草稿”。编辑器会显示已保存、保存中、离线或失败状态。
6. 点击“提交任务 -> 发布”，或者先生成私密网站预览。

编辑已经上线的文章时，访客仍看到旧版本；新版本只有在构建和部署成功后才上线。

导入已有 Markdown#

在文章或动态列表中点击“导入”：

1. 选择 Firefly 项目目录，扫描 src/content。
2. 查看 Frontmatter、slug、图片路径和重复项。
3. 解决冲突后导入可用项目。
4. 导出导入报告，确认失败项。

重复导入同一个文件不会创建重复内容；原 Markdown 和资源仍保留。MDX 文件可以只读查看和原样导出，应用不会在服务器直接执行来源不明的 MDX 组件。

删除和批量操作#

原文件或已上线内容需要先通过实际发布任务从网站正文、归档、RSS、站点地图和搜索中移除。列表多选后可提交一个统一删除/重建任务，成功后自动移入回收站；失败不会当作删除成功。单篇操作以确认窗口提示为准，已撤回内容可以直接移入回收站。

本地恢复副本与服务器内容是两回事。若列表仍显示“本地恢复副本”，在该列表中使用“彻底删除”，或“全选本地副本 → 批量彻底删除…”；这只清除本机副本，不删除服务器正式版本。

修改“关于我”及其他独立页面#

1. 打开左侧 “关于我与独立页面”→“编辑关于我”，直接打开现有原文或草稿，不重复创建。
2. 编辑 Markdown 正文，新增段落、标题、图片或链接。网页正文标题是以 # 开头的行；“管理标题”只用于应用列表。
3. 点 保存草稿 → 提交任务 → 发布…，到发布中心等待服务器重建成功。
4. 新增页面… 可接入现有 About、留言板说明、友链说明。首次接入 Markdown 时可选空白正文，原文仍在历史中，已有草稿不会被清空。当前不新增任意 URL，可信友链 MDX 只读。
5. 删除… 明确提示影响范围。成功重建后地址返回 404，内容进入回收站；恢复后需再次发布。导航入口可另在“导航栏”移除。

长篇“关于我”在这里修改；头像、昵称和简短简介仍在 “个人资料”。本轮只接入原文，没有发布测试内容。完整步骤及验收边界见 关于我管理说明。

配置回滚#

在“快照管理”中选择历史版本，查看 JSON Diff 或可读 Diff，再点击“恢复此版本”。恢复会创建一个新的版本并留下审计记录，不会直接覆盖历史记录。

内容回滚#

在发布中心选择成功的发布任务，点击“回滚至此快照”。服务器会使用当时固定的代码包、内容和资源重新构建；只有线上检查通过后才会切换。内容回滚不会自动回滚独立的 runtime-config，如需完全恢复外观，还要在配置历史中回滚对应分区。

释放空间#

配置快照回收站和服务器构建工作区是两个地方：

• “快照管理 → 回收站”处理配置历史记录，本身很小，不能靠删除它释放大量服务器磁盘。
• “快照管理 → 服务器备份 · 释放磁盘”或“存储空间 → 服务器构建备份”可扫描服务器工作区，先看计划，再确认清理。
• 资源管理可检查未引用资源；它与服务器构建备份清理是不同操作。
• 服务器 /var/lib/firefly-content/jobs/ 保存构建工作区和日志，不能在任务运行时直接删除。

服务器清理前先查看任务状态，保留当前线上版本和约定数量的可回滚版本，再使用项目提供的清理脚本执行 dry-run。不要使用 rm -rf /var/lib/firefly-content/*，否则可能删除正在运行的构建或排查所需日志。

修改后网页没有变化#

先看字段说明：

• “运行时生效”：确认已经保存并发布配置，刷新网站或等待缓存过期。
• “需要重建”：进入发布中心提交“重建线上内容与已发布配置”。

普通 pnpm build 不会自动读取 Supabase，也不会自动部署。

应用提示 PGRST002#

Could not query the database for the schema cache 通常是 Supabase PostgREST 暂时无法读取数据库结构，常见原因是数据库连接暂时不可用、迁移正在执行、项目暂停，或接口缓存尚未刷新。先检查 Supabase 项目状态和 SQL 迁移，再退出重开应用；不要把 service role key 放进应用来绕过问题。

保存草稿超时#

应用会保留当前编辑内容，并在超时后只读核对服务器版本，避免重复写入。检查网络、Supabase 状态和是否有另一个设备同时编辑。出现 409 冲突时先比较差异，再选择合并或重新加载。

构建失败但网站还能打开#

这是预期的保护行为。worker 在构建和产物检查通过后原子切换 current，再执行线上 HTTP 检查；检查失败会尝试切回上一目录，只有验证成功才标记“已上线”。若线上状态与数据库记录不一致，任务会保留保护状态，须先核对，不能直接改成成功。查看发布中心错误摘要和服务器 build.log 后处理。

壁纸或顶栏效果消失#

检查“壁纸与毛玻璃”中的 URL、模式、遮罩和顶栏透明设置是否已发布；涉及视频、字体或模板的字段还要重建。浏览器缓存也可能保留旧 CSS，可使用无痕窗口或强制刷新验证。

页面、RSS 或搜索没有更新#

文章和动态必须完成一次真实发布任务。只有 succeeded 且线上检查通过后，正文、分类、RSS、站点地图和 Pagefind 才会一起更新。

应用启动时一直等待#

检查 macOS 是否弹出钥匙串授权窗口。允许 Firefly Admin 读取登录凭证和本地草稿密钥后重新启动。若应用来自不同路径，macOS 可能再次询问授权。

评论为什么没有显示想要的昵称或头像#

到网站 /account/ 登录，编辑公开昵称和头像地址。评论读取用户公开资料，不展示登录邮箱；尚未设置公开昵称时显示稳定的“读者-…”名称，没有头像时使用默认头像。这里的评论账号资料与应用“个人资料”中的站长侧边栏介绍不是同一项设置。

已完成并有生产记录#

• 网站已部署到腾讯云，Nginx 和 HTTPS 正常工作。
• Supabase Auth、PostgreSQL、Storage、RLS、Realtime 和 Edge Functions 已接入。
• 配置草稿、发布、历史、审计和回滚已接入。
• 文章、动态、项目、Markdown 导入、资源管理和批量删除已接入。
• 服务器 worker、固定源码包、构建失败保护、Nginx 原子切换和内容回滚已有生产记录。
• 私密预览、定时发布、应用关闭后继续执行已有实现和验收记录。
• 视频资源迁移和 admin-assets 直传接口已完成生产部署，MP4 上传不再经过 Edge Function 中转。
• Firefly Admin macOS 应用可构建、安装和使用。

需要留意的事项#

• 2026-09-28 已补齐真实管理员 MP4 上传验收，包括原生应用上传 32 MiB 文件；公开与私密视频、并发登记、伪造格式拒绝等 5 组生产检查及 14 项评论身份检查通过，测试数据已清理。视频最大文件仍受当前 Free 项目 50 MiB 上限约束。
• “关于我与独立页面”已实现并安装，真实 API 接入原文且保留为 v1 草稿。本地原生编译、网站三项检查、183 项内容测试和 7 项构建映射测试通过；没有发布测试正文，也没有在生产删除真实 About 页面。最后一次列表滚动修正版的截图验收仍待补齐，不能记为全部界面验收通过。
• 字体下载依赖外部网络。字体下载失败会让构建任务失败，线上会继续保留上一成功版本。
• 新增网站组件、路由、字体、Markdown 内容处理或构建插件，必须生成新的固定源码包并重建网站。
• 本项目按个人使用需求维护，没有额外建设企业级灾备、告警和自动部署体系；已有服务器备份和回滚能力仍应保留。

只改标题、壁纸、主题色或公告#

1
打开 Firefly Admin
2
  -> 对应配置分区
3
  -> 修改并保存草稿
4
  -> 发布配置
5
  -> 如果字段要求重建，再到发布中心提交重建

新增并上线一篇文章#

1
文章管理 -> 新建文章
2
  -> 编辑正文和元数据
3
  -> 保存草稿
4
  -> 可选：生成私密网站预览
5
  -> 提交发布任务
6
  -> 等待“已上线”

服务器空间不足#

1
先查看发布中心是否有 building/deploying 任务
2
  -> 打开“快照管理 -> 服务器备份”或“存储空间 -> 服务器构建备份”
3
  -> 扫描服务器并查看清理计划（dry-run）
4
  -> 保留当前线上版本和回滚版本
5
  -> 再清理旧构建工作区和日志

修改“关于我”并上线#

1
关于我与独立页面 -> 编辑关于我
2
  -> 修改 Markdown 正文
3
  -> 保存草稿
4
  -> 提交任务 -> 发布
5
  -> 等待发布中心显示“已上线”

记住：保存草稿、发布配置、重建网站、已上线是不同状态。运行时配置发布后即可由网站读取；需要重建的配置和正文，须等待相应服务器任务完成。“已保存”不代表访客已经看到改动。