Core.php

<?php

namespace TypechoPlugin\Access;

use Redis;
use Typecho\Config;
use Typecho\Cookie;
use Typecho\Db;
use Typecho\Db\Exception as DbException;
use Typecho\I18n;
use Typecho\Plugin\Exception as PluginException;
use Typecho\Request;
use Typecho\Response;
use Utils\Helper;
use Widget\Options;
use Widget\User;

if (!defined('__TYPECHO_ROOT_DIR__')) {
    exit;
}

class Core
{
    /** 统计数据所在的数据库，可能是 Typecho 主库，也可能是独立配置的库 */
    protected readonly Db $db;

    /** Typecho 主库，用于读取文章标题等内容信息 */
    protected readonly Db $mainDb;

    protected readonly Request $request;
    protected readonly Response $response;

    /** Redis 缓存实例，未启用时为 null */
    protected ?Redis $redis = null;

    /** 本次请求是否已经安排过刷库，避免重复注册 */
    protected bool $flushScheduled = false;

    /** 缺 event_id 唯一索引的判定结果，一次请求里问一次就够 */
    private ?bool $degraded = null;

    /** Redis 缓存键前缀 */

    /** 历史日期的统计不会再变化，缓存 40 天足够覆盖当月图表 */
    private const PAST_DAY_TTL = 3456000;

    /**
     * 全表聚合的「新鲜期」（秒）
     *
     * 超过这个岁数就该重算了，但重算发生在响应发出之后，读的人拿到的仍是旧值。
     * total 比 referer/pie 短，是因为它是首屏三个大数字，看着更该跟得上。
     */
    private const TOTAL_FRESH_TTL = 600;
    private const LIST_FRESH_TTL = 1800;

    /**
     * 陈旧值在 Redis 里留多久（秒）
     *
     * 给得很长是故意的：拿一个礼拜前的总数顶一下，比让访客盯着 504 强得多。
     * 只要有人来看，后台刷新就会把它顶成新的。
     */
    private const AGGREGATE_STALE_TTL = 604800;

    /**
     * 「正在重算」互斥锁的存活时间（秒）
     *
     * 冷缓存时前端会反复轮询，不挡一下的话每轮询一次就多一条全表聚合在跑 ——
     * 那正是把数据库 CPU 打满的形状。
     *
     * **这个值必须覆盖一次重算的最坏耗时，而且不可能靠续租来兜底。**
     * 续租要求持锁进程周期性醒过来，而重算是一次阻塞的 PDO 调用：
     * PHP 停在 libpq / mysqlnd 的 read 上，中间没有任何执行点。
     * 队列的 LOCK_TTL 能取 30 秒是因为刷库天然按批切开，批与批之间可以续租；
     * 这里没有那个缝，只能把 TTL 一次性给够。
     *
     * 取值按实测的最坏情况留余量：n_distinct 没调之前，单条
     * 「总计独立 IP」跑过 643 秒（HashAggregate 落盘重分区）。
     * 两个方向的代价严重不对等，所以宁可给长：
     *   给短了 → 锁提前过期，下一个请求再起一条同样的全表聚合，
     *            几轮下来就是这个锁本来要防的那个形状；
     *   给长了 → 持锁进程崩掉后重算被推迟最多这么久，但陈旧值照常返回
     *            （AGGREGATE_STALE_TTL 有 7 天），用户只是看到稍旧的数字。
     */
    private const AGGREGATE_LOCK_TTL = 1800;

    /**
     * 重算失败后的退避时间（秒）
     *
     * 以前失败退避和互斥锁是同一个键：算失败就不删标记，让它自然过期。
     * 但这两件事要的 TTL 方向相反 —— 互斥锁要长到覆盖最坏耗时，
     * 退避只要挡住前端接下来几轮轮询就够。合用一个键时只能二选一，
     * 选长了失败后要等半小时才肯重试，选短了锁就形同虚设。
     * 现在拆成两个键，各给各的 TTL。
     */
    private const AGGREGATE_BACKOFF_TTL = 300;

    /** 值还没算出来时，告诉前端隔多久再来问（秒） */
    private const AGGREGATE_RETRY_AFTER = 2;

    /** 匿名埋点接口每个 IP 每分钟允许的次数 */
    private const TRACK_RATE_LIMIT = 60;

    /**
     * 限流计数键的存活时间（秒）
     *
     * 键名按分钟分桶、靠换键滚动，TTL 只是兜底回收，取两倍桶宽留出时钟误差余量。
     */
    private const TRACK_RATE_WINDOW = 120;

    public readonly UA $ua;
    public readonly Config $config;
    public readonly string $action;
    public readonly string $title;
    public array $logs = [];
    public array $overview = [];
    public array $referer = [];
    public array $postPie = [];

    /**
     * 构造函数，根据不同类型的请求，计算不同的数据并渲染输出
     *
     * @access public
     * @throws PluginException
     * @throws DbException
     */
    public function __construct()
    {
        # Load language pack
        if (I18n::getLang() !== 'zh_CN') {
            $file = __TYPECHO_ROOT_DIR__ . __TYPECHO_PLUGIN_DIR__ .
            '/Access/lang/' . I18n::getLang() . '.mo';
            file_exists($file) && I18n::addLang($file);
        }
        # Init variables
        $this->config = Options::alloc()->plugin('Access');
        $this->mainDb = Db::get();
        $this->db = Database::get($this->config);
        $this->request = Request::getInstance();
        $this->response = Response::getInstance();
        if ($this->config->pageSize == null || $this->config->isDrop == null) {
            throw new PluginException(_t('请先设置插件！'));
        }
        $this->ua = new UA($this->request->getAgent());
        $this->initRedis();
        switch ($this->request->get('action')) {
            case 'overview':
                $this->action = 'overview';
                $this->title = _t('访问概览');
                break;
            case 'logs':
            default:
                $this->action = 'logs';
                $this->title = _t('访问日志');
                break;
        }
    }

    /**
     * 获取概览页全部数据（供 AJAX 接口调用）
     *
     * @access public
     * @return array
     * @throws DbException
     */
    public function getOverviewData(): array
    {
        # 先把队列里积压的写进去，否则控制台看到的数字会偏低
        $this->flushQueue();

        $this->parseOverview();
        $this->parseReferer();
        $this->parsePostPie();

        return [
            'overview' => [
                'today'     => $this->overview['today'],
                'yesterday' => $this->overview['yesterday'],
                'total'     => $this->overview['total'],
            ],
            'referer'    => $this->referer,
            'chart_data' => json_decode($this->overview['chart_data'], true),
            'post_pie'   => $this->postPie,
        ];
    }

    /**
     * 分段获取概览数据
     *
     * 数据量大时一次算完整个概览会超出 Web 超时（300 万行实测本地就要 6 秒），
     * 而首次加载失败又会导致缓存永远建不起来，形成死循环。
     * 这里把概览拆成几块分别请求，每块都足够小；算完的部分会写进缓存，
     * 于是即使某一块要跑好几次也能逐步推进。
     *
     * @access public
     * @param string $section today / yesterday / month / total / referer / pie
     * @param float|null $deadline 时间预算（microtime 时间戳），仅 month 分段使用
     * @return array
     * @throws DbException
     */
    public function getOverviewSection(string $section, ?float $deadline = null): array
    {
        # 队列只在第一段刷一次就够，避免每段都刷
        if ($section === 'today') {
            $this->flushQueue();
        }

        return match ($section) {
            'today' => [
                'done' => true,
                'today' => $this->chartOf($this->queryDayOverview(date('Y-m-d')), 'day'),
            ],
            'yesterday' => [
                'done' => true,
                'yesterday' => $this->chartOf($this->cachedDayOverview(date('Y-m-d', strtotime('-1 day'))), 'day'),
            ],
            'total' => $this->totalSection(),
            'month' => $this->monthSection($deadline),
            'referer' => [
                'done' => true,
                'referer' => $this->refererData(),
            ],
            'pie' => [
                'done' => true,
                'post_pie' => $this->postPieData(),
            ],
            default => throw new \InvalidArgumentException('unknown section: ' . $section),
        };
    }

    /**
     * 概览分段的顺序，控制台按这个顺序逐个请求
     *
     * @return string[]
     */
    public static function overviewSections(): array
    {
        return ['today', 'yesterday', 'total', 'referer', 'pie', 'month'];
    }

    /**
     * 补上图表需要的标题与横轴
     *
     * @access protected
     * @param array $data
     * @param string $kind day / month
     * @return array
     */
    protected function chartOf(array $data, string $kind): array
    {
        $data['sub_title'] = 'Generate By AccessPlugin';
        $count = count($data['ip']['detail'] ?? []);
        if ($kind === 'day') {
            $data['xAxis'] = range(0, $count);
            $data['title'] = _t('%s 统计', $data['time']);
        } else {
            $data['xAxis'] = range(1, max(1, $count));
            $data['title'] = _t('%s 月统计', $data['time']);
        }
        return $data;
    }

    /**
     * 带缓存的单日概览（含小时明细）
     * 历史日期的数据不会再变，可以长期缓存
     *
     * @access protected
     * @param string $date
     * @return array
     * @throws DbException
     */
    protected function cachedDayOverview(string $date): array
    {
        $key = 'overview:dayfull:' . $date;
        $cached = $this->getCache($key);
        if ($cached !== null) {
            return $cached;
        }

        $data = $this->queryDayOverview($date);
        if ($date !== date('Y-m-d')) {
            $this->setCache($key, $data, self::PAST_DAY_TTL);
        }
        return $data;
    }

    /**
     * 带缓存的单日汇总（只要 ip/uv/pv 三个数，供月图表使用）
     *
     * @access protected
     * @param string $date
     * @return array
     * @throws DbException
     */
    protected function cachedDayCounts(string $date): array
    {
        $key = 'overview:daycount:' . $date;
        $cached = $this->getCache($key);
        if ($cached !== null) {
            return $cached;
        }

        $data = $this->queryDayCounts($date);
        if ($date !== date('Y-m-d')) {
            $this->setCache($key, $data, self::PAST_DAY_TTL);
        }
        return $data;
    }

    /**
     * 全表聚合的缓存读取：陈旧优先，重算放到响应发出之后
     *
     * 这几个数字（总计、来源 Top N、文章饼图）都是不带时间范围的全表聚合，
     * 覆盖索引帮不上忙，代价随数据量线性增长且没有上界。以前它们被当成
     * 普通缓存：命中就用、没命中就当场算 —— 于是「缓存刚好过期」这件事
     * 决定了某个倒霉的访客要不要等上几分钟。
     *
     * 现在分三种情况：
     *   新鲜   直接给
     *   过期   还是先把旧值给出去，重算挂到 shutdown，下次来就是新的
     *   没有   $allowDefer 为 true 时不算，回 done=false 让前端稍后再问；
     *          为 false（一次性返回全部的老接口）时只能当场算
     *
     * @access protected
     * @param string $key 缓存键（不含前缀）
     * @param callable $compute 真正干活的闭包，返回要缓存的数据
     * @param int $freshTtl 新鲜期（秒）
     * @param bool $allowDefer 允许把「还没算出来」如实告诉调用方
     * @return array{data: mixed, done: bool, retry_after: int}
     */
    protected function cachedAggregate(string $key, callable $compute, int $freshTtl, bool $allowDefer = false): array
    {
        # 没有 Redis 就没有缓存可言，也无处存中间结果，只能同步算
        if ($this->redis === null) {
            return ['data' => $compute(), 'done' => true, 'retry_after' => 0];
        }

        $envelope = $this->getCache($key);
        $hasValue = is_array($envelope) && array_key_exists('data', $envelope);

        if ($hasValue) {
            if (time() - (int)($envelope['at'] ?? 0) < $freshTtl) {
                return ['data' => $envelope['data'], 'done' => true, 'retry_after' => 0];
            }
            # 过期了也先给旧值，重算在后台做，读的人一秒都不用等
            $this->refreshAggregateLater($key, $compute);
            return ['data' => $envelope['data'], 'done' => true, 'retry_after' => 0];
        }

        if (!$allowDefer) {
            $data = $compute();
            $this->setCache($key, ['at' => time(), 'data' => $data], self::AGGREGATE_STALE_TTL);
            return ['data' => $data, 'done' => true, 'retry_after' => 0];
        }

        # 一个值都没有：也绝不让浏览器在一条没有上界的查询上干等
        $this->refreshAggregateLater($key, $compute);
        return ['data' => null, 'done' => false, 'retry_after' => self::AGGREGATE_RETRY_AFTER];
    }

    /**
     * 把重算挂到响应发出之后
     *
     * 同一时间只允许一个请求去算：冷缓存时前端每隔两秒问一次，
     * 不挡的话每问一次就多一条全表聚合，几轮下来就把数据库压垮了。
     *
     * 用两个键，因为「有人在算」和「刚算挂了，缓一缓」要的 TTL 方向相反：
     *   {key}:computing  互斥锁，TTL = AGGREGATE_LOCK_TTL，必须覆盖最坏耗时
     *   {key}:backoff    失败退避，TTL = AGGREGATE_BACKOFF_TTL，只要挡住几轮轮询
     * 合用一个键的话两个 TTL 只能二选一，怎么选都是错的。
     *
     * @access protected
     * @param string $key
     * @param callable $compute
     * @return void
     */
    protected function refreshAggregateLater(string $key, callable $compute): void
    {
        $redis = $this->redis;
        if ($redis === null) {
            return;
        }

        $lockKey = Cache::key($key . ':computing');
        $backoffKey = Cache::key($key . ':backoff');

        /*
         * 锁值用一次性随机 token 而不是固定的 '1'，理由同 Queue::acquireLock()：
         * 重算有可能跑过 AGGREGATE_LOCK_TTL，此时锁已经过期、可能已被下一个请求抢走。
         * 固定值分不出「我的锁」和「别人的锁」，收尾时一个 DEL 就把新持有者的锁删了，
         * 于是第三个请求又能抢到，同一个聚合上并排跑好几条 —— 正是这把锁要防的东西。
         * 这个坑刷库锁踩过一次（当年锁值是 PID），别在这儿再踩一遍。
         */
        $token = bin2hex(random_bytes(16));

        try {
            # 上一轮刚算挂过就先别急着重试，免得前端每问一次就重跑一次全表聚合
            if ($redis->exists($backoffKey)) {
                return;
            }
            if (!$redis->set($lockKey, $token, ['nx', 'ex' => self::AGGREGATE_LOCK_TTL])) {
                # 已经有人在算了
                return;
            }
        } catch (\Throwable $e) {
            return;
        }

        register_shutdown_function(function () use ($key, $compute, $redis, $lockKey, $backoffKey, $token) {
            // 页面已经输出完毕，先把响应交给用户再慢慢算
            if (PHP_SAPI === 'fpm-fcgi' && function_exists('fastcgi_finish_request')) {
                @fastcgi_finish_request();
            }
            @set_time_limit(0);

            try {
                $data = $compute();
                /*
                 * 即使这次重算超时、锁已经不在自己手上，算出来的值照样写回：
                 * 它总比缓存里那个更新。真正不能做的是替别人释放锁，那由下面按 token 保证。
                 */
                $this->setCache($key, ['at' => time(), 'data' => $data], self::AGGREGATE_STALE_TTL);
            } catch (\Throwable $e) {
                // 算不出来不影响任何人，旧值还在。记一条退避，别让下一轮轮询立刻又来一遍
                try {
                    $redis->set($backoffKey, '1', ['ex' => self::AGGREGATE_BACKOFF_TTL]);
                } catch (\Throwable $ignored) {
                }
            } finally {
                $this->releaseAggregateLock($redis, $lockKey, $token);
            }
        });
    }

    /**
     * 释放重算锁，且只释放自己那把
     *
     * 比较和删除必须原子：先 GET 再 DEL 的话，两步之间锁正好过期并被别人抢走，
     * 那个 DEL 删掉的就是新持有者的锁。
     *
     * @access protected
     * @param Redis $redis
     * @param string $lockKey 完整键名
     * @param string $token 抢锁时写进去的 token
     * @return void
     */
    protected function releaseAggregateLock(Redis $redis, string $lockKey, string $token): void
    {
        try {
            $script = <<<'LUA'
if redis.call("get", KEYS[1]) == ARGV[1] then
    return redis.call("del", KEYS[1])
else
    return 0
end
LUA;
            $redis->eval($script, [$lockKey, $token], 1);
        } catch (\Throwable $e) {
            // 释放失败就让它自然过期，最坏是重算被推迟到锁过期为止
        }
    }

    /**
     * 带缓存的总计
     *
     * @access protected
     * @param bool $allowDefer 冷缓存时是否允许回「还没算好」而不是当场算
     * @return array{data: mixed, done: bool, retry_after: int}
     * @throws DbException
     */
    protected function cachedTotalOverview(bool $allowDefer = false): array
    {
        return $this->cachedAggregate(
            'overview:total',
            fn(): array => $this->queryTotalOverview(),
            self::TOTAL_FRESH_TTL,
            $allowDefer
        );
    }

    /**
     * 总计分段
     *
     * 这三个数字来自不带时间范围的全表聚合，代价没有上界。冷缓存时不当场算，
     * 而是回 done=false 让前端稍后再问 —— 真算起来可能比 nginx 的
     * fastcgi_read_timeout 还久，那时浏览器早已 504，而 PHP 还在那儿磨，
     * 刷新几次就把 FPM 的 worker 堆满了。
     *
     * @access protected
     * @return array
     * @throws DbException
     */
    protected function totalSection(): array
    {
        $result = $this->cachedTotalOverview(true);

        if (!$result['done']) {
            return [
                'done' => false,
                'retry_after' => $result['retry_after'],
                'total' => null,
            ];
        }

        return ['done' => true, 'total' => $result['data']];
    }

    /**
     * 当月图表分段
     *
     * 逐天计算并逐天缓存。有 Redis 时支持时间预算：跑不完就先返回已完成的部分，
     * 下次请求从缓存里直接拿到已算好的天数继续往下推进。
     * 没有 Redis 时无处存放中间结果，只能一次算完。
     *
     * @access protected
     * @param float|null $deadline
     * @return array
     * @throws DbException
     */
    protected function monthSection(?float $deadline): array
    {
        $year = date('Y');
        $month = date('m');
        $monthDays = (int)date('t');
        $today = (int)date('j');

        $result = ['time' => $month];
        $ready = 0;
        $computed = 0;
        $done = true;

        for ($day = 1; $day <= $monthDays; $day++) {
            if ($day > $today) {
                # 未来的日期直接补 0，不用查库
                $result['ip']['detail'][$day - 1] = 0;
                $result['uv']['detail'][$day - 1] = 0;
                $result['pv']['detail'][$day - 1] = 0;
                $ready++;
                continue;
            }

            $date = sprintf('%s-%s-%02d', $year, $month, $day);
            $cached = $this->getCache('overview:daycount:' . $date);
            $counts = $cached ?? $this->cachedDayCounts($date);
            if ($cached === null) {
                $computed++;
            }

            $result['ip']['detail'][$day - 1] = $counts['ip'];
            $result['uv']['detail'][$day - 1] = $counts['uv'];
            $result['pv']['detail'][$day - 1] = $counts['pv'];
            $ready++;

            /*
             * 只有能把中间结果缓存下来时，中断才有意义。
             * 另外必须至少真算出了一天才允许中断：否则时间预算在「回放缓存」的阶段
             * 就耗尽的话，每次请求都停在同一天，前端会一直请求却毫无进展。
             */
            if ($computed > 0 && $this->redis !== null && $deadline !== null
                && $day < $today && microtime(true) >= $deadline) {
                $done = false;
                break;
            }
        }

        if (!$done) {
            return ['done' => false, 'progress' => $ready, 'total_days' => $monthDays];
        }

        return [
            'done' => true,
            'progress' => $ready,
            'total_days' => $monthDays,
            'month' => $this->chartOf($result, 'month'),
        ];
    }

    /**
     * 来源统计数据（供分段接口使用）
     *
     * @access protected
     * @return array
     * @throws DbException
     */
    protected function refererData(): array
    {
        $this->parseReferer();
        return $this->referer;
    }

    /**
     * 文章饼图数据（供分段接口使用）
     *
     * @access protected
     * @return array
     * @throws DbException
     */
    protected function postPieData(): array
    {
        $this->parsePostPie();
        return $this->postPie;
    }

    /**
     * 生成文章访问量饼图数据（Top N）
     *
     * @return void
     * @throws DbException
     */
    protected function parsePostPie(): void
    {
        $limit = (int)$this->config->pageSize;
        $limit = $limit > 0 ? min($limit, 50) : 20;

        $this->postPie = $this->cachedAggregate(
            'overview:post_pie:top' . $limit,
            fn(): array => $this->buildPostPie($limit),
            self::LIST_FRESH_TTL
        )['data'];
    }

    /**
     * 真正把文章饼图算出来（全表 GROUP BY content_id，代价随数据量线性增长）
     *
     * @access protected
     * @param int $limit
     * @return array
     * @throws DbException
     */
    protected function buildPostPie(int $limit): array
    {
        // 统计库与内容库可能不是同一个库，无法 JOIN，改为两次查询后在 PHP 中合并
        $counts = $this->fetchContentCounts();
        $meta = $this->fetchContentMeta(array_column($counts, 'cid'));

        $series = [];
        foreach ($counts as $item) {
            $cid = $item['cid'];
            $info = $meta[$cid] ?? null;

            // 只统计文章；页面、附件等不计入，已被删除的内容（查不到）仍然保留
            if ($info !== null && $info['type'] !== 'post') {
                continue;
            }

            $title = $info === null ? '' : trim($info['title']);
            if ($title === '') {
                $title = _t('已删除文章 #%d', $cid);
            }

            $series[] = [
                'cid' => $cid,
                'name' => $title,
                'y' => $item['count'],
            ];

            if (count($series) >= $limit) {
                break;
            }
        }

        return $series;
    }

    /**
     * 从统计库中取出各内容的访问次数，按次数降序
     *
     * @access protected
     * @return array [['cid' => int, 'count' => int], ...]
     * @throws DbException
     */
    protected function fetchContentCounts(): array
    {
        $rows = $this->db->fetchAll(
            $this->db->select('content_id AS cid', 'COUNT(1) AS count')
                ->from('table.access')
                ->where('content_id IS NOT NULL')
                ->where('content_id <> ?', 0)
                ->group('content_id')
                ->order('count', Db::SORT_DESC)
                // 次数相同时各数据库的返回顺序不一致，补一个稳定的次级排序
                ->order('content_id', Db::SORT_ASC)
        );

        $result = [];
        foreach ($rows as $row) {
            $cid = (int)($row['cid'] ?? 0);
            if ($cid > 0) {
                $result[] = ['cid' => $cid, 'count' => (int)($row['count'] ?? 0)];
            }
        }

        return $result;
    }

    /**
     * 到 Typecho 主库按 cid 批量取内容标题与类型
     *
     * @access protected
     * @param array $cids
     * @return array cid => ['title' => string, 'type' => string]
     * @throws DbException
     */
    protected function fetchContentMeta(array $cids): array
    {
        $cids = array_values(array_unique(array_filter(array_map('intval', $cids))));
        $meta = [];

        foreach (array_chunk($cids, 200) as $chunk) {
            $rows = $this->mainDb->fetchAll(
                $this->mainDb->select('cid', 'title', 'type')
                    ->from('table.contents')
                    ->where('cid IN ?', $chunk)
            );
            foreach ($rows as $row) {
                $meta[(int)$row['cid']] = [
                    'title' => (string)($row['title'] ?? ''),
                    'type' => (string)($row['type'] ?? ''),
                ];
            }
        }

        return $meta;
    }

    /**
     * 获取日志页全部数据（供 AJAX 接口调用）
     *
     * @access public
     * @param int $page 页码
     * @param int $type 类型 1=人类 2=爬虫 3=全部
     * @param string $filter 筛选类型 all/ip/post/path
     * @param string $filterValue 筛选值
     * @return array
     * @throws DbException
     */
    public function getLogsData(int $page, int $type, string $filter, string $filterValue): array
    {
        # 先把队列里积压的写进去，否则最新的访问不会出现在列表里
        $this->flushQueue();

        $offset = (max($page, 1) - 1) * $this->config->pageSize;
        $query = $this->db->select()->from('table.access')
            ->order('time', Db::SORT_DESC)
            ->offset($offset)->limit($this->config->pageSize);
        $qcount = $this->db->select('count(1) AS count')->from('table.access');

        switch ($type) {
            case 1:
                $query->where('robot = ?', 0);
                $qcount->where('robot = ?', 0);
                break;
            case 2:
                $query->where('robot = ?', 1);
                $qcount->where('robot = ?', 1);
                break;
        }

        switch ($filter) {
            case 'ip':
                if (filter_var($filterValue, FILTER_VALIDATE_IP, FILTER_FLAG_IPV6)) {
                    $ip = $this->ip62long($filterValue);
                } else {
                    $ip = (string)bindec(decbin((int)ip2long($filterValue)));
                }
                $query->where('ip = ?', $ip);
                $qcount->where('ip = ?', $ip);
                break;
            case 'post':
                // PostgreSQL 对整型列不接受空串等非数字字面量，这里统一转成整型
                $cid = (int)$filterValue;
                $query->where('content_id = ?', $cid);
                $qcount->where('content_id = ?', $cid);
                break;
            case 'path':
                $query->where('path = ?', $filterValue);
                $qcount->where('path = ?', $filterValue);
                break;
        }

        $list = $this->db->fetchAll($query);
        foreach ($list as &$row) {
            if (!empty($row['robot']) && $row['robot'] == 1) {
                $name = $row['robot_id'] ?? '';
                $version = $row['robot_version'] ?? '';
            } else {
                $name = $row['browser_id'] ?? '';
                $version = $row['browser_version'] ?? '';
            }
            if ($name === '' && !empty($row['ua'])) {
                $ua = new UA($row['ua']);
                if ($ua->isRobot()) {
                    $name = $ua->getRobotID();
                    $version = $ua->getRobotVersion();
                } else {
                    $name = $ua->getBrowserName();
                    $version = $ua->getBrowserVersion();
                }
            }
            if ($name == '') {
                $row['display_name'] = _t('Unknown');
            } elseif ($version == '') {
                $row['display_name'] = $name;
            } else {
                $row['display_name'] = $name . ' / ' . $version;
            }
            // 转换 IP 以便前端直接使用
            $row['ip_display'] = $this->long2ip($row['ip']);
        }
        /*
         * 这里既不转义也不解码，原样交给前端。
         *
         * 不转义：渲染方（page/console.php）已经逐字段 createTextNode 转过一遍，
         * 服务端再转一次，页面上就会显示出 &#039; 这类字面量而不是引号本身。
         *
         * 不解码：以前这里对整个 $list 做了一遍 urlDecode，有两个毛病 ——
         *   1) 前端对 url 还会再 decodeURIComponent 一次，等于解码两遍，
         *      含 %2520 的地址会被还原成一个根本不存在的 URL；
         *   2) 它把 path 也一起解码了，而 path 同时是「按路径筛选」的取值，
         *      回传给服务端后要跟库里的原始值比对 —— 库里存的是编码过的，
         *      解码过的自然就对不上，含 %20 的路径永远筛不出东西。
         * 解码只关乎显示，交给渲染层按字段决定，服务端别一刀切。
         */
        $rows = (int)$this->db->fetchAll($qcount)[0]['count'];

        $filterArr = ['filter' => $filter];
        if ($filter !== 'all') {
            $filterArr[$filter] = $filterValue;
        }
        $pageObj = new Page($this->config->pageSize, $rows, $page, 10, array_merge($filterArr, [
            'panel' => Plugin::$panel,
            'action' => 'logs',
            'type' => $type,
        ]));

        // 统计库与内容库可能不是同一个库，无法 JOIN，改为两次查询后在 PHP 中合并
        $counts = $this->fetchContentCounts();
        $meta = $this->fetchContentMeta(array_column($counts, 'cid'));
        $cidList = [];
        foreach ($counts as $item) {
            $info = $meta[$item['cid']] ?? null;
            // 对应原来的 INNER JOIN 语义：已删除的内容不出现在筛选下拉框里
            if ($info === null || $info['type'] !== 'post') {
                continue;
            }
            $cidList[] = [
                'cid' => $item['cid'],
                'count' => $item['count'],
                'title' => $info['title'],
            ];
        }

        return [
            'list'    => $list,
            'rows'    => $rows,
            'page'    => $pageObj->show(),
            'cidList' => $cidList,
        ];
    }

    /**
     * 初始化 Redis 连接
     *
     * @access protected
     * @return void
     */
    protected function initRedis(): void
    {
        if (!extension_loaded('redis')) {
            return;
        }

        if (!isset($this->config->redisCache) || $this->config->redisCache != '1') {
            return;
        }

        /*
         * 上次连接失败后的熔断窗口内直接降级，不再尝试。
         * Redis 不可达时连接会一直等到超时，而本类是在每个前台请求里构造的，
         * 没有这道闸门的话每个访客都要白等一次。
         */
        if (Health::tripped(Health::REDIS)) {
            return;
        }

        try {
            # 连接超时、读写超时统一在 Health::connect() 里设置
            $this->redis = Health::connect(
                $this->config->redisHost ?: '127.0.0.1',
                (int)($this->config->redisPort ?: 6379),
                (string)($this->config->redisAuth ?? '')
            );
            # 连上了就立刻解除熔断，Redis 恢复后不用等窗口自然过期
            Health::clear(Health::REDIS);
        } catch (\Throwable $e) {
            Health::trip(Health::REDIS);
            $this->redis = null;
        }
    }

    /**
     * 从 Redis 获取缓存数据
     *
     * @access protected
     * @param string $key 缓存键名
     * @return array|null 缓存数据，未命中返回 null
     */
    protected function getCache(string $key): ?array
    {
        if ($this->redis === null) {
            return null;
        }

        try {
            $data = $this->redis->get(Cache::key($key));
            if ($data === false) {
                return null;
            }
            $decoded = json_decode($data, true);
            return is_array($decoded) ? $decoded : null;
        } catch (\Throwable $e) {
            return null;
        }
    }

    /**
     * 写入 Redis 缓存
     * 默认 TTL 为距明天 0 点的剩余秒数，可显式指定（历史日期的统计永不变化，可以长期缓存）
     *
     * @access protected
     * @param string $key 缓存键名
     * @param array $data 缓存数据
     * @param int|null $ttl 自定义存活秒数
     * @return void
     */
    protected function setCache(string $key, array $data, ?int $ttl = null): void
    {
        if ($this->redis === null) {
            return;
        }

        try {
            $ttl = $ttl ?? (86400 - (time() - strtotime(date("Y-m-d 00:00:00"))));
            $this->redis->setex(
                Cache::key($key),
                max($ttl, 1),
                json_encode($data, JSON_UNESCAPED_UNICODE)
            );
        } catch (\Throwable $e) {
            // 写入失败静默忽略，不影响主流程
        }
    }

    /**
     * 生成来源统计数据，提供给页面渲染使用
     * 优先从 Redis 缓存读取，缓存未命中时查询数据库并回填缓存
     *
     * @access protected
     * @return void
     */
    protected function parseReferer()
    {
        /*
         * 下面两段都只做 URL 解码、不做 HTML 转义，理由同 getLogsData()：
         * 这些值只经 JSON 接口出去，console.php 渲染时已经逐字段转义过。
         * 服务端再转一次，来源里带引号的 URL 就会显示成 &#039; 这种字面量 ——
         * 扫描器把 SQL 注入探测串塞进 Referer 头时尤其明显。
         */

        $limit = $this->config->pageSize;

        /*
         * 只统计「看起来是来源地址」的记录，理由见 plausibleUrl()。
         * 过滤必须放在 SQL 里而不是取回来再筛：Top N 是数据库排序取前几名，
         * 而垃圾来源往往被扫描器刷出很高的次数、正好占着前排。
         */
        $urlOk = $this->urlLikeCondition('entrypoint');

        // ── 来源 URL ──
        $this->referer['url'] = $this->cachedAggregate(
            'referer:url',
            fn(): array => $this->urlDecode($this->db->fetchAll(
                $this->db->select('DISTINCT entrypoint AS value, COUNT(1) as count')
                    ->from('table.access')->where("entrypoint <> '' AND {$urlOk}")->group('entrypoint')
                    ->order('count', Db::SORT_DESC)->limit($limit)
            )),
            self::LIST_FRESH_TTL
        )['data'];

        // ── 来源域名 ──
        $this->referer['domain'] = $this->cachedAggregate(
            'referer:domain',
            fn(): array => $this->urlDecode($this->db->fetchAll(
                $this->db->select('DISTINCT entrypoint_domain AS value, COUNT(1) as count')
                    ->from('table.access')->where("entrypoint_domain <> ''")->group('entrypoint_domain')
                    ->order('count', Db::SORT_DESC)->limit($limit)
            )),
            self::LIST_FRESH_TTL
        )['data'];
    }

    /**
     * 生成用于图标的 JSON 数据
     *
     * @access protected
     * @return string
     */
    protected function makeChartJson(): string
    {
        $chart = [];
        foreach ($this->overview as $type => $val) {
            $val['sub_title'] = 'Generate By AccessPlugin';
            if ($type == 'today' || $type == 'yesterday') {
                $val['xAxis'] = range(0, count($val['ip']['detail']));
                $val['title'] = _t('%s 统计', $val['time']);
            } elseif ($type == 'month') {
                $val['xAxis'] = range(1, count($val['ip']['detail']));
                $val['title'] = _t('%s 月统计', $val['time']);
            }
            $chart[$type] = $val;
        }
        return json_encode($chart, JSON_UNESCAPED_UNICODE);
    }

    /**
     * 生成总览数据，提供给页面渲染使用
     * "昨日"、"总计"、"当月" 优先从 Redis 缓存读取；"今日" 始终实时查询
     *
     * @access protected
     * @return void
     */
    protected function parseOverview(): void
    {
        // ── 今日数据：始终实时查询，保证准确性 ──
        $this->overview['today'] = $this->queryDayOverview(date("Y-m-d"));

        // ── 昨日数据：缓存键包含日期，跨天自动失效 ──
        $yesterdayDate = date("Y-m-d", strtotime('-1 day'));
        $yesterdayCacheKey = 'overview:yesterday:' . $yesterdayDate;
        $cached = $this->getCache($yesterdayCacheKey);
        if ($cached !== null) {
            $this->overview['yesterday'] = $cached;
        } else {
            $this->overview['yesterday'] = $this->queryDayOverview($yesterdayDate);
            $this->setCache($yesterdayCacheKey, $this->overview['yesterday']);
        }

        // ── 当月数据：按 TTL 缓存 ──
        $monthCacheKey = 'overview:month:' . date('Y-m');
        $cached = $this->getCache($monthCacheKey);
        if ($cached !== null) {
            $this->overview['month'] = $cached;
        } else {
            $this->overview['month'] = $this->queryMonthOverview();
            $this->setCache($monthCacheKey, $this->overview['month']);
        }

        // ── 总计数据：陈旧优先，过期后台重算（见 cachedAggregate()） ──
        # 这条路是一次性返回全部的老接口，没法回「还没算好」，所以不允许延迟
        $this->overview['total'] = $this->cachedTotalOverview()['data'];

        # 输出用于图表的Json
        $this->overview['chart_data'] = $this->makeChartJson();
    }

    /**
     * 查询某一天的访问概览（按小时维度 + 当日汇总）
     *
     * @access protected
     * @param string $date 日期，格式 Y-m-d
     * @return array
     */
    protected function queryDayOverview(string $date): array
    {
        $result = ['time' => $date];
        $dayStart = strtotime("{$date} 00:00:00");
        $dayEnd   = strtotime("{$date} 23:59:59");

        # 按小时统计明细
        for ($hour = 0; $hour < 24; $hour++) {
            $start = strtotime("{$date} {$hour}:00:00");
            $end   = strtotime("{$date} {$hour}:59:59");

            $subQuery = $this->db->select('DISTINCT ip')->from('table.access')
                ->where("time >= ? AND time <= ?", $start, $end);
            if (method_exists($subQuery, 'prepare')) {
                $subQuery = $subQuery->prepare($subQuery);
            }
            $result['ip']['detail'][$hour] = (int)$this->db->fetchAll($this->db->select('COUNT(1) AS count')
                ->from('(' . $subQuery . ') AS tmp'))[0]['count'];

            $subQuery = $this->db->select('DISTINCT ip,ua')->from('table.access')
                ->where("time >= ? AND time <= ?", $start, $end);
            if (method_exists($subQuery, 'prepare')) {
                $subQuery = $subQuery->prepare($subQuery);
            }
            $result['uv']['detail'][$hour] = (int)$this->db->fetchAll($this->db->select('COUNT(1) AS count')
                ->from('(' . $subQuery . ') AS tmp'))[0]['count'];

            $result['pv']['detail'][$hour] = (int)$this->db->fetchAll($this->db->select('COUNT(1) AS count')
                ->from('table.access')->where('time >= ? AND time <= ?', $start, $end))[0]['count'];
        }

        # 当日汇总
        $subQuery = $this->db->select('DISTINCT ip')->from('table.access')
            ->where("time >= ? AND time <= ?", $dayStart, $dayEnd);
        if (method_exists($subQuery, 'prepare')) {
            $subQuery = $subQuery->prepare($subQuery);
        }
        $result['ip']['count'] = (int)$this->db->fetchAll($this->db->select('COUNT(1) AS count')
            ->from('(' . $subQuery . ') AS tmp'))[0]['count'];

        $subQuery = $this->db->select('DISTINCT ip,ua')->from('table.access')
            ->where("time >= ? AND time <= ?", $dayStart, $dayEnd);
        if (method_exists($subQuery, 'prepare')) {
            $subQuery = $subQuery->prepare($subQuery);
        }
        $result['uv']['count'] = (int)$this->db->fetchAll($this->db->select('COUNT(1) AS count')
            ->from('(' . $subQuery . ') AS tmp'))[0]['count'];

        $result['pv']['count'] = (int)$this->db->fetchAll($this->db->select('COUNT(1) AS count')
            ->from('table.access')
            ->where("time >= ? AND time <= ?", $dayStart, $dayEnd)
        )[0]['count'];

        return $result;
    }

    /**
     * 查询当月访问概览（按天维度）
     *
     * @access protected
     * @return array
     */
    protected function queryMonthOverview(): array
    {
        $year  = date('Y');
        $month = date('m');
        // 用 date('t') 而不是 cal_days_in_month()，后者需要 calendar 扩展，结果完全一致
        $monthDays = (int)date('t', mktime(0, 0, 0, (int)$month, 1, (int)$year));
        $result = ['time' => $month];

        for ($day = 1; $day <= $monthDays; $day++) {
            $counts = $this->queryDayCounts(sprintf('%s-%s-%02d', $year, $month, $day));
            $result['ip']['detail'][$day - 1] = $counts['ip'];
            $result['uv']['detail'][$day - 1] = $counts['uv'];
            $result['pv']['detail'][$day - 1] = $counts['pv'];
        }

        return $result;
    }

    /**
     * 查询某一天的汇总（只有 ip / uv / pv 三个数，不含小时明细）
     *
     * 这是概览里可以独立缓存的最小单元：历史日期算过一次就不会再变，
     * 月图表按天拼装，因此某一天算不完也能在下一次请求继续。
     *
     * @access protected
     * @param string $date 日期，格式 Y-m-d
     * @return array {ip: int, uv: int, pv: int}
     * @throws DbException
     */
    protected function queryDayCounts(string $date): array
    {
        $start = strtotime("{$date} 00:00:00");
        $end   = strtotime("{$date} 23:59:59");

        $subQuery = $this->db->select('DISTINCT ip')->from('table.access')
            ->where('time >= ? AND time <= ?', $start, $end);
        if (method_exists($subQuery, 'prepare')) {
            $subQuery = $subQuery->prepare($subQuery);
        }
        $ip = (int)$this->db->fetchAll($this->db->select('COUNT(1) AS count')
            ->from('(' . $subQuery . ') AS tmp'))[0]['count'];

        $subQuery = $this->db->select('DISTINCT ip,ua')->from('table.access')
            ->where('time >= ? AND time <= ?', $start, $end);
        if (method_exists($subQuery, 'prepare')) {
            $subQuery = $subQuery->prepare($subQuery);
        }
        $uv = (int)$this->db->fetchAll($this->db->select('COUNT(1) AS count')
            ->from('(' . $subQuery . ') AS tmp'))[0]['count'];

        $pv = (int)$this->db->fetchAll($this->db->select('COUNT(1) AS count')
            ->from('table.access')->where('time >= ? AND time <= ?', $start, $end))[0]['count'];

        return ['ip' => $ip, 'uv' => $uv, 'pv' => $pv];
    }

    /**
     * 查询总计访问概览
     *
     * @access protected
     * @return array
     */
    protected function queryTotalOverview(): array
    {
        $result = [];

        $result['ip'] = (int)$this->db->fetchAll($this->db->select('COUNT(1) AS count')
            ->from('(' . $this->db->select('DISTINCT ip')->from('table.access') . ') AS tmp'))[0]['count'];
        $result['uv'] = (int)$this->db->fetchAll($this->db->select('COUNT(1) AS count')
            ->from('(' . $this->db->select('DISTINCT ip,ua')->from('table.access') . ') AS tmp'))[0]['count'];
        $result['pv'] = (int)$this->db->fetchAll($this->db->select('COUNT(1) AS count')
            ->from('table.access'))[0]['count'];

        return $result;
    }

    /**
     * 编码数组中的字符串为 HTML 实体
     *
     * 注意：**不要拿它处理 JSON 接口的返回值**。控制台是前端渲染的，
     * page/console.php 里每个字段都过了 createTextNode 转义；这里再转一遍
     * 就是转两遍，页面上会显示出 &#039; &quot; 这类字面量而不是引号本身。
     * 转义属于渲染那一层，接口只负责给数据。
     * 留着它是给将来可能出现的服务端渲染路径用的。
     *
     * @param array|string $data 将要被编码的数据
     * @param bool $valuesOnly 是否只编码数组数值
     * @param string $charset 字符串编码方式
     * @return array|string 编码后的数据
     */
    protected function htmlEncode($data, bool $valuesOnly = true, string $charset = 'UTF-8')
    {
        if (is_array($data)) {
            $d = [];
            foreach ($data as $key => $value) {
                if (!$valuesOnly) {
                    $key = $this->htmlEncode($key, $valuesOnly, $charset);
                }
                $d[$key] = $this->htmlEncode($value, $valuesOnly, $charset);
            }
            $data = $d;
        } elseif (is_string($data)) {
            $data = htmlspecialchars($data, ENT_QUOTES | ENT_SUBSTITUTE, $charset);
        }
        return $data;
    }

    /**
     * 解析所有 URL 编码过的字符
     *
     * @param array|string $data 将要被解码的数据
     * @param bool $valuesOnly 是否只解码数组数值
     * @return array|string 解码后的数据
     */
    protected function urlDecode($data, bool $valuesOnly = true)
    {
        if (is_array($data)) {
            $d = [];
            foreach ($data as $key => $value) {
                if (!$valuesOnly) {
                    $key = $this->urlDecode($key, $valuesOnly);
                }
                $d[$key] = $this->urlDecode($value, $valuesOnly);
            }
            $data = $d;
        } elseif (is_string($data)) {
            /*
             * rawurldecode 而不是 urldecode：后者会把 + 当成空格。
             * 那是 application/x-www-form-urlencoded 的规矩，只在查询串里成立；
             * 路径里的 + 就是一个普通加号，/c++tutorial 会被解成 /c  tutorial。
             * 代价是查询串里真正表示空格的 + 会原样显示 —— 显示成加号只是不够好看，
             * 把路径改错则是把地址变成了另一个地址，两者不对等。
             * 顺带和前端的 decodeURIComponent 对齐了，它同样不动 +。
             */
            $data = rawurldecode($data);
        }
        return $data;
    }

    /**
     * 判断是否是管理员登录状态
     *
     * @access public
     * @return bool
     */
    public function isAdmin(): bool
    {
        $hasLogin = User::alloc()->hasLogin();
        if (!$hasLogin) {
            return false;
        }
        return User::alloc()->pass('administrator', true);
    }

    /**
     * 删除记录
     *
     * @access public
     * @param array $ids
     * @return void
     */
    public function deleteLogs(array $ids)
    {
        // PostgreSQL 对整型列不接受非数字字面量，这里统一转成整型
        $ids = array_values(array_filter(array_map('intval', $ids)));
        if (empty($ids)) {
            return;
        }

        /*
         * 删之前先把这些记录的日期取出来：删完就查不到了，
         * 而统计缓存必须按日期失效，否则后台还会一直显示删除前的数字。
         */
        $dates = [];
        if ($this->redis !== null) {
            try {
                $rows = $this->db->fetchAll(
                    $this->db->select('time')->from('table.access')
                        ->where('id IN (' . implode(',', $ids) . ')')
                );
                $dates = Cache::datesOf($rows);
            } catch (\Throwable $e) {
            }
        }

        foreach ($ids as $id) {
            $this->db->query($this->db->delete('table.access')->where('id = ?', $id));
        }

        if ($this->redis !== null) {
            Cache::invalidate($this->redis, $dates);
        }
    }

    /**
     * 这个值看起来像不像一个来源地址
     *
     * Referer 头完全由对方控制，扫描器每天都在往里塞各种探测串
     * （`(select(0)from(select(sleep(15)))v)`、`if(now()=sysdate(),sleep(15),0)` 之类）。
     * 它们会被当成一次「来源」记下来，然后堂而皇之地出现在来源 Top 20 里。
     *
     * 这里用白名单而不是黑名单，理由是黑名单在这件事上必然失败：
     * payload 的花样是无穷的，而且拿 sleep/select/union 这类关键词去匹配，
     * 迟早会误伤查询串里带这些词的正常地址。
     * 真正该问的从来不是「它像不像攻击」，而是「它是不是一个来源地址」——
     * 后者有明确定义：带 scheme 和主机名的绝对 http(s) URL，中间没有空白字符。
     * 上面那两个 payload 连 http:// 都没有，第一关就过不去。
     *
     * @access public
     * @param string|null $value
     * @return string 合格返回原值，不合格返回空串
     */
    public static function plausibleUrl(?string $value): string
    {
        $value = trim((string)$value);
        if ($value === '') {
            return '';
        }

        # 合法 URL 里不会有空白和控制字符；有就说明这是被塞进来的东西
        if (preg_match('/[\s\x00-\x1F\x7F]/', $value) === 1) {
            return '';
        }

        if (preg_match('~^https?://~i', $value) !== 1) {
            return '';
        }

        # 有 scheme 还不够，还得真解析得出主机名（挡住 http:// 后面空着的情况）
        $host = parse_url($value, PHP_URL_HOST);
        return ($host === null || $host === false || $host === '') ? '' : $value;
    }

    /**
     * plausibleUrl() 的 SQL 版本，用来过滤已经存进库里的旧数据
     *
     * 写入侧从此不会再收下这些值，但库里已经躺着的那些还得靠这一条挡住。
     * 两处是同一条规则的两种实现，改一个记得改另一个 ——
     * 之所以要有 SQL 版，是因为 Top N 是在数据库里排序取前几名的：
     * 垃圾来源往往被扫描器刷出很高的次数，正好占着前排，
     * 取回 PHP 再过滤的话，取到手的二十条可能被筛得只剩几条。
     *
     * @access protected
     * @param string $column
     * @return string
     */
    protected function urlLikeCondition(string $column): string
    {
        # LIKE 里的 _ 是「任意单个字符」，用它要求 scheme 后面至少还有点东西，
        # 免得放过 'http://' 这种光有协议头、没有主机名的值
        return "({$column} LIKE 'http://_%' OR {$column} LIKE 'https://_%') AND {$column} NOT LIKE '% %'";
    }

    /**
     * 获取首次进入网站时的来源
     *
     * @access public
     * @return string
     */
    public function getEntryPoint(): string
    {
        $entrypoint = $this->request->getReferer();
        if ($entrypoint == null) {
            $entrypoint = Cookie::get('__typecho_access_entrypoint') ?: '';
        }

        /*
         * 先过一遍白名单再谈别的。
         * 这一步同时挡住了一个更烦人的后果：下面会把 entrypoint 写进 cookie，
         * 不拦的话，一个扫描器塞进来的 payload 会被它自己的后续每一次请求
         * 反复带回来，一条垃圾变成一串垃圾。
         */
        $entrypoint = self::plausibleUrl($entrypoint);

        /*
         * 规范化要排在下面那个「是不是站内来源」的比较之前。
         *
         * 主机名不区分大小写，而这里原来是逐字比较：来路写成 HTTPS://YOURSITE.COM/x 时
         * 跟 siteUrl 的主机名对不上，于是**自己站内的跳转被当成外部来源记了下来**，
         * 混进来源统计里，还会被写进 cookie 一路带下去。
         * 顺手也让写进 cookie 的值是规范化过的，后续请求带回来的就不会再有大小写变体。
         */
        $entrypoint = Queue::normalizeUrl($entrypoint);

        $siteHost = strtolower((string)parse_url(Helper::options()->siteUrl, PHP_URL_HOST));
        if (strtolower((string)parse_url($entrypoint, PHP_URL_HOST)) === $siteHost) {
            $entrypoint = '';
        }
        if ($entrypoint != null) {
            Cookie::set('__typecho_access_entrypoint', $entrypoint);
        }
        return $entrypoint;
    }

    /**
     * IPv6 地址转长字符串
     *
     * @param string $ipv6
     * @return string
     */
    public function ip62long(string $ipv6): string
    {
        $ip_n = inet_pton($ipv6);
        $bits = 15;
        $ipv6long = '';
        while ($bits >= 0) {
            $bin = sprintf("%08b", (ord($ip_n[$bits])));
            $ipv6long = $bin . $ipv6long;
            $bits--;
        }
        return gmp_strval(gmp_init($ipv6long, 2), 10);
    }

    /**
     * 长字符还原 IPv6
     *
     * @param string $ipv6long
     * @return false|string
     */
    public function long2ip6(string $ipv6long)
    {
        $bin = gmp_strval(gmp_init($ipv6long, 10), 2);
        if (strlen($bin) < 128) {
            $pad = 128 - strlen($bin);
            for ($i = 1; $i <= $pad; $i++) {
                $bin = "0" . $bin;
            }
        }
        $ipv6 = '';
        $bits = 0;
        while ($bits <= 7) {
            $bin_part = substr($bin, ($bits * 16), 16);
            $ipv6 .= dechex(bindec($bin_part)) . ":";
            $bits++;
        }
        return inet_ntop(inet_pton(substr($ipv6, 0, -1)));
    }

    /**
     * 记录当前访问（管理员登录不会记录）
     *
     * @access public
     * @return void
     */
    public function writeLogs($archive = null, $url = null, $content_id = null, $meta_id = null)
    {
        if ($this->isAdmin()) {
            return;
        }
        if ($url == null) {
            $url = $this->request->getServer('REQUEST_URI');
        }
        $ip = $this->request->getIp();
        if ($ip == null) {
            $ip = '0.0.0.0';
        }
        // 判断 IP 类型
        if (filter_var($ip, FILTER_VALIDATE_IP, FILTER_FLAG_IPV4)) {
            $ip = bindec(decbin(ip2long($ip)));
        } else if (filter_var($ip, FILTER_VALIDATE_IP, FILTER_FLAG_IPV6)) {
            $ip = $this->ip62long($ip);
        }

        $entrypoint = $this->getEntryPoint();
        $referer = $this->request->getReferer();
        if (empty($referer)) {
            $referer = '';
        }
        $time = Helper::options()->gmtTime + (Helper::options()->timezone - Helper::options()->serverTimezone);

        if ($archive != null) {
            $parsedArchive = $this->parseArchive($archive);
            $content_id = $parsedArchive['content_id'];
            $meta_id = $parsedArchive['meta_id'];
        } else {
            $content_id = is_numeric($content_id) ? $content_id : null;
            $meta_id = is_numeric($meta_id) ? $meta_id : null;
        }

        $rows = [
            'ua' => $this->ua->getUA(),
            'browser_id' => $this->ua->getBrowserID(),
            'browser_version' => $this->ua->getBrowserVersion(),
            'os_id' => $this->ua->getOSID(),
            'os_version' => $this->ua->getOSVersion(),
            'url' => $url,
            'path' => parse_url($url, PHP_URL_PATH),
            'query_string' => parse_url($url, PHP_URL_QUERY),
            'ip' => $ip,
            'referer' => $referer,
            'referer_domain' => parse_url($referer, PHP_URL_HOST),
            'entrypoint' => $entrypoint,
            'entrypoint_domain' => parse_url($entrypoint, PHP_URL_HOST),
            'time' => $time,
            'content_id' => $content_id,
            'meta_id' => $meta_id,
            'robot' => $this->ua->isRobot() ? 1 : 0,
            'robot_id' => $this->ua->getRobotID(),
            'robot_version' => $this->ua->getRobotVersion(),
            # 在这里生成、随消息一起入队；重试时沿用同一个值，落库才是幂等的。
            # 放到落库时再生成的话，每次重试都是一条「新」记录，唯一索引形同虚设
            'event_id' => Queue::newEventId(),
        ];

        /*
         * 所有字段都来自访客可控的请求头和查询串，先按表结构裁到合法范围。
         * 直写这条路也必须过一遍：Redis 不可用时每次访问都走它，
         * 只在入队时截断的话，恰恰是最脆弱的降级路径没有防护。
         */
        $rows = Queue::normalize($rows);

        /*
         * 优先入队，攒批后统一落库；Redis 不可用或入队失败时退回直写。
         *
         * 但缺 event_id 唯一索引时**必须**走直写：队列做的是「至少一次」投递，
         * 靠唯一索引把重复的那次挡掉才变成「恰好一次」的结果。索引不在的话
         * （建索引权限不足、存量数据已有重复值），进程被杀后 processing 重放、
         * 或者命令行重跑一次，同一条访问日志就会被重复计入统计 —— 而且毫无迹象，
         * 数字只是慢慢变得不对。以前这种情况只在后台留一句黄字就放行了。
         * 直写慢一些，但慢是看得见的，统计悄悄变错不是。
         */
        if (Queue::isEnabled($this->redis, $this->config)
            && !$this->schemaDegraded()
            && Queue::push($this->redis, $rows)
        ) {
            $this->scheduleFlush();
            return;
        }

        try {
            $this->db->query($this->db->insert('table.access')->rows($rows));
        } catch (\Throwable $e) {
            /*
             * 异常仍然不能往外抛 —— 这条路跑在页面渲染里，统计写不进去不该让访客看到白屏。
             * 但也不能像原来那样完全无声：缺 event_id 唯一索引时队列会被强制降级为直写
             * （见 writeLogs() 上面的说明），此时**直写是唯一的写入路径**，
             * 它一直失败而没有任何痕迹的话，表现就是「统计突然不涨了」，无从查起。
             * 至少写一条服务器错误日志，让 tail 一眼能看见。
             */
            error_log(sprintf(
                '[Access] 直写统计表失败（本次访问未被记录）：%s',
                $e->getMessage()
            ));
        }
    }

    /**
     * 这个统计库缺不缺幂等保护（event_id 唯一索引）
     *
     * 缺了就不能走写入队列，见 writeLogs()。判定结果按请求缓存：
     * 一次请求可能写多条日志，而降级标记在一次请求内不会变。
     *
     * 注意标记存在**主库**的 options 里，不是统计库 —— 配了独立统计库时两者不是一回事，
     * 所以这里不传 $this->db（那是统计库），让 Schema 自己去取主库。
     *
     * @access protected
     * @return bool
     */
    protected function schemaDegraded(): bool
    {
        if ($this->degraded === null) {
            try {
                $this->degraded = Schema::isDegraded(
                    Migrate::fingerprint(Database::settings($this->config))
                );
            } catch (\Throwable $e) {
                # 判定不了就别拦着写入，理由同 Schema::isDegraded() 里的说明
                $this->degraded = false;
            }
        }

        return $this->degraded;
    }

    /**
     * 匿名埋点接口的频率闸门
     *
     * /access/track/flag.gif 无需登录即可调用，不限速的话一个脚本就能
     * 无限灌入日志，既污染统计也放大写入压力。
     * 计数放在 Redis 里；没有 Redis 时无处计数，那就不限（宁可不拦，也不误伤）。
     *
     * @access public
     * @return bool 允许记录返回 true
     */
    public function allowTracking(): bool
    {
        if ($this->redis === null) {
            return true;
        }

        try {
            $ip = $this->request->getIp() ?: '0.0.0.0';
            # 按分钟分桶，键名自带时间戳，过期即天然滚动
            $key = Cache::key('rate:' . date('YmdHi') . ':' . md5($ip));

            /*
             * INCR 和 EXPIRE 必须在一条 Lua 里。
             *
             * 分成两次往返时，「INCR 成功、EXPIRE 没成功」这个中间态会留下一个
             * **永不过期**的计数键：EXPIRE 只在 hits === 1 时发，错过这一次就再没有
             * 第二次机会。连接抖一下、或者恰好在两条命令之间断开就会发生。
             * 单个键很小，但泄漏是按「分钟 × IP」累积的，跑得久了谁也想不起来它是什么。
             *
             * 顺带少一次往返 —— 这段代码在每一次匿名埋点请求上都要跑。
             */
            $script = <<<'LUA'
local hits = redis.call("incr", KEYS[1])
if hits == 1 then
    redis.call("expire", KEYS[1], ARGV[1])
end
return hits
LUA;
            $hits = (int)$this->redis->eval($script, [$key, self::TRACK_RATE_WINDOW], 1);

            /*
             * 脚本没跑成时 eval 返回 false，转成 int 是 0 —— 那不是「这个 IP 一次都没来过」，
             * 而是「这次没数着」。当成 0 会让限流悄悄失效且毫无征兆，所以显式判掉，
             * 走和「没有 Redis」一样的放行分支：宁可不拦，也不误伤。
             */
            if ($hits < 1) {
                return true;
            }

            return $hits <= self::TRACK_RATE_LIMIT;
        } catch (\Throwable $e) {
            // 限流自己出问题不该把正常统计一起拦下来
            return true;
        }
    }

    /**
     * 达到阈值时安排一次刷库
     *
     * 刷库推迟到响应发出之后执行，承担这次刷库的访客感知不到延迟。
     * 注意不能在这里直接调用 fastcgi_finish_request：writeLogs 是在页面渲染前
     * 由 Widget\Archive::beforeRender 调用的，此时提前结束响应会让页面内容丢失，
     * 所以统一放到 shutdown 阶段。
     *
     * @access protected
     * @return void
     */
    protected function scheduleFlush(): void
    {
        if ($this->flushScheduled || $this->redis === null) {
            return;
        }

        $size = (int)($this->config->queueFlushSize ?? 0);
        $interval = (int)($this->config->queueFlushInterval ?? 0);
        $size = $size > 0 ? $size : 100;
        $interval = $interval > 0 ? $interval : 60;

        if (!Queue::isDue($this->redis, $size, $interval)) {
            return;
        }

        $this->flushScheduled = true;
        $redis = $this->redis;
        $db = $this->db;

        register_shutdown_function(static function () use ($redis, $db) {
            // 页面此时已经输出完毕，先把响应交给访客再慢慢写库
            if (PHP_SAPI === 'fpm-fcgi' && function_exists('fastcgi_finish_request')) {
                @fastcgi_finish_request();
            }
            @set_time_limit(0);

            /*
             * 锁在这里才抢，而不是在上面的调度阶段。
             * scheduleFlush() 跑在 beforeRender 里，离真正刷库隔着整个页面渲染和输出，
             * 提前抢锁等于把渲染时间也算进锁的存活期 —— 慢页面上锁很可能在刷到一半时过期，
             * 于是队列上同时出现两个消费者。
             * 代价只是并发请求会多做几次 SET NX，抢不到的直接收工。
             */
            $token = Queue::acquireLock($redis);
            if ($token === null) {
                // 已经有别的请求在刷了
                return;
            }
            try {
                Queue::flush($redis, $db, 0, null, $token);
            } finally {
                Queue::releaseLock($redis, $token);
            }
        });
    }

    /**
     * 同步刷一次队列，供控制台和命令行使用
     *
     * @access public
     * @return int 写入行数
     */
    public function flushQueue(): int
    {
        if (!Queue::isEnabled($this->redis, $this->config)) {
            return 0;
        }
        $token = Queue::acquireLock($this->redis);
        if ($token === null) {
            return 0;
        }
        try {
            # 这里只关心写入行数；完整的 attempted/invalid/rejected/stopped 见 Queue::flush()
            return Queue::flush($this->redis, $this->db, 0, null, $token)['written'];
        } finally {
            Queue::releaseLock($this->redis, $token);
        }
    }

    /**
     * 尽力把队列刷干净，并如实回报最终状态
     *
     * 给「停用插件」这类一次性场景用：那里需要的不是「刷了一次」，而是
     * 「到底还剩没剩」—— flushQueue() 单次最多 FLUSH_LIMIT 条、抢不到锁就返回 0，
     * 拿它的返回值当作「已经刷完了」是靠不住的。
     *
     * @access public
     * @param float $budget 时间预算（秒）
     * @return array{written:int,pending:?int,dead:int,clean:bool,error:?string}
     *         pending 为剩余积压（null 表示读不到）；dead 为死信队列当前长度；
     *         clean 为 true 才代表「Redis 里确实没有未落库的数据了」
     */
    public function drainQueue(float $budget = 25.0): array
    {
        $out = ['written' => 0, 'pending' => null, 'dead' => 0, 'clean' => false, 'error' => null];

        if (!isset($this->config->redisCache) || $this->config->redisCache != '1') {
            # 压根没启用 Redis，自然不存在积压
            $out['pending'] = 0;
            $out['clean'] = true;
            return $out;
        }

        if ($this->redis === null) {
            # 启用了却连不上：既刷不了也确认不了，绝不能当成「干净」
            $out['error'] = 'Redis 不可用，无法确认队列状态';
            return $out;
        }

        if (!Queue::isEnabled($this->redis, $this->config)) {
            $out['pending'] = Queue::tryLength($this->redis);
            $out['dead'] = Queue::deadLength($this->redis);
            # 写入队列被关掉了，但之前攒下的消息可能还在
            $out['clean'] = $out['pending'] === 0 && $out['dead'] === 0;
            return $out;
        }

        $deadline = microtime(true) + max(1.0, $budget);

        # 别的请求可能正在刷，短暂重试而不是立刻放弃
        $token = null;
        while (microtime(true) < $deadline) {
            $token = Queue::acquireLock($this->redis);
            if ($token !== null) {
                break;
            }
            usleep(200000);
        }
        if ($token === null) {
            $out['pending'] = Queue::tryLength($this->redis);
            $out['dead'] = Queue::deadLength($this->redis);
            $out['error'] = '另一个进程正在刷库，未能取得刷库锁';
            return $out;
        }

        try {
            $drained = Queue::drain($this->redis, $this->db, $token, $deadline);
            $out['written'] = $drained['written'];
            $out['error'] = $drained['error'];
        } finally {
            Queue::releaseLock($this->redis, $token);
        }

        $out['pending'] = Queue::tryLength($this->redis);
        $out['dead'] = Queue::deadLength($this->redis);
        $out['clean'] = $out['error'] === null && $out['pending'] === 0 && $out['dead'] === 0;

        return $out;
    }

    /**
     * 队列积压条数
     *
     * @access public
     * @return int
     */
    public function queueLength(): int
    {
        return $this->redis === null ? 0 : Queue::length($this->redis);
    }

    /**
     * 重新刷数据库，当遇到一些算法变更时可能需要用到
     *
     * @access public
     * @return void
     * @throws PluginException
     */
    public static function rewriteLogs()
    {
        $db = Database::get();
        $rows = $db->fetchAll($db->select()->from('table.access'));
        foreach ($rows as $row) {
            $ua = new UA($row['ua']);
            $row['browser_id'] = $ua->getBrowserID();
            $row['browser_version'] = $ua->getBrowserVersion();
            $row['os_id'] = $ua->getOSID();
            $row['os_version'] = $ua->getOSVersion();
            $row['robot'] = $ua->isRobot() ? 1 : 0;
            $row['robot_id'] = $ua->getRobotID();
            $row['robot_version'] = $ua->getRobotVersion();
            try {
                $db->query($db->update('table.access')->rows($row)->where('id = ?', $row['id']));
            } catch (Db\Exception $e) {
                throw new PluginException(_t('刷新数据库失败：%s。', $e->getMessage()));
            }
        }
    }

    /**
     * 解析archive对象
     *
     * @access public
     * @param $archive
     * @return array
     */
    public function parseArchive($archive): array
    {
        $content_id = null;
        $meta_id = null;
        if ($archive->is('index')) {
            $meta_id = 0;
        } elseif ($archive->is('post') || $archive->is('page')) {
            $content_id = $archive->cid;
        } elseif ($archive->is('tag')) {
            if (is_array($archive->tags) && !empty($archive->tags)) {
                $meta_id = $archive->tags[0]['mid'];
            }
        } elseif ($archive->is('category')) {
            if (is_array($archive->categories) && !empty($archive->categories)) {
                $meta_id = $archive->categories[0]['mid'];
            }
        }

        return [
            'content_id' => $content_id,
            'meta_id' => $meta_id,
        ];
    }

    /**
     * 长整型转 IP 地址
     *
     * @param string $long
     * @return false|string
     */
    public function long2ip($long)
    {
        // 不同数据库返回的类型不一致（PostgreSQL 的 bpchar 还会补空格），先归一化为纯数字字符串
        $long = trim((string)$long);
        if ($long === '' || !ctype_digit($long)) {
            return false;
        }
        // 超过 IPv4 上限（4294967295）的一律按 IPv6 处理，不再依赖字段长度
        if (strlen($long) > 10 || (float)$long > 4294967295.0) {
            return $this->long2ip6($long);
        }
        if ($long < 0 || $long > 4294967295) return false;
        $ip = "";
        for ($i = 3; $i >= 0; $i--) {
            $ip .= (int)($long / pow(256, $i));
            $long -= (int)($long / pow(256, $i)) * pow(256, $i);
            if ($i > 0) $ip .= ".";
        }
        return $ip;
    }
}