v1.11.0 源码导航索引

一、从公开路由进入

路由映射和长度约束从 backend/nginx/nginx.md 开始看。该文件还包含公开目录屏蔽、API/跳转限流、内部 18500 端口、PHP-FPM 映射、1-5 位跳转规则和 worker 初始化入口。

二、认证链路

标准链路

api/routes/*.php
  -> api/common/bootstrap.php
  -> auth_extract(RAW_INPUT, "api")
  -> auth_verify(raw, "api")
  -> KeyStore::verify()

无头链路

headless/*.php
  -> headless/bootstrap.php
  -> auth_extract(RAW_INPUT, "headless")
  -> auth_verify(raw, "headless")
  -> KeyStore::verify()

一次性 Key 安全流

收到凭证
  -> 对原文做 auth_hash
  -> 锁定 keys.json.lock
  -> 常驻 / 服务 / 一次性槽恒定时间比较
  -> 一次性命中后把 key_hash 设为 null
  -> safe write keys.json
  -> 返回 type=onetime
  -> 之后才进入路由业务校验

这解释了为何已通过 Header 完成认证后，坏 JSON 或后续失败也会消费 Key。标准链路若仅把 Key 放在坏 JSON 的 body 中则无法提取凭证，也就不会消费。delete/list/stat 在 bootstrap 后显式禁止一次性 Key；create 允许；headless/get.php 当前未设置该禁令。

三、公共引导与配置

关键公共函数：

四、创建链路

阅读 api/routes/create.php 与 headless/create.php 时，按以下阶段定位：

1. bootstrap 已完成数据访问检查与 Key 消费。
2. 解码缓存的 RAW_INPUT。
3. 校验 URL 字符串、HTTP(S)、2048 长度和 SSRF。
4. 解析严格整数 TTL，缺省为 0。
5. 根据 $AUTH['type'] 选择普通或服务短码/配额。
6. 永久、无自定义短码时从冷存储做 URL 严格去重。
7. 校验自定义短码与保留字。
8. JsonStore::withBothLocks 同时锁定永久/临时 Store，原子检查冲突、配额并写入一个 Store。
9. internalSetWithRetry 同步 OpenResty 热存储。
10. 返回固定 short_url/exp/dedup/synced/warning/key_consumed 字段。

无头创建的额外分支：服务 Key 可用 len 在 4/5 位自动短码间覆盖配置；自定义服务短码最长 5 位；创建使用 svc_perm_limit/svc_temp_limit。

安全相关代码锚点：

五、删除、列表与统计

删除

api/routes/delete.php 与 headless/delete.php：

冷存储查类型
  -> 对目标 Store 加独立 .lock 排他锁
  -> 再读、再确认、删除、安全写入
  -> internalDelete(code, "perm"|"temp")
  -> {ok:true, synced:boolean}

冷存储提交后不因热删除失败而回滚。Lua 使用 PHP 传入的冷存储类型作为计数器递减的权威提示。

列表与单条查询

统计

api/routes/stat.php 和 headless/stat.php 均先用 JsonStore::countActive() 计算冷存储权威值，再调用 internalStat() 获取热诊断值：

标准 stat 还会记录热冷漂移日志；无头 stat 当前只在热不可用时记录日志。

六、冷存储

核心文件：api/storage/json_store.php。

冷存储 envelope：

{
  "v": 1,
  "at": "ISO 8601",
  "d": {
    "code": { "id": "code", "url": "https://...", "lurl": "https://.../code", "t": "临时项才有" }
  }
}

Key 存储的安全写入在 api/key/keys.php::writeLockedFile，使用相同的备份、临时文件、rename、验证和回滚思想，但锁定 keys.json.lock。

七、PHP 到 OpenResty 的内部桥

核心文件：api/lua/internal.php。

内部接口同时依赖 Nginx IP allow/deny 和 LPA-Key。令牌文件路径由 api/config.php::internal_token_path 与 Nginx $su_internal_token_path 对齐。

八、OpenResty 热路径

热存储结构：

九、部署与 CLI

SECURITY_FIXES.md 建议与源码一起阅读，重点覆盖：Lua 随机播种移除、共享字典驱逐恢复、常驻 Key 验证只读化、双 Store TOCTOU 修复、损坏 Key 文件拒绝覆盖、跨服务器时区的 ISO 8601 修复。

十、按问题检索