Skip to content

Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.

fix(server): 分阶段 lifespan 使 /health 在初始化期间可响应 (#1878)

A0nameless0man660835a09edb
diff --git a/openviking/server/app.py b/openviking/server/app.py
index 049d7e723..3be6d76f1 100644
--- a/openviking/server/app.py
+++ b/openviking/server/app.py
@@ -143,17 +143,9 @@ def create_app(
validate_server_config(config)
- @asynccontextmanager
- async def lifespan(app: FastAPI):
- """Application lifespan handler."""
- nonlocal service
- owns_service = service is None
- if owns_service:
- service = OpenVikingService()
- await service.initialize()
-
- assert service is not None
- set_service(service)
+ async def _deferred_init(service, app, config):
+ """Run heavy initialization in background after server starts accepting requests."""
+ await service.initialize()
# Initialize APIKeyManager after service (needs VikingFS)
effective_auth_mode = config.get_effective_auth_mode()
@@ -189,6 +181,19 @@ def create_app(
# AuthMode.DEV - logging already handled in validate_server_config
app.state.api_key_manager = None
+ logger.info("OpenVikingService initialization complete")
+
+ @asynccontextmanager
+ async def lifespan(app: FastAPI):
+ """Application lifespan handler."""
+ nonlocal service
+ owns_service = service is None
+ if owns_service:
+ service = OpenVikingService()
+
+ assert service is not None
+ set_service(service)
+
from openviking.metrics.global_api import (
init_metrics_from_server_config,
)
@@ -210,9 +215,28 @@ def create_app(
# Start MCP session manager (must be active before /mcp requests)
from openviking.server.mcp_endpoint import mcp_lifespan
+ deferred_task = None
+
async with mcp_lifespan():
+ # Start heavy initialization as background task after yield
+ if service is not None:
+ deferred_task = asyncio.create_task(_deferred_init(service, app, config))
+ deferred_task.add_done_callback(
+ lambda t: (
+ logger.error("Deferred initialization failed", exc_info=t.exception())
+ if t.exception()
+ else None
+ )
+ )
yield
+ # Wait for deferred initialization to complete before shutdown
+ if deferred_task and not deferred_task.done():
+ try:
+ await deferred_task
+ except Exception:
+ logger.exception("Deferred initialization failed")
+
# Cleanup
from openviking.metrics.global_api import shutdown_metrics_async
diff --git a/openviking/server/routers/system.py b/openviking/server/routers/system.py
index ee54c7bb8..b8a73e3e3 100644
--- a/openviking/server/routers/system.py
+++ b/openviking/server/routers/system.py
@@ -72,6 +72,21 @@ async def readiness_check(request: Request):
Returns 200 when all subsystems are operational, 503 otherwise.
No authentication required (designed for K8s probes).
"""
+ # If service is still initializing, return 503 immediately
+ try:
+ service = get_service()
+ if not service._initialized:
+ return JSONResponse(
+ status_code=503,
+ content={"status": "not_ready", "reason": "initializing"},
+ )
+ except RuntimeError:
+ # get_service() raises RuntimeError when service not yet set
+ return JSONResponse(
+ status_code=503,
+ content={"status": "not_ready", "reason": "initializing"},
+ )
+
checks = {}
# 1. AGFS: try to list root
diff --git a/tests/server/test_server_health.py b/tests/server/test_server_health.py
index 69445a485..15d3f1539 100644
--- a/tests/server/test_server_health.py
+++ b/tests/server/test_server_health.py
@@ -4,6 +4,7 @@
"""Tests for server infrastructure: health, system status, middleware, error handling."""
import asyncio
+import time
import httpx
@@ -56,3 +57,97 @@ async def test_lifespan_shutdown_ignores_cancelled_service_close():
async with app.router.lifespan_context(app):
pass
+
+
+async def test_health_responds_during_initialization(monkeypatch):
+ """Health endpoint responds 200 even during phased service initialization."""
+
+ # Service is "initializing" — _initialized is False
+ class MockService:
+ _initialized = False
+
+ service = MockService()
+ monkeypatch.setattr("openviking.server.dependencies._service", service)
+
+ app = create_app(config=ServerConfig(), service=service)
+ transport = httpx.ASGITransport(app=app)
+ async with httpx.AsyncClient(transport=transport, base_url="http://test") as client:
+ resp = await client.get("/health")
+ assert resp.status_code == 200
+ body = resp.json()
+ assert body["status"] == "ok"
+
+
+async def test_ready_returns_503_before_initialized(monkeypatch):
+ """Ready returns 503 when service._initialized is False."""
+
+ class MockService:
+ _initialized = False
+
+ service = MockService()
+ monkeypatch.setattr("openviking.server.dependencies._service", service)
+
+ app = create_app(config=ServerConfig(), service=service)
+ transport = httpx.ASGITransport(app=app)
+ async with httpx.AsyncClient(transport=transport, base_url="http://test") as client:
+ resp = await client.get("/ready")
+ assert resp.status_code == 503
+ body = resp.json()
+ assert body["status"] == "not_ready"
+ assert body["reason"] == "initializing"
+
+
+async def test_ready_returns_200_after_initialized(monkeypatch):
+ """Ready returns 200 when service is fully initialized and subsystems are healthy."""
+
+ class MockVikingFS:
+ async def ls(self, path, ctx=None):
+ return []
+
+ def _get_vector_store(self):
+ class MockVectorStore:
+ async def health_check(self):
+ return True
+
+ return MockVectorStore()
+
+ class MockService:
+ _initialized = True
+
+ service = MockService()
+ monkeypatch.setattr("openviking.server.dependencies._service", service)
+ monkeypatch.setattr("openviking.server.routers.system.get_viking_fs", lambda: MockVikingFS())
+ monkeypatch.setattr(
+ "openviking_cli.utils.ollama.detect_ollama_in_config",
+ lambda config: (False, None, None),
+ )
+
+ app = create_app(config=ServerConfig(), service=service)
+ transport = httpx.ASGITransport(app=app)
+ async with httpx.AsyncClient(transport=transport, base_url="http://test") as client:
+ resp = await client.get("/ready")
+ assert resp.status_code == 200
+ body = resp.json()
+ assert body["status"] == "ready"
+
+
+async def test_slow_init_does_not_block_health(monkeypatch):
+ """Health endpoint responds quickly even when initialization is slow."""
+
+ # Health is stateless — it doesn't call get_service() or depend on _initialized
+ class MockService:
+ _initialized = False
+
+ service = MockService()
+ monkeypatch.setattr("openviking.server.dependencies._service", service)
+
+ app = create_app(config=ServerConfig(), service=service)
+ transport = httpx.ASGITransport(app=app)
+ async with httpx.AsyncClient(transport=transport, base_url="http://test") as client:
+ start = time.perf_counter()
+ resp = await client.get("/health")
+ elapsed = time.perf_counter() - start
+
+ assert resp.status_code == 200
+ # Health responds instantly since it's stateless (no service dependency)
+ assert elapsed < 0.5