الوحدة 15 — التّشخيص: اثنتا عشرة عطلًا كلاسيكيًّا وعلاجها

تعمل حقيبة Veille، والفهرس جاهز، والرّسم البيانيّ مُحمَّل — ثمّ يومًا ما، تعرض Kibana « server is not ready yet »، أو لا يجد LOAD CSV الملفَّ، أو يرفض Elasticsearch المصادقة. صنّفت إيناس الأمور في النّهاية: اثنتا عشرة عطلًا متكرّرة، تُستفزّ يدويًّا، وتُقرأ في السّجلّات، وتُصلَح بأمر واحد، وتُتحقَّق منها.

جدول مُلخِّص

الرّقم	العَرَض الحرفيّ	السّبب	التّصحيح
1	failed to bind host port ... address already in use	المنفذ 9200 أو 5601 أو 7474 أو 7687 مأخوذ	docker ps ثمّ docker stop <nom>، أو حرّر المنفذ
2	مستوعب Exited (137)، OOMKilled: true	Docker قتل العمليّة، تجاوز الذّاكرة	ارفع Docker Desktop → Memory أو mem_limit
3	max virtual memory areas vm.max_map_count [65530] is too low	Linux: قيمة النّواة أدنى من اللّازم	sudo sysctl -w vm.max_map_count=262144
4	_cluster/health بحالة yellow أو red	نُسَخ غير مُسنَدة أو shard رئيسيّ ضائع	GET _cluster/allocation/explain ثمّ التّصحيح
5	cluster_block_exception, index read-only / allow delete (api)	بلغ حدّ watermark للقرص	PUT news/_settings {"index.blocks.read_only_allow_delete": null}
6	security_exception ... unable to authenticate user [elastic]	عُدِّل ELASTIC_PASSWORD بعد إنشاء الحجم	./lab.sh reset ثمّ ./lab.sh up
7	Kibana server is not ready yet	kibana_system أو Elasticsearch غير جاهز	./lab.sh logs setup ثمّ إعادة ./lab.sh up
8	mapper_parsing_exception أو mapper cannot be changed	نوع حقل غير متوافق	_reindex نحو فهرس جديد بالـmapping السّليم
9	Couldn't load the external resource at: file:/import/news.csv	ملفّ غائب في neo4j/import/	./lab.sh import-news
10	CALL { ... } IN TRANSACTIONS can only be executed in an implicit transaction	نُفِّذ داخل معاملة صريحة	صدِّرها بـ :auto في Neo4j Browser
11	There is no procedure with the name apoc.periodic.iterate registered	APOC غير مُحمَّل	تحقّق من NEO4J_PLUGINS، وأعد تشغيل Neo4j
12	The client is unauthorized due to authentication failure (Neo4j)	كلمة السّرّ عُدِّلت في .env والحجم قائم	./lab.sh reset ثمّ ./lab.sh up

يعيد بقيّة الوحدة كلّ سطر: كيف تُستفزّ العطلة عمدًا في الحقيبة (حين يكون آمنًا)، وما ستقرؤه في السّجلّات، وأمر التّصحيح، وكيف تتحقّق من أنّها حُلّت فعلًا.

1. منفذ مأخوذ

كيف تُستفَزّ. افتح طرفيّة واحتفظ فيها بخادم زائف على المنفذ 9200:

docker run --rm -p 9200:80 --name faux-serveur nginx

في طرفيّة ثانية، شغّل ./lab.sh up.

الرّسالة الحرفيّة.

Error response from daemon: driver failed programming external connectivity on endpoint veille-es
(...): failed to bind host port for 0.0.0.0:9200:172.19.0.2:9200/tcp: address already in use

السّبب. برنامج آخر (غالبًا مستوعب Elasticsearch قديم، أحيانًا خدمة محلّيّة) يمسك المنفذ 9200 سلفًا. لا يستطيع Docker تعيين المنفذ نفسه مرّتين على المضيف.

كيف تُصلحها.

docker ps
docker stop faux-serveur
./lab.sh doctor
./lab.sh up

على Linux وmacOS، يُحدّد sudo lsof -iTCP:9200 -sTCP:LISTEN العمليّة إن لم تكن مستوعبًا. على Windows PowerShell، يُعطي netstat -ano | findstr :9200 الـ PID.

كيف تتحقّق. يجب أن يعرض ./lab.sh status المستوعبات الثّلاثة بحالة Up (healthy) مع المنافذ 0.0.0.0:9200->9200/tcp قبالة veille-es.

2. مستوعب قتلته الذّاكرة (Exited (137))

كيف تُستفَزّ. خفّض ذاكرة Docker Desktop تحت 4 GB (Settings → Resources → Memory). أعد تشغيل Docker ثمّ ./lab.sh up. على آلة محدودة، أضف مؤقّتًا mem_limit: 1g على خدمة elasticsearch في docker-compose.yml.

الرّسالة الحرفيّة.

docker ps -a

CONTAINER   IMAGE                                       STATUS
veille-es   docker.elastic.co/.../elasticsearch:9.5.3   Exited (137) 12 seconds ago

docker inspect -f '{{.State.OOMKilled}}' veille-es

true

137 يساوي 128 + 9 : أرسلت النّواة SIGKILL (الإشارة 9) إلى المستوعب، غالبًا لأنّ حدّ الذّاكرة بُلِغ. تُؤكّد OOMKilled: true ذلك.

السّبب. تجاوزت عمليّة Elasticsearch (heap بحجم 1 GB زائد كلفة JVM زائد page cache) حدّ ذاكرة المستوعب أو Docker Desktop.

كيف تُصلحها. ارفع Docker Desktop → Settings → Resources → Memory إلى 6 GB (8 GB إن أضفت OpenSearch). على Linux عبر WSL2، عدّل %UserProfile%\.wslconfig :

[wsl2]
memory=8GB

ثمّ wsl --shutdown وأعِد فتح Docker Desktop. وأخيرًا:

./lab.sh down
./lab.sh up

كيف تتحقّق. يجب أن يعرض docker stats --no-stream أنّ veille-es قرب 1.3 GB من المقيم (heap مع buffers). ويجب أن ينتهي ./lab.sh logs elasticsearch --tail=20 بـ started.

3. vm.max_map_count منخفض جدًّا (Linux أصيل)

كيف تُستفَزّ. على آلة Linux بلا Docker Desktop (Docker Engine مباشرة):

sudo sysctl -w vm.max_map_count=65530
./lab.sh reset
./lab.sh up

الرّسالة الحرفيّة في ./lab.sh logs elasticsearch :

ERROR: [1] bootstrap checks failed
[1]: max virtual memory areas vm.max_map_count [65530] is too low, increase to at least [262144]

السّبب. يستعمل Elasticsearch mmap بكثافة لفهارس Lucene. تحدّ نواة Linux افتراضيًّا عدد مناطق الذّاكرة القابلة للتّعيين بـ 65 530 — غير كافٍ. يضبط Docker Desktop القيمة وحده في توزيعة WSL2 الدّاخليّة؛ على Linux الأصيل، يقع الأمر على المسؤول.

كيف تُصلحها.

sudo sysctl -w vm.max_map_count=262144
echo 'vm.max_map_count=262144' | sudo tee /etc/sysctl.d/99-elasticsearch.conf
./lab.sh up

يجعل السّطر الثّاني الضّبط دائمًا بعد إعادة التّشغيل.

كيف تتحقّق.

sysctl vm.max_map_count
./lab.sh logs elasticsearch --tail=20

القيمة المعروضة هي 262144 وينتهي السّجلّ بـ started.

4. عنقود yellow أو red

كيف تُستفَزّ. على عنقود بعقدة واحدة (الحقيبة)، أنشئ فهرسًا بنسخة واحدة — يتعذّر إسنادها:

PUT test_yellow
{
  "settings": { "number_of_shards": 1, "number_of_replicas": 1 }
}
GET _cluster/health

الرّسالة الحرفيّة.

{
  "cluster_name": "veille",
  "status": "yellow",
  "unassigned_shards": 1,
  ...
}

يُفصّل GET _cluster/allocation/explain السّبب:

"explanation": "the shard cannot be allocated to the same node on which a copy of the shard already exists"

السّبب. yellow = shard رئيسيّ حاضر، ونسخة غير موجودة (غالبًا: عدد العقد غير كافٍ). red = shard الرّئيسيّ نفسه غائب (سقوط عقدة، أو تلف قرص). أُعِدّت مجموعة news بـ number_of_replicas: 0 لتبقى green على عقدة واحدة.

كيف تُصلحها. على عنقود أحاديّ العقدة، اجعل النّسخ صفرًا:

PUT test_yellow/_settings
{
  "index": { "number_of_replicas": 0 }
}

في حالة red حقيقيّة، يُعطي GET _cluster/allocation/explain السّبب الدّقيق: قرص ممتلئ، أو عقدة غائبة، أو تلف. يعتمد العلاج على التّشخيص — لكنّ الأمر الأوّل يبقى دائمًا هو نفسه.

كيف تتحقّق. يُعيد GET _cluster/health القيمة "status": "green" و"unassigned_shards": 0.

5. فهرس للقراءة فقط (watermark للقرص)

كيف تُستفَزّ. تُعطّل الحقيبة العتبة للمختبر. حاكِ الأثر يدويًّا:

PUT news/_settings
{
  "index.blocks.read_only_allow_delete": true
}
POST news/_doc
{ "headline": "test" }

الرّسالة الحرفيّة.

{
  "error": {
    "type": "cluster_block_exception",
    "reason": "index [news] blocked by: [FORBIDDEN/12/index read-only / allow delete (api)];"
  },
  "status": 429
}

السّبب. في الإنتاج، يراقب Elasticsearch القرص. عند 95 ٪ من الامتلاء (عتبة flood_stage)، يضيف تلقائيًّا الحجب read_only_allow_delete على جميع الفهارس لمنع التّلف. ما إن يُوضَع هذا الحجب، لا يُرفَع من نفسه حتّى وإن هبطت النّسبة — عن قصد.

كيف تُصلحها.

PUT news/_settings
{
  "index.blocks.read_only_allow_delete": null
}

يحذف null الإعداد. يسقط الحجب فورًا، وتستأنف الكتابة. في الإنتاج، حرّر المساحة أوّلًا (حذف فهارس قديمة، توسيع الحجم) قبل رفع الحجب.

كيف تتحقّق. أعِد POST news/_doc {"headline":"test"} : الجواب هو {"result": "created"} لا cluster_block_exception.

6. خطأ 401 بعد تغيير ELASTIC_PASSWORD

كيف تُستفَزّ. عدّل .env، استبدل ELASTIC_PASSWORD=veille2026 بـ ELASTIC_PASSWORD=nouveau2026، ثمّ:

./lab.sh down
./lab.sh up

الرّسالة الحرفيّة عند أوّل نداء إلى Kibana (./lab.sh logs kibana) :

[error][elasticsearch-service] Unable to retrieve version information from Elasticsearch nodes.
security_exception: [security_exception] Reason: unable to authenticate user [elastic] for REST request [/_nodes?filter_path=nodes.*.version%2Cnodes.*.http.publish_address%2Cnodes.*.ip]

السّبب. كلمة سرّ المستخدم elastic مكتوبة في الحجم es-data عند أوّل تشغيل. بعد كتابتها، لا يُغيّرها متغيّر البيئة ELASTIC_PASSWORD : يقرؤه Elasticsearch فقط عند تهيئة عقدة جديدة. يُبقي ./lab.sh down على الحجوم؛ فتظلّ كلمة السّرّ المخزَّنة قديمة، وما تكتبه في .env هو الجديد، فلا يتطابقان.

كيف تُصلحها. خياران.

الخيار أ (سريع، دون العودة من الصّفر) — حدِّث كلمة السّرّ عبر الواجهة بالمصادقة بالقديمة:

docker exec veille-es curl -s -u elastic:veille2026 \
  -H 'Content-Type: application/json' \
  -X POST http://localhost:9200/_security/user/elastic/_password \
  -d '{"password":"nouveau2026"}'

الخيار ب (جذريّ) — انطلق من الصّفر:

./lab.sh reset
./lab.sh up

كيف تتحقّق.

./lab.sh es _cluster/health

يصل جواب JSON بدل security_exception.

7. Kibana: « Kibana server is not ready yet »

كيف تُستفَزّ. أوقف Elasticsearch أثناء إقلاع Kibana:

./lab.sh down
docker compose up -d kibana   # دون elasticsearch مسبقًا

ثمّ افتح http://localhost:5601.

الرّسالة الحرفيّة في المتصفّح:

Kibana server is not ready yet

في ./lab.sh logs kibana :

[error][elasticsearch-service] Unable to retrieve version information from Elasticsearch nodes.

السّبب. لا تُسلّم Kibana اليد قبل أن تتحدّث مع Elasticsearch ببيانات اعتماد kibana_system. ثلاثة أسباب محتملة: Elasticsearch لم يُقلع، أو setup فشل (فيبقى لـ kibana_system كلمة السّرّ القديمة)، أو أُقلعت Kibana قبل الباقي. تحمي healthchecks في الحقيبة من هذه الحالة عادةً؛ لكن docker compose up -d kibana وحدها تتجاوز التّبعيّات.

كيف تُصلحها.

./lab.sh logs setup
./lab.sh down
./lab.sh up

يحترم ./lab.sh up التّرتيب: elasticsearch → setup → kibana → neo4j، مع انتظار service_healthy بين كلّ خطوة. إن أظهر ./lab.sh logs setup فشلًا (كلمة سرّ غير متزامنة، أو خدمة Elasticsearch ميّتة)، فإنّ ./lab.sh reset متبوعًا بـ ./lab.sh up يعيد كلّ شيء إلى نظافته.

كيف تتحقّق. يُعيد curl -s http://localhost:5601/api/status | grep 'available' القيمة "level":"available".

8. صراع mapping (mapper_parsing_exception، mapper cannot be changed)

كيف تُستفَزّ.

PUT test_mapping
{
  "mappings": {
    "properties": {
      "date": { "type": "date", "format": "yyyy-MM-dd" }
    }
  }
}
POST test_mapping/_doc
{ "date": "hier" }

ثمّ الحالة الثّانية:

PUT test_mapping/_mapping
{
  "properties": {
    "date": { "type": "text" }
  }
}

الرّسائل الحرفيّة.

{"error":{"type":"mapper_parsing_exception","reason":"failed to parse field [date] of type [date] in document with id ..."}}

{"error":{"type":"illegal_argument_exception","reason":"mapper [date] cannot be changed from type [date] to [text]"}}

السّبب. يُثبّت Elasticsearch نوع الحقل منذ أوّل فهرسة. يمكن إضافة حقل، لا تغيير نوعه أبدًا. المرور من date إلى text (أو من text إلى keyword) يستلزم إنشاء فهرس جديد بالـmapping السّليم ونسخ المستندات بـ _reindex.

كيف تُصلحها.

PUT test_mapping_v2
{
  "mappings": {
    "properties": {
      "date": { "type": "text" }
    }
  }
}

POST _reindex
{
  "source": { "index": "test_mapping" },
  "dest":   { "index": "test_mapping_v2" }
}

ثمّ حوِّل القرّاء والكتّاب إلى test_mapping_v2، مثاليًّا عبر اسم مستعار (POST _aliases)، واحذف القديم.

كيف تتحقّق.

GET test_mapping_v2/_mapping

الحقل date من النّوع text بوضوح في الجواب.

9. LOAD CSV : « Couldn't load the external resource »

كيف تُستفَزّ.

./lab.sh reset
./lab.sh up
./lab.sh cypher 11-charger-news.cypher

من دون ./lab.sh import-news مُسبقًا، الملفّ neo4j/import/news.csv غير موجود.

الرّسالة الحرفيّة في خرج cypher-shell :

Couldn't load the external resource at: file:/import/news.csv

السّبب. يبحث LOAD CSV WITH HEADERS FROM 'file:///news.csv' عن الملفّ في مسار /import داخل مستوعب Neo4j — مسار مركَّب على ./neo4j/import/ من المضيف. لا يُكتب news.csv إلّا بأمر ./lab.sh import-news، الّذي يُنزّل المجموعة أوّلًا، ويُفهرسها في Elasticsearch، ثمّ يُنتج CSV لـ Neo4j.

كيف تُصلحها.

./lab.sh import-news
./lab.sh cypher 11-charger-news.cypher

كيف تتحقّق.

ls neo4j/import/

news.csv (نحو 25 MB) موجود، ويحسب apoc.meta.stats() في cypher-shell المقالات الـ 200 853، والفئات 41، والمؤلّفين 23 082.

10. CALL { ... } IN TRANSACTIONS في معاملة صريحة

كيف تُستفَزّ. افتح Neo4j Browser (http://localhost:7474) ونفّذ، من دون بادئة :auto :

LOAD CSV WITH HEADERS FROM 'file:///news.csv' AS ligne
CALL {
  WITH ligne
  MERGE (a:Article {id: toInteger(ligne.id)})
} IN TRANSACTIONS OF 1000 ROWS

الرّسالة الحرفيّة.

A query with 'CALL { ... } IN TRANSACTIONS' can only be executed in an implicit transaction, but tried to execute in an explicit transaction.

السّبب. يُغلّف Neo4j Browser افتراضيًّا كلّ استعلام في معاملة صريحة (BEGIN/COMMIT) لإتاحة زرّ الإلغاء. لكنّ CALL { } IN TRANSACTIONS — الصّياغة الّتي تعالج الأحمال الكبيرة على دفعات — يحتاج إلى معاملة ضمنيّة، تلك الّتي يُنشئها الخادم تلقائيًّا لكلّ أمر يُقدَّم. الوضعان غير متوافقَين.

كيف تُصلحها. صدِّر الاستعلام بـ :auto في Neo4j Browser:

:auto
LOAD CSV WITH HEADERS FROM 'file:///news.csv' AS ligne
CALL {
  WITH ligne
  MERGE (a:Article {id: toInteger(ligne.id)})
} IN TRANSACTIONS OF 1000 ROWS

:auto أمر خاصّ بالمتصفّح ينقل الاستعلام إلى الوضع الضّمنيّ. من cypher-shell، يقوم ./lab.sh cypher 11-charger-news.cypher بالعمل ذاته دون بادئة: يُشغَّل الملفّ في الوضع الضّمنيّ افتراضيًّا.

كيف تتحقّق. ينتهي الاستعلام بنجاح ويعيد apoc.meta.stats() عدد المقالات المتوقّع.

11. إجراء APOC غير معروف

كيف تُستفَزّ. أزل المِلحق مؤقّتًا:

docker exec veille-neo4j sh -c 'rm -f /plugins/apoc-*.jar'
docker restart veille-neo4j

ثمّ في cypher-shell :

CALL apoc.periodic.iterate(
  "MATCH (a:Article) RETURN a",
  "SET a.vu = true",
  {batchSize: 1000}
);

الرّسالة الحرفيّة.

There is no procedure with the name `apoc.periodic.iterate` registered for this database instance.
Please ensure you've spelled the procedure name correctly and that the procedure is properly deployed.

السّبب. APOC مكتبة إجراءات خارجيّة. لا تُضمَّن افتراضيًّا في Neo4j Community: تُنزّلها الحقيبة في أوّل تشغيل عبر NEO4J_PLUGINS=["apoc"] وتحفظها في الحجم neo4j-plugins. إن كان الحجم فارغًا أو تالفًا أو فشل التّنزيل عند أوّل up (شبكة محجوبة)، فإجراءات apoc.* غير مسجّلة.

كيف تُصلحها.

./lab.sh logs neo4j | grep -i apoc
./lab.sh down
./lab.sh up

يعرض السّجلّ Loading APOC plugins عند الإقلاع. إن غاب السّطر، تحقّق من أنّ docker-compose.yml يتضمّن فعلًا NEO4J_PLUGINS=["apoc"] وأنّ الحجم neo4j-plugins معلَن. كملاذ أخير، ./lab.sh reset ثمّ ./lab.sh up يُجبر تنزيلًا جديدًا.

كيف تتحقّق.

CALL apoc.help("apoc.periodic.iterate");

يُدرَج الإجراء مع توقيعه.

12. كلمة سرّ Neo4j عُدِّلت في .env ورُفضت

كيف تُستفَزّ. عدّل .env، استبدل NEO4J_PASSWORD=veille2026 بـ NEO4J_PASSWORD=nouveau2026، ثمّ:

./lab.sh down
./lab.sh up

حاول الاتّصال بـ Neo4j Browser بكلمة nouveau2026.

الرّسالة الحرفيّة.

The client is unauthorized due to authentication failure.

في ./lab.sh logs neo4j :

[o.n.k.a.p.SecurityLogFilter] Failed authentication attempt for 'neo4j' from ...

السّبب. متناظر مع الحالة 6. يكتب Neo4j التّجزئة (hash) لكلمة السّرّ في الحجم neo4j-data عند أوّل تشغيل. لا يُقرَأ NEO4J_AUTH=neo4j/${NEO4J_PASSWORD} إلّا في تلك اللّحظة؛ ثمّ تبقى كلمة السّرّ هي المخزَّنة في الحجم، لا في .env.

كيف تُصلحها. خياران.

الخيار أ — غيِّر كلمة السّرّ عبر cypher-shell بالمصادقة بالقديمة:

docker exec -it veille-neo4j cypher-shell -u neo4j -p veille2026 \
  "ALTER USER neo4j SET PASSWORD 'nouveau2026' CHANGE NOT REQUIRED;"

الخيار ب — انطلق من الصّفر:

./lab.sh reset
./lab.sh up

يختفي الحجم neo4j-data، وتُعاد قراءة المتغيّر NEO4J_AUTH عند أوّل تشغيل.

كيف تتحقّق.

docker exec veille-neo4j cypher-shell -u neo4j -p nouveau2026 \
  "RETURN 1 AS ok;"

يُعيد العمود ok القيمة 1 بلا خطأ مصادقة.

طريقة عامّة في خمس خطوات

حين لا تكون العطلة في أيّ من الاثنتَي عشرة السّابقة، طبّق التّسلسل نفسه:

1. اقرأ الحالة. ./lab.sh status — أيّ مستوعبات Up (healthy) وأيّها Exited (code) ؟ يُعطي الرّمز الأساسيّ (0 = طبيعيّ، 137 = OOM، 143 = SIGTERM، 1 = خطأ تطبيقيّ).
2. اقرأ سجلّات الخدمة المعنيّة. ./lab.sh logs <service> --tail=200. الرّسالة الحرفيّة تكون تقريبًا دائمًا في الأسطر الأخيرة. انسخها كلمة بكلمة.
3. اعزل الخدمة. اختبر كلّ لَبِنة على حدة: ./lab.sh es _cluster/health، ثمّ Kibana (/api/status)، ثمّ Neo4j (cypher-shell "RETURN 1;"). الأولى الّتي تُخفق هي المصدر.
4. أعِد التّهيئة على المستوى المناسب. ثلاث مراتب: docker restart <conteneur>، ثمّ ./lab.sh down / up (يُبقي الحجوم)، ثمّ ./lab.sh reset / up (يمحو كلّ شيء، آخر ملاذ). لا تُطبّق 3 من دون تجربة 1 و2 قبلها.
5. اطلب المساعدة بالمعلومات الصّحيحة. انسخ بالتّرتيب: الأمر المنفَّذ، وخرج ./lab.sh status، والأسطر العشرين الأخيرة من ./lab.sh logs <service>، و./lab.sh doctor، ونظام تشغيلك، وdocker version --format '{{.Server.Version}}'. تُتيح هذه الكتل الخمس لأيّ شخص إعادة إنتاج وضعك في ثلاثين ثانية.

السّجلّ محقّ

عمل السّجلّ الوحيد هو قول الحقيقة. كلّما فكّرت في «إعادة التّشغيل لنرى»، أعِد قراءة الأسطر العشرين الأخيرة أوّلًا. تسعًا من عشر، سيكون السّبب مكتوبًا بالحرف — وغالبًا مع أمر التّصحيح.

جرّب 1 — إعادة الإنتاج والقراءة

استفزّ العطلة 5 (فهرس للقراءة فقط) على فهرس اختبار، واكتب في ملفّ panne5.txt : الرّسالة الحرفيّة المُعادة، والأمر الّذي يُصلح، والأمر الّذي يتحقّق من الإصلاح.

الحلّ

PUT test_ro
{"settings":{"index":{"number_of_shards":1,"number_of_replicas":0}}}

PUT test_ro/_settings
{"index.blocks.read_only_allow_delete": true}

POST test_ro/_doc
{"x": 1}

الرّسالة:

cluster_block_exception, index [test_ro] blocked by: [FORBIDDEN/12/index read-only / allow delete (api)];

التّصحيح:

PUT test_ro/_settings
{"index.blocks.read_only_allow_delete": null}

التّحقّق:

POST test_ro/_doc
{"x": 2}

الجواب: {"result": "created"}. رُفع الحجب.

جرّب 2 — تشخيص بارد

يعرض عليك زميل شاشته: تعرض Kibana « Kibana server is not ready yet » منذ ثلاث دقائق. أعاد تشغيل متصفّحه ثلاث مرّات. اكتب التّسلسل الحرفيّ لثلاثة أوامر تُنفَّذ بالتّرتيب، دون تخمين، لتحديد السّبب.

الحلّ

./lab.sh status
./lab.sh logs setup --tail=50
./lab.sh logs elasticsearch --tail=50

يقول status هل veille-es وveille-setup بحال جيّد؛ يكشف logs setup عن فشل مواءمة كلمة سرّ kibana_system؛ يكشف logs elasticsearch مشكلة أعمق (heap مشبع، watermark، منفذ). إن مرّت الثّلاثة، ينهي ./lab.sh logs kibana --tail=50 التّشخيص. القاعدة: لا تُعِد التّشغيل قبل أن تقرأ.

جرّب 3 — الرّسالة الّتي تُنسَخ

حرّر، وكأنّك تفتح سؤالًا على قناة مساعدة داخليّة، الرّسالة المثاليّة للعطلة 12 (كلمة سرّ Neo4j مرفوضة بعد التّغيير). خمس كتل بترتيب الخطوة 5 من الطّريقة العامّة.

الحلّ

مرحبًا، يرفض لي Neo4j Browser المصادقة منذ تغيير كلمة السّرّ في .env.

الأمر المنفَّذ :
  docker exec veille-neo4j cypher-shell -u neo4j -p nouveau2026 "RETURN 1;"

./lab.sh status :
  veille-es       Up 8 minutes (healthy)   0.0.0.0:9200->9200/tcp
  veille-kibana   Up 7 minutes (healthy)   0.0.0.0:5601->5601/tcp
  veille-neo4j    Up 8 minutes (healthy)   0.0.0.0:7474->7474/tcp, 0.0.0.0:7687->7687/tcp

./lab.sh logs neo4j --tail=20 :
  ...
  [o.n.k.a.p.SecurityLogFilter] Failed authentication attempt for 'neo4j' from 172.19.0.5
  ...

./lab.sh doctor : كلّ شيء سليم، منافذ حرّة، ذاكرة 8 GB.

نظام التّشغيل : Windows 11 + WSL2 Ubuntu، Docker Desktop 29.0.2.

بعد ثلاثين ثانية، يعرف الشّخص الّذي يُساعد أنّها العطلة 12 ويُشير إلى ./lab.sh reset.

النقاط الأساسيّة

• تُغطّي اثنتا عشرة عطلًا شبه كلّ الحُصر الّتي تصيب الحقيبة: المنفذ، والذّاكرة، وvm.max_map_count، ولون العنقود، وwatermark، وكلمة سرّ Elasticsearch، وKibana غير جاهز، وmapping مُثبَّت، وLOAD CSV، و:auto، وAPOC، وكلمة سرّ Neo4j.
• خمس منها تُصحَّح بـ أمر واحد؛ اثنتان (كلمتا السّرّ 6 و12) تستلزمان ./lab.sh reset لأنّ بيانات الاعتماد تعيش في الحجم منذ أوّل تشغيل.
• يعطي رمز خروج المستوعب الأساس: 137 = OOM، و143 = SIGTERM، و1 = خطأ تطبيقيّ.
• تصمد الطّريقة العامّة في خمس خطوات — الحالة، والسّجلّات، والعزل، وإعادة التّهيئة المتدرّجة، والمساعدة المُعلَمة — على العطل الّتي لا تظهر في الجدول أيضًا.
• يكشف ./lab.sh doctor مسبقًا العطل 1 (المنافذ) و2 (الذّاكرة) و3 (vm.max_map_count) ؛ شغّله قبل أيّ شيء.
• السّجلّ محقّ دومًا: تحوي أسطر ./lab.sh logs <service> العشرون الأخيرة تقريبًا دائمًا السّبب الحرفيّ.
• رسالة مساعدة جيّدة (الأمر، الحالة، السّجلّات، doctor، نظام التّشغيل) توفّر ثلاثين دقيقة لمن يُساعد ولمن يطلب.

استكشاف الأخطاء

يُحيل هذا القسم إلى الجدول أعلاه: ابحث عن العَرَض الحرفيّ في عمود «العَرَض»، واتبع السّطر. إن لم تكن رسالة الخطأ فيه، طبّق الطّريقة العامّة في خمس خطوات وانسخ الكتل الخمس إلى شخص من الفريق. تسعًا من عشر، يصل الجواب قبل أن تنهي الكتابة.

للاستزادة

• Elasticsearch — Cluster allocation explain
• Elasticsearch — Fix a red or yellow cluster status
• Elasticsearch — Fix common cluster issues (watermark, mapping)
• Neo4j — Cypher CALL { } IN TRANSACTIONS