Elasticsearch Rails 集成（elasticsearch-model / ActiveRecord）

一、安装与版本

Gemfile：

gem 'elasticsearch-rails'
# 可选：只用 API/客户端
# gem 'elasticsearch'
# gem 'elasticsearch-model'

• elasticsearch-rails 中含 elasticsearch-model；后者依赖官方 Ruby 客户端 elasticsearch。官方 ActiveModel/ActiveRecord 文档条目对特性有总览说明。(Elastic)
• GitHub 主仓列出了：ActiveModel 适配、Enumerable 结果封装、ActiveRecord::Relation 返回、分页支持、Rake 导入任务等。(GitHub)

二、快速上手：把 ES 接入 ActiveRecord

2.1 为模型混入模块

class Article < ApplicationRecord
  include Elasticsearch::Model
  # 自动回写（保存/删除时同步 ES）
  include Elasticsearch::Model::Callbacks
end

• Elasticsearch::Model 提供搜索、映射、导入等便捷方法；
• Elasticsearch::Model::Callbacks 自动注入 after_save/after_destroy 等回调以更新索引。(rubydoc.info, GitHub)

2.2 初始化索引并导入

# 第一次：创建索引 + 导入
Article.__elasticsearch__.create_index!
Article.import  # 或 Rake 任务，见第 4 节

• README/文档提供了 import 及 Rake 任务方式进行全量导入。(rubydoc.info, GitHub)

三、索引设置与映射（Mapping）

建议为每个模型定义索引设置与映射 ，并自定义序列化字段（as_indexed_json）：

class Article < ApplicationRecord
  include Elasticsearch::Model
  include Elasticsearch::Model::Callbacks

  index_name "articles_#{Rails.env}"
  document_type "_doc" # 现代版本通常不再使用自定义 type

  settings index: {
    number_of_shards: 1,
    analysis: {
      analyzer: {
        my_text_analyzer: {
          type: 'standard' # 可按需替换为内置语言分析器/插件
        }
      }
    }
  } do
    mappings dynamic: 'false' do
      indexes :title,      type: 'text', analyzer: 'my_text_analyzer'
      indexes :tags,       type: 'keyword'
      indexes :published_at, type: 'date'
    end
  end

  def as_indexed_json(_options={})
    {
      title: title,
      tags: tags,
      published_at: published_at
    }
  end
end

• 映射定义是告诉 ES 如何存储/检索字段的"契约"；对 text 字段可指定 analyzer（也可为检索指定 search_analyzer）。(Elastic)
• 已存在索引 只能"增加字段/调整少量参数"，若要变更字段类型/分析器，需新建索引 + 重建 （见第 7 节"零停机重建"）。(Elastic)

中文场景提示：若需中文分词，可考虑安装官方 analysis-smartcn 或社区 IK 分词插件，再在 analyzer 中引用相应分词器；上线前请用 _analyze API 验证。(Elastic)

四、批量导入与数据同步（Import / Callbacks / 异步）

4.1 一次性全量导入

# Rake 任务（先在 lib/tasks/elasticsearch.rake 中引入任务定义）
#   require 'elasticsearch/rails/tasks/import'
bundle exec rake environment elasticsearch:import:model CLASS='Article'

• 官方提供了导入 Rake 任务，支持限制到某个 scope。(rubydoc.info)

4.2 模型回调自动同步

include Elasticsearch::Model::Callbacks

• 保存/删除后会触发更新/删除文档请求，适合中小型写入量或对"最终一致"要求不高场景。(rubydoc.info)

4.3 异步同步（推荐）

• 在高写入场景，建议 关闭自动回调 ，改为在 after_commit 推送 ActiveJob/Sidekiq 任务执行 index_document / update_document / delete_document，避免事务未提交导致的竞态。(Justin Weiss)

五、查询结果包装、records vs results、高亮与聚合

# 关键字搜索
response = Article.search(
  query: { multi_match: { query: params[:q], fields: %w[title] } },
  highlight: { fields: { title: {} } },
  aggs: { tags: { terms: { field: 'tags' } } },
  _source: %w[title tags published_at]
)

# 两种取法：
response.records.to_a  # => 返回 ActiveRecord 实例（会触发 SQL 加载）
response.results.to_a  # => 返回 ES 文档包装对象（_score/_source 等）

# 访问包装对象
first = response.results.first
first._score
first._source.title

• Enumerable 风格包装 + records / results 的双访问模式是 elasticsearch-model 的亮点之一。(GitHub)

六、分页：Kaminari / WillPaginate

elasticsearch-model 已提供对 Kaminari 和 WillPaginate 的分页适配：

# Kaminari
@page  = params[:page] || 1
@per   = 20
@resp  = Article.search(query: { match_all: {} }).page(@page).per(@per)
@items = @resp.records # 或 results

• 适配代码位于仓库 response/pagination/kaminari.rb 等。(GitHub)
• 两大分页库都能直接配合；社区也常用 Pagy，但官方适配以 Kaminari/WillPaginate 为主。(GitHub, reinteractive.com)

七、零停机重建索引（别名/重建/切换）

当变更映射 （如字段类型/分词器）时，需新建索引并重建数据，最后原子切换别名：

1. 写入与读取均指向别名 （如 articles_read / articles_write 或统一 articles）；
2. 新建 articles_v2（新映射）；
3. 用 _reindex 后台重建；
4. 切换别名到新索引（原子操作）；
5. 删除旧索引。

Elastic 官方博客/讨论区及 API 文档长期推荐"用别名原子切换 "实现零停机重建；这是 Rails 项目升级映射的标准做法。(Elastic, Discuss the Elastic Stack)

讨论区也有关于"更新期写入一致性"的实践探讨：严格零数据丢失需在切换窗口内协调写入策略。(Discuss the Elastic Stack)

八、常见坑与排错

• "改映射失败" ：已存在索引不能随意改字段类型/分析器；只能新增字段或少量参数 ，其他需重建索引。(Elastic)
• 事务竞态 ：直接用 after_save 回写，在分布式环境可能遇到"事务尚未提交，后台任务已读取"的问题；建议 after_commit 推送异步任务。(Justin Weiss)
• 分页性能 ：传统 from/size 深翻页开销大；大量遍历建议改为 ES 端的 PIT + search_after（在 Ruby 客户端层实现，与 rails 集成无冲突）。官方推荐在 API 侧使用该模式。
• Kaminari 配置未生效 ：确认加载了 response/pagination/kaminari 的扩展（随 gem 自动载入），GitHub issues 有过相关讨论。(GitHub)

九、进阶实践清单

• 模型序列化 ：通过 as_indexed_json 精简存储字段，避免把整行业务字段都塞入 ES（降低 _source 体积）。
• 高亮与安全：高亮返回 HTML 片段，前端渲染需做转义/白名单。
• 聚合与统计 ：在 search 里直接添加 aggs，将结果与列表一并返回。
• 索引命名约定 ：<model>_<env>_v<ver> + 读写别名；CI/CD 中把"创建新索引 + 重建 + 别名切换"流水线化。(Elastic)
• Rake 任务与数据回填 ：利用官方 elasticsearch:import:model 任务分批导入历史数据，必要时通过 scope 分段导入。(rubydoc.info)

十、参考资料

• ActiveModel / ActiveRecord 官方页 （elasticsearch-model 入口与特性概述）。(Elastic)
• elasticsearch-rails 仓库 （特性列表、分页适配、源码）。(GitHub)
• Kaminari 分页适配源码 。(GitHub)
• 映射与分析器 （Mapping/Analyzer 官方文档）。(Elastic)
• Rake 导入任务 （elasticsearch:import:model）。(rubydoc.info)
• 零停机重建（别名/重建/切换） 。(Elastic, Discuss the Elastic Stack)

附：最小可运行示例（Rails 控制器）

class ArticlesController < ApplicationController
  def index
    q    = params[:q].presence
    page = params[:page] || 1
    per  = 20

    body =
      if q
        { query: { multi_match: { query: q, fields: %w[title] } } }
      else
        { query: { match_all: {} } }
      end

    @resp   = Article.search(body).page(page).per(per)
    @items  = @resp.records
    @facets = @resp.response['aggregations']

    render json: {
      total:  @resp.response.dig('hits', 'total', 'value'),
      items:  @items.as_json(only: %i[id title tags published_at]),
      took:   @resp.response['took']
    }
  end
end