3.3 环境变量与连接管理

3.3 环境变量与连接管理

本节摘要：Letta 的全部运行时配置都走环境变量：模型密钥决定智能体用什么大脑，连接串决定状态存在哪里，服务器密码决定谁能访问你的实验台。本节把这些变量收拢成一份分层清单，讲清凭据管理的安全底线与客户端连接的认证机制。读完本节，你的配置将有三量好品质：可查、可控、不泄密。

配置的分层：进程靠什么认识世界

服务进程启动时是"失忆"的——它不知道用哪个模型、连哪个数据库、允许谁访问，这些全靠启动环境里注入的环境变量。把 Letta 涉及的变量按职责分成三层，管理思路立刻清晰：

三层一个共同点：都含敏感凭据，都该按同样的纪律管理。除了敏感项，还有少量行为开关类变量（如调试日志开关），敏感度低但同样建议纳入清单——排障时你会感谢"配置都在一个地方"的决定。

凭据管理的三条底线

环境变量的安全风险只有一个来源：凭据落到了不该落的地方。三条底线覆盖绝大多数场景。底线一：凭据不进代码库。 密钥写在代码里提交，是历史上最高频的泄露事故。本地开发用环境文件承载变量并在版本控制里忽略它；团队协作时，环境文件只传"变量名清单"，真实值私下交付。底线二：一份环境一个来源。 同一台机器上 Pip 与 Docker 混用时，确认服务进程实际读到的值——容器里靠注入，宿主机靠 shell 环境，两处值不一致是"改了配置却没生效"的头号原因。底线三：生产凭据定期轮换。 轮换的操作越熟练越好：换新值、重启服务、验证、作废旧值，一套动作十分钟内完成，凭据泄露时才不至于手忙脚乱。

⚠️ 一个易被忽视的细节：连接串本身内嵌了数据库密码，等于"一份凭据装着另一份凭据"。给连接串设专用账号并只授予必要库的权限，能让这份嵌套的风险可控——用超级用户账号当连接串，是又一个高频反模式。

服务端的门锁：认证机制

服务器密码是访问层的核心：设置后，所有 API 调用必须携带它才被受理。这对两个场景至关重要——服务部署在团队共享网络时，防止无关人员操纵你的智能体；把实验台暴露到公网时（不推荐但常见），这是最后一道门锁。设置同样走环境变量，服务启动时生效：

# 服务端设置访问密码后启动
export LETTA_SERVER_PASSWORD="a_strong_password_here"
letta server
​

客户端侧的对应动作是把同一密码交给 SDK，每次请求自动携带。认证的完整交互如下面的时序图所示——重点看验证失败时的行为：服务端直接拒绝，不产生任何智能体推理，这意味着未授权请求不会消耗你的模型费用：

💡 建议在本地实验阶段就启用密码，哪怕密码很简单。理由不是本地有对手，而是让客户端代码从一开始就养成携带凭据的习惯——等部署到共享环境时再补认证，所有客户端代码都要回头改。

认证还有一层容易被忽略的价值：它把"访问"变成了可审计的事件。 没有门锁时，你无法区分"没人访问"与"有人访问但没留痕"；有了门锁，每一次被拒的请求都是一次明确的尝试记录。生产排障时，"请求被拒是因为密码错还是地址错"往往就是问题的全部真相——而这份真相只存在于启用了认证的服务日志里。安全机制的第一收益常常不是防住攻击，而是让系统行为变得可解释。

配置管理的进阶姿势

环境文件之外，两种进阶做法值得了解。一是分环境文件：本地、测试、生产各一份环境文件，启动时按环境加载——配置的第三个"一"从"一份环境一个来源"升级为"一个环境一份清单"。二是密钥托管服务：生产环境的密钥不落文件，由密钥管理服务在启动时注入。起步阶段环境文件足够，密钥托管是团队规模化后的自然升级，知道有这条路即可，不必提前支付复杂度。

三是配置变更留痕：每次对生产配置的修改记一行变更日志（改了什么、谁改的、为什么）。配置是智能体系统里最廉价的"事后复盘材料"——出了行为异常，先查配置变更日志往往三分钟定位，不查日志则可能排查三小时。这个习惯的成本是一行日志，回报是一次次的快速止血。

客户端连接：一个地址一个密码

服务端配置就绪后，客户端的连接配置收敛到极简：服务地址加访问密码，其余一切（智能体在哪、记忆怎么存）都由服务端负责：

from letta_client import Letta

# 指向服务端地址，携带访问密码；之后的用法与本地无密码时完全一致
client = Letta(
    base_url="http://your-server-host:8283",
)

# 远程服务与本地服务共用同一套业务代码，切换只改连接参数
agents = client.agents.list()
​

这个"切换只改连接参数"的特性，支持一种很实用的工作流：本地实验台调试通过的业务代码，原样指向生产服务即可上线，不存在两套写法。团队协作时，把服务地址与密码的交付流程制度化（谁在什么渠道发放、如何回收），实验台就从个人玩具升级成了团队基础设施。

配置排障的三板斧

配置问题的表现千奇百怪，排查套路却只有三招。第一招看进程读到什么：让服务以调试模式输出启动配置摘要，确认每层变量是否就位——大多数"不生效"问题在这一步现形。第二招隔离变量：怀疑某个配置时，只改它、重启、验证，一次一个变量，别一把全改。第三招对照最小可复现：用 3.1 节那条最小验证请求测试，排除业务代码的干扰后，问题就收缩在服务端配置或网络层。三招走完还没定位，把三层变量逐个清点，通常就能找到漏网的那个。

最后给配置管理定个性：它不是环境章的附属话题，而是实验台可靠性的根基。第 3 章之前你所有实验的变量只有一个——你对框架的理解；实验台上线后，配置成了新的变量来源。谁先把配置管出秩序，谁就先获得"行为可解释"的实验环境——而可解释，正是第 5 章一切进阶实验的前提。

本节要点回顾

• 三层清单：模型密钥、存储连接串、访问密码，全部是高敏感凭据，统一纳入配置清单管理。
• 三条底线：凭据不进代码库、一份环境一个来源、生产凭据定期轮换。
• 连接串嵌套风险：为连接串设专用最小权限账号，避免用超级用户。
• 门锁机制：服务器密码拦截未授权请求，认证失败不触发模型推理，不产生费用。
• 极简客户端：切换环境只改地址与凭据，业务代码跨环境复用。
• 排障三板斧：看进程实读配置、单变量隔离变更、最小请求复现。

下一节面向想深挖框架行为的读者：什么时候值得从源码装一份可调试的 Letta，以及 Poetry 工具链的基本用法。