Yuxi 架构深度解析知识智能体的事务不变量与运行时边界【免费下载链接】Yuxi可私有部署的多租户知识智能体平台统一 RAG、知识图谱、多智能体、MCP/Skills、沙盒与权限管理。Yuxi Cloud Agents Knowledge RAG, Self-hosted knowledge agent platform for RAG, knowledge graphs and multi-agent workflows.项目地址: https://gitcode.com/GitHub_Trending/yu/Yuxi构建智能体系统时很多团队最先撞上的 bug 不是模型质量而是队列先于数据库看见了任务。Yuxi语析是一个可私有部署的多租户知识智能体平台把私有部署 RAG、知识图谱与 LangGraph 多智能体编排放进同一工作区它把这条次序放在架构顶层请求先提交 PostgreSQL提交成功后才向 ARQ 投递执行。本文不讲功能清单只讲运行时的工程决策为什么先落库再投队列为什么三种知识库后端里只有一条完整写链路为什么数据库 Schema 由单一迁移进程独占以及同一份文件字节如何在智能体、查看器和交付物之间保持一致。它是什么、不是什么多租户知识智能体平台的边界是什么统一 RAG 知识库、Neo4j 知识图谱、LangGraph 智能体编排、MCP/Skills 扩展、沙盒命令执行与用户/部门级权限治理的自托管平台。不是什么不带权限和文件操作的单文档聊天页——只需要那个场景时Yuxi 的能力偏多。适合谁必须自己管理数据、模型与权限边界的团队不适合追求开箱即用 SaaS 的团队。撑起运行时的三个抽象理解 Yuxi 的代码只需盯住三个概念其余模块都是它们的投影。Agent运行单元解决配置与执行漂移问题。backend/package/yuxi/agents/base.py的BaseAgent声明context_schema与capabilities运行时 Context 由 worker 一次准备manifest 与执行流消费同一个对象。运行例子模型与审批模式在请求接入时固定其余配置在 worker 准备时读取两个时间点不会因两次读取产生不同值。Workdir持久文件视图解决同一份文件在三个入口出现三种视图的问题。backend/package/yuxi/workspace/paths.py拥有 uid 到宿主根的映射filesystem.py提供 no-follow 文件原语目录 fd follow_symlinksFalseworkdir.py把浏览 scope 固定到一个 Project 根。运行例子智能体在沙盒写入的产物查看器预览与 artifact 下载读到同一份持久 POSIX 字节Run 终态清理 runtime 进程但保留 Workdir。Durable Task后台执行意图解决解析/索引失败后无人接手的问题。API 只持久化task_type handler_version payloadworker 从 registry 惰性加载领域 HandlerTask 行以唯一 owner、heartbeat 和 lease 闭合并发。运行例子解析失败把文件置为error_parsing重试走条件抢占同一文件不会被两个动作同时推进PG 中的 pending 行由启动与周期 publisher 补发。三者互相咬合Agent 的文件视图依赖 Workdir 的字节一致性Workdir 的物化发生在请求提交事务之后AgentRun 与 Durable Task 共享 PostgreSQL 事实与 ARQ 投递模式但被明确禁止合并状态模型——这是ARCHITECTURE.md里写死的边界。 四个塑造架构的决策请求为什么先落库再投队列submit_agent_request在同一数据库事务中创建用户消息、AgentRunRequest 并尝试派发 FIFO 队头db.commit()之后才执行enqueue_agent_run(dispatch.run_id)。被放弃的方案是先投队列再落库worker 可能领到一个数据库里查无请求的 Run幂等重放、断线恢复和 SSE 回读都失去一致的事实源。代价是多一次事务往返换来的是队列消息永远不先于数据库状态可见。值得注意的是两个边界条件提交失败时目录物化与投递都不发生——投递严格挂在 commit 成功之后见backend/package/yuxi/services/agent_request_service.py。实际派发的队头可能不是当前请求新请求 B 提交后可以把此前排队的 A 派出去因此投递依据事务返回的DispatchResult而不是从 B 的响应推测修复记录在 agent-runtime-simplification 决策。三条知识库写链路里只有一条是完整的backend/package/yuxi/knowledge/implementations/下有四个 executor但只有 Milvus 支持上传、解析、分块、向量索引与图谱构建的完整链路Dify 与 Notion 是只读连接器只保存外部连接信息并执行 Query。理由是事实源归属Dify/Notion 的数据所有权在外部系统让 Yuxi 回写就是双写者。被放弃的统一写抽象被收到不支持操作时明确报错替代前端按钮只反映 executor 能力最终判断由后端完成。失效场景值得提前知道Milvus 索引把 chunk 写 PostgreSQL、向量写 Milvus这不是跨存储事务任一侧失败时补偿并把文件置为error_indexing排查要同时看两侧文件状态机覆盖uploaded → parsed → indexed与error_parsing/error_indexing由条件抢占驱动机制见 知识库。前端路由守卫真正在做什么最终授权由后端 FastAPI 认证依赖与 repository 可见性查询执行web/src/router/index.js的全局守卫只做登录跳转与管理员页面体验。被放弃的方案是前端隐藏即授权——它防不住任何绕过路由直接调 API 的请求前端只负责体验的代价是授权逻辑全部收敛到数据层一处失守不代表系统失守。知识库权限治理的运行时机制用户权限与 Agent 的knowledges求交集后存为_visible_knowledge_bases快照工具的kb_id、file_id必须属于该快照Agent 选择只能缩小用户已有权限。失效场景运行中撤权不会刷新正在运行的 Context撤权从下一次 Run 生效——系统显式选择了 Run 级快照语义而非实时撤权。为什么由单一迁移进程独占数据库 Schemastorage-migrator是 Compose 中唯一修改 Yuxi 数据库 Schema 的进程在 PostgreSQL advisory lock 内执行 DDL 并记录 business 与 knowledge 两个域的版本API 与 worker 不建表、不执行收敛 DDL启动时只校验版本任一域缺失、过旧或过新即拒绝启动。被放弃的方案是每个进程自管理迁移多进程并发启动时 DDL 必然竞态而一次性 migrator 让Schema 何时变化成为唯一可观察事件。边界条件migrator 成功退出Exited 0是正常状态不是故障API 与 worker 等它完成并校验版本后才启动。若版本漂移结果是整套实例拒启动而不是 API 在运行时悄悄修表——后者会把迁移故障藏成线上 DDL 竞态。️ 一次请求的运行时链路从 POST 到 SSEWeb / CLI / 外部 API ↓ POST /api/agent/runs FastAPI校验用户与智能体构建 AgentRequestInput ↓ submit_agent_request同事务Message Request 派发队头 PostgreSQL 提交成功 ↓ enqueue_agent_run(run_id) Redis / ARQ 投递 AgentRun ↓ ARQ worker进程 identity attempt token 取得 lease → 准备 Context → 派生 manifest → 执行 LangGraph ↓ 过程事件 → Redis Stream前端 SSE 消费 终态、消息、审计 → PostgreSQL组件职责PostgreSQL业务事实、请求队列、Run 与 lease、LangGraph checkpoint最终状态唯一来源Redis / ARQ投递、短期事件、取消信号与带版本缓存不承担最终状态MinIO附件、知识库原件与解析 Markdown 等对象文件Milvuschunk 向量与 BM25/混合检索字段Neo4j可选知识图谱的实体与关系sandbox-provisioner动态创建隔离容器/Pod唯一持有 Docker socket这条链路上有两条关键不变量running/cancel_requested的 Run 必须由唯一 attempt lease 拥有heartbeat 只能由当前 owner 续租过期 ownership 不能被另一个执行者静默接管——这是 worker 失联恢复的并发闭合。取消先提交 PostgreSQL durable 状态再经 Redis key 轮询快速提示PostgreSQL watcher 兜底不使用 Pub/Sub——避免订阅断开时丢失取消信号。 部署拓扑与运维要点服务拓扑api、worker、storage-migrator、sandbox-provisioner、web、graphNeo4j、etcd、minio、milvus、postgres、redismineru-api与paddlex文档解析/OCR需要 GPU仅在allprofile 启动。关键端口API5050、Web5173、sandbox-provisioner8002沙盒之外的存储服务端口全部只绑127.0.0.1。就绪语义GET /api/system/ready要求 API、PostgreSQL、Redis 与兼容 worker 同时满足才返回 ready/api/system/health只表达 API 进程存活。沙盒隔离docker后端为每个沙盒创建独立 bridge 网络不接入应用网络、不发布端口memory后端仅用于单元测试不创建真实隔离环境生产必须用真实后端。密钥init.sh生成三个相互独立、各至少 32 字符的密钥JWT_SECRET_KEY、API_KEY_DERIVATION_SECRET、SANDBOX_PROVISIONER_TOKEN升级时必须保留原值。git clone --branch v0.7.3 --depth 1 https://gitcode.com/GitHub_Trending/yu/Yuxi cd Yuxi ./scripts/init.sh docker compose up --build -d curl --fail http://localhost:5050/api/system/ready技术栈速览层技术一句话职责前端Vue 3 / Vite / Pinia工作区、配置界面与 SSE 实时运行展示API 与编排FastAPI / LangGraph请求接入、智能体构图与中间件组合后台执行ARQ基于 RedisAgentRun 与 Durable Task 的 FIFO 派发单 worker 顺序消费持久化PostgreSQL业务事实、知识库元数据、checkpoint 与 Schema 唯一 Owner缓存与事件Redis投递、短期事件、取消信号与可失效缓存对象与检索MinIO / Milvus / Neo4j文件对象、向量索引与可选知识图谱文档处理MinerU / PaddleX / RapidOCR解析、版面分析与 OCR按需经allprofile 启用后端保持两个顶层边界backend/server是 HTTP 适配层只处理请求模型、认证上下文与响应装配新领域逻辑进backend/package/yuxi路由层不得绕过 repository 直接拼装持久化。边界、约束与再分发注意许可Yuxi 本体为 MIT LicenseCompose 引入的第三方组件遵循各自许可证生产部署与再分发前按实际镜像版本核对上游义务。只读后端Dify 与 Notion 知识库不支持上传、解析、索引系统不承诺为它们补齐写链路。测试专用模式memory沙盒后端不提供真实隔离kubernetes后端的隔离能力取决于集群与 Pod 安全策略。GPU 边界默认拓扑不要求 GPUMinerU、PP-Structure-V3 等本地 OCR 服务需要 GPU 且不默认启动。非事务边界Milvus 索引不是跨存储事务失败后文件停留error_indexing需两侧对账。决策可追溯非平凡变更要求先创建决策记录docs/develop-guides/decisions/下有 39 条 implemented 与 87 条 archived 记录本文每个决策都能在其中找到对应条目。继续深入的入口ARCHITECTURE.md先提交后投递不变量与三套后台状态边界的权威定义改主链路前先读它。Agent 运行时上下文理解配置字段如何进入一次 Run、Context 如何一次准备并被 manifest 与执行流复用。沙盒与文件系统机制runtime identity、挂载与回收语义是 Workdir 同字节约束的运行时落点。agent_request_queue_service.pyFIFO 派发、steer 与队列冲突判定的具体实现。决策记录规范proposed → implemented → archived 的生命周期解释了这套架构为什么能逐条回溯为什么这样做。队列消息是否先于数据库状态可见这个问题初看不起眼却决定系统的恢复下限。先落库再投递、字节单点归属、授权收敛到数据层都是对这条下限的不同变奏——它们共同回答了 Yuxi 作为私有部署 RAG 与多智能体平台时工程上最贵的那部分钱花在哪里。【免费下载链接】Yuxi可私有部署的多租户知识智能体平台统一 RAG、知识图谱、多智能体、MCP/Skills、沙盒与权限管理。Yuxi Cloud Agents Knowledge RAG, Self-hosted knowledge agent platform for RAG, knowledge graphs and multi-agent workflows.项目地址: https://gitcode.com/GitHub_Trending/yu/Yuxi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
