web-counter 0.1.0__tar.gz

web_counter-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 mikigo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

web_counter-0.1.0/PKG-INFO

@@ -0,0 +1,181 @@
+Metadata-Version: 2.4
+Name: web-counter
+Version: 0.1.0
+Summary: A self-hosted website visit counter with zero-config frontend integration
+License-Expression: MIT
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: fastapi>=0.100.0
+Requires-Dist: uvicorn[standard]
+Requires-Dist: aiosqlite
+Requires-Dist: bcrypt
+Requires-Dist: python-multipart
+Dynamic: license-file
+
+# web-counter
+
+一个开源、可自托管的网站访问计数服务。一行命令部署，一行 `<script>` 接入，数据完全由你掌控。
+
+## 统计指标
+
+| 指标 | 含义 |
+|------|------|
+| 今日访问量 (PV Today) | 今天所有页面的总访问次数 |
+| 今日访客数 (UV Today) | 今天的独立访客数（IP + salt 哈希去重） |
+| 总访问量 (PV Site) | 建站以来所有页面的累计访问次数 |
+| 总访客数 (UV Site) | 建站以来的累计独立访客数 |
+| 页面阅读量 (PV Page) | 当前页面的累计访问次数 |
+
+## 快速开始
+
+```bash
+# 1. 安装
+pip install web-counter
+
+# 2. 设置 salt（必填，用于哈希访客 IP 保护隐私）
+export COUNTER_SALT="$(openssl rand -hex 16)"
+
+# 3. 启动
+web-counter start
+
+# 4. 创建管理员（用于访问统计看板）
+web-counter createsuperuser
+
+# 5. 将终端输出的代码粘贴到网页 </body> 前，完成接入
+```
+
+## 前端接入
+
+在网页 `</body>` 前添加以下代码：
+
+```html
+<script async src="https://你的域名/counter.js"></script>
+
+<!-- 显示计数（放在 display:none 容器中，JS 加载后自动显示） -->
+<span style="display:none" class="counter-container" data-counter-style="card">
+  本站访问次数 <span data-pv-site></span> 次 ·
+  今日访问量 <span data-pv-today></span> 次 ·
+  今日访客 <span data-uv-today></span> 人 ·
+  总访客 <span data-uv-site></span> 人
+</span>
+```
+
+### 数据属性一览
+
+| 属性 | 含义 |
+|------|------|
+| `data-pv-today` | 今日访问量 |
+| `data-uv-today` | 今日访客数 |
+| `data-pv-site` | 总访问量 |
+| `data-uv-site` | 总访客数 |
+| `data-pv-page` | 当前页面阅读量 |
+| `data-counter-style` | 展示风格：`default` / `badge` / `card` / `bordered` |
+| `data-counter-api` | 手动指定 API 基地址（JS 独立部署时使用） |
+
+### SPA 支持
+
+对于 Vue/React 等单页应用，路由切换不会触发计数。可在路由切换后手动上报：
+
+```js
+fetch('https://你的域名/api/visit', {
+  method: 'POST',
+  headers: { 'Content-Type': 'application/json' },
+  body: JSON.stringify({ path: window.location.pathname })
+})
+```
+
+## CLI 命令
+
+```bash
+web-counter start           # 后台启动服务
+web-counter restart         # 重启服务
+web-counter stop            # 停止服务
+web-counter createsuperuser # 创建管理员账号
+web-counter export-js       # 导出 counter.js 到 stdout
+```
+
+## 配置
+
+优先级：**CLI 参数 > 环境变量 > .env 文件**
+
+| 参数 | 环境变量 | 默认值 | 说明 |
+|------|------|--------|------|
+| `--salt` | `COUNTER_SALT` | 无（必填） | IP 哈希盐值 |
+| `--host` | `COUNTER_HOST` | `0.0.0.0` | 监听地址 |
+| `--port` | `COUNTER_PORT` | `8000` | 监听端口 |
+| `--db-path` | `COUNTER_DB_PATH` | `./data/counter.db` | 数据库路径 |
+| `--pid-file` | `COUNTER_PID_FILE` | `./data/counter.pid` | PID 文件路径 |
+| `--allowed-origins` | `COUNTER_ALLOWED_ORIGINS` | `*` | CORS 允许域名 |
+| `--rate-limit` | `COUNTER_RATE_LIMIT` | `60` | 每 IP 每分钟限流 |
+
+## API 接口
+
+| 方法 | 路径 | 说明 |
+|------|------|------|
+| POST | `/api/visit` | 记录访问 |
+| GET | `/api/count?paths=/page1,/page2` | 批量查询计数 |
+| GET | `/counter.js` | 获取前端 JS 脚本 |
+| GET | `/api/health` | 健康检查 |
+| GET | `/dashboard` | 统计看板（需登录） |
+| POST | `/api/admin/login` | 管理员登录（JSON） |
+| POST | `/api/admin/logout` | 退出登录 |
+| POST | `/api/admin/reset` | 重置数据（需登录） |
+| GET/POST | `/api/admin/offset` | 查看/设置起始值（需登录） |
+
+## 生产环境部署
+
+### 使用反代 (Caddy)
+
+```
+your-domain.com {
+    reverse_proxy localhost:8000
+}
+```
+
+### 使用 systemd
+
+```ini
+[Unit]
+Description=web-counter
+After=network.target
+
+[Service]
+Type=forking
+PIDFile=/opt/web-counter/data/counter.pid
+Environment="COUNTER_SALT=your-random-salt"
+ExecStart=/usr/bin/web-counter start
+ExecStop=/usr/bin/web-counter stop
+ExecReload=/usr/bin/web-counter restart
+Restart=on-failure
+
+[Install]
+WantedBy=multi-user.target
+```
+
+### 使用 Docker
+
+```bash
+docker compose up -d
+```
+
+## 数据管理
+
+后台登录 `/dashboard` 后可进行：
+
+- **数据重置**：支持重置今日/全部/指定页面的访问数据
+- **起始值设置**：为累计指标设置偏移量，适用于从其他统计工具迁移
+
+## 隐私设计
+
+- 不存储原始 IP 地址
+- 不设置 Cookie（后台 session cookie 除外）
+- 不做浏览器指纹
+- 访客唯一性通过 `SHA256(IP + salt)` 标识
+- salt 由部署者自行设置，无法被外部反向破解
+
+> **注意**：salt 设定后不要更换，否则历史访客标识失联，UV 统计将清零重来。
+
+## License
+
+MIT

web_counter-0.1.0/README.md

@@ -0,0 +1,166 @@
+# web-counter
+
+一个开源、可自托管的网站访问计数服务。一行命令部署，一行 `<script>` 接入，数据完全由你掌控。
+
+## 统计指标
+
+| 指标 | 含义 |
+|------|------|
+| 今日访问量 (PV Today) | 今天所有页面的总访问次数 |
+| 今日访客数 (UV Today) | 今天的独立访客数（IP + salt 哈希去重） |
+| 总访问量 (PV Site) | 建站以来所有页面的累计访问次数 |
+| 总访客数 (UV Site) | 建站以来的累计独立访客数 |
+| 页面阅读量 (PV Page) | 当前页面的累计访问次数 |
+
+## 快速开始
+
+```bash
+# 1. 安装
+pip install web-counter
+
+# 2. 设置 salt（必填，用于哈希访客 IP 保护隐私）
+export COUNTER_SALT="$(openssl rand -hex 16)"
+
+# 3. 启动
+web-counter start
+
+# 4. 创建管理员（用于访问统计看板）
+web-counter createsuperuser
+
+# 5. 将终端输出的代码粘贴到网页 </body> 前，完成接入
+```
+
+## 前端接入
+
+在网页 `</body>` 前添加以下代码：
+
+```html
+<script async src="https://你的域名/counter.js"></script>
+
+<!-- 显示计数（放在 display:none 容器中，JS 加载后自动显示） -->
+<span style="display:none" class="counter-container" data-counter-style="card">
+  本站访问次数 <span data-pv-site></span> 次 ·
+  今日访问量 <span data-pv-today></span> 次 ·
+  今日访客 <span data-uv-today></span> 人 ·
+  总访客 <span data-uv-site></span> 人
+</span>
+```
+
+### 数据属性一览
+
+| 属性 | 含义 |
+|------|------|
+| `data-pv-today` | 今日访问量 |
+| `data-uv-today` | 今日访客数 |
+| `data-pv-site` | 总访问量 |
+| `data-uv-site` | 总访客数 |
+| `data-pv-page` | 当前页面阅读量 |
+| `data-counter-style` | 展示风格：`default` / `badge` / `card` / `bordered` |
+| `data-counter-api` | 手动指定 API 基地址（JS 独立部署时使用） |
+
+### SPA 支持
+
+对于 Vue/React 等单页应用，路由切换不会触发计数。可在路由切换后手动上报：
+
+```js
+fetch('https://你的域名/api/visit', {
+  method: 'POST',
+  headers: { 'Content-Type': 'application/json' },
+  body: JSON.stringify({ path: window.location.pathname })
+})
+```
+
+## CLI 命令
+
+```bash
+web-counter start           # 后台启动服务
+web-counter restart         # 重启服务
+web-counter stop            # 停止服务
+web-counter createsuperuser # 创建管理员账号
+web-counter export-js       # 导出 counter.js 到 stdout
+```
+
+## 配置
+
+优先级：**CLI 参数 > 环境变量 > .env 文件**
+
+| 参数 | 环境变量 | 默认值 | 说明 |
+|------|------|--------|------|
+| `--salt` | `COUNTER_SALT` | 无（必填） | IP 哈希盐值 |
+| `--host` | `COUNTER_HOST` | `0.0.0.0` | 监听地址 |
+| `--port` | `COUNTER_PORT` | `8000` | 监听端口 |
+| `--db-path` | `COUNTER_DB_PATH` | `./data/counter.db` | 数据库路径 |
+| `--pid-file` | `COUNTER_PID_FILE` | `./data/counter.pid` | PID 文件路径 |
+| `--allowed-origins` | `COUNTER_ALLOWED_ORIGINS` | `*` | CORS 允许域名 |
+| `--rate-limit` | `COUNTER_RATE_LIMIT` | `60` | 每 IP 每分钟限流 |
+
+## API 接口
+
+| 方法 | 路径 | 说明 |
+|------|------|------|
+| POST | `/api/visit` | 记录访问 |
+| GET | `/api/count?paths=/page1,/page2` | 批量查询计数 |
+| GET | `/counter.js` | 获取前端 JS 脚本 |
+| GET | `/api/health` | 健康检查 |
+| GET | `/dashboard` | 统计看板（需登录） |
+| POST | `/api/admin/login` | 管理员登录（JSON） |
+| POST | `/api/admin/logout` | 退出登录 |
+| POST | `/api/admin/reset` | 重置数据（需登录） |
+| GET/POST | `/api/admin/offset` | 查看/设置起始值（需登录） |
+
+## 生产环境部署
+
+### 使用反代 (Caddy)
+
+```
+your-domain.com {
+    reverse_proxy localhost:8000
+}
+```
+
+### 使用 systemd
+
+```ini
+[Unit]
+Description=web-counter
+After=network.target
+
+[Service]
+Type=forking
+PIDFile=/opt/web-counter/data/counter.pid
+Environment="COUNTER_SALT=your-random-salt"
+ExecStart=/usr/bin/web-counter start
+ExecStop=/usr/bin/web-counter stop
+ExecReload=/usr/bin/web-counter restart
+Restart=on-failure
+
+[Install]
+WantedBy=multi-user.target
+```
+
+### 使用 Docker
+
+```bash
+docker compose up -d
+```
+
+## 数据管理
+
+后台登录 `/dashboard` 后可进行：
+
+- **数据重置**：支持重置今日/全部/指定页面的访问数据
+- **起始值设置**：为累计指标设置偏移量，适用于从其他统计工具迁移
+
+## 隐私设计
+
+- 不存储原始 IP 地址
+- 不设置 Cookie（后台 session cookie 除外）
+- 不做浏览器指纹
+- 访客唯一性通过 `SHA256(IP + salt)` 标识
+- salt 由部署者自行设置，无法被外部反向破解
+
+> **注意**：salt 设定后不要更换，否则历史访客标识失联，UV 统计将清零重来。
+
+## License
+
+MIT

web_counter-0.1.0/pyproject.toml

@@ -0,0 +1,27 @@
+[build-system]
+requires = ["setuptools>=68.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "web-counter"
+version = "0.1.0"
+description = "A self-hosted website visit counter with zero-config frontend integration"
+license = "MIT"
+readme = "README.md"
+requires-python = ">=3.9"
+dependencies = [
+    "fastapi>=0.100.0",
+    "uvicorn[standard]",
+    "aiosqlite",
+    "bcrypt",
+    "python-multipart",
+]
+
+[project.scripts]
+web-counter = "web_counter.cli:main"
+
+[tool.setuptools.packages.find]
+include = ["web_counter*"]
+
+[tool.setuptools.package-data]
+web_counter = ["static/*.js", "templates/*.html"]

web_counter-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

web_counter-0.1.0/web_counter/__init__.py

@@ -0,0 +1 @@
+"""web-counter: A self-hosted website visit counter."""

web_counter-0.1.0/web_counter/auth.py

@@ -0,0 +1,44 @@
+"""Authentication: bcrypt password hashing and session management."""
+
+import secrets
+import time
+
+import bcrypt
+
+# In-memory session store: token -> {"username": str, "created_at": float}
+_sessions: dict[str, dict] = {}
+
+SESSION_MAX_AGE = 86400  # 24 hours
+
+
+def hash_password(password: str) -> str:
+    """Hash a password with bcrypt."""
+    return bcrypt.hashpw(password.encode("utf-8"), bcrypt.gensalt()).decode("utf-8")
+
+
+def verify_password(password: str, password_hash: str) -> bool:
+    """Verify a password against its bcrypt hash."""
+    return bcrypt.checkpw(password.encode("utf-8"), password_hash.encode("utf-8"))
+
+
+def create_session(username: str) -> str:
+    """Create a new session token for the given username."""
+    token = secrets.token_hex(32)
+    _sessions[token] = {"username": username, "created_at": time.time()}
+    return token
+
+
+def validate_session(token: str) -> str | None:
+    """Validate a session token. Returns username if valid, None otherwise."""
+    if token not in _sessions:
+        return None
+    session = _sessions[token]
+    if time.time() - session["created_at"] > SESSION_MAX_AGE:
+        del _sessions[token]
+        return None
+    return session["username"]
+
+
+def destroy_session(token: str):
+    """Destroy a session token."""
+    _sessions.pop(token, None)

web_counter-0.1.0/web_counter/cli.py

@@ -0,0 +1,249 @@
+"""CLI: start, restart, stop, createsuperuser, export-js."""
+
+import argparse
+import asyncio
+import os
+import signal
+import subprocess
+import sys
+import time
+from pathlib import Path
+
+
+def _read_pid(pid_file: str) -> int | None:
+    """Read PID from file."""
+    try:
+        with open(pid_file, "r") as f:
+            return int(f.read().strip())
+    except (FileNotFoundError, ValueError):
+        return None
+
+
+def _is_running(pid: int | None) -> bool:
+    """Check if a process with given PID is running."""
+    if pid is None:
+        return False
+    try:
+        os.kill(pid, 0)
+        return True
+    except OSError:
+        return False
+
+
+def start_command(args):
+    """Start the web-counter server in the background."""
+    from .config import Config
+
+    config = Config(
+        salt=args.salt,
+        host=args.host,
+        port=args.port,
+        db_path=args.db_path,
+        pid_file=args.pid_file,
+        allowed_origins=args.allowed_origins,
+        rate_limit=args.rate_limit,
+    )
+    config.validate()
+
+    # Check if already running
+    pid = _read_pid(config.pid_file)
+    if _is_running(pid):
+        print(f"✗ web-counter 已在运行中 (PID: {pid})")
+        sys.exit(1)
+
+    # Ensure data directory exists
+    Path(config.db_path).parent.mkdir(parents=True, exist_ok=True)
+    Path(config.pid_file).parent.mkdir(parents=True, exist_ok=True)
+
+    # Build command
+    cmd = [
+        sys.executable, "-m", "uvicorn", "web_counter.main:app",
+        "--host", config.host,
+        "--port", str(config.port),
+        "--log-level", "info",
+    ]
+
+    # Set environment variables for the subprocess
+    env = os.environ.copy()
+    env["COUNTER_SALT"] = config.salt
+    env["COUNTER_HOST"] = config.host
+    env["COUNTER_PORT"] = str(config.port)
+    env["COUNTER_DB_PATH"] = config.db_path
+    env["COUNTER_PID_FILE"] = config.pid_file
+    env["COUNTER_ALLOWED_ORIGINS"] = config.allowed_origins
+    env["COUNTER_RATE_LIMIT"] = str(config.rate_limit)
+
+    # Start process (background)
+    proc = subprocess.Popen(
+        cmd,
+        env=env,
+        stdout=subprocess.DEVNULL,
+        stderr=subprocess.DEVNULL,
+        creationflags=subprocess.CREATE_NO_WINDOW if sys.platform == "win32" else 0,
+    )
+
+    # Write PID file
+    with open(config.pid_file, "w") as f:
+        f.write(str(proc.pid))
+
+    origin = f"http://{config.host}:{config.port}"
+    print(f"✓ web-counter 已启动，监听 {origin}")
+    print()
+    print("---------- 复制以下代码到网页 </body> 前 ----------")
+    print()
+    print(f'<script async src="{origin}/counter.js"></script>')
+    print()
+    print('<span style="display:none" class="counter-container" data-counter-style="card">')
+    print("  本站访问次数 <span data-pv-site></span> 次 ·")
+    print("  今日访问量 <span data-pv-today></span> 次 ·")
+    print("  今日访客 <span data-uv-today></span> 人 ·")
+    print("  总访问量 <span data-pv-site></span> 次 ·")
+    print("  总访客 <span data-uv-site></span> 人")
+    print("</span>")
+    print()
+    print("------------------------------------------------------")
+
+
+def stop_command(args):
+    """Stop the running web-counter server."""
+    from .config import Config
+
+    config = Config(pid_file=args.pid_file)
+
+    pid = _read_pid(config.pid_file)
+    if not _is_running(pid):
+        print("✗ web-counter 未在运行")
+        if Path(config.pid_file).exists():
+            Path(config.pid_file).unlink()
+        sys.exit(1)
+
+    # Send SIGTERM for graceful shutdown
+    os.kill(pid, signal.SIGTERM)
+
+    # Wait for process to exit (max 10 seconds)
+    for _ in range(100):
+        if not _is_running(pid):
+            break
+        time.sleep(0.1)
+
+    if _is_running(pid):
+        print(f"✗ 无法停止进程 (PID: {pid})，尝试强制终止...")
+        try:
+            os.kill(pid, signal.SIGKILL)
+        except OSError:
+            pass
+        time.sleep(0.5)
+
+    # Clean up PID file
+    if Path(config.pid_file).exists():
+        Path(config.pid_file).unlink()
+
+    print("✓ web-counter 已停止")
+
+
+def restart_command(args):
+    """Restart the web-counter server."""
+    print("正在重启 web-counter...")
+    stop_command(args)
+    start_command(args)
+
+
+def createsuperuser_command(args):
+    """Create an admin user interactively."""
+    from .config import Config
+    from .database import init_db, create_admin
+    from .auth import hash_password
+
+    config = Config(
+        salt="dummy",
+        db_path=args.db_path,
+    )
+
+    username = input("Username: ").strip()
+    if not username:
+        print("✗ 用户名不能为空")
+        sys.exit(1)
+
+    password = input("Password: ").strip()
+    if not password:
+        print("✗ 密码不能为空")
+        sys.exit(1)
+
+    confirm = input("Confirm password: ").strip()
+    if password != confirm:
+        print("✗ 两次输入的密码不一致")
+        sys.exit(1)
+
+    async def _create():
+        await init_db(config.db_path)
+        password_hash = hash_password(password)
+        await create_admin(config.db_path, username, password_hash)
+
+    asyncio.run(_create())
+    print(f"✓ 管理员 {username} 创建成功")
+
+
+def export_js_command(args):
+    """Export counter.js to stdout."""
+    js_path = Path(__file__).parent / "static" / "counter.js"
+    print(js_path.read_text(encoding="utf-8"))
+
+
+def main():
+    """CLI entry point."""
+    parser = argparse.ArgumentParser(
+        prog="web-counter",
+        description="A self-hosted website visit counter",
+    )
+    subparsers = parser.add_subparsers(dest="command", help="Available commands")
+
+    # start
+    p = subparsers.add_parser("start", help="Start the server in background")
+    p.add_argument("--salt", default=None, help="IP hash salt (required)")
+    p.add_argument("--host", default=None, help="Listen address (default: 0.0.0.0)")
+    p.add_argument("--port", type=int, default=None, help="Listen port (default: 8000)")
+    p.add_argument("--db-path", default=None, help="SQLite database path")
+    p.add_argument("--pid-file", default=None, help="PID file path")
+    p.add_argument("--allowed-origins", default=None, help="CORS allowed origins")
+    p.add_argument("--rate-limit", type=int, default=None, help="Rate limit per IP per minute")
+
+    # restart
+    p = subparsers.add_parser("restart", help="Restart the server")
+    p.add_argument("--salt", default=None, help="IP hash salt")
+    p.add_argument("--host", default=None, help="Listen address")
+    p.add_argument("--port", type=int, default=None, help="Listen port")
+    p.add_argument("--db-path", default=None, help="SQLite database path")
+    p.add_argument("--pid-file", default=None, help="PID file path")
+    p.add_argument("--allowed-origins", default=None, help="CORS allowed origins")
+    p.add_argument("--rate-limit", type=int, default=None, help="Rate limit per IP per minute")
+
+    # stop
+    p = subparsers.add_parser("stop", help="Stop the server")
+    p.add_argument("--pid-file", default=None, help="PID file path")
+
+    # createsuperuser
+    p = subparsers.add_parser("createsuperuser", help="Create an admin user")
+    p.add_argument("--db-path", default=None, help="SQLite database path")
+
+    # export-js
+    subparsers.add_parser("export-js", help="Export counter.js to stdout")
+
+    args = parser.parse_args()
+
+    if args.command == "start":
+        start_command(args)
+    elif args.command == "restart":
+        restart_command(args)
+    elif args.command == "stop":
+        stop_command(args)
+    elif args.command == "createsuperuser":
+        createsuperuser_command(args)
+    elif args.command == "export-js":
+        export_js_command(args)
+    else:
+        parser.print_help()
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()