Skip to content

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

feat(server): make HTTP keep-alive idle timeout configurable (#3743)

jiakun-lub8738e05f1fa
diff --git a/docs/en/configuration/01-server.md b/docs/en/configuration/01-server.md
index bd1cfa4db..702a6bd3c 100644
--- a/docs/en/configuration/01-server.md
+++ b/docs/en/configuration/01-server.md
@@ -233,6 +233,7 @@ This setting controls queue-job concurrency. It is separate from `vlm.media.max_
| `host` | IP / hostname | `"127.0.0.1"` | Listen address |
| `port` | integer | `1933` | Listen port |
| `workers` | integer | `1` | Worker process count |
+| `timeout_keep_alive` | integer (seconds) | `5` | Idle HTTP keep-alive timeout; raise it above the upstream's idle-connection lifetime |
| `auth_mode` | `dev`, `api_key`, `trusted` / `null` | `null` | Auth mode; null is inferred from `root_api_key` |
| `root_api_key` | string / `null` | `null` | Root key; setting it defaults auth to `api_key` |
| `cors_origins` | string[] | `["*"]` | Allowed origins |
diff --git a/docs/zh/configuration/01-server.md b/docs/zh/configuration/01-server.md
index ffce60be7..a90f0a0e9 100644
--- a/docs/zh/configuration/01-server.md
+++ b/docs/zh/configuration/01-server.md
@@ -233,6 +233,7 @@ Search 和 Find 请求的默认 `limit` 为 `10`,可以在每次 API 或 SDK
| `host` | IP / hostname | `"127.0.0.1"` | HTTP 监听地址 |
| `port` | integer | `1933` | HTTP 监听端口 |
| `workers` | integer | `1` | 服务进程数量 |
+| `timeout_keep_alive` | integer(秒) | `5` | 空闲 HTTP keep-alive 超时;应调大到超过上游空闲连接寿命 |
| `auth_mode` | `dev`、`api_key`、`trusted` / `null` | `null` | 鉴权模式;空值根据 `root_api_key` 自动判断 |
| `root_api_key` | string / `null` | `null` | Root API Key;配置后默认启用 `api_key` 模式 |
| `cors_origins` | string[] | `["*"]` | 允许的跨域来源 |
diff --git a/examples/ov.conf.example b/examples/ov.conf.example
index 5c5f3e88c..48e8c4c9b 100644
--- a/examples/ov.conf.example
+++ b/examples/ov.conf.example
@@ -2,6 +2,7 @@
"server": {
"host": "0.0.0.0",
"port": 1933,
+ "timeout_keep_alive": 5,
"root_api_key": null,
"cors_origins": ["*"],
"agent_evolution": {
diff --git a/openviking/server/bootstrap.py b/openviking/server/bootstrap.py
index cc50f180e..01c991f7d 100644
--- a/openviking/server/bootstrap.py
+++ b/openviking/server/bootstrap.py
@@ -318,10 +318,17 @@ def main():
host=config.host,
port=config.port,
workers=workers,
+ timeout_keep_alive=config.timeout_keep_alive,
log_config=None,
)
else:
- uvicorn.run(app, host=config.host, port=config.port, log_config=None)
+ uvicorn.run(
+ app,
+ host=config.host,
+ port=config.port,
+ timeout_keep_alive=config.timeout_keep_alive,
+ log_config=None,
+ )
finally:
# Cleanup vikingbot process on shutdown
if bot_process is not None:
diff --git a/openviking/server/config.py b/openviking/server/config.py
index 121c8328b..74deb5257 100644
--- a/openviking/server/config.py
+++ b/openviking/server/config.py
@@ -270,6 +270,15 @@ class ServerConfig(BaseModel):
host: str = "127.0.0.1"
port: int = 1933
workers: int = 1
+ # Seconds an idle HTTP keep-alive connection is kept open before the server
+ # closes it. Defaults to 5 to match uvicorn's built-in default and preserve
+ # the existing service behavior. Raise it above the idle-connection lifetime
+ # of any upstream client or load balancer that reuses connections (e.g. the
+ # serverless VKE forwarder keeps idle connections for up to 60s via
+ # WithMaxIdleConnDuration(1*time.Minute)); otherwise the server may close
+ # connections the client still believes are reusable, causing sporadic
+ # connection-reset / EOF errors.
+ timeout_keep_alive: int = 5
auth_mode: Optional[str] = None # If None, auto-detect based on root_api_key
root_api_key: Optional[str] = None
# OIDC/LDAP authentication configuration
diff --git a/tests/test_server_config_loader.py b/tests/test_server_config_loader.py
index c5ae73404..0a670d7e7 100644
--- a/tests/test_server_config_loader.py
+++ b/tests/test_server_config_loader.py
@@ -61,6 +61,7 @@ def test_load_server_config_preserves_supported_fields(tmp_path):
"host": "0.0.0.0",
"port": 1944,
"workers": 2,
+ "timeout_keep_alive": 120,
"auth_mode": "trusted",
"with_bot": True,
"bot_api_url": "http://localhost:19999",
@@ -77,6 +78,7 @@ def test_load_server_config_preserves_supported_fields(tmp_path):
assert config.host == "0.0.0.0"
assert config.port == 1944
assert config.workers == 2
+ assert config.timeout_keep_alive == 120
assert config.auth_mode == "trusted"
assert config.with_bot is True
assert config.bot_api_url == "http://localhost:19999"
@@ -84,6 +86,15 @@ def test_load_server_config_preserves_supported_fields(tmp_path):
assert config.encryption_enabled is True
+def test_load_server_config_defaults_timeout_keep_alive(tmp_path):
+ config_path = tmp_path / "ov.conf"
+ config_path.write_text(json.dumps({"server": {"host": "0.0.0.0"}}))
+
+ config = load_server_config(str(config_path))
+
+ assert config.timeout_keep_alive == 5
+
+
def test_load_server_config_rejects_legacy_queuefs_scope(tmp_path):
config_path = tmp_path / "ov.conf"
config_path.write_text(json.dumps({"server": {"queuefs_scope": "process"}}))