Skip to content

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

fix(server): 未配置 root_api_key 时仅允许 localhost 绑定 (#310)

Qin Haojie9e69113ad0de
diff --git a/docs/en/guides/04-authentication.md b/docs/en/guides/04-authentication.md
index 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 Endpoints
The `/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.md
index 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.py
index 99ee15f0d..038aeb25e 100644
--- a/openviking/server/app.py
+++ b/openviking/server/app.py
@@ -11,7 +11,7 @@ from fastapi.middleware.cors import CORSMiddleware
from fastapi.responses import JSONResponse
from 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_config
from openviking.server.dependencies import set_service
from openviking.server.models import ERROR_CODE_TO_HTTP_STATUS, ErrorInfo, Response
from openviking.server.routers import (
@@ -50,6 +50,8 @@ def create_app(
if config is None:
config = load_server_config()
+ validate_server_config(config)
+
@asynccontextmanager
async 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,
+ )
yield
diff --git a/openviking/server/config.py b/openviking/server/config.py
index 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 sys
from dataclasses import dataclass, field
from typing import List, Optional
+from openviking_cli.utils import get_logger
from 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__)
+
@dataclass
class ServerConfig:
"""Server configuration (from the ``server`` section of ov.conf)."""
- host: str = "0.0.0.0"
+ host: str = "127.0.0.1"
port: int = 1933
root_api_key: Optional[str] = None
cors_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.py
index 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 pytest
import pytest_asyncio
from openviking.server.app import create_app
-from openviking.server.config import ServerConfig
+from openviking.server.config import ServerConfig, _is_localhost, validate_server_config
from openviking.server.dependencies import set_service
from openviking.service.core import OpenVikingService
from 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 == 404
assert 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