Source: Dev.to

如何使用 Docker 自托管 Ackee 分析

注意：本文档中的所有代码块、URL 以及技术术语均保持原样，不进行翻译。

---

前言

Ackee 是一个轻量级、开源且自托管的网页分析工具，专注于隐私保护且不使用 cookie。通过 Docker，你可以在几分钟内将 Ackee 部署到自己的服务器上，而无需手动配置每个依赖项。

本文将一步步演示：

1. 准备环境
2. 拉取 Ackee Docker 镜像
3. 配置环境变量
4. 使用 docker-compose 启动服务
5. 配置反向代理（可选）

---

前置条件

在开始之前，请确保你的服务器满足以下条件：

• 操作系统：Ubuntu 20.04+、Debian 10+、CentOS 8+（其他 Linux 发行版亦可）
• Docker：已安装 Docker Engine（>= 20.10）
• Docker Compose：已安装 Docker Compose（>= 2.0）
• 域名（可选）：如果想通过自定义域名访问 Ackee，需要一个指向服务器 IP 的 A 记录
• HTTPS 证书（可选）：推荐使用 Let’s Encrypt（可通过 Caddy、NGINX 或 Traefik 自动获取）

提示：如果你还没有安装 Docker，请参考官方文档：https://docs.docker.com/engine/install/

---

第一步：克隆官方仓库

git clone https://github.com/electerious/Ackee.git
cd Ackee

这一步会把 Ackee 的源码以及示例 docker-compose.yml 拉取到本地。

---

第二步：创建 .env 文件

在项目根目录下新建一个 .env 文件，用于存放环境变量。以下是最小化配置示例：

# 数据库配置（使用 MongoDB）
MONGO_URL=mongodb://mongo:27017/ackee

# Ackee Web UI 配置
BASE_URL=https://analytics.example.com   # 替换为你的域名或 IP
TOKEN_SECRET=your_random_secret_here    # 生成一个 32 位以上的随机字符串

生成安全的 TOKEN_SECRET

openssl rand -base64 32

如果你想使用外部 MongoDB 实例，只需把 MONGO_URL 改为对应的连接字符串（包括用户名、密码和端口）。

---

第三步：编辑 docker-compose.yml

官方提供的 docker-compose.yml 已经基本可用，只需要确认以下几点：

version: "3.8"

services:
  ackee:
    image: electerious/ackee:latest
    container_name: ackee
    env_file:
      - .env
    ports:
      - "3000:3000"   # 本地调试时使用
    depends_on:
      - mongo
    restart: unless-stopped

  mongo:
    image: mongo:5
    container_name: ackee-mongo
    volumes:
      - mongo-data:/data/db
    restart: unless-stopped

volumes:
  mongo-data:

• 端口映射：如果你计划通过反向代理（Nginx/Caddy/Traefik）暴露服务，可将 3000:3000 保持不变，或者直接删除 ports 部分，让容器只在内部网络中可达。
• 持久化：mongo-data 卷确保 MongoDB 数据不会因为容器重启而丢失。

---

第四步：启动容器

docker compose up -d

运行后，你可以检查容器状态：

docker compose ps

如果一切正常，MongoDB 与 Ackee 两个容器都会显示 Up。

---

第五步：配置反向代理（可选）

使用 Nginx 示例

server {
    listen 80;
    server_name analytics.example.com;

    # 自动重定向到 HTTPS（如果已配置 SSL）
    return 301 https://$host$request_uri;
}

server {
    listen 443 ssl;
    server_name analytics.example.com;

    ssl_certificate /etc/letsencrypt/live/analytics.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/analytics.example.com/privkey.pem;

    location / {
        proxy_pass http://localhost:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

说明

• proxy_pass 指向容器内部的 3000 端口（因为我们在 docker-compose.yml 中保留了端口映射）。
• 如果你使用 Docker 网络（即不暴露端口），可以把 proxy_pass 改为 http://ackee:3000，并在 Nginx 所在的宿主机上加入 --network 参数，使 Nginx 与 Ackee 同属一个 Docker 网络。

使用 Caddy 示例（自动获取 HTTPS）

analytics.example.com {
    reverse_proxy ackee:3000
}

将上述文件保存为 Caddyfile，并在同一目录下运行：

docker run -d \
  --name caddy \
  -p 80:80 -p 443:443 \
  -v $(pwd)/Caddyfile:/etc/caddy/Caddyfile \
  -v caddy_data:/data \
  -v caddy_config:/config \
  caddy:latest

Caddy 会自动为 analytics.example.com 申请 Let’s Encrypt 证书并完成反向代理。

---

第六步：访问 Ackee 仪表盘

打开浏览器，访问你在 .env 中配置的 BASE_URL（例如 https://analytics.example.com）。首次登录时，需要使用 初始化令牌：

1. 在容器日志中查找生成的令牌：

   docker logs ackee

2. 复制日志中类似 Your first token is: <TOKEN> 的字符串。
3. 在登录页面粘贴该令牌，即可创建管理员账户并开始使用。

安全建议：登录后立即删除或更改该初始化令牌，以防止未授权访问。

---

常见问题（FAQ）

---

结语

通过 Docker，你可以在几分钟内完成 Ackee 的自托管部署，并通过 Nginx、Caddy 或 Traefik 等反向代理实现安全的 HTTPS 访问。整个过程完全开源、无需第三方追踪，适合对隐私有严格要求的个人站点或企业内部项目。

如果你在部署过程中遇到其他问题，欢迎在 Ackee 的 GitHub Issues 页面提出，或在社区论坛分享你的经验。祝你玩得开心！ 🚀

什么是 Ackee？

Ackee 是一个 自托管、注重隐私的分析工具，它在 不使用 Cookie 的情况下跟踪页面浏览量、来源、浏览器和操作系统。
它将数据存储在 MongoDB 中，提供 GraphQL API，并提供简洁的单页仪表盘。
Ackee 适用于希望获取基本流量指标、但不想使用 Matomo 的复杂性或 Google Analytics 的云依赖的开发者。

前置条件

Docker‑Compose 设置

创建一个 docker-compose.yml 文件：

services:
  ackee:
    image: electerious/ackee:3.5.1
    container_name: ackee
    restart: unless-stopped
    ports:
      - "3000:3000"
    environment:
      ACKEE_MONGODB: "mongodb://mongo:27017/ackee"
      ACKEE_USERNAME: "admin"                 # CHANGE: dashboard login username
      ACKEE_PASSWORD: "change-this-password"  # CHANGE: use a strong password
      ACKEE_ALLOW_ORIGIN: "https://example.com" # CHANGE: your website's domain (CORS)
    depends_on:
      - mongo
    networks:
      - analytics

  mongo:
    image: mongo:7.0.16
    container_name: ackee-mongo
    restart: unless-stopped
    volumes:
      - ackee-data:/data/db
    networks:
      - analytics

networks:
  analytics:
    driver: bridge

volumes:
  ackee-data:

环境变量

启动堆栈

docker compose up -d

• 在 http://:3000 打开仪表盘
• 使用环境变量中定义的用户名和密码登录
• Settings → Domains → Add Domain → 输入站点的名称和域名

跟踪脚本

复制生成的代码片段并将其放置在您网站的 “ 中：

• 脚本约 2 KB，异步加载，且 不设置任何 cookie。
• Ackee 可以从单个实例跟踪多个站点；每个站点都有自己的域 ID 和代码片段。

启用详细模式（可选）

详细模式 会在每次访问时收集屏幕尺寸、语言和来源。它仍然不使用 cookie，但提供了更细粒度的数据。

GraphQL API

{
  domains {
    id
    title
    statistics {
      views {
        id
        count
      }
    }
  }
}

• 端点: https://your-ackee-instance.com/api
• 身份验证: Bearer 令牌（在 设置 → 令牌 中创建永久令牌）

生产部署（HTTPS 反向代理）

server {
    listen 443 ssl;
    server_name analytics.example.com;

    location / {
        proxy_pass http://localhost:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

提示: 强烈建议使用 HTTPS。ACKEE_ALLOW_ORIGIN 在 HTTPS 来源下表现最佳，浏览器可能会在混合内容页面上阻止跟踪器。请参阅 Reverse Proxy Setup 指南获取完整配置。

备份 MongoDB 数据

# Dump the database inside the container
docker exec ackee-mongo mongodump --out /tmp/backup --db ackee

# Copy the dump to the host
docker cp ackee-mongo:/tmp/backup ./ackee-backup-$(date +%Y%m%d)

或者，使用 Restic 或 BorgBackup 等工具备份整个 ackee-data Docker 卷。请参阅 Backup Strategy 文档。

常见问题与解决方案

资源使用（典型）

何时使用（或不使用）Ackee

优点

• 极其轻量——仅包含基础：页面浏览量、引用来源、浏览器、屏幕尺寸。
• 开箱即用的 GDPR 友好（匿名模式）。
• GraphQL API，可进行自定义集成。

缺点

• 没有漏斗、目标、自定义事件或活动跟踪。
• 如果需要高级分析，容易很快超出其能力。

替代方案：

• Plausible 或 Umami – 添加目标和自定义事件。
• Matomo – 功能完整，但更重。

GDPR 与无Cookie操作

• Anonymous mode (default): 不收集任何可识别个人身份的信息，不使用 cookie，仅收集汇总指标。无需显示同意横幅。
• Detailed mode: 收集稍多的信息（屏幕尺寸、语言、引用页面），但仍然 cookieless，并避免指纹识别。

跟踪多个网站

1. 在 Ackee 仪表盘，前往 Settings → Domains → Add Domain。
2. 每个域名都会获得唯一的 Domain ID 和跟踪代码片段。
3. 将相应的代码片段插入每个站点的 “.

概览

单个 Ackee 实例可以跟踪的域名数量没有硬性限制——主要限制是 MongoDB 的存储空间，存储需求会随流量增长而增加。

• Ackee – 最简方案：基本的页面浏览量、来源、浏览器和屏幕尺寸，并提供 GraphQL API。
• Plausible – 在此基础上添加目标、自定义事件和活动追踪，拥有精致的仪表盘。
• Umami – 介于两者之间，提供自定义事件，设置比 Plausible 更简便。

如果你真的只想要最基础、仅通过 API 的分析功能，请选择 Ackee。

跟踪器拦截

一些注重隐私的广告拦截插件会维护已知分析域名列表，导致 Ackee 的跟踪脚本被拦截。自行托管有助于缓解此问题，因为你的 Ackee 实例运行在自己的域名下，拦截器更难识别。你还可以通过在主站点域名下代理跟踪脚本来进一步降低被拦截的概率。

资源需求

• Ackee 本身仅使用约 50 MB 的 RAM。
• 瓶颈在于 MongoDB，至少需要 100–200 MB。

一台配备 2 GB RAM 的 Raspberry Pi 4 能够轻松应对低至中等流量的网站。使用 ARM64 版 MongoDB 镜像：

docker pull mongo:7.0.16

该镜像可在 Pi 4/5 上原生运行。

数据保留

Ackee 没有内置的数据保留策略。数据会在 MongoDB 中无限累积。若需管理存储空间，你可以：

1. 通过 MongoDB 查询手动删除旧记录。
2. 设置 cron 任务定期清除旧条目。
3. 使用 MongoDB 的 TTL 索引 功能实现自动过期（在相应集合上配置即可）。

主题与指南

• 最佳自托管分析
• 如何自托管 Plausible
• 如何自托管 Umami
• Plausible 与 Umami 对比
• 替代 Google Analytics
• Docker Compose 基础
• 反向代理设置
• 备份策略