LangSmith离线部署如何配置私有网络代理？

Question

在LangSmith离线部署环境中，如何正确配置私有网络代理以确保追踪数据安全传输至内部LangSmith服务？常见问题包括：代理未正确拦截LangSmith SDK的外网调用（如api.smith.langchain.com），导致请求超时或泄露风险；内网DNS无法解析外部域名，需通过代理映射到本地服务IP；以及SSL中间人代理导致证书校验失败。如何在不连接公网的前提下，通过Nginx或Squid代理转发，并配合自定义CA证书，实现与LangSmith API的加密通信？

Answer 1

LangSmith离线部署环境中的私有网络代理配置深度解析

1. 背景与核心挑战概述

在企业级AI应用开发中，LangSmith作为LangChain生态的核心调试与追踪平台，常需部署于隔离的内网环境中以满足安全合规要求。然而，默认情况下LangSmith SDK会尝试连接api.smith.langchain.com等公网地址，若未正确配置代理，则会出现请求超时、数据泄露或DNS解析失败等问题。

典型问题包括：

• SDK直接发起外网调用，绕过内部代理策略；
• 内网DNS无法解析外部域名，导致连接中断；
• 使用SSL中间人代理时，客户端校验自签CA证书失败；
• HTTPS流量被拦截但未正确重加密转发。

2. 网络架构设计原则

设计维度	推荐方案	说明
流量控制	Nginx反向代理 + Squid透明代理	Nginx处理HTTPS终止，Squid实现细粒度访问控制
DNS解析	内网DNS映射 api.smith.langchain.com → 内部Nginx IP	避免依赖公网DNS，提升稳定性
证书管理	自建私有CA并预装至所有客户端系统信任库	支持SSL中间人解密与重加密

3. 分步实施流程图

graph TD
    A[LangSmith SDK发起请求] --> B{是否匹配api.smith.langchain.com?}
    B -- 是 --> C[内网DNS返回代理IP]
    C --> D[Nginx接收HTTPS请求]
    D --> E[使用私有CA证书完成TLS握手]
    E --> F[解密后转发至内部LangSmith服务]
    F --> G[获取响应并重新加密返回客户端]
    B -- 否 --> H[走默认路由（应被防火墙阻断）]

4. Nginx代理配置详解

以下为关键Nginx配置片段，用于拦截并代理LangSmith API调用：

server {
    listen 443 ssl;
    server_name api.smith.langchain.com;

    ssl_certificate /etc/nginx/certs/internal-ca.crt;
    ssl_certificate_key /etc/nginx/certs/internal-ca.key;
    ssl_client_certificate /etc/nginx/certs/root-ca.pem;
    ssl_verify_client off; # 可根据需要开启双向认证

    location / {
        proxy_pass https://internal-langsmith-backend:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_ssl_verify off; # 若后端使用自签证书则关闭验证
    }
}

5. 自定义CA证书体系构建

为解决SSL中间人代理导致的证书校验失败问题，必须建立完整的PKI体系：

1. 生成根CA私钥：openssl genrsa -out root-ca.key 4096
2. 签发根证书：openssl req -x509 -new -nodes -key root-ca.key -days 3650 -out root-ca.crt
3. 为Nginx生成服务器证书请求并由根CA签署
4. 将root-ca.crt预安装到所有运行LangSmith SDK的机器的信任根证书库中
5. 确保Python requests库或urllib能识别系统级CA证书（Linux下通常为/etc/ssl/certs）
6. 测试证书链有效性：curl --cacert root-ca.crt https://api.smith.langchain.com/v1/version
7. 设置环境变量LANGCHAIN_API_KEY和LANGCHAIN_TRACING_V2=true，同时指定LANGCHAIN_ENDPOINT=https://api.smith.langchain.com
8. 通过tcpdump或Wireshark抓包确认流量未出内网
9. 启用Nginx日志记录所有API调用以便审计
10. 定期轮换证书并更新客户端信任库

6. 客户端SDK行为控制策略

即使部署了代理，仍需从代码层面确保LangSmith SDK不会绕行：

import os

# 强制指定API端点指向内网代理
os.environ["LANGCHAIN_ENDPOINT"] = "https://api.smith.langchain.com"
os.environ["LANGCHAIN_API_KEY"] = "your-internal-api-key"
os.environ["LANGCHAIN_PROJECT"] = "offline-tracing-project"

# 禁用自动公网发现机制（如有）
os.environ["LANGCHAIN_DISABLE_AUTO_CONFIG"] = "true"

# 设置HTTP代理环境变量（适用于requests底层）
os.environ["HTTP_PROXY"] = "http://squid-proxy.internal:3128"
os.environ["HTTPS_PROXY"] = "http://squid-proxy.internal:3128"
os.environ["NO_PROXY"] = "localhost,127.0.0.1,.internal"