web-counter

web-counter 解决的是静态网站的统计难题——GitHub Pages、VitePress、Rspress 等没有后端，无法统计访问数据。只需在你的服务器上部署一个轻量服务，所有静态站点就能拥有不输专业平台的访问分析能力。

快速开始

pip install web-counter                                              # 安装
export COUNTER_SALT="$(openssl rand -hex 16)"                       # 生成密钥
web-counter start                                                   # 启动服务
web-counter createsuperuser                                         # 创建管理员

终端会直接打印前端接入代码，复制到网页中即可。就这么简单。

在线示例

mikigo.site 是 web-counter 在生产环境中的实际应用。页面底部展示了全站访问统计，每篇文章底部有阅读量，排行榜页面展示了热门内容。

<!-- mikigo.site 页脚的计数器代码 -->
<span style="display:none" class="counter-container" data-counter-style="badge">
  本站访问量 <span data-pv-site></span> 次 ·
  今日访问量 <span data-pv-today></span> 次 ·
  访客 <span data-uv-today></span> 人
</span>

核心特性

实时统计指标

热门排行榜

<ol data-pv-top="10"></ol> 一行代码嵌入热门文章排行。文章标题自动采集，排除规则支持 * 通配符，Dashboard 可视化配置。

curl https://你的域名/api/top?limit=10
# → [{"path":"/blog/hello","title":"Redis 入门指南","count":123}, ...]

统计看板 Dashboard

登录即用的管理后台，包含实时统计卡片、30 天趋势图（Chart.js）、排行榜管理、数据重置和起始值配置。

隐私设计

• 不存储 IP、不设追踪 Cookie、不做浏览器指纹
• 访客唯一性 = SHA256(IP + salt)，salt 仅部署者持有
• 换 salt 后历史 UV 清零，建议一次设定不再更改

前端接入

在页面任意位置插入声明式标签，counter.js 自动填充数据：

<script async src="/counter.js"></script>

<span style="display:none" class="counter-container" data-counter-style="badge">
  本站访问量 <span data-pv-site></span> 次 ·
  访客 <span data-uv-site></span> 人 ·
  今日 <span data-pv-today></span> 次 ·
  访客 <span data-uv-today></span> 人
</span>

计数器初始隐藏（display:none），数据加载成功后自动显示；后端不可用时完全无感。

数据属性

SPA 客户端路由

VitePress、Rspress、Next.js 等框架的客户端路由切换不会整页刷新。v0.2.0 起内置 MutationObserver，自动检测 DOM 变化并刷新计数器，无需任何额外配置。

JSX/TSX 注意事项

在 React/Rspress MDX 中使用 data-pv-page 必须写空字符串：

<span data-pv-page=""></span>       // ✅ 正确
<span data-pv-page></span>          // ❌ 渲染为 data-pv-page="true"

Agent Skill（推荐）

内置 Claude Code Skills，涵盖完整集成和部署流程，自动处理框架特有坑点：

在 Claude Code 对话中包含框架名即可自动加载。

CLI 命令

web-counter start              # 后台启动
web-counter stop               # 优雅停止
web-counter restart            # 重启
web-counter createsuperuser    # 创建管理员
web-counter export-js          # 导出 counter.js

配置

优先级：CLI 参数 > 环境变量 > .env 文件

API

生产部署

Caddy 同域反代（推荐）

mysite.site {
    handle /counter.js { reverse_proxy 127.0.0.1:8000 }
    handle /api/*      { reverse_proxy 127.0.0.1:8000 }
    handle /dashboard  { reverse_proxy 127.0.0.1:8000 }
    root * /var/www/mysite
    file_server
}

systemd 守护

[Service]
Type=simple
Environment="COUNTER_SALT=<密钥>"
Environment="COUNTER_HOST=127.0.0.1"
Environment="COUNTER_PORT=8000"
ExecStart=python3 -m uvicorn web_counter.main:app --host 127.0.0.1 --port 8000
Restart=on-failure

绑 127.0.0.1 确保不直接暴露公网，所有请求经反代进入。

Docker

docker compose up -d

自动部署流水线

push main → GitHub Actions 构建
               ↓
       sync-to-gitee 镜像
               ↓
     服务器 cron git pull
               ↓
       Caddy / Nginx 静态 serve

完整示例见 DEPLOY.md。

数据管理

Dashboard 登录后可进行：

• 数据重置 — 重置今日 / 全部 / 指定页面，全部重置需二次确认
• 起始值 — 为累计 PV/UV 设置偏移量，适用于从其他统计工具迁入
• 排行榜排除 — 支持 * 通配符排除首页、目录页等，持久化存储

License

MIT