DeerFlow 接入 OpenViking 长期记忆后端认证边界、配置全解与失败语义【免费下载链接】deer-flowAn open-source long-horizon SuperAgent harness that researches, codes, and creates. With the help of sandboxes, memories, tools, skill, subagents and message gateway, it handles different levels of tasks that could take minutes to hours.项目地址: https://gitcode.com/GitHub_Trending/de/deer-flow本文以 docs/OPENVIKING.md 为主体完整讲解 DeerFlow 的 OpenViking 长期记忆后端如何用 USER API Key 配置manager_class: openviking、如何启动并验证 OpenViking 服务、线程到 Session 的确定性映射规则以及读取/写入失败策略、哈希游标与优雅关闭的底层实现。读完后你可以独立完成该后端的部署配置并从源码层面理解其身份隔离与数据一致性边界。OpenViking 后端定位与当前范围DeerFlow 支持把远程 OpenViking 服务器作为可选的长期记忆后端默认后端仍是 DeerMem。该后端不自行实现 OpenViking 的 HTTP 协议而是直接使用官方维护的langchain-openviking中通过常规uv sync流程安装。首个官方适配器集成刻意保留 DeerFlow 现有的自动记忆行为记忆通过 DeerFlow 既有的固定记忆查询fixed memory query召回已完成的轮次由现有 memory middleware 捕获即将被压缩compaction的消息由现有 summarization hook 捕获每条被接受的捕获都提交到该线程稳定的 OpenViking Session消息转换、工具调用与结果处理、100 条消息分批、部分写入进度记录、提交重试和 SDK 传输全部由官方适配器负责一个由 recorder 拥有的 SDK 客户端与检索共享并通过 DeerFlow 既有的 memory 关闭契约统一关闭。明确的范围边界这些不是缺陷而是有意为之仅支持memory.mode: middleware。在 OpenVikingMemoryManager.from_config 中mode ! middleware会直接抛出ValueError并提示需要模型主动调用记忆工具时应走 OpenViking MCP不实现 DeerMem 的 fact CRUD、导入/导出也不提供 Settings 中的记忆文档视图OpenViking MCP 工具是另一个独立的集成面不由该后端启用见 extensions_config.example.json 中默认enabled: false的openvikingMCP 条目。认证边界一个 USER Key 绑定一个 DeerFlow 用户api_key 模式是唯一支持的服务器配置当前版本面向「一个 DeerFlow 用户 一个普通 OpenVikingUSER API Key」的部署形态。OpenViking 从该凭据推导 account 和 userDeerFlow 不配置 trusted account/user 请求头正常记忆流量也不应持有 root key。支持的服务端配置是 OpenViking 的api_key模式DeerFlow 显式提供 URL 与 API Key在记忆操作中覆盖任何环境里的 actor peer且不继承ovcli.conf中的任意 HTTP 头。源码中这一点有明确对应OpenVikingMemoryManager 构造 recorder 时传入extra_headers{}注释写明该显式映射会禁用 SDK 的 ovcli.conf 头回退每次操作再用use_actor_peer作用域覆盖环境身份。启用该后端前的清理清单从 DeerFlow 仓库根.env和服务环境中移除遗留的OPENVIKING_ACCOUNT、OPENVIKING_USER从~/.openviking/ovcli.conf移除account、user默认值。这些设置属于 trusted 模式不在本适配器的支持范围内。配置校验在启动期就会拦截遗留字段OpenVikingConfig.from_backend_config 检测到auth_mode或account字段会直接抛错trusted mode is no longer supported自定义 HTTP 客户端字段如connect_timeout_seconds、max_retries等同样被拒。owner_user_id防止一个 Key 被多个用户共享owner_user_id把配置好的 Key 绑定到一个 DeerFlow 身份DeerFlow 认证关闭时用default启用认证的单用户部署填该用户的 DeerFlow ID。请求属于其他 DeerFlow 用户时会在联系 OpenViking 之前被拒绝避免一个 USER Key 在用户之间静默共享记忆。源码中的强制点在 _resolve_scoperesolved_user str(user_id or default) if resolved_user ! self._config.owner_user_id: raise MemoryManagerError( fOpenViking USER API key is bound to DeerFlow owner_user_id f{self._config.owner_user_id!r}, but this request belongs to f{resolved_user!r}. Refusing to share one credential across users. )多用户的凭据供给与存储被有意排除在第一个适配器之外。旧 trusted 模式配置不会自动迁移现有 trusted 模式配置不会被自动迁移。需要把 OpenViking 服务器配置为api_key模式用owner_user_id USER Key 替换auth_mode、account和 root key并移除上述遗留环境身份设置。由于凭据绑定的 user/Session 映射与旧的 trusted-user 映射不同先前捕获的 trusted 模式数据会留在其旧的 OpenViking 命名空间中不会被静默重分配。配置 DeerFlow第一步写入 .env 与 config.yaml在 OpenViking 中创建或选择用户把其 USER API Key 写入 DeerFlow 仓库根.envOPENVIKING_API_KEYreplace-with-an-openviking-user-api-key在config.yaml中选择后端memory: enabled: true injection_enabled: true shutdown_flush_timeout_seconds: 30 manager_class: openviking mode: middleware backend_config: base_url: http://127.0.0.1:1933 owner_user_id: default api_key_env: OPENVIKING_API_KEY startup_policy: fail_fast failure_policy: read: fail_open write: log_and_drop retrieval: top_k: 8 score_threshold: 0.25 max_injection_chars: 12000 content_mode: overview injection_query: - user profile preferences important entities events ongoing goals constraints and prior decisions同一份示例也内嵌在 config.example.yaml 的 memory 配置注释区manager_class: openviking时替换默认 DeerMem 的backend_config块。backend_config 完整参数表源码校验值下表由 OpenVikingConfig 的默认值与_validate()取值范围整理可复制到实际配置中使用参数默认值取值范围 / 说明base_urlhttp://127.0.0.1:1933必须是绝对 http(s) URL纯 HTTP 仅允许127.0.0.1/localhost/openviking其他主机必须 HTTPS 或显式allow_insecure_http: trueowner_user_id必填无默认绑定 Key 的 DeerFlow 用户 ID认证关闭时用default空值启动失败api_key_envOPENVIKING_API_KEY存放 USER Key 的环境变量名Key 缺失时启动失败fail_fast语义default_peer_iddeerflow默认 agent 的 OpenViking peer ID必须匹配^[a-z0-9][a-z0-9_-]{0,63}$且不得以保留前缀df-agent-开头timeout_seconds30.0必须为 0 的有限数值storage_path空用 DeerFlow base_dir本地哈希游标根目录前缀startup_policyfail_fastfail_fast或warn控制启动期健康检查失败是否直接抛错failure_policy.readfail_openfail_open记日志并返回无注入记忆或raise向调用方传播failure_policy.writelog_and_droplog_and_drop记日志不使已生成的回答失败或raiseallow_insecure_httpfalse受信内网下才置truemax_seen_message_ids512有界哈希游标容量范围 16–10000retrieval.top_k81–100retrieval.score_threshold无阈值null0–1 的有限数值retrieval.max_injection_chars12000256–100000retrieval.content_modeoverviewauto/abstract/overview/readretrieval.injection_query与上文示例相同固定记忆查询不得为空此外任何未识别的backend_config顶层字段、retrieval.*或failure_policy.*字段都会触发启动期报错config.py#L98-L106可以防止拼写错误被静默忽略。宿主安装 vs Docker 部署的地址差异宿主安装 OpenViking、Docker 运行 DeerFlowbase_url设为http://host.docker.internal:1933并配allow_insecure_http: true使用仓库自带的可选 Compose overlay 时走容器网络内部地址http://openviking:1933该主机名在纯 HTTP 白名单内无需allow_insecure_http。启动服务本地进程先起 OpenViking 并验证openviking-server doctor openviking-server curl http://127.0.0.1:1933/health随后正常启动 DeerFlowmake doctor make devDeerFlow 位于http://localhost:2026OpenViking Studio 位于http://localhost:1933/studio可在 Studio 中人工检查记忆捕获与 Session 归档。Docker可选 Compose overlaydocker compose \ -f docker/docker-compose.yaml \ -f docker/docker-compose.openviking.yaml \ up -d openviking docker exec -it deer-flow-openviking openviking-server init docker compose \ -f docker/docker-compose.yaml \ -f docker/docker-compose.openviking.yaml \ up -d --buildoverlay 文件 的关键点镜像默认${OPENVIKING_IMAGE:-ghcr.io/volcengine/openviking:latest}以--without-bot启动端口映射${OPENVIKING_PORT:-1933}:1933数据卷openviking-data挂到容器内/app/.openviking健康检查通过/health探测且gateway服务depends_on: openviking: condition: service_healthy——即 OpenViking 不就绪时 gateway 不会被拉起。启动后把 OpenViking 配置为 API-key 模式通过其身份管理流程获取 USER Key只有这个 USER Key应写入 DeerFlow 的OPENVIKING_API_KEY变量。身份与会话映射线程 → Session → Peer一个 DeerFlow 线程确定性地映射为一个 OpenViking SessionSession ID 由 session.py 中的_session_id派生对deerflow-openviking-adapter-v1命名空间 owner_user_idpeer_idthread_id做 SHA-256取前 48 个十六进制字符加df_前缀。commit 在该 Session 内部创建 archive而不创建新 Session——因此用户稍后回来时线程保持同一身份。Peer用户内部的作用域分离默认 DeerFlow agent 使用default_peer_id默认deerflow具名 agent 使用小写 OpenViking peer IDagent 名 strip lower不是合法 peer ID、与默认值冲突、或进入保留的df-agent-命名空间的名字会映射到抗碰撞 ID_canonical_peer_id 对其 SHA-256 摘要取前 32 位拼上df-agent-前缀保证与合法名互不别名USER Key 身份始终是安全边界peer 只在该用户内部隔离记忆作用域。检索时_memory_target_uris 同时查询viking://user/memories用户全局与viking://user/peers/{peer_id}/memories当前 peer。在 get_context 中如果请求带thread_id检索器切换为search模式并绑定该线程的 Session否则为find模式做跨 Session 检索。重试、游标与失败语义读写失败策略的落点read: fail_open检索失败记日志并返回空字符串无注入记忆read: raise向 DeerFlow 调用方传播异常。对应 get_context / search 的异常分支捕获异常后按策略raise或logger.warning降级。write: log_and_drop捕获失败记日志但不使已生成的回答失败write: raise则抛出MemoryManagerError。见 _handle_write_error。启动期健康检查由startup_policy控制fail_fast下不健康直接抛错warn下降级运行warm。只存哈希的本地捕获游标DeerFlow 只在{storage_path}/openviking/sessions/下维护一个有界的本地捕获游标其中只有哈希与计数器从不存消息文本。游标的作用防止把完整的 LangGraph transcript 快照重复提交每次捕获前用 _matching_prefix_count 比对已提交前缀或基于submitted_prefix_count 前缀摘要处理压缩后的情况记录部分批次中已确认的进度在追加更多消息前先重试失败的 commit见下文不可读的游标按失败关闭处理重放未知前缀可能复制私有对话历史_load_cursor 对读不到/解析失败的游标直接抛MemoryManagerError拒绝不安全重放。游标写入采用「临时文件 os.replace」的原子替换_save_cursor避免半写状态。消息签名的计算见 _message_signature对id / role / content / tool_calls / tool_call_id / tool_name / tool_status做规范化 JSON 后 SHA-256因此工具调用与结果的变化也会被感知。部分写入与提交重试捕获路径 _capture_locked 的流程若游标标记commit_pending先调用recorder.flush(session_id)重试上次未完成的提交重试失败则按写策略处理并保留游标计算已提交前缀只提交增量pending消息捕获官方适配器抛出的OpenVikingPartialWriteError按input_messages_consumed把已确认前缀写入游标commit_pending一并记录下次捕获时先重试 commit其他异常不推进游标全部成功后推进游标并清空commit_pending。整个写入在每 Session 一把RLock_session_lock下串行避免并发捕获互相覆盖游标。优雅关闭shutdown_flush(timeout)openviking_manager.py#L288-L301置关闭标志停止新工作在shutdown_flush_timeout_seconds预算内等待已接受的操作排空然后关闭 recorder 拥有的 SDK 客户端。它不引入新的 DeerFlow 生命周期或后台 worker完全复用既有 memory 关闭契约。明确的局限不承诺 at-least-once对于「丢失一次记忆更新不可接受」的部署仍然需要引入持久化 outbox。该初始集成不声称 at-least-once 投递——write: log_and_drop下的写入丢失是有意的可恢复性取舍而非静默承诺。适用前提与验证路径仅支持memory.mode: middleware需要模型显式记忆工具时走 OpenViking MCP独立集成面需要openviking-sdk0.1.6,0.2import 检查 在缺少 request-scoped actor-peer 支持时会明确报错服务器必须处于api_key模式.env/ovcli.conf中不得残留 trusted 模式的身份字段行为验证可参考仓库内测试backend/tests/test_openviking_memory_backend.py 覆盖配置校验、游标与失败语义backend/tests/test_openviking_mcp_integration.py 覆盖 MCP 集成面。按上述步骤完成配置后DeerFlow 会在每轮对话后把可捕获消息增量提交到该线程的 OpenViking Session并在下一轮按固定查询把记忆注入系统提示整个链路的身份隔离由 USER Key owner_user_id双重约束任何跨用户访问都会在触达 OpenViking 之前被拒绝。【免费下载链接】deer-flowAn open-source long-horizon SuperAgent harness that researches, codes, and creates. With the help of sandboxes, memories, tools, skill, subagents and message gateway, it handles different levels of tasks that could take minutes to hours.项目地址: https://gitcode.com/GitHub_Trending/de/deer-flow创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考