先弄清：LangSmith 适合装在哪里

LangSmith 常用于记录、调试和评估大语言模型应用的调用链路，例如提示词版本、输入输出、延迟、错误堆栈和评测结果。个人学习可以优先使用托管服务，部署成本低；团队内网测试、数据合规要求较高或需要统一管理日志时，才建议考虑自托管安装。自托管并不是简单运行一个程序，它通常涉及应用服务、数据库、缓存、对象存储、访问域名、密钥配置和备份策略，小白上手前要先确认机器资源和维护能力。

测试环境建议至少准备 2 核 CPU、8GB 内存和 50GB 可用磁盘；团队多人使用建议 4 核以上、16GB 内存起步，并把数据库与文件存储空间预留充足。系统可以选择常见 Linux 发行版，提前安装 Docker 与 Docker Compose 会更省事。若部署在本机学习，也要确认端口没有被占用，常见 Web 服务端口、数据库端口、缓存端口都需要检查。

安装前环境检查清单

第一项检查系统版本和基础命令。确认系统时间准确，磁盘分区空间足够，当前用户具备执行容器和读写数据目录的权限。第二项检查网络连通性。安装过程需要拉取镜像和依赖包，若处在企业网络中，要提前向管理员确认镜像源、域名解析和出站访问规则，避免安装到一半失败。

第三项检查运行组件。自托管通常需要应用容器、PostgreSQL、Redis 以及对象存储或本地文件目录。PostgreSQL 负责保存结构化数据，Redis 用于队列或缓存，对象存储或挂载目录用于保存较大的附件、运行记录等。第四项检查密钥与环境变量。至少要准备应用密钥、数据库连接信息、服务访问地址、管理员账号初始化信息，以及与模型服务相关的 API Key。所有密钥不要写进公开仓库，也不要发到群聊里。

第五项检查端口规划。假设 Web 入口使用 3000 或 8080，数据库使用 5432，缓存使用 6379，对象存储使用独立端口，就要确保这些端口不会与已有服务冲突。第六项检查备份方案。只要准备长期使用，就要明确数据库备份、文件目录备份、配置文件备份三件事，否则后续迁移或故障恢复会非常被动。

基础安装思路：从配置文件开始

新手不建议一上来改很多参数。比较稳妥的流程是：先创建一个独立目录，例如 /opt/langsmith，把 compose 文件、环境变量文件和数据挂载目录都放在这里；再创建 data、postgres、redis、object 这类子目录，便于后续查找和迁移。目录命名保持英文和小写，避免空格与特殊符号。

配置环境变量时，重点看四类内容。第一类是访问地址，例如 APP_URL 或 FRONTEND_URL，要填写用户实际访问的域名或内网地址。第二类是数据库连接，如主机名、端口、用户名、口令和库名，容器网络内通常使用服务名访问。第三类是对象存储配置，如果使用本地挂载目录，要保证应用容器有读写权限；如果使用兼容 S3 的存储，要填写 endpoint、bucket、access key 等信息。第四类是安全密钥，必须使用足够随机的字符串，不要用 123456、test、admin 这类弱值。

启动前先执行配置校验，确认 compose 文件语法无误；再拉取镜像并启动服务。首次启动可能会进行数据库初始化，日志里出现迁移、建表等信息属于正常现象。启动完成后，访问 Web 地址，创建管理员账号或按配置完成初始化。登录后可以先跑一个最小调用链路，把一条测试 trace 写入 LangSmith，确认页面可见、搜索正常、详情可打开。

数据目录为什么要迁移

数据目录迁移常见于三种情况：一是安装时放在系统盘，运行一段时间后空间不足；二是从测试机迁到正式机；三是要把数据放到更可靠的磁盘或统一存储上。迁移看似只是复制文件，实际要同时处理数据库数据、对象文件、配置路径和权限。如果只搬走部分目录，很容易出现页面能打开但历史记录缺失、附件打不开、任务队列异常等问题。

迁移前先判断当前部署方式。若数据库也运行在容器里，通常会把数据挂载到宿主机某个目录；若数据库是独立服务，则需要使用数据库备份工具导出。对象存储若是本地目录，需要复制完整目录；若使用外部对象存储，则主要修改连接配置即可。Redis 通常不作为长期核心数据来源，但停服迁移时仍建议保持干净状态，避免任务执行到一半。

数据目录迁移步骤

第一步，通知使用者暂停写入。迁移期间不要继续接入新应用，也不要运行评测任务。第二步，停止 LangSmith 相关服务，优先使用正常停止命令，避免直接强制结束进程。第三步，备份配置文件和环境变量文件，把 compose 文件、.env 文件、初始化脚本单独复制一份，并记录当前镜像版本。

第四步，备份数据库。如果 PostgreSQL 在容器内，可以使用逻辑备份方式导出为 dump 文件；如果采用挂载目录迁移，必须在数据库完全停止后复制数据目录。更推荐逻辑备份加文件目录复制双保险，恢复时更可控。第五步，复制对象文件目录。使用保留权限和时间戳的复制方式，把旧目录完整复制到新磁盘，例如从 /opt/langsmith/data 迁到 /data/langsmith。复制完成后检查文件数量和目录大小是否接近，不能只看命令是否结束。

第六步，修改挂载路径。打开 compose 文件，把旧的 volume 路径改成新路径；如果环境变量里也写了数据路径或对象存储路径，同步修改。第七步，修正权限。确保运行容器的用户对新目录有读写权限，尤其是数据库目录对权限更敏感，权限过宽或属主不对都可能导致启动失败。第八步，启动服务并观察日志。重点看数据库连接、迁移脚本、对象存储初始化和 Web 服务启动是否正常。

第九步，做回归验证。登录后台后检查历史项目、trace 列表、评测数据、附件或大文本详情是否正常；再新建一条测试记录，确认新数据会写入新目录。第十步，保留旧目录一段时间。不要迁移成功后立刻删除旧数据，至少保留一个完整备份周期，确认无异常后再清理。

迁移后的常见问题

问题一：服务启动后页面空白。先看前端访问地址是否配置错误，再看后端日志是否有数据库连接失败。很多时候是环境变量仍指向旧主机或旧端口。问题二：能登录但历史数据没有了。优先检查数据库是否恢复到正确实例，以及 compose 挂载的是否为新目录。若误启动了一个空库，需要停服后按备份重新恢复。

问题三：历史记录存在，但详情中的文件或长内容打不开。通常是对象存储目录未迁移完整，或新目录权限不足。检查应用日志中是否有 read permission、not found、bucket una vailable 等提示。问题四：数据库容器反复重启。常见原因是数据目录属主不匹配、复制时破坏了文件权限、数据库版本与旧数据不兼容。此时不要反复初始化，先停止服务，确认版本和备份可用。

问题五：新数据没有写入新磁盘。可能是 compose 文件改了但容器没有重新创建，也可能是还有旧 volume 未清理。可以查看容器实际挂载信息，确认宿主机路径是否已经变更。

安全边界与实用建议

LangSmith 里可能保存提示词、用户输入、模型输出、报错信息和业务上下文，部署时要默认按敏感系统对待。不要把服务直接暴露到不受控网络，至少配置登录认证、访问白名单、HTTPS 入口和最小权限账号。API Key、数据库口令、对象存储密钥要定期轮换，离职或项目结束后及时回收权限。

日志采集也要有边界。接入应用时，避免上传身份证号、手机号、合同原文、内部密钥等不必要字段；调试阶段可以保留详细数据，生产阶段建议做脱敏、采样和保留周期设置。团队协作时，把项目、环境、标签命名统一，例如 dev、staging、prod，后续排查会更快。

最后给小白一个简明检查表：安装前确认系统资源、Docker、端口、域名、磁盘和密钥；启动时盯住数据库、缓存、对象存储和 Web 日志；迁移前停服、备份、记录版本；迁移中完整复制并修改挂载；迁移后验证历史数据和新增写入。只要按这个顺序执行，LangSmith 的安装和数据目录调整就能大幅降低出错概率。