nekonest-cloud/docs/retention-maintenance.md

到期技术数据自动维护

这是免费公测阶段的数据最小化运行手册。它只自动化已经确定期限的技术记录，不替账户、审计、反馈、租户卷或备份决定最终保存期。

调度与范围

• Cloudflare Worker Cron 使用 17 18 * * *，即每天 UTC 18:17、北京时间 02:17。
• 自动任务与管理员手工回退调用同一套有界清理：过期配对码摘要转为不可恢复 tombstone；24 小时前的来源限速窗口、30 天前的配对尝试和自身已经到期的幂等记录被删除。
• 成功清理继续追加 privacy.retention_cleanup 审计。不会删除账户、主机、设备凭据、反馈、故障公告、审计、租户、开通任务、卷或备份。

防重与失败

maintenance_jobs 对 retention_cleanup 只保存一行。调度开始时通过一条条件 upsert 取得运行权；已有任务在 30 分钟内运行时，重复触发直接跳过。超过 30 分钟仍未收口时，下一次触发可以用新 run ID 接管，旧任务不能覆盖新状态。

成功时覆盖最近成功时间、结果摘要并清零连续失败数。失败时只保存稳定错误码和连续失败数，不保存异常堆栈、请求内容或用户数据；异常继续向 Worker 调度事件抛出，使托管平台把该次执行记为失败。

后台判读

• 最近 36 小时内有成功：正常；
• 超过 36 小时无成功：逾期；
• 当前运行不超过 30 分钟：运行中；
• 当前运行超过 30 分钟：卡住；
• 最近一次失败：失败，并显示最小错误码；
• 从未有任务记录：尚未自动运行。

部署后应等待首个调度窗口，确认后台出现一次成功、maintenance_jobs 只有一行，并在 Cloudflare 观测中核对该 Cron 事件。部署前的本地构建和 SQL 回归只能证明入口、配置与状态机存在，不能冒充真实托管执行证据。