Fix cleanup coordination between Gunicorn and UvicornWorker lifecycles

• Document UvicornWorker hook limitations
• Add GUNICORN_CMD_ARGS cleanup guard
• Prevent double cleanup in workers

lightrag/api/gunicorn_config.py

@@ -168,8 +168,21 @@ def worker_exit(server, worker):
     """
     Executed when a worker is about to exit.
 
-    This is called for each worker process when it exits. We should only
-    clean up worker-local resources here, NOT the shared Manager.
+    NOTE: When using UvicornWorker (worker_class = "uvicorn.workers.UvicornWorker"),
+    this hook may NOT be called reliably. UvicornWorker has its own lifecycle
+    management that prioritizes ASGI lifespan shutdown events.
+
+    The primary cleanup mechanism is handled by:
+    1. FastAPI lifespan context manager with GUNICORN_CMD_ARGS check (in lightrag_server.py)
+       - Workers skip cleanup when GUNICORN_CMD_ARGS is set
+    2. on_exit() hook for main process cleanup
+
+    This function serves as a defensive fallback for:
+    - Non-UvicornWorker scenarios
+    - Future Gunicorn/Uvicorn behavior changes
+    - Additional safety layer
+
+    When called, we should only clean up worker-local resources, NOT the shared Manager.
     The Manager should only be shut down by the main process in on_exit().
     """
     print("=" * 80)

lightrag/api/lightrag_server.py

@@ -326,6 +326,10 @@ def create_app(args):
             # Clean up database connections
             await rag.finalize_storages()
 
+            # In Gunicorn mode with preload_app=True, cleanup is handled by worker_exit/on_exit hooks
+            # Only perform cleanup in Uvicorn single-process mode
+            if "GUNICORN_CMD_ARGS" not in os.environ:
+
                 # Clean up shared data
                 finalize_share_data()