1. 初始需求与产品范围#

最初目标是开发一个可以直接编译、安装和使用的个人上下班打卡工具，而不只是界面演示。首版范围包括：

• 每天分别记录一次上班、下班打卡，附带可选照片和备注。
• 显示当天状态，提供月历、历史筛选、搜索和记录详情。
• 设置上下班本地通知，选择提醒时间及生效星期。
• 修改、补录和删除记录前确认，导出 CSV，清除本机数据。
• 处理权限拒绝、保存失败、照片不可用及首次启动空状态。
• 使用简体中文、原生组件、系统颜色，适配深色模式、Dynamic Type 和 VoiceOver。
• 提供单元、持久化和 UI 测试，完成真机安装验证。

产品定位是个人记录工具。打卡时间来自设备系统时钟，用户可以补录和修改内容，因此不作为企业防篡改考勤认证或历史地点证明。

2. 工程搭建与架构选择#

工程采用 SwiftUI + ViewModel + Repository / Service 的分层结构，尽量把界面、业务规则、持久化和系统能力分开。通知、照片存储、数据仓库与定位提供可替换接口，便于测试成功和失败场景。

1
签到打卡/
2
├── WorkPunch.xcodeproj/           Xcode 工程与共享 Scheme
3
├── WorkPunch/
4
│   ├── App/                      App 入口、依赖组装、通知路由
5
│   ├── Core/
6
│   │   ├── Models/               打卡、位置、提醒、节假日模型
7
│   │   ├── Repositories/         仓库接口与 SwiftData 实现
8
│   │   ├── Services/             打卡事务、照片文件与 CSV
9
│   │   └── Utilities/            日期、月历、筛选等规则
10
│   ├── ViewModels/               今日、日历、记录、设置与编辑逻辑
11
│   ├── Views/                    四个标签页与编辑、详情、隐私页面
12
│   ├── Services/                 通知、节假日、定位与图片处理
13
│   ├── Components/               相机、记录行、图片查看与分享面板
14
│   └── Resources/                权限、隐私清单、图标、节假日资源
15
├── WorkPunchTests/               单元与 SwiftData 集成测试
16
├── WorkPunchUITests/             真机交互流程测试
17
├── Scripts/                      工程生成、检查、编译与测试脚本
18
├── TestResults/                  编译日志、测试摘要、截图和验证报告
19
├── Package.swift                 可在 Mac 上测试的共享业务代码
20
├── README.md                     工程入口说明
21
└── 开发记录与使用说明.md          本文

主要技术选择及作用如下：

Swift 6 并发检查用于约束线程访问。界面、相机和主 ModelContext 的操作在主 Actor 执行，图片解码压缩、导出等耗时工作放到后台任务。工程将编译警告视为错误。

3. 数据和核心业务实现#

PunchRecord 除了 UUID、类型、打卡时间、备注、照片路径、创建时间和更新时间，还保存以下信息：

• dayKey、timeZoneID：记录打卡时的当地日期和时区，避免切换时区后历史记录换到另一日期。
• uniquenessKey：日期与打卡类型组成唯一键，配合业务检查防止同一天同类型重复保存。
• isManual：标记经过确认的补录记录。
• 可选位置字段：纬度、经度、水平精度、采集时间和地址。

图片最长边压缩到 1800 像素，使用 JPEG 质量 0.78；缩略图单独降采样。处理时移除原图的 EXIF 和原始定位等元数据。用户主动附加的打卡位置作为独立记录字段保存。

保存新照片后如果数据库提交失败，会回滚记录并清理新文件。删除记录后同步清理无引用照片；清理异常会显示说明，并在后续加载时重试。提醒设置使用 Codable 编码后保存在 UserDefaults 中。

相关代码：数据模型、打卡业务、照片存储。

4. 首次编译和真机安装#

开发开始时，命令行环境未找到可用的完整 Xcode。随后确认 Xcode 已安装，并完成 Apple 许可确认与首次组件安装；编译命令显式选择完整 Xcode 的 Developer 目录。

真机通过数据线连接后，依次完成解锁、信任电脑、签名安装及开发者 App 信任。安装初期系统曾拒绝启动尚未信任的开发者应用，完成信任后继续验证。真机测试期间也遇到设备锁定导致无法启动的情况，解锁后恢复测试。

首版留存的真机测试摘要为 22 / 22 通过，无运行时警告。证据见 首版测试摘要。这只代表该阶段测试覆盖的范围；后续用户实际使用反馈又发现并推动修复了相机和通知问题。

5. 1.1：修复闪退并完善提醒和节假日#

用户反馈点击拍照闪退、点击通知进入应用闪退，同时希望提醒持续保留、每小时再提醒，并跟随中国节假日和调休。处理过程如下。

6. 1.2：附带当前位置与修复删除布局#

第二轮新增需求是打卡时附带当前位置，并修复删除操作位置过高、布局不正常的问题。

7. 实际验证结果与边界#

1.2 唯一失败的 UI 断言假定新文字一定追加在备注末尾，而自动化点击后的光标实际位于其他位置。将断言改为核对编辑框的实际输入与保存结果一致后，该用例单独复测通过。这里没有将两次结果写成一次完整的 52 / 52 全绿运行。

测试覆盖打卡保存、重复判断、日历状态、月份与闰年、历史筛选、CSV 转义、通知日程、节假日调休、照片删除、SwiftData 持久化和位置迁移。UI 覆盖无照片打卡、日历、筛选、修改提醒时间、位置保存与保留、关闭定位、删除弹窗、相机打开取消，以及通知后台点击与冷启动。

真机实际取得当前位置的流程已验证，但获取后取消，未保存真实位置或附加真实坐标截图。普通 UI 测试使用独立数据目录和虚构位置，不清除正常使用的记录。相机自动化只验证打开和取消，未拍摄用户环境；每小时间隔由固定时钟单元测试覆盖，没有声称完成长期每小时实际等待测试。

不同屏幕尺寸、横屏、深色模式、全部大字号和 VoiceOver 组合没有逐一完成真机验收。后台刷新执行时间、长期通知送达和专注模式／摘要的各种组合由系统影响，不作保证。

完整证据：当前验证报告、1.2 完整运行摘要、定向复测摘要、Mac 测试日志。

1. 首次打开与四个页面#

无需登录。底部四个标签的作用如下：

首次没有记录时会显示空状态，这是正常情况。完成第一条打卡后，各页面会同步显示。

默认上班时间为 08<50>，下班时间为 18<00>，普通工作日为周一至周五。上下班提醒初始都关闭；“每小时追提醒”和“同步中国节假日与调休”默认开启，但需要先开启相应的上下班提醒才会安排正式通知。

2. 完成一次上班或下班打卡#

1. 打开“今日”，点击“上班打卡”或“下班打卡”。
2. 确认页面会尝试获取当前位置；首次使用时按系统提示允许“使用 App 期间”定位。如果不需要位置，关闭“附带位置”。
3. 可点击“拍照”调用相机，也可点击“从相册选择”。照片选填，拍照时首次需要相机授权。
4. 在“备注”中填写说明，也可以留空。
5. 点击“确认打卡”。实时打卡以保存时的设备时间记录。
6. 成功后页面关闭，显示“打卡已保存”并给出触觉反馈；今日状态更新。

同一天每种类型最多一条。已经完成的项目会显示记录和“查看或修改记录”，不会再次新增相同类型的打卡。照片处理中、定位中或保存中需要等待；如果开启了附带位置却没有取得位置，可重试，也可主动关闭开关后继续保存。

3. 使用打卡位置#

位置记录包括地址（如果查询成功）、经纬度、定位精度和实际采集时间。允许近似位置时，会保存系统提供的近似结果；精度受权限、信号和设备状态影响。

• 保留原位置：编辑已有记录时默认保留，修改备注不会自动把位置替换为当前所在地。
• 重新采集：在编辑页点击“重新获取当前位置”，确认保存后替换原位置。
• 不带位置或移除位置：关闭“附带位置”。编辑已有记录时，确认保存会移除该记录的位置。
• 没有地址：只要取得有效坐标，即使地址查询失败，也可以保存坐标。
• 授权失败：按页面提示打开定位设置，或从“设置 → 权限 → 打开系统设置”调整权限，再返回重试。

应用不在后台持续定位。补录时取得的是此刻的位置，不代表所补录时刻的历史地点。

4. 在日历查看和补录#

点击“日历”，用左右箭头切换月份；右上角“今天”返回当天。点击某一天，下面显示该日记录和可用操作。

“休／班”表示已知的节假日安排，实际是否按它安排提醒取决于设置中的节假日开关；普通周末不会因此都标成“休”。

补录步骤：选择今天或过去日期 → 点击缺少的“补录上班打卡”或“补录下班打卡” → 调整时间，填写可选内容 → 保存 → 在二次确认框确认。未来日期不提供补录操作；补录记录会有补录标记，默认不附带当前位置。

点击照片缩略图可全屏查看，支持捏合缩放、双击缩放，点击“完成”关闭。若照片损坏或丢失，会显示“照片不可用”，可去详情替换。

5. 搜索、筛选、修改和删除#

进入“记录”，默认按日期倒序展示全部记录。可选择“月份”，通过“打卡类型”选择“全部、上班、下班、异常”，并在搜索栏输入备注关键字。这些条件可以组合使用。

“异常”指过去日期只完成一次打卡，或者记录本身带有补录标记。整天没有任何打卡时，不会自动生成缺勤记录，也不会出现在异常列表中；今天尚未下班而只有上班记录，不因这一点立即判为异常。

修改记录：

1. 点击记录进入“打卡详情”。
2. 点击“修改备注、照片或位置”。
3. 修改内容后点击“保存修改”，再确认保存。
4. 原始打卡时间不变，今日、日历、记录页面同步更新。

删除记录：进入详情 → 点击“删除记录” → 在居中的系统弹窗选择“取消”或“删除记录及照片”。确认后移除本条记录、位置及对应照片，无法在应用内撤销。

6. 开启和修改每日提醒#

1. 打开“设置”，分别开启“启用上班提醒”和／或“启用下班提醒”。
2. 首次启用时，允许系统通知权限。
3. 点击“上班提醒时间”或“下班提醒时间”，选择小时、分钟并点击“保存”。
4. 在“提醒生效的星期”勾选需要的日期；星期选择同时用于两类提醒。
5. 根据需要保留或关闭“同步中国节假日与调休”“每小时追提醒”。
6. 在“测试与提醒状态”查看“下一次提醒”“已安排至”和待发送数量。

修改时间后，应用取消旧日程并安排新日程，使用稳定标识避免重复通知。首次开启或修改时间时，如果当天时间已经过去，会从下一个有效日期开始，不补发启用前的通知。

通知文案分别是“上班时间快到了，别忘记打卡”和“准备下班了，记得完成下班打卡”。点击通知进入相应打卡页；已有对应记录时进入编辑流程，不会直接新增重复记录，也不会自动保存。

7. 立即测试通知#

不用等到上班时间，也不用更改手机时间：

1. 进入“设置 → 测试与提醒状态”。
2. 点击“发送上班测试通知（10 秒）”或“发送下班测试通知（10 秒）”。
3. 如有授权提示，允许通知，然后返回桌面等待。
4. 收到后点击通知，确认进入对应打卡页面。

测试通知不受所选星期和节假日限制，不会自动保存打卡，也不会替你开启正式的上下班提醒。系统专注模式、通知摘要或其他设置可能延迟它，约 10 秒是安排时间，不是必达承诺。

8. 每小时追提醒、停止本轮与彻底关闭#

开启“每小时追提醒”后，每类提醒从首次到点开始按小时继续，可能跨夜；休息日暂停。进入 App 或完成打卡都不会自动停止，需要明确操作。

明确停止本轮会清理对应已送达通知并取消当天后续追提醒。系统向应用回传单条通知清除操作时也会停止；“清除全部”不保证回传，因此推荐使用明确的停止按钮。

应用最多滚动预排 60 条正式通知，这是两类合计的队列，不是保证 60 天。返回应用或系统允许后台刷新时会续排；长期不开应用可能耗尽队列，请留意“已安排至”。

iOS 不允许第三方 App 强制通知常驻且不可清除。系统中的“持续横幅”也不等于永久锁定通知中心条目。专注模式、通知摘要、后台刷新、低电量及强制退出等都会影响提醒表现。

9. 中国节假日与调休#

在“设置 → 节假日”开启“同步中国节假日与调休”，可点击“立即同步节假日”，并查看同步状态和时间。

提醒生效顺序为：

1. 已公布的放假日：不提醒，即使落在选中的周一至周五。
2. 已公布的调休上班日：提醒，即使是原本未选中的周末。
3. 其他日期：按“提醒生效的星期”判断。

例如内置 2026 年安排中，10 月 1—7 日休息，10 月 10 日调休上班。因此在国庆期间正式提醒没有出现，可能是休息日规则正常生效；可用 10 秒测试通知检查通知能力。

如果未选择任何普通星期但开启了节假日跟随，已公布的调休上班日仍会提醒。关闭节假日跟随后，仅按所选星期判断。节假日只影响提醒安排，不限制休息日手动打卡。

离线时继续使用内置或缓存数据。某年数据尚未取得时，不会猜测放假安排，而是暂按所选星期提醒并显示说明。数据依据国务院通知整理，但单位实际排班可能不同，需要自行决定是否启用。

10. 导出 CSV#

进入“设置 → 数据 → 导出打卡记录（CSV）”，在系统分享面板选择“存储到‘文件’”或其他需要的目标。

导出文件名为 上下班打卡记录.csv，包含全部历史记录，不受“记录”页面当前筛选条件限制。字段为：日期、打卡类型、时间、备注、补录、时区、位置地址、纬度、经度、定位精度（米）、定位时间。没有位置的旧记录对应字段留空。

文件使用 UTF-8 BOM、标准 CSV 引号转义和 CRLF 行结束，支持中文、逗号、双引号和备注内换行。照片本体不在 CSV 中。分享结束后应用清理临时导出文件，已另存或发出的副本由使用者管理。

当前没有 CSV 导入或恢复功能，因此 CSV 是可阅读的记录导出，不能作为含照片的完整应用备份。

11. 清除所有数据#

进入“设置 → 数据 → 清除所有数据”，阅读提示并确认“清除全部记录和照片”。此操作删除应用内记录（包括位置）、照片及临时导出文件，关闭提醒并恢复默认提醒设置，不能撤销。

需要保留记录时先导出。外部已保存的 CSV 不会随应用清除而删除；系统是否备份应用文件取决于自己的 iPhone 备份设置。卸载应用也会移除本机应用数据。

12. 权限、网络与隐私#

照片、备注、打卡记录和位置保存在本机，开发者不会收集或上传这些资料，不包含广告和分析 SDK。应用不会主动进行 iCloud 同步。

两项系统／网络行为需要区分：节假日同步从公开托管源下载 JSON，不携带打卡数据，托管方仍可看到 IP 等基础请求信息；地址查询由系统 Apple 地图服务处理坐标。核心打卡和本机记录查看不需要后端，网络不可用时节假日依赖缓存，地址查询可能退回坐标显示。

13. 常见问题#

1. 在 Xcode 中运行#

1. 安装带 iOS 27 SDK 的完整 Xcode，首次打开完成许可和所需组件安装。
2. 打开 WorkPunch.xcodeproj，选择共享 Scheme WorkPunch。
3. 模拟器运行时选择已安装的 iOS 27 iPhone 模拟器；真机运行时连接手机、解锁并信任电脑，按系统要求开启开发者模式。
4. 真机需在 Xcode 的 Accounts 登录 Apple ID，并在 App Target 的 Signing & Capabilities 中选择可用 Team。给自己的新安装使用唯一 Bundle Identifier；更新当前安装并保留旧数据时，应保持原应用身份和可用签名。
5. 按 ⌘R 编译运行。若手机提示开发者未信任，按系统指引在“设置 → 通用 → VPN 与设备管理”完成信任。

个人开发签名的可用期限受 Apple 当前规则约束，到期后可能需要重新签名安装；不要为了更新而先卸载已有应用，以免删除本机记录。

2. 运行项目检查和测试#

在项目根目录的终端执行：

1
# 检查工程结构、资源和权限配置
2
python3 Scripts/validate_project.py
3

4
# Mac 上的共享核心与 SwiftData 测试
5
bash Scripts/test_core.sh
6

7
# 已安装 iOS 27 模拟器的构建与测试
8
bash Scripts/verify.sh
9

10
# 列出连接设备，取得需要测试的设备标识
11
DEVELOPER_DIR=/Applications/Xcode.app/Contents/Developer xcrun devicectl list devices
12

13
# 将占位内容替换为上一步设备标识；测试期间保持手机解锁
14
bash Scripts/verify_device.sh <IPHONE_UDID>

也可在 Xcode 中按 ⌘U。脚本会选择完整 Xcode 并把结果写入 TestResults/。真机测试会操作测试 App；Debug 的 --uitesting 使用独立数据和设置，普通 UI 用例注入虚构位置，--live-location 用例才请求实际定位，Release 不包含测试定位实现。

3. 手动回归建议#

每次涉及系统能力或签名的更新后，建议在真机完成以下检查：

1. 无照片打卡、有照片打卡，重启应用确认记录仍在。
2. 相机授权、打开、取消和实际拍摄；相册选择并查看全屏照片。
3. 定位允许、拒绝、不带位置保存，以及修改备注后位置保持。
4. 10 秒测试通知，分别验证后台点击和应用终止后的通知启动。
5. 修改提醒时间、停止本轮、关闭某类提醒，并查看重新安排后的状态。
6. 节假日同步失败时保留缓存、调休工作日及普通星期规则。
7. 删除弹窗取消与确认、日历状态和历史列表同步。
8. 含中文、引号、逗号和换行备注的 CSV 导出。
9. 深色模式、大字号、VoiceOver 和目标屏幕尺寸下的可读性。

4. 维护入口和参考材料#

新增文件后可在 Xcode 中加入相应 Target，或运行 python3 Scripts/generate_project.py 重新生成工程。生成器保留现有签名 Team 和 Bundle Identifier，并固定相机、相册和定位权限说明。改动系统权限后应同时检查源码配置与最终安装包。

节假日参考来源：国务院 2026 年放假通知、NateScarlet/holiday-cn（MIT 许可）。

网站前端#

后端#

部署和管理#

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
  -> 等待发布中心显示“已上线”

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