docs(api): update docs about gevent setup in app.py (#27611)

Add a warning about top level importing in gunicorn.conf.py

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

api/README.md

@@ -80,7 +80,7 @@
 1. If you need to handle and debug the async tasks (e.g. dataset importing and documents indexing), please start the worker service.
 
 ```bash
-uv run celery -A app.celery worker -P gevent -c 2 --loglevel INFO -Q dataset,mail,ops_trace,app_deletion,plugin,workflow_storage,conversation,priority_pipeline,pipeline
+uv run celery -A app.celery worker -P threads -c 2 --loglevel INFO -Q dataset,mail,ops_trace,app_deletion,plugin,workflow_storage,conversation,priority_pipeline,pipeline
 ```
 
 Additionally, if you want to debug the celery scheduled tasks, you can run the following command in another terminal to start the beat service:

api/app.py

@@ -13,23 +13,12 @@ if is_db_command():
 
     app = create_migrations_app()
 else:
-    # It seems that JetBrains Python debugger does not work well with gevent,
-    # so we need to disable gevent in debug mode.
-    # If you are using debugpy and set GEVENT_SUPPORT=True, you can debug with gevent.
-    # if (flask_debug := os.environ.get("FLASK_DEBUG", "0")) and flask_debug.lower() in {"false", "0", "no"}:
-    # from gevent import monkey
+    # Gunicorn and Celery handle monkey patching automatically in production by
+    # specifying the `gevent` worker class. Manual monkey patching is not required here.
     #
-    # # gevent
-    # monkey.patch_all()
+    # See `api/docker/entrypoint.sh` (lines 33 and 47) for details.
     #
-    # from grpc.experimental import gevent as grpc_gevent  # type: ignore
-    #
-    # # grpc gevent
-    # grpc_gevent.init_gevent()
-
-    # import psycogreen.gevent  # type: ignore
-    #
-    # psycogreen.gevent.patch_psycopg()
+    # For third-party library patching, refer to `gunicorn.conf.py` and `celery_entrypoint.py`.
 
     from app_factory import create_app
 

api/gunicorn.conf.py

@@ -2,6 +2,19 @@ import psycogreen.gevent as pscycogreen_gevent  # type: ignore
 from gevent import events as gevent_events
 from grpc.experimental import gevent as grpc_gevent  # type: ignore
 
+# WARNING: This module is loaded very early in the Gunicorn worker lifecycle,
+# before gevent's monkey-patching is applied. Importing modules at the top level here can
+# interfere with gevent's ability to properly patch the standard library,
+# potentially causing subtle and difficult-to-diagnose bugs.
+#
+# To ensure correct behavior, defer any initialization or imports that depend on monkey-patching
+# to the `post_patch` hook below, or use a gevent_events subscriber as shown.
+#
+# For further context, see: https://github.com/langgenius/dify/issues/26689
+#
+# Note: The `post_fork` hook is also executed before monkey-patching,
+# so moving imports there does not resolve this issue.
+
 # NOTE(QuantumGhost): here we cannot use post_fork to patch gRPC, as
 # grpc_gevent.init_gevent must be called after patching stdlib.
 # Gunicorn calls `post_init` before applying monkey patch.
@@ -11,7 +24,7 @@ from grpc.experimental import gevent as grpc_gevent  # type: ignore
 # ref:
 # - https://github.com/grpc/grpc/blob/62533ea13879d6ee95c6fda11ec0826ca822c9dd/src/python/grpcio/grpc/experimental/gevent.py
 # - https://github.com/gevent/gevent/issues/2060#issuecomment-3016768668
-# - https://github.com/benoitc/gunicorn/blob/master/gunicorn/arbiter.py#L607-L613
+# - https://github.com/benoitc/gunicorn/blob/23.0.0/gunicorn/arbiter.py#L605-L609
 
 
 def post_patch(event):