必须用elasticsearch实现高性能全文检索，因其支持中文分词、相关性排序等；需正确配置es服务、ik分词器、mapping及异步同步机制，并做好查询兜底与限流。
__icontains 和 SearchVector 在十万行以上数据里就会明显卡顿，这不是调优能解决的问题——底层是 SQL LIKE 或静态 tsvector，不支持中文分词、同义词、相关性排序，更没法做拼音容错或高亮。真要高性能全文检索，必须用 Elasticsearch，但直接 pip install 就跑不起来，缺了三样东西：独立运行的 ES 进程、明确定义的 mapping（尤其中文分词器）、以及可靠的数据同步机制。
ES 服务连不上？先确认版本和连接参数是否对得上
常见错误是 ConnectionError: Connection refused 或 NotFoundError: No such index，根本原因往往是客户端、服务端、Haystack/django-elasticsearch-dsl 三方版本没对齐。
- ES 8.12.2 服务启动后，用
curl -X GET "http://localhost:9200/"看返回 JSON 里"version": {"number": "8.12.2"}才算真正跑起来了 - Python 客户端必须用
elasticsearch>=8.0.0（不是elasticsearch-py），装错会 import 失败或连不上 -
HAYSTACK_CONNECTIONS里别写'URL'，ES 8+ 废弃该参数；改用'hosts': ['http://localhost:9200']，且必须带协议头 - django-elasticsearch-dsl 用户注意：
ELASTICSEARCH_DSL配置里hosts写成'localhost:9200'（缺http://）也会静默失败
中文搜不到？分词器没配或 mapping 写错了
ES 默认 standard 分词器对中文是逐字切，“人工智能”变成 [“人”, “工”, “智”, “能”]，当然搜不出完整词。这不是代码问题，是索引定义缺陷。
Python 3.14.2
下载
Python 3.14.2是Python编程语言在2025年12月5日发布的稳定版本，属于3.14系列的第二个维护更新。该版本包含了18项修复，重点解决了多进程、数据类及正则表达式等模块的回归问题，并修复了CVE-2025-12084等安全漏洞。此版本标志着自由线程模式（移除GIL）正式获得官方支持，是Python发展的重要里程碑。
- 必须装 ik 插件：
bin/elasticsearch-plugin install https://github.com/medcl/elasticsearch-analysis-ik/releases/download/v8.12.2/elasticsearch-analysis-ik-8.12.2.zip - 建索引时显式指定
"analyzer": "ik_max_word"，不能依赖 dynamic mapping - 字段类型必须是
text，不是keyword；如果还要精确匹配（比如 ID 或状态码），得额外加fields: { raw: { type: keyword } } - 上线前务必验证分词效果：
curl -X GET "http://localhost:9200/my_index/_analyze" -H "Content-Type: application/json" -d '{"analyzer": "ik_max_word", "text": "蓝牙耳机"}'
Django 模型改了，ES 里还是旧数据？同步机制靠不住
用 @registry.register_document 或 RealtimeSignalProcessor 听起来省事，但在 bulk_create、事务回滚、Celery 异步场景下极易丢数据——信号触发时机和 DB 提交不严格同步，这是设计使然，不是 bug。
- 开发阶段可关掉自动同步：
ELASTICSEARCH_DSL_AUTOSYNC = False，避免测试时反复刷索引 - 生产环境推荐异步任务驱动：模型
save()里只发update_es_document.delay(instance.id)，由 Celery 单独拉取最新数据构造文档 - 重建索引别依赖信号：
python manage.py search_index --rebuild是唯一能保证全量一致的操作，上线新 mapping 前必须跑 - 索引名建议带版本号，如
article_v3，同步完再用 alias 原子切换，避免搜索中断
视图里调 ES 查询总出错？别直接裸调，得兜底和限流
Search().query(...).execute() 看似简单，但用户输个空字符串、通配符 * 或翻到第 1000 页，ES 就可能抛 Result window is too large 或触发 circuit breaker，进程卡死。
- 结果集必须硬限制：
s[0:100]，ES 默认只返回 10 条，但用户可能设size=10000，得在代码里拦住 - 三种异常必须区分处理：
ConnectionError降级回Model.objects.filter(title__icontains=q)；NotFoundError说明索引不存在，要告警；RequestError（如 query DSL 错）需记录日志并返回友好提示 - 分页别用
Paginator直接套Search对象——它不是 QuerySet；先list(s[0:100])转成 Python list，再喂给 Paginator -
response["hits"]["total"]在 ES 7.x+ 是 dict（{"value": 123, "relation": "eq"}），别直接int()，要用response.hits.total.value
Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！
