nodehub/docs/maintenance/FREENODE.md

# 免费节点订阅接收

Nodehub只负责接收和托管产物；上游生成、内核校验和站点分发见[master01维护正文](/Users/hellcat/Documents/GemCodes/dd.loc/docs/maintenance/FREENODE.md)。项目身份和访问规则见[GemDocs项目档案](/Users/hellcat/Documents/GemDocs/AI版/10-项目/nodehub.md)。

## 订阅日期契约

`POST /api/freenode/file/put`由`Api/v1/FreenodeController::filePut()`接收，参数仍为`site_code_short`和各格式`raw`，接口及链接算法不变。

接收时通过`CarbonImmutable::now('Asia/Shanghai')`确定一次业务日期，目录令牌和所有格式文件名均使用同一日期。应用默认时区仍为UTC，不改整个应用的日期、任务或日志。与master01按北京时间生成的当天链接保持一致；当天首次正常分发前不保证新日期文件已存在。

旧实现用UTC的`date()`，北京时间00:15、06:15两轮会写到前一天目录，直到12:15一轮才产生当天文件。2026-10-21已确认该问题；本次改动仅修复订阅接收日期，不移动历史文件、不复制旧节点伪造未来批次。

## 回归验证

`php vendor/bin/phpunit tests/Feature/FreenodeDateTest.php --do-not-cache-result`在隔离临时目录运行真实接收控制器，模拟北京时间零点前后以及00:15、06:15、12:15同步时刻，核对三种格式的日期、目录、内容以及全局UTC时区保持不变。Telegram被替换为测试对象，不访问网络或真实公开目录。

2026-10-21本机PHP 8.4.1通过5项、35断言。macOS本机使用真实PHP二进制`/usr/local/Cellar/php/8.4.1_1/bin/php`运行，避免Herd包装器导致PHPUnit隔离子进程启动失败。生产部署及验收结果另按实际记录。

## 发布与恢复

通过Git提交、服务端推送仓库，再将线上工作树更新到明确提交。提交只包括控制器、上述测试和本文；保留已有权限及未跟踪文件。部署前在服务器保存旧提交、控制器原字节/权限、工作区状态和当日订阅哈希；回退只还原本次控制器并记录代码版本，不reset整个有并行改动的工作树，不清除公开订阅目录。数据库、环境配置和系统时间不需要改动。

## 2026-10-21 部署验收

- 功能提交`0a1698b69d514a649a63040053fae1d96f30b7f4`，分支`codex/subscription-beijing-date`。按用户线上部署授权，通过SSH传送增量Git bundle，在Nodehub服务器侧推送既有`tom/nodehub`仓库，再更新工作树到明确提交；未从本机访问Git HTTP。
- 生产基线`d8aa76e7ad754b0dd4501efe2c91c9e7004fd43d`；旧控制器原文/权限、工作区状态、当日10文件哈希及激活记录在`/var/backups/nodehub-subscription-date-20261021/`。原有大量权限差异及未跟踪文件均保留，部署前后工作区状态摘要完全一致。未改全局UTC、数据库、环境、Nginx或系统时钟，未重启服务。
- 生产PHP 8.4.14通过5项、35断言。实际PHP-FPM另在隔离临时目录中模拟UTC `2026-10-21T16:15:00Z`与`22:15:00Z`（北京时间明日00:15/06:15），三格式均生成20261022对应目录和文件，响应成功、全局UTC未变、stderr为0；虚构内容与临时脚本已清理，没有伪造明天公开订阅。结果记录在同备份目录`fpm-date-check.json`。
- 通过master01现有接口重放当前已验证批次，四站全部成功；接收端10文件逐份哈希通过，URI/Sing-box精确一致，Clash与既有首尾空白处理后的内容一致。Nodehub服务器正常HTTPS请求这10份当日订阅全部200，响应哈希与文件一致。
- 已完成服务器侧验收，未做线上页面验收。未等到明天实际定时触发；已用实际FPM模拟对应跨日时段验证本次缺陷。后续若上游抓取、原生校验或网络另行失败，仍按各自错误调查，不把本次日期修复等同于整个链路永不失败。