基于 PostgreSQL 和 Redis 的自托管 LangGraph Agent 服务器

了解 Langhost 如何用 Postgres 和 Redis 替代 LangGraph 的持久化层，从而使团队能够根据 MIT 许可证自行托管未经修改的 Agent Server。

1503 词

无需更改 LangGraph SDK、Studio 和 Agent Server 的原有结构。只需将持久化状态存储到 Postgres 中，协调任务交由 Redis 处理，整个过程都不需要运行时许可证密钥。

编写 LangGraph 代理通常是最简单的部分。

你在本地运行图结构，相关工具执行任务，状态在节点间流转。但随后总会有人提出一个问题，让原型变成真正的实际应用难题：如何让它在真实的生产环境中运行？

代理服务器需要处理的内容远比简单的请求-响应API复杂得多。对话功能需要能够跨会话持续存在的持久线程。某些任务会在等待人工审批某个步骤时暂停，之后很久才继续执行。客户端期望收到一系列事件流而非单一响应。即使有多个工作节点同时尝试处理定时任务，也必须确保这些任务仅被触发一次。此外，如果某个工作节点在运行过程中崩溃，另一个工作节点需要干净地接管任务，不能导致状态损坏。

langgraph dev适用于本地开发，LangChain的文档也明确将其定义为开发服务器而非生产环境服务器。它将状态存储在内存和本地文件夹中。而用于生产环境的正式方案是LangSmith Deployments，该服务既可作为托管服务使用，也可通过自托管许可证获取。

Langhost 提出了一条不同的路径。它在 Postgres 和 Redis 之上运行未经修改的 LangGraph Agent Server，并使用基于 MIT 许可证发布的持久化运行时。

表面上看这只是一个小改动，确实如此，但正因如此才值得关注。

让 Langhost 变得有趣的设计选择

Langhost 并没有重新实现 Agent 协议或强制应用程序使用不同的 API，而是保留了官方的 Agent Server 包 langgraph-api 不变。发生变化的是其底层架构：langgraph-runtime-pg 包负责处理持久化功能。

各组件的大致组合方式如下：

LangSmith Studio, SDK clients, Chat UI, MCP, A2A
                         |
                   langhost serve
                         |
              stock langgraph-api
                         |
              langgraph-runtime-pg
                    /          \
              Postgres        Redis

现有的应用程序会保持其图结构定义及langgraph.json文件不变。客户端继续使用langgraph-sdk进行通信。Studio则通过其一贯使用的Agent Server API保持连接。Langhost刻意避免在该接口处做任何复杂的处理，这正是基础设施应有的设计思路。

由于官方服务器包保持不变，其全部功能也能在切换后继续正常使用：管理助手、追踪线程与单次运行记录、提供键值存储功能、执行定时任务、推送流式输出、调用 webhook，同时支持 MCP 和 A2A 协议。其他竞争性的服务器实现则需要不断跟踪各种协议变更才能维持这些功能的正常运行。而 Langhost 通过将协议实现交由上游服务器处理，仅专注于存储与协调功能，从而完全避免了这类维护负担。

Postgres 和 Redis 的各自功能

Postgres保存了重启后仍需保留的所有内容：助手配置、线程历史记录、运行日志、定时任务定义、检查点以及存储在其中的所有应用数据。模式迁移通过Alembic来实现。对于生产环境部署，项目建议在正式上线前先应用迁移，并在服务器启动时关闭自动迁移功能。

Redis用于处理短时效的协调任务。它会在新任务加入队列时通知工作节点，将流式事件广播给所有连接的服务器处理进程，并持续监控工作节点的运行状态。

当系统扩展为多个副本时，这种区分就变得非常重要。当某个工作节点想要处理待处理的任务时，它会使用SKIP LOCKED在Postgres中锁定对应行，从而防止其他工作节点同时获取同一任务。Redis的心跳机制用于确认该工作节点仍在运行；如果心跳中断，队列就可以将任务重新分配给其他节点。该项目的测试套件涵盖了任务独占性、故障工作节点的恢复、并发线程处理、流式处理行为、任务取消，以及任务执行过程中状态更新等场景。

这正是许多“如何部署代理”指南所忽略的部分。启动ASGI服务器其实很简单，而在并发负载下确保队列所有权和故障恢复功能正常运行才是真正的工程挑战。

迁移现有项目

如果您已经拥有包含 langgraph.json 文件的 Python LangGraph 项目，那么在 Langhost 上部署只需几步即可完成。

首先进行安装：

uv add langhost

接着将其配置为连接您的 Postgres 和 Redis 实例：

DATABASE_URI=postgresql+asyncpg://postgres:postgres@localhost:5432/langgraph?sslmode=disable
REDIS_URI=redis://localhost:6379/0

随后启动服务器：

uv run langhost serve --reload

在正式生产环境中，应明确指定网络接口并设置固定的工作进程数量：

uv run langhost serve --host 0.0.0.0 --workers 4

默认情况下，该服务会在 31296 端口上监听。启动后，会显示 API 本身、相关文档、LangSmith Studio 以及 Agent Chat 用户界面的链接。您现有的客户端代码无需修改，仍可继续使用标准 SDK：

import asyncio
from langgraph_sdk import get_client

client = get_client(url="http://127.0.0.1:31296")async def main():
    async for chunk in client.runs.stream(
        None,
        "agent",
        input={
            "messages": [
                {"role": "human", "content": "What is LangGraph?"}
            ]
        },
    ):
        print(chunk.event, chunk.data)asyncio.run(main())

这种低门槛的迁移方式可以说是 Langhost 最大的优势。团队无需先修改应用程序代码或更换任何客户端库，即可尝试使用该服务。

许可条款需仔细阅读

langhost CLI与langgraph-runtime-pg采用MIT许可协议发布。而标准的langgraph-api包则仍受Elastic License 2.0约束。Langhost的实际作用是替换掉专有的Postgres和Redis运行时层，但这并不影响官方服务器包本身的许可条款。

当人们将整个技术栈统称为“开源”时，这种细微差别往往会被忽略。通过Langhost运行并可修改的持久化层确实遵循MIT许可协议。但位于其之上的服务器组件仍以Elastic 2.0的开放源代码形式存在，您依然受该许可条款的约束。

即便如此，对许多组织而言，这一实际转变仍具有重要意义。它们无需运行时许可证密钥，即可针对自管理的数据库运行稳定的 LangGraph 工作负载。这也意味着应用程序的状态可以完全保留在其自身的云账户或内部网络中。不过，任何考虑将此技术用于企业的人士都应让法律或采购团队直接阅读相关许可证条款，而非仅依赖营销材料中的概述。

自托管会带来的责任

Langhost 解除了许可证和运行时的限制，但并未减轻运营负担。

您需要负责 Postgres 的容量规划、备份、恢复演练、连接池限制以及架构迁移工作。同时还要确保 Redis 的正常运行时间并制定内存释放策略。此外，您还需要通过指标和日志来掌握作业队列是否正在备份、工作进程是否出现停滞，以及数据流是否有无声丢失的情况。在将 API 对外开放之前，必须先做好严格的安全防护措施。

请记住，这个项目仍处于早期阶段。在 PyPI 上的当前版本为 0.11.1.post1，带有测试版标签。它固定了 langgraph-api 的特定匹配版本，从而确保该版本的兼容性，但这也意味着项目必须持续跟踪上游的变更以保持同步。该仓库的测试套件会运行自身的测试以及针对实时 Agent Server 的上游 Python SDK 集成测试，这确实令人放心——但它无法替代对您自己的图结构、流量模式、故障场景及升级流程的验证。

对于那些不愿自行处理这些工作的团队而言，使用托管式的 LangSmith 部署仍是更明智的选择。对于那些已经熟悉 Postgres 和 Redis 的使用、需要精确控制数据存储位置，或无法采用带许可的自托管运行时的团队来说，Langhost 更为合适。

一种实用的评估方法

不必从功能列表开始，只需取一个正在运行的 LangGraph 应用程序的测试副本，将其指向 Langhost 即可。

继续使用您目前所依赖的同一份 langgraph.json、相同的 SDK 客户端以及同样的 Studio 工作流程。启动一个持久线程，实现长时间运行的任务处理；可在执行过程中中断它并稍后继续。可以创建多个工作进程，在某个进程正在执行任务时将其终止，然后检查任务是否仍能正常完成。之后对 Postgres 数据库进行备份，将其恢复到另一个环境中，确认线程历史记录能够完整保留。

如果您的设置通过了所有这些测试，那就意味着您已经回答了真正重要的问题——Langhost 是否能够无缝融入您的基础设施而不成为负担。

源代码、设置指南以及问题追踪器均可在 GitHub 上的 langhost/langhost 地址找到。