代码锚点索引表

一、前端暴露接口函数

共 9 个，分布在 api/routes/ 和 headless/ 两个链路中。

锚点代码：#_[编号]

编号	锚点	所在文件	说明
#1	`POST /api/create`	`api/routes/create.php`	创建短链（前端链路入口），检查配额、原子写冷存储、同步热存储
#2	`POST /api/delete`	`api/routes/delete.php`	删除短链（前端链路入口），先删冷后删热、文件锁保护
#3	`GET /api/list`	`api/routes/list.php`	查询所有短链（前端链路入口），读取冷存储并过滤过期条目
#4	`GET /api/stat`	`api/routes/stat.php`	查询配额状态（前端链路入口），优先读热存储，不可用时回退冷存储
#5	`POST /headless/api/create`	`headless/create.php`	创建短链（无头链路入口），逻辑同 #1，错误格式为 `hl_error`
#6	`POST /headless/api/delete`	`headless/delete.php`	删除短链（无头链路入口），逻辑同 #2，错误格式为 `hl_error`
#7	`GET /headless/api/list`	`headless/list.php`	查询所有短链（无头链路入口），逻辑同 #3
#8	`GET /headless/api/stat`	`headless/stat.php`	查询配额状态（无头链路入口），逻辑同 #4
#9	`GET /headless/api/get/{code}`	`headless/get.php`	按短码查询单条短链（无头专属），仅无头链路可用，依次查永久/临时存储

二、内部关键处理函数

共 34 个，分布在 api/common/、api/key/、api/storage/、api/lua/ 及路由文件中。

锚点代码：$_[编号]

编号	锚点	所在文件	说明
$1	`formatIso8601`	`api/common/helpers.php`	将 Unix 时间戳格式化为带时区偏移的 ISO 8601 字符串
$2	`isExpired`	`api/common/helpers.php`	判断临时条目是否已过期（Unix 时间戳比较，时区安全）
$3	`cleanExpiredEntries`	`api/common/helpers.php`	从数据数组中原地移除过期条目，由 `create/delete` 写入时调用
$4	`readFile`	`api/key/keys.php`	读取 `keys.json` 文件，返回常驻 Key、服务 Key 和一次性 Key 池数据
$5	`writeLockedFile`	`api/key/keys.php`	在持有文件锁状态下安全写入 keys 数据（v2.1：备份 + 写入 + 验证 + 回滚）
$6	`verify`	`api/key/keys.php`	验证 API Key（支持常驻/一次性/服务三种 Key，`hash_equals` 恒定时间比较防时序攻击，返回 `'resident'`/`'onetime'`/`'service'`/`false`）
$7	`generateResident`	`api/key/keys.php`	生成新的常驻 Key（返回明文，仅此一次显示，通过 `generateRawKey` 生成 Base58 密钥）
$8	`fillPool`	`api/key/keys.php`	将一次性 Key 池补充到最大容量（通过 `generateRawKey` 生成 Base58 密钥）
$9	`revoke`	`api/key/keys.php`	吊销指定类型的 Key（常驻/一次性/服务/全部）
$10	`status`	`api/key/keys.php`	获取当前 Key 状态（供 CLI 工具 `nurl -look` 显示，含常驻/服务/一次性密钥池信息）
$11	`read`	`api/storage/json_store.php`	无锁读取 JSON 文件，返回数据对象（`rename` 保证原子性）
$12	`write`	`api/storage/json_store.php`	安全写入 JSON 文件（v2.1：备份 + `.php.tmp` + `rename` + 验证 + 回滚）
$13	`find`	`api/storage/json_store.php`	按短码查找条目（大小写不敏感）
$14	`count`	`api/storage/json_store.php`	统计总条目数
$15	`countActive`	`api/storage/json_store.php`	统计有效（未过期）条目数
$16	`lockBegin`	`api/storage/json_store.php`	获取排他文件锁，用于原子读-检查-写操作
$17	`readLocked`	`api/storage/json_store.php`	在持有排他锁状态下读取数据
$18	`writeLocked`	`api/storage/json_store.php`	在持有排他锁状态下安全写入数据（v2.1：备份 + 写入 + 验证 + 回滚）
$19	`lockEnd`	`api/storage/json_store.php`	释放排他文件锁
$20	`internalPost`	`api/lua/internal.php`	内部 POST 请求辅助函数（cURL 与 OpenResty 通信）
$21	`getKeyStore`	`api/common/helpers.php`	获取全局 KeyStore 单例（延迟初始化，`function_exists` 守卫防重复定义，4 参数：path/tz/ttl/pool）
$22	`hl_error`	`headless/bootstrap.php`	无头链路统一错误输出（`{error:code, message:中文}` 格式）
$23	`checkDataAccess`	`api/common/helpers.php`	检查数据文件可读写性，支持文件不存在时检查目录可写性（允许首次部署自动创建），不可访问返回 false（触发 430 错误）
$24	`checkFileAccess`	`api/common/helpers.php`	检查单个文件的可访问性（文件存在检查可读写，不存在检查目录可写）
$25	`withLock`	`api/key/keys.php`	在 flock 排他锁内执行回调（保证 CLI 与 API 操作互斥，统一 inode）
$26	`永久链去重`	`api/routes/create.php`, `headless/create.php`	ttl==0 且未传自定义短码时遍历 perm.json 冷存储，URL 严格匹配则返回已有短码（HTTP 200 + dedup:true）
$27	`auth_hash`	`api/key/auth_hash.php`	认证哈希函数（SHA-256），换算法只改此文件，零依赖
$28	`auth_extract`	`api/key/auth_extract.php`	从 HTTP 请求提取认证凭证（Header/Body 优先级），不做验证，返回 `string
$29	`auth_verify`	`api/key/auth_verify.php`	验证凭证原文，返回标准 `$authCtx`（`valid`/`type`/`reason`），不含错误输出；服务密钥在非无头模式下返回 `wrong_channel`
$30	`base58_encode`	`api/key/base58.php`	Base58 编码函数（Bitcoin 标准字母表，bcmath 大整数运算，将二进制数据编码为 Base58 字符串）
$31	`base58_decode`	`api/key/base58.php`	Base58 解码函数（Bitcoin 标准字母表，bcmath 大整数运算，将 Base58 字符串还原为二进制数据）
$32	`generateRawKey`	`api/key/keys.php`	生成原始密钥：`random_bytes(32)` → `base58_encode()` → `'su_'` 前缀（约 47 字符，替代原 64 字符随机拼接）
$33	`generateService`	`api/key/keys.php`	生成服务密钥（永不过期、不限使用次数，仅限无头模式），通过 `generateRawKey` 生成，存储于 `keys.json` 的 `service` 字段，已存在时抛出 `RuntimeException`
$34	`getLastInternalError`	`api/lua/internal.php`	获取最近一次内部通信（`internalPost`）的 cURL 错误信息，供调用方在同步热存储失败时输出诊断

三、调用外部模块函数

共 28 个，记录所有跨模块调用点。

锚点代码：&_[编号]

编号	锚点	所在文件	调用目标	说明
&1	`internalPost`	`api/lua/internal.php`	`internalPost()`	`internalSet()` 内部调用，向 OpenResty `POST /internal/set`
&2	`internalPost`	`api/lua/internal.php`	`internalPost()`	`internalDelete()` 内部调用，向 OpenResty `POST /internal/delete`
&3	`auth_extract`	`api/common/bootstrap.php`	`auth_extract()`	API 链路认证凭证提取
&4	`auth_verify`	`api/common/bootstrap.php`	`auth_verify()`	API 链路认证凭证验证，返回 `$authCtx`
&5	`auth_extract`	`headless/bootstrap.php`	`auth_extract()`	无头链路认证凭证提取
&6	`auth_verify`	`headless/bootstrap.php`	`auth_verify()`	无头链路认证凭证验证，返回 `$authCtx`
&7	`internalSet`	`api/routes/create.php`	`internalSet()`	前端创建去重路径写入热存储（永久链去重命中时同步热存储）
&8	`auth_hash`	`api/key/keys.php`	`auth_hash()`	哈希运算（`verify`/`generateResident`/`fillPool`/`generateService` 4 处调用，换算法改 `auth_hash.php`）
&9	`internalSet`	`api/routes/create.php`	`internalSet()`	前端创建接口写入热存储
&10	`internalDelete`	`api/routes/delete.php`	`internalDelete()`	前端删除接口清除热存储
&11	`internalStat`	`api/routes/stat.php`	`internalStat()`	前端配额接口读取热存储计数
&12	`internalSet`	`headless/create.php`	`internalSet()`	无头创建接口写入热存储
&13	`internalDelete`	`headless/delete.php`	`internalDelete()`	无头删除接口清除热存储
&14	`internalStat`	`headless/stat.php`	`internalStat()`	无头配额接口读取热存储计数
&15	`base58_encode`	`api/key/keys.php`	`base58_encode()`	Base58 编码（`generateRawKey` 内调用，将 32 字节随机数编码为 Base58 字符串）
&16	`generateRawKey`	`api/key/keys.php`	`KeyStore::generateRawKey()`	密钥生成（`generateResident`/`fillPool`/`generateService` 3 处调用）
&17	`internalSet`	`headless/create.php`	`internalSet()`	无头创建去重路径写入热存储（永久链去重命中时同步热存储）
&18	`generateResident`	`nurl`	`KeyStore::generateResident()`	`nurl -new` 生成常驻密钥
&19	`fillPool`	`nurl`	`KeyStore::fillPool()`	`nurl -new` 补充一次性密钥池
&20	`status`	`nurl`	`KeyStore::status()`	`nurl -look` 查看密钥状态
&21	`generateService`	`nurl`	`KeyStore::generateService()`	`nurl -svc` 生成服务密钥
&22	`revoke`	`nurl`	`KeyStore::revoke()`	`nurl -drop` 撤销密钥
&23	`cleanExpiredEntries`	`nurl`	`cleanExpiredEntries()`	`nurl -sweep` 清理过期条目
&24	`headlessGet`	`nurl-key`	`headlessGet()`	`nurl-key -list` 查询短链列表
&25	`headlessGet`	`nurl-key`	`headlessGet()`	`nurl-key -stat` 查询配额状态
&26	`headlessGet`	`nurl-key`	`headlessGet()`	`nurl-key -get` 查询单条短链
&27	`headlessPost`	`nurl-key`	`headlessPost()`	`nurl-key -add` 创建短链
&28	`headlessPost`	`nurl-key`	`headlessPost()`	`nurl-key -rm` 删除短链

四、被外部调用的入口

共 3 个，均为 PHP → OpenResty 内部 API 的桥接函数。

锚点代码：%_[编号]

编号	锚点	所在文件	对应端点	说明
%1	`internalSet`	`api/lua/internal.php`	`POST /internal/set`	写入热存储桥接，被 `api/routes/create.php` 和 `headless/create.php` 调用
%2	`internalDelete`	`api/lua/internal.php`	`POST /internal/delete`	删除热存储桥接，被 `api/routes/delete.php` 和 `headless/delete.php` 调用
%3	`internalStat`	`api/lua/internal.php`	`GET /internal/stat`	读取热存储计数桥接，被 `api/routes/stat.php` 和 `headless/stat.php` 调用

五、锚点统计

类型	标记	数量
对外接口函数	`@外接口_#`	9
内部关键函数	`@关键_$`	34
调用外部模块	`@外调用_&`	28
被外部调用入口	`@外调用入口_%`	3
合计		74

六、文件与锚点分布

1. 公共库 `api/common/`

文件	接口 `#`	内部函数 `$`	调用外部 `&`	被外部调用 `%`
`bootstrap.php`			&3, &4
`helpers.php`		$1, $2, $3, $21, $23, $24

2. Key 认证 `api/key/`

文件	内部函数 `$`	调用外部 `&`
`auth_hash.php`	$27
`auth_extract.php`	$28
`auth_verify.php`	$29	&7
`base58.php`	$30, $31
`keys.php`	$4, $5, $6–$10, $25, $32, $33	&8, &15, &16

3. Lua 通信 `api/lua/`

文件	接口 `#`	内部函数 `$`	调用外部 `&`	被外部调用 `%`
`internal.php`		$20, $34	&1, &2	%1, %2, %3

4. 冷存储 `api/storage/`

文件	接口 `#`	内部函数 `$`	调用外部 `&`	被外部调用 `%`
`json_store.php`		$11–$19

5. 前端链路 `api/routes/`

文件	接口 `#`	内部函数 `$`	调用外部 `&`
`create.php`	#1	$26	&7, &9
`delete.php`	#2		&10
`list.php`	#3
`stat.php`	#4		&11

6. 无头链路 `headless/`

文件	接口 `#`	内部函数 `$`	调用外部 `&`
`bootstrap.php`		$22	&5, &6
`create.php`	#5	$26	&12, &17
`delete.php`	#6		&13
`list.php`	#7
`stat.php`	#8		&14
`get.php`	#9

7. CLI 工具 `nurl`

文件	调用外部 `&`
`nurl`	&18, &19, &20, &21, &22, &23

8. CLI 工具 `nurl-key`

文件	调用外部 `&`
`nurl-key`	&24, &25, &26, &27, &28

声明

作者：圣堂之魂；发布于：2026-05-19；许可协议：CC BY-NC-SA 4.0

代码锚点索引表

声明

本页目录