终极 Ackee 3.0 升级指南：保护隐私的自托管分析工具关键变更与适配方案

Ackee 作为一款注重隐私的自托管 Node.js 分析工具，其 3.0 版本带来了多项重要更新。本指南将帮助您顺利完成从 2.x 到 3.x 的升级，确保您的隐私分析系统持续稳定运行。## 🌟 核心变更概览Ackee 3.0 版本在安全性、API 设计和跟踪功能上进行了显著优化。主要变更包括 CORS 配置增强、跟踪器 API 重构以及 GraphQL 接口调整，这些更新旨在提升系统

贡子霏Myra

377人浏览 · 2026-02-02 05:37:30

贡子霏Myra · 2026-02-02 05:37:30 发布

终极 Ackee 3.0 升级指南：保护隐私的自托管分析工具关键变更与适配方案

【免费下载链接】Ackee Self-hosted, Node.js based analytics tool for those who care about privacy. 项目地址: https://gitcode.com/gh_mirrors/ac/Ackee

Ackee 作为一款注重隐私的自托管 Node.js 分析工具，其 3.0 版本带来了多项重要更新。本指南将帮助您顺利完成从 2.x 到 3.x 的升级，确保您的隐私分析系统持续稳定运行。

🌟 核心变更概览

Ackee 3.0 版本在安全性、API 设计和跟踪功能上进行了显著优化。主要变更包括 CORS 配置增强、跟踪器 API 重构以及 GraphQL 接口调整，这些更新旨在提升系统安全性并提供更灵活的数据分析能力。

🔒 CORS 配置重大调整

`Access-Control-Allow-Origin: "*"` 不再推荐

使用通配符 * 作为跨域请求头存在安全隐患，且会导致 Ackee 无法忽略您自己的访问记录。如果您当前使用通配符配置，请按以下步骤修改：

禁用 ackee-tracker 中的 ignoreOwnVisits 选项
参考 SSL and HTTPS 文档配置更安全的跨域策略

⚠️ 注意：ignoreOwnVisits 现在默认启用，但在使用通配符时将无法工作

新增 `Access-Control-Allow-Credentials` 头要求

所有用户都需要添加这个新的响应头。您可以在服务器或反向代理配置中添加：

Access-Control-Allow-Credentials: true

详细配置指南请参考 CORS headers 文档。

📊 ackee-tracker API 重构

如果您通过手动或编程方式使用 ackee-tracker，需要适应新的 .create 和 .record 语法。这是 3.0 版本最显著的 API 变更，确保您的跟踪代码与新版本兼容。

最新的 ackee-tracker 版本为 ^5.1.1（在 package.json 中定义），完整的变更说明请查看 ackee-tracker 变更日志。

📡 GraphQL API 调整

Referrers 查询需指定 `ReferrerType`

请求 referrers 数据时，现在必须提供 ReferrerType 参数，可选值包括：

WITH_SOURCE
NO_SOURCE
ONLY_SOURCE

Referrers ID 格式变更

referrers 的 id 字段已从 URL 格式改为字符串类型，以支持包含参数的引用来源（如使用 ackee-tracker 时的 source 参数）。详细信息请参考 Enhancing referrers 文档。

🚀 升级步骤

克隆最新代码

git clone https://gitcode.com/gh_mirrors/ac/Ackee
cd Ackee

安装依赖
```
npm install
```
更新配置文件
- 检查 CORS 相关设置，移除通配符配置
- 添加 Access-Control-Allow-Credentials: true 头
更新跟踪代码 根据 ackee-tracker 新语法调整您网站中的跟踪代码
重启服务
```
npm run start
```