站点登录状态与密钥备份

pt-tools 用你配置的 Cookie、API Key 或 Passkey 定时访问站点的个人信息，读取站点提供的 last_access / last_login，算出距离不活跃封号还剩几天，快到期限时通过已配置的通知通道提醒；也可以按站点开启每日签到。Cookie 可以用 PT Tools Helper 同步。

使用流程

1. 在站点 → 站点列表中启用目标站点，并配置好认证信息。Cookie 认证的站点可以安装 PT Tools Helper，在浏览器中登录站点后一键同步 Cookie；API Key 和 Passkey 站点在 Web UI 中手动填写。
2. 站点列表的「剩余天数」列显示距离封号阈值还有几天，负数表示已经超过阈值；「判定活跃」列（默认隐藏，可在「列设置」里打开）是用于提醒判定的活跃时间，规则见判定活跃。鼠标悬停「剩余天数」或「判定活跃」可以看到判定依据、下次探测时间和连续失败的开始时间，悬停「状态」可以看到最近一次没有成功的探测结果；尚无探测结果的站点（从未探测过，或探测对它不适用）显示灰色的「未探测」；pt-tools 没有内置定义的站点探测不了登录状态，显示灰色的「不支持」，悬停写明原因。
3. 点击行内的「保号配置」按钮，按站点设置封号判定天数、提前提醒天数、提醒 cron、通知通道和探测模式。
4. 行内的「立即探测」按钮马上探测一次登录状态，「测试提醒」按钮向通知通道发送一条测试消息；列表上方的「探测启用站点」对所有已启用站点各探测一次，最多 3 个并发。
5. 收到提醒后正常访问站点。Cookie 失效时重新同步，再点「立即探测」确认状态已经刷新。

站点详情页的「保号规则」卡片也显示探测结果、判定依据、下次探测时间、连续失败的开始时间和访问状态。

说明

探测能刷新多数站点的 last_access（最近动向）。少数站点按 last_login（实际登录）或做种活跃度判断是否清理账号，这类站点仍需定期手动登录，不能只看剩余天数。

每站点配置

「保号配置」对话框中的各项：

配置项	默认值	说明
封号判定天数	30	不活跃超过这个天数，站点就可能封号
提前提醒天数	10	距离封号还剩多少天开始提醒
提醒 cron	0 10,22 * * *	标准 5 字段 cron（分 时 日 月 周），默认每天 10:00 与 22:00
通知通道	空	选择后只发送到选中且已启用的通道；留空则发送到所有已启用通道
探测模式	自动	自动：跟随定时探测；手动：只在点击「立即探测」时执行；禁用：不探测

定时探测

探测模式为「自动」的已启用站点由后台定时探测：

• 后台每分钟检查一次，逐个探测到了时间的站点。
• 每个站点有一个固定的随机偏移，在 1 秒到 6 小时之间。已经有过探测结果、但尚未安排下一次的站点（例如旧版本升级上来的）按这个偏移安排第一次探测，第一轮分散在 6 小时内完成。从没探测过、也没有任何活动数据的站点（新加的站点、刚升级上来的库）在 5 分钟内探测，不必等上几个小时才看到最近活跃。重启不会让所有站点重新探测一遍，没到时间的站点照常等待。
• 更新凭证（包括浏览器扩展同步 Cookie）或保存站点配置之后，一分钟内自动探测一次该站点，不必等到下一次定时探测（探测模式为「手动」「禁用」的站点除外）。
• 探测与用户统计、搜索共用同一个站点连接和限速；探测成功时，用户统计里该站点的上传、下载、魔力等数据也随之刷新。
• 每次探测之后，按结果安排下一次：

本次结果	下次探测
正常	约 6 小时后（上下浮动 10%）
会话已过期、密钥错误	24 小时后，失效的凭证不必频繁请求站点
被反爬拦截、网络错误、请求过于频繁、解析失败、未知状态	连续第 1、2、3 次失败后分别隔 1、2、4 小时，之后每 6 小时
未配置凭证	不请求站点；补上凭证后一分钟内自动探测，否则 6 小时后在本地再检查一次
暂不支持探测	不请求站点；24 小时后再检查一次

「立即探测」不受这张表限制，执行后按本次结果重新安排下一次。

单次探测最多 150 秒，其中向站点发出的请求最多 90 秒（和同步用户信息时一个站点的时限一样）。超时按失败记录，不影响其他站点的探测。

探测前先做两项不发请求的检查：

• 站点没有内置定义（不在支持站点列表中，例如通过接口或模板导入添加的动态站点）时，状态记为「暂不支持探测」。
• 缺少认证方式要求的凭证时，状态记为「未配置凭证」：Cookie 认证需要 Cookie，API Key 认证需要 API Key，Cookie + API Key 认证两者都要，Passkey 认证需要 Passkey。

这两种状态不请求站点、不计入连续失败，也不发失败提醒。

CloakBrowser 后备

探测平时直接请求站点（按站点的认证方式带 Cookie、API Key 或 Passkey）。站点开了 Cloudflare 等反爬时，直接请求可能拿不到个人页。配置 CloakBrowser 之后，这类探测会改用 CloakBrowser 打开站点的个人页再判定一次。

• 在 系统 → CloakBrowser 填写「CloakBrowser-Manager 端点」「Auth Token」和「Profile ID」，三项都填好才使用后备。CloakBrowser-Manager（cloakhq/cloakbrowser-manager）需要自行部署，并在其中建好 profile。「测试连接」只检查端点和 token，不检查 Profile ID。
• 只有直接请求的结果是「被反爬拦截」「网络错误」「请求过于频繁」时才使用后备；会话过期、密钥错误这类凭证问题不使用。站点返回 Cloudflare 的质询页时记为「被反爬拦截」，不会当成凭证失效。
• 后备判定为正常时，采用后备的结果。后备也没有成功时，保留直接请求的结果，后备失败的原因接在失败原因后面，点「立即探测」后的提示里可以看到。
• 后备只用站点的 Cookie：没有配置 Cookie 的站点（例如只填了 API Key 或 Passkey）不使用后备。它打开的页面与直接请求访问同一个站点地址，并把站点的 Cookie 带进浏览器：

站点架构	打开的页面	前提
NexusPHP	/userdetails.php?id=<用户 ID>	该站至少成功探测过一次，已知用户 ID
Unit3D	/users/<用户名>	该站至少成功探测过一次，已知用户名
Gazelle	/user.php?id=<用户 ID>	该站至少成功探测过一次，已知用户 ID
M-Team	网页版的 /profile	无其他前提
HDDolby、Rousi	不使用后备	—

• 所有站点共用这一个 profile，同一时间只跑一个后备探测，其他站点排队等待。排队和后备都算在单次探测的 150 秒以内。
• 修改这三项不需要重启，下一次探测就按新配置执行。

判定活跃

「判定活跃」是剩余天数和封号提醒依据的时间：

• 最近一次探测正常时，用站点返回的最近访问时间（last_access）；站点不提供时，用站点返回的最近登录时间。
• 最近一次探测没有成功（或者从未探测过）时，站点数据可能已经过时，再与浏览器扩展记录的访问时间比较，取较新的一个。所以探测出问题期间，你用浏览器正常访问站点，剩余天数不会照样减少。
• 浏览器扩展在你打开站点页面时上报访问时间，同步 Cookie 时也会附带；这个时间只会前进，不会被较早的上报覆盖。

判定依据显示为「站点最近访问」「站点最近登录」或「浏览器访问」。

Rousi Pro 的最近活跃时间只在用浏览器访问网页时更新；pt-tools 用 API Key 取资料、签到都不会刷新它（2026-10 实测），签到也不算活跃。所以 Rousi Pro 要定期用浏览器登录一次。访问以后，下一次探测或下一次提醒前的探测就会读到新的时间。

猫站（PTerClub）未封存的账号连续 60 天不登录会被禁用，只认你自己手动登录，自动签到和工具访问都不算（官方 wiki「账号保留规则」）。北洋园（TJUPT）威震一方以下的账号，180 天内要签到过 1 天、发过 1 个种子（或趣味盒、论坛新主题），或者实际上传增量超过 5 TiB 且做种积分增量超过 30 万，才算活跃，只访问网页不算；北洋园禁止自动签到，pt-tools 不替你签到。这两个站点的探测会刷新最近动向，剩余天数不代表站点自己的不活跃判定，要按站点规则定期手动登录、签到。

如果探测正常，但站点返回的最近访问时间与上次相同，并且已经是 48 小时以前，说明自动探测没有刷新这个站点的访问时间。站点列表在「剩余天数」旁标出「访问未生效」，封号提醒的正文也会加上一句提示。这类站点需要你手动登录访问；站点的最近访问时间前进后，标记自动消失。

提醒

封号提醒

剩余天数不超过「提前提醒天数」后开始提醒：

• 按「提醒 cron」的时间发送，同一个 cron 时段只发一次。
• 剩余天数降到比上一次提醒更紧急的档位（14、7、3、1 天）时，立即补发一次，不等 cron。
• 要发提醒时，自动探测的站点如果上一次探测成功、已经过了 30 分钟（或者从未探测过），先探测一次再判断：你刚用浏览器登录过站点时，不会再收到按几小时前的结果发出的提醒。上一次探测失败（凭证失效、被限流等），或者站点正在探测、签到时，不额外探测，照旧按已有的结果提醒。
• 提醒正文包含上次活跃时间、判定依据和剩余天数。

探测失败与恢复提醒

情况	什么时候提醒
会话已过期、密钥错误	发现后的下一次检查（每分钟一次）就提醒；没有恢复时，每 24 小时至多再提醒一次
被反爬拦截、网络错误、请求过于频繁、解析失败、未知状态	从第一次失败起持续满 24 小时后提醒；之后每 24 小时至多一次
未配置凭证、暂不支持探测	不提醒
恢复正常	发过失败提醒的站点，探测恢复正常后提醒一次

通知通道与静默时段

• 提醒发到「保号配置」里选中且已启用的通道；没有选择时，发到提醒产生时所有已启用的通道。
• 静默时段按通道各自生效，设置位置与 RSS 通知相同，见RSS 上新通知的静默时段。处在静默时段的通道等静默结束再发，其他通道照常发送。
• 剩余 1 天以内（含已超过阈值）的封号提醒和「测试提醒」不受静默时段限制。
• 发送失败时分别在 1 分钟、5 分钟、30 分钟、2 小时、6 小时后重试，第 6 次仍失败就放弃；重试时间落在静默时段内也会等到静默结束。
• 提醒经 ChatOps 已连接的通道发送，QQ、Telegram 不会另起连接。通知服务没有启动时（日志里有相应告警），提醒只记录、不发送。

每日签到

每日签到是 1.0 预览版加入的功能。pt-tools 可以每天在站点签到一次（NexusPHP 站点的签到插件，默认请求 attendance.php；HDArea、PTerClub、Rousi Pro 等站点走各自的签到接口），默认关闭。新版 NexusPHP 打开签到页不再直接签到，只显示一个「立即签到」按钮，pt-tools 照这个按钮的做法提交一次。站点打开了签到验证码时，按钮旁边还有一张图片验证码，pt-tools 交给 AI 识别后再提交（要打开「用 AI 签到」，见下一节）；要通过 Cloudflare Turnstile、reCAPTCHA 这类人机验证时 AI 也过不了，当天记为「签到失败」、不重试，原因里写明要在网页上签到。签到的开关、结果和设置都在左侧导航「站点 → 自动签到」这一页。

• 开启：在「自动签到」页的表格里打开站点的「自动签到」开关（站点列表行内的「保号配置」里也能开）。不支持自动签到的站点不能开启，表格里写明原因。
• 时间：每天在「自动签到」页「签到设置」的时间窗内随机选一个时刻签到，默认 08:00–10:00，按服务器时区（Docker 的 TZ）。开启时或程序启动时已经过了当天的时间窗，就在接下来的 10 分钟内签到。
• 结果：签到成功或今天已经签到过之后，当天不再请求。失败时分别在 10 分钟、30 分钟后重试，第 3 次仍失败记为「签到失败」，第二天重新开始。站点回 404（没有签到的那一页，多半改了签到方式）时不重试，当天直接记为「签到失败」，原因里写明请求的地址。页面里认不出签到结果时，原因里带上站点回的页面标题，看得出是签到页、登录页还是 Cloudflare 的验证页。关掉自动签到或停用站点以后，当天尚无结果的站点显示「未开启」或「站点未启用」，不再显示「待重试」。每个站点每天的结果都记下来，「签到记录」里按站点列出最近 14 天，每天一格。
• 签到详情：「签到记录」下面是某一天的「签到详情」，默认是今天；点「签到记录」表头的日期换成那一天，也可以前后翻或者在下拉框里选。上面一行是当天的汇总（几个站点、成功几个、失败几个；借助 AI 的有几个站点、调用了几次、用了多少输入与输出 token）。每个站点一行：结果、方式（直接签到、AI 识别验证码、AI 答题）、尝试了几次、AI 用量、时间与说明（成功时是站点回的话，失败时是原因，还要重试时写明什么时候再试）。展开一行看这一天的每次尝试：定时还是手动、结果、用时与原因。每次尝试的记录保存 90 天；这个功能加入以前的日子只有当天的结果。
• 与登录探测共用同一个站点连接和限速，同一个站点不会同时探测和签到。
• 推送：「签到设置」里的「推送签到结果」默认打开：当天所有开启了签到的站点都有结果之后，推一条汇总（签上了几个、哪些失败及原因）。「推送到」不选时推到所有已启用的通知通道，也可以只选几个；处在静默时段的通道等静默结束再发。关掉以后不推，签到记录照常记下。
• 一键签到：「自动签到」页右上角的「一键签到」，给开启了自动签到、今天尚无结果的站点各签一次，在后台进行，页面上显示进度。要识别验证码的站点一个最多要几分钟，可以先离开这一页。
• 手动签到：「自动签到」页每一行的「立即签到」、站点列表行内的「立即签到」（日历图标）、站点详情「保号规则」卡片里的「立即签到」，以及 ChatOps 命令 /signin [站点]（不带站点时签到所有开启了自动签到、当天尚无结果的站点）。手动签到不要求开启自动签到，失败也不占用自动重试的次数。

HDSky、OpenCD、PTCHDBits、52PT 签到要识别验证码或答题，要用 AI，见下一节。Rousi Pro 用站点设置里 Passkey 一栏填的个人 API Key 签到，这个 Key 要有「执行签到」权限（attendance:claim）；没有时签到失败，原因里写明。UHDDolby 用站点设置里的 Cookie 签到（API Key 不能签到），没填 Cookie 时签到记为不支持，原因里写明要填 Cookie。以下内置站点不支持自动签到：

站点	原因
M-Team	没有签到；保号要定期用浏览器登录，站方不允许第三方工具调用更新访问时间的接口
SpringSunday	没有签到，站点上没有签到页
BYRPT	没有签到，站点上没有签到页
TJUPT	签到页写明禁止用脚本或程序签到，答错还会扣魔力值
U2	签到要从动态图片验证码里认出番剧名
BTSCHOOL	签到方式与常见 NexusPHP 站点不同
MooKo	不是 NexusPHP 架构，暂不支持签到
Audiences	站点已取消签到，站点上没有签到页了

签到每天会额外请求一次站点，开启前请确认站点规则允许自动签到。

用 AI 识别验证码与答题

HDSky、OpenCD 签到要识别验证码，PTCHDBits、52PT 签到要答一道选择题；新版 NexusPHP 的站点打开了签到验证码时，签到页上也有一张图片验证码。在「自动签到」页的「签到设置」里打开「用 AI 签到」以后，这些站点签到时交给 AI 助手的模型来做。默认关闭。

• 前提：先在「AI 助手设置」里填好接口地址、API Key 和模型，并启用 AI 助手。
• 识别验证码要能看图的模型，在「识别验证码用的模型」里选，例如 Gemini、gpt-4o-mini、Llama 4；不选时用 AI 助手的模型。DeepSeek 的模型不能看图。点「测试看图」，pt-tools 会现画一张 6 位验证码让模型认，并写明认没认对。
• 答题用 AI 助手的模型：题目和选项交给模型，按它选的选项提交。答错了站点照样记签到，奖励按站点规则（通常更少），签到记录里写明「AI 答错了」。
• 验证码认错了会换一张再认，一次签到最多认 3 张。还是不对，或者模型没给出答案，按签到失败处理，10 分钟、30 分钟后重试。
• 没有打开「用 AI 签到」，或者 AI 助手没启用、没配好时，这些站点当天的签到记为失败，原因里写明怎么打开，不会重试。
• 验证码图片和题目会发给「AI 助手设置」里的服务商，Cookie 和 Passkey 不会发出去。

备份加密密钥

~/.pt-tools/secret.key 用于 AES-256-GCM 加密站点 Cookie 等凭证。密钥丢失后，已存储凭证无法解密，只能重新同步。

导出备份：

pt-tools secret export > ~/secret.key.backup
chmod 600 ~/secret.key.backup

恢复备份：

pt-tools secret import --force < ~/secret.key.backup

警告

密钥备份具备与原始密钥相同的敏感性。请存入密码管理器、加密介质或受控备份系统，不要提交到代码仓库或明文云盘。

Docker 持久化

容器部署必须把 /app/.pt-tools 挂载到宿主机或受管卷。该目录同时包含 secret.key、数据库、日志和临时种子文件；重建容器前应确认挂载存在且备份可用。

volumes:
  - ./data:/app/.pt-tools

删除 ./data 会同时丢失数据库与密钥。备份时请把密钥与数据库作为一个一致性单元保存。

合规边界

此功能使用用户自己的 Cookie、API Key 或 Passkey 周期访问站点页面或 profile API。启用前请确认站点规则允许自动化访问，并根据个人风险偏好设置探测频率：

• 部分站点可能把频繁脚本访问视为违规。
• 登录状态字段由站点提供，可能缺失、延迟或语义不同。
• pt-tools 不保证该功能可以避免封号，也不承担因自动化访问导致的警告、降级或封禁。

认证信息获取与同步方法见获取 Cookie / API Key。