Ackee 3.0 升级指南：关键变更与适配方案

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 是一款轻量级的网站流量分析工具，其 3.0 版本引入了一些重要的安全性和功能改进。本文将为开发者详细解析从 2.x 升级到 3.0 版本的关键变更点，并提供具体的适配方案。

核心变更解析

1. CORS 安全策略升级

变更背景： 在 2.x 版本中，部分开发者可能使用了通配符(*)作为 Access-Control-Allow-Origin 的值，这种做法存在安全隐患且无法支持访客过滤功能。

具体变更：

• 3.0 版本不再推荐使用通配符
• ignoreOwnVisits 选项默认启用且不再支持通配符配置

适配方案：

1. 移除 CORS 配置中的 * 通配符
2. 改为配置具体的允许域名
3. 如需禁用自身访问过滤，显式设置 ignoreOwnVisits: false

技术建议： 建议配置 Nginx 或 Apache 的反向代理规则，为每个需要访问的域名单独设置 CORS 头，这是更安全的做法。

2. 新增凭证控制头

变更内容： 3.0 版本强制要求 Access-Control-Allow-Credentials 头，该头在 2.x 版本是可选的。

配置示例：

add_header 'Access-Control-Allow-Credentials' 'true';

注意事项： 当启用此头时，Access-Control-Allow-Origin 不能使用通配符，必须指定具体域名。

3. 数据收集器 API 变更

影响范围： 仅影响手动或编程方式使用 ackee-tracker 的情况。

主要变更点：

• 创建和记录方法采用了新的语法结构
• 方法调用方式更加清晰和类型安全

迁移示例： 旧版代码：

ackeeTracker.create(server).record(domainId)

新版代码：

ackeeTracker.create(server).record({
  domainId: 'your-domain-id'
})

4. GraphQL API 变更

4.1 引用来源查询参数变更

变更内容： 查询引用来源时新增必填参数 ReferrerType，可选值：

• WITH_SOURCE：包含来源信息
• NO_SOURCE：不包含来源信息
• ONLY_SOURCE：仅包含来源信息

查询示例：

query {
  referrers(type: WITH_SOURCE) {
    id
    count
  }
}

4.2 引用来源ID格式变更

变更背景： 为支持增强的引用来源功能，引用来源的ID不再仅限于URL格式。

变更内容：

• ID字段类型从URL改为字符串
• 可包含额外参数（如来源信息）

影响范围： 所有处理引用来源ID的客户端代码需要更新，不再假设ID是有效的URL格式。

升级检查清单

1. [ ] 检查并更新CORS配置，移除通配符
2. [ ] 添加 Access-Control-Allow-Credentials 头
3. [ ] 更新 ackee-tracker 调用语法（如适用）
4. [ ] 修改 GraphQL 查询，添加 ReferrerType 参数
5. [ ] 检查引用来源ID的处理逻辑

常见问题解答

Q：为什么不再支持CORS通配符？ A：出于安全考虑，通配符配置会导致潜在的安全风险，同时无法支持访客过滤等高级功能。

Q：升级后引用来源数据会丢失吗？ A：不会，所有历史数据都会保留，只是API查询方式有所变化。

Q：是否有回滚方案？ A：建议在升级前备份数据库，如遇问题可回退到2.x版本并恢复备份。

结语

Ackee 3.0 的变更加强了安全性和功能性，虽然需要一定的适配工作，但这些改进将为用户带来更好的使用体验和更准确的数据分析能力。建议开发者在测试环境中充分验证后再部署到生产环境。

Ackee Self-hosted, Node.js based analytics tool for those who care about privacy. 项目地址: https://gitcode.com/gh_mirrors/ac/Ackee