Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.
Python agent-contextagent-memoryagent-pluginsagentic-ragcontext-databasedsh-pluginknowledge-basememorymemory-managementself-evolvingvector-database
fix(server): 未配置 root_api_key 时仅允许 localhost 绑定 (#310)
Qin Haojie9e69113ad0de
diff --git a/docs/en/guides/04-authentication.md b/docs/en/guides/04-authentication.mdindex 57206983e..c6a76d768 100644--- a/docs/en/guides/04-authentication.md+++ b/docs/en/guides/04-authentication.md@@ -101,17 +101,19 @@ client = ov.SyncHTTPClient(## Development Mode-When no `root_api_key` is configured, authentication is disabled. All requests are accepted as ROOT with the default account.+When no `root_api_key` is configured, authentication is disabled. All requests are accepted as ROOT with the default account. **This is only allowed when the server binds to localhost** (`127.0.0.1`, `localhost`, or `::1`). If `host` is set to a non-loopback address (e.g. `0.0.0.0`) without a `root_api_key`, the server will refuse to start.```json{"server": {- "host": "0.0.0.0",+ "host": "127.0.0.1","port": 1933}}```+> **Security note:** The default `host` is `127.0.0.1`. If you need to expose the server on the network, you **must** configure `root_api_key`.+## Unauthenticated EndpointsThe `/health` endpoint never requires authentication. This allows load balancers and monitoring tools to check server health.diff --git a/docs/zh/guides/04-authentication.md b/docs/zh/guides/04-authentication.mdindex ae9dc5d7c..8b0030a22 100644--- a/docs/zh/guides/04-authentication.md+++ b/docs/zh/guides/04-authentication.md@@ -101,17 +101,19 @@ client = ov.SyncHTTPClient(## 开发模式-不配置 `root_api_key` 时,认证禁用。所有请求以 ROOT 身份访问 default account。+不配置 `root_api_key` 时,认证禁用,所有请求以 ROOT 身份访问 default account。**此模式仅允许在服务器绑定 localhost 时使用**(`127.0.0.1`、`localhost` 或 `::1`)。如果 `host` 设置为非回环地址(如 `0.0.0.0`)且未配置 `root_api_key`,服务器将拒绝启动。```json{"server": {- "host": "0.0.0.0",+ "host": "127.0.0.1","port": 1933}}```+> **安全提示:** 默认 `host` 为 `127.0.0.1`。如需将服务暴露到网络,**必须**配置 `root_api_key`。+## 无需认证的端点`/health` 端点始终不需要认证,用于负载均衡器和监控工具检查服务健康状态。diff --git a/openviking/server/app.py b/openviking/server/app.pyindex 99ee15f0d..038aeb25e 100644--- a/openviking/server/app.py+++ b/openviking/server/app.py@@ -11,7 +11,7 @@ from fastapi.middleware.cors import CORSMiddlewarefrom fastapi.responses import JSONResponsefrom openviking.server.api_keys import APIKeyManager-from openviking.server.config import ServerConfig, load_server_config+from openviking.server.config import ServerConfig, load_server_config, validate_server_configfrom openviking.server.dependencies import set_servicefrom openviking.server.models import ERROR_CODE_TO_HTTP_STATUS, ErrorInfo, Responsefrom openviking.server.routers import (@@ -50,6 +50,8 @@ def create_app(if config is None:config = load_server_config()+ validate_server_config(config)+@asynccontextmanagerasync def lifespan(app: FastAPI):"""Application lifespan handler."""@@ -72,7 +74,13 @@ def create_app(logger.info("APIKeyManager initialized")else:app.state.api_key_manager = None- logger.info("Dev mode: no root_api_key configured, authentication disabled")+ logger.warning(+ "Dev mode: no root_api_key configured, authentication disabled. "+ "This is allowed because the server is bound to localhost (%s). "+ "Do NOT expose this server to the network without configuring "+ "server.root_api_key in ov.conf.",+ config.host,+ )yielddiff --git a/openviking/server/config.py b/openviking/server/config.pyindex 37d3f3762..9b1631d69 100644--- a/openviking/server/config.py+++ b/openviking/server/config.py@@ -2,9 +2,11 @@# SPDX-License-Identifier: Apache-2.0"""Server configuration for OpenViking HTTP Server."""+import sysfrom dataclasses import dataclass, fieldfrom typing import List, Optional+from openviking_cli.utils import get_loggerfrom openviking_cli.utils.config.config_loader import (DEFAULT_OV_CONF,OPENVIKING_CONFIG_ENV,@@ -12,12 +14,14 @@ from openviking_cli.utils.config.config_loader import (resolve_config_path,)+logger = get_logger(__name__)+@dataclassclass ServerConfig:"""Server configuration (from the ``server`` section of ov.conf)."""- host: str = "0.0.0.0"+ host: str = "127.0.0.1"port: int = 1933root_api_key: Optional[str] = Nonecors_origins: List[str] = field(default_factory=lambda: ["*"])@@ -59,10 +63,47 @@ def load_server_config(config_path: Optional[str] = None) -> ServerConfig:server_data = data.get("server", {})config = ServerConfig(- host=server_data.get("host", "0.0.0.0"),+ host=server_data.get("host", "127.0.0.1"),port=server_data.get("port", 1933),root_api_key=server_data.get("root_api_key"),cors_origins=server_data.get("cors_origins", ["*"]),)return config+++_LOCALHOST_HOSTS = {"127.0.0.1", "localhost", "::1"}+++def _is_localhost(host: str) -> bool:+ """Return True if *host* resolves to a loopback address."""+ return host in _LOCALHOST_HOSTS+++def validate_server_config(config: ServerConfig) -> None:+ """Validate server config for safe startup.++ When ``root_api_key`` is not set, authentication is disabled (dev mode).+ This is only acceptable when the server binds to localhost. Binding to a+ non-loopback address without authentication exposes an unauthenticated ROOT+ endpoint to the network.++ Raises:+ SystemExit: If the configuration is unsafe.+ """+ if config.root_api_key:+ return++ if not _is_localhost(config.host):+ logger.error(+ "SECURITY: server.root_api_key is not configured and server.host "+ "is '%s' (non-localhost). This would expose an unauthenticated "+ "ROOT endpoint to the network.",+ config.host,+ )+ logger.error(+ "To fix, either:\n"+ " 1. Set server.root_api_key in ov.conf, or\n"+ ' 2. Bind to localhost (server.host = "127.0.0.1")'+ )+ sys.exit(1)diff --git a/tests/server/test_auth.py b/tests/server/test_auth.pyindex dd856dfce..ce919e44e 100644--- a/tests/server/test_auth.py+++ b/tests/server/test_auth.py@@ -4,10 +4,11 @@"""Tests for multi-tenant authentication (openviking/server/auth.py)."""import httpx+import pytestimport pytest_asynciofrom openviking.server.app import create_app-from openviking.server.config import ServerConfig+from openviking.server.config import ServerConfig, _is_localhost, validate_server_configfrom openviking.server.dependencies import set_servicefrom openviking.service.core import OpenVikingServicefrom openviking_cli.session.user_id import UserIdentifier@@ -199,3 +200,40 @@ async def test_cross_tenant_session_get_returns_not_found(auth_client: httpx.Asy)assert cross_get.status_code == 404assert cross_get.json()["error"]["code"] == "NOT_FOUND"+++# ---- _is_localhost tests ----++[email protected]("host", ["127.0.0.1", "localhost", "::1"])+def test_is_localhost_true(host: str):+ assert _is_localhost(host) is True++[email protected]("host", ["0.0.0.0", "::", "192.168.1.1", "10.0.0.1"])+def test_is_localhost_false(host: str):+ assert _is_localhost(host) is False+++# ---- validate_server_config tests ----+++def test_validate_no_key_localhost_passes():+ """No root_api_key + localhost should pass validation."""+ for host in ("127.0.0.1", "localhost", "::1"):+ config = ServerConfig(host=host, root_api_key=None)+ validate_server_config(config) # should not raise+++def test_validate_no_key_non_localhost_raises():+ """No root_api_key + non-localhost should raise SystemExit."""+ config = ServerConfig(host="0.0.0.0", root_api_key=None)+ with pytest.raises(SystemExit):+ validate_server_config(config)+++def test_validate_with_key_any_host_passes():+ """With root_api_key set, any host should pass validation."""+ for host in ("0.0.0.0", "::", "192.168.1.1", "127.0.0.1"):+ config = ServerConfig(host=host, root_api_key="some-secret-key")+ validate_server_config(config) # should not raise