Skip to content

RAGFlow is an agent-native database: a Retrieval-Augmented Generation (RAG) engine that grew into context infrastructure.

fix(admin): display AWS S3 status correctly (#17300)

Paul Yao647cddc3ccc7
diff --git a/api/utils/health_utils.py b/api/utils/health_utils.py
index de11a58bc0..3cc6fc44a5 100644
--- a/api/utils/health_utils.py
+++ b/api/utils/health_utils.py
@@ -73,8 +73,8 @@ def check_doc_engine() -> tuple[bool, dict]:
def check_storage() -> tuple[bool, dict]:
st = timer()
try:
- settings.STORAGE_IMPL.health()
- return True, {"elapsed": f"{(timer() - st) * 1000.0:.1f}"}
+ health_result = settings.STORAGE_IMPL.health()
+ return health_result is not False, {"elapsed": f"{(timer() - st) * 1000.0:.1f}"}
except Exception as e:
return False, {"elapsed": f"{(timer() - st) * 1000.0:.1f}", "error": str(e)}
diff --git a/rag/utils/s3_conn.py b/rag/utils/s3_conn.py
index fe2a5ad248..d3623ef4f6 100644
--- a/rag/utils/s3_conn.py
+++ b/rag/utils/s3_conn.py
@@ -32,7 +32,7 @@ class RAGFlowS3:
self.access_key = self.s3_config.get("access_key", None)
self.secret_key = self.s3_config.get("secret_key", None)
self.session_token = self.s3_config.get("session_token", None)
- self.region_name = self.s3_config.get("region_name", None)
+ self.region_name = self.s3_config.get("region_name") or self.s3_config.get("region")
self.endpoint_url = self.s3_config.get("endpoint_url", None)
self.signature_version = self.s3_config.get("signature_version", None)
self.addressing_style = self.s3_config.get("addressing_style", None)
@@ -113,15 +113,15 @@ class RAGFlowS3:
return exists
def health(self):
- bucket = self.bucket
- fnm = "txtxtxtxt1"
- fnm, binary = f"{self.prefix_path}/{fnm}" if self.prefix_path else fnm, b"_t@@@1"
- if not self.bucket_exists(bucket):
- self.conn[0].create_bucket(Bucket=bucket)
- logging.debug(f"create bucket {bucket} ********")
-
- r = self.conn[0].upload_fileobj(BytesIO(binary), bucket, fnm)
- return r
+ try:
+ if self.bucket:
+ self.conn[0].head_bucket(Bucket=self.bucket)
+ else:
+ self.conn[0].list_buckets()
+ return True
+ except Exception as e:
+ logging.warning(f"S3 health check failed: {e}")
+ return False
def get_properties(self, bucket, key):
return {}
diff --git a/test/unit_test/api/utils/test_health_utils_storage.py b/test/unit_test/api/utils/test_health_utils_storage.py
new file mode 100644
index 0000000000..a2f27e8402
--- /dev/null
+++ b/test/unit_test/api/utils/test_health_utils_storage.py
@@ -0,0 +1,63 @@
+#
+# Copyright 2026 The InfiniFlow Authors. All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+
+from unittest.mock import Mock, patch
+
+from api.utils.health_utils import check_s3_alive, check_storage
+
+
+@patch("api.utils.health_utils.settings")
+def test_check_s3_alive_reports_success(mock_settings):
+ mock_settings.STORAGE_IMPL = Mock()
+ mock_settings.STORAGE_IMPL.health.return_value = True
+
+ result = check_s3_alive()
+
+ assert result["status"] == "alive"
+ assert "elapsed" in result["message"]
+
+
+@patch("api.utils.health_utils.settings")
+def test_check_s3_alive_reports_explicit_false_as_timeout(mock_settings):
+ # Storage backends (e.g. RAGFlowS3, MinIO, GCS) signal failure by
+ # returning False rather than raising; check_s3_alive must honor that.
+ mock_settings.STORAGE_IMPL = Mock()
+ mock_settings.STORAGE_IMPL.health.return_value = False
+
+ result = check_s3_alive()
+
+ assert result["status"] == "timeout"
+
+
+@patch("api.utils.health_utils.settings")
+def test_check_s3_alive_reports_exception_as_timeout(mock_settings):
+ mock_settings.STORAGE_IMPL = Mock()
+ mock_settings.STORAGE_IMPL.health.side_effect = ConnectionError("unavailable")
+
+ result = check_s3_alive()
+
+ assert result == {"status": "timeout", "message": "error: unavailable"}
+
+
+@patch("api.utils.health_utils.settings")
+def test_check_storage_respects_explicit_false_result(mock_settings):
+ mock_settings.STORAGE_IMPL = Mock()
+ mock_settings.STORAGE_IMPL.health.return_value = False
+
+ ok, metadata = check_storage()
+
+ assert ok is False
+ assert "elapsed" in metadata
diff --git a/test/unit_test/rag/utils/test_s3_conn.py b/test/unit_test/rag/utils/test_s3_conn.py
new file mode 100644
index 0000000000..c77178c8ee
--- /dev/null
+++ b/test/unit_test/rag/utils/test_s3_conn.py
@@ -0,0 +1,65 @@
+#
+# Copyright 2026 The InfiniFlow Authors. All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+
+import importlib
+from unittest.mock import Mock
+
+# rag.utils.s3_conn and common.settings import each other (s3_conn needs
+# settings.S3; settings re-imports RAGFlowS3). The cycle resolves only when
+# common.settings is imported first, the same order the app uses. Importing it
+# here before s3_conn lets both modules load fully so other tests that depend
+# on the real settings (e.g. db_models reads settings.DATABASE_TYPE) keep
+# working in the same session.
+import common.settings # noqa: F401 (imported for load-order side effect: breaks the s3_conn <-> settings cycle)
+from rag.utils import s3_conn
+
+
+def _new_storage(monkeypatch, config):
+ module = importlib.reload(s3_conn)
+ client = Mock()
+ monkeypatch.setattr(module.settings, "S3", config)
+ monkeypatch.setattr(module.boto3, "client", Mock(return_value=client))
+ return module.RAGFlowS3(), client, module.boto3.client
+
+
+def test_s3_accepts_region_config_key(monkeypatch):
+ storage, _, client_factory = _new_storage(monkeypatch, {"region": "us-east-1", "bucket": "ragflow"})
+
+ assert storage.region_name == "us-east-1"
+ client_factory.assert_called_once_with("s3", region_name="us-east-1")
+
+
+def test_s3_health_uses_head_bucket_without_writing(monkeypatch):
+ storage, client, _ = _new_storage(monkeypatch, {"bucket": "ragflow"})
+
+ assert storage.health() is True
+ client.head_bucket.assert_called_once_with(Bucket="ragflow")
+ client.create_bucket.assert_not_called()
+ client.upload_fileobj.assert_not_called()
+
+
+def test_s3_health_uses_list_buckets_without_default_bucket(monkeypatch):
+ storage, client, _ = _new_storage(monkeypatch, {})
+
+ assert storage.health() is True
+ client.list_buckets.assert_called_once_with()
+
+
+def test_s3_health_returns_false_on_client_error(monkeypatch):
+ storage, client, _ = _new_storage(monkeypatch, {"bucket": "ragflow"})
+ client.head_bucket.side_effect = ConnectionError("unavailable")
+
+ assert storage.health() is False