本地部署 LangServe 时,很多人会先确认模型能正常加载、invoke 能返回结果,然后就把服务丢给同事或挂到测试环境用。实际上,LangServe 默认把 /docs、/redoc、/invoke、/batch、/stream 全部暴露出来,谁拿到地址就能直接调用模型。尤其是通过 Nginx 反代到公网后,没有认证就等于把模型当公共 API 开放,token 消耗和内容安全都不可控。先别急着改配置,以下处理路径适合已经有 LangServe 基础服务、想快速加一层统一鉴权的场景,不涉及修改 LangChain 内部逻辑。
认证切入点:中间件比改每个端点更省事
LangServe 的 add_routes 背后是标准 FastAPI 路由,因此认证逻辑不必侵入每个具体的 invoke 或 stream 端点。建议在创建 FastAPI 应用后、注册 LangServe 路由前,用 @app.middleware('http') 挂一个统一的 JWT 检查中间件。这样所有请求路径(包括 /docs、/invoke、/batch、/stream)都会先经过令牌校验,未通过时直接返回 401,不会进入 LangServe 服务逻辑。中间件里只保留验证逻辑,不要做业务处理,避免与 LangServe 内部异常处理互相干扰。
这段实现的关键是路由注册顺序。很多人的做法是先 add_routes 再挂中间件,虽然 FastAPI 仍然会让中间件生效,但为了逻辑清晰,还是建议把中间件写在 app 创建之后、add_routes 之前。这样后续维护时一眼就能看出“所有进站请求先过 JWT,再到 LangServe 路由”。中间件里也不要自己去读请求体,因为 /stream 这类端点是流式响应,提前读 body 会破坏 LangServe 的流式行为。只需要检查 Authorization 头,不做多余操作。
import os
from fastapi import FastAPI, HTTPException, Request
from fastapi.responses import JSONResponse
from langserve import add_routes
app = FastAPI(title="LocalModelService", docs_url=None, redoc_url=None)
@app.middleware("http")
async def jwt_auth_middleware(request: Request, call_next):
auth_header = request.headers.get("Authorization", "")
if not auth_header.startswith("Bearer "):
return JSONResponse(status_code=401, content={"detail": "Missing or invalid Authorization header"})
token = auth_header.split(" ")[1]
payload = verify_jwt_token(token) # 下面定义的函数
if payload is None:
return JSONResponse(status_code=401, content={"detail": "Invalid or expired token"})
request.state.payload = payload
response = await call_next(request)
return response
# 之后再把 LangServe 路由注册到 app 上
# add_routes(app, runnable, path="/model")这段代码在本地开发时够用。注意其中 docs_url=None 和 redoc_url=None 是故意关掉的,后面会解释。实际部署时,中间件里返回的 JSON 格式可以自行定义,但建议保持简单,不要在这里做日志记录或审计,否则会影响每个请求的延迟。
JWT 校验函数:签名和权限都要查
校验函数建议用 PyJWT 实现,核心是 jwt.decode 的调用。解码时必须显式传入 algorithms=['HS256'],并检查 options 中的 verify_exp 是否开启;如果 token 没有 exp 字段,应视为非法令牌。解码得到 payload 后,还要确认 sub 或 scope 字段是否满足接口调用权限,不要只验证签名就放行。任何校验失败都要统一抛出 HTTPException 401,错误信息保持模糊,避免泄露密钥或算法细节。
很多人在本地测试时只调用一次 jwt.decode,发现签名正确就认为认证没问题,忽略了 scope 校验。如果服务只给内部几个项目用,可以简单检查 sub 是否在允许列表里;如果模型接口后续要开放给不同业务方,最好在签发 token 时带上 scope,例如 {"sub": "service-a", "scope": "model:read"},中间件里再校验 scope 包含 model:read。这样即使某个 token 被泄露,至少还能通过 scope 限制影响范围。
import jwt
from fastapi import HTTPException
def verify_jwt_token(token: str) -> dict | None:
try:
payload = jwt.decode(
token,
os.environ["JWT_SECRET"],
algorithms=["HS256"],
options={"verify_exp": True, "require_exp": True}
)
except jwt.PyJWTError:
raise HTTPException(status_code=401, detail="Invalid token")
# 权限校验:检查 sub 或 scope
scope = payload.get("scope", "")
if "model:read" not in scope.split():
raise HTTPException(status_code=403, detail="Insufficient scope")
return payload这段代码中 require_exp: True 是关键,它强制 token 必须带 exp 字段,否则直接拒绝。另外,raise HTTPException 在中间件里会被 FastAPI 捕获并返回错误 JSON,但注意中间件中如果直接 raise,会返回 FastAPI 默认的 {"detail":"..."} 结构,这没问题。如果希望完全统一返回格式,可以在中间件里用 JSONResponse,两者可自行取舍。
密钥与签名:固定 HS256,但别写死在代码里
JWT 签名密钥至少 256 位随机字节,存放在环境变量或秘密管理服务中,不要写入代码仓库。服务多副本部署时,所有实例必须使用同一个 JWT_SECRET,否则产生随机校验失败。签名算法在生成和解码两侧都要固定为 HS256,并在解码时核对 payload 的 alg 头,防止算法替换攻击。另外,密钥轮换时要预留新老密钥同时有效的窗口,避免重启瞬间所有 token 全部失效。
生成密钥可以用 Python 一行命令:python -c "import secrets; print(secrets.token_hex(32))",这个值设置到环境变量里。PyJWT 在解码时默认会检查 alg 头,但历史上一些库允许算法混淆,因此建议你在 jwt.decode 之前手动核对 token 头中 alg 是否为 HS256。虽然 PyJWT 已经通过 algorithms=['HS256'] 做了限制,但多写一个判断也不多余。
关于密钥轮换,简单做法是设置两个环境变量:JWT_SECRET_CURRENT 和 JWT_SECRET_PREVIOUS,解码时先尝试当前密钥,失败再尝试上一个。这样在切换密钥的过渡期,旧 token 依然可用,避免所有客户端同时重新登录。具体实现不必写得花哨,能解决重启瞬间的认证风暴就行。
常见坑:文档页面和明文传输
一个容易忽略的风险是 LangServe 自带的 /docs 和 /redoc 页面默认开放,攻击者可以在页面上直接调用你已保护的接口。如果业务不需要这些文档,在创建 FastAPI 应用时设置 docs_url=None 和 redoc_url=None;如果还需要,就对这些文档路由单独加上 Basic Auth 或同套 JWT 校验。另一个坑是 JWT 明文传输,本地模型服务如果被代理到公网,必须在前置 Nginx 上配置 TLS,否则令牌易被截获,认证形同虚设。
实际操作中,很多人只关掉 /docs 而忘了 /openapi.json,这个接口同样会暴露路由信息。虽然它本身不涉及模型调用,但攻击者可以根据路径猜到 invoke 和 stream 的具体参数结构。可以用中间件对 /openapi.json 也做一次 JWT 校验,或者把 docs 和 openapi 都关掉,只保留一个内部专用的接口说明文档。如果你确实需要保留文档,建议在 Nginx 层做 Basic Auth,这样后端不用重复处理。
Nginx 反代时,TLS 配置属于基本功,但有个细节容易忽略:在 location 块里不要关闭 proxy_set_header Authorization,否则 Nginx 默认不会向后端传递 Authorization 头。很多“中间件明明写了但没生效”的问题就出在这里。
server {
listen 443 ssl;
server_name model.example.com;
ssl_certificate /etc/nginx/certs/model.crt;
ssl_certificate_key /etc/nginx/certs/model.key;
location /model/ {
proxy_pass http://127.0.0.1:8000/model/;
proxy_set_header Host $host;
proxy_set_header Authorization $http_authorization;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}
}这里把 proxy_set_header Authorization 显式写出来,是为了防止某些 Nginx 配置模板里默认不传递。如果你已经在 Nginx 层做了 TLS,可以顺便加上 proxy_http_version 1.1 和 proxy_set_header Connection "",避免 stream 长连接被 Nginx 缓冲掉。后端 LangServe 服务只监听本机端口,不要暴露到公网。
改完后看这几个信号
接口上线前至少按五类场景自测:不带 Authorization 头返回 401;带格式错误的 Bearer 串返回 401;带有效且未过期的 token 返回 200;带过期 token 返回 401;用错误密钥签名的 token 返回 401。生成测试 token 时可以用 PyJWT 的 jwt.encode 配合同一套 JWT_SECRET,过期时间设为 60 秒。不要只调一次 curl 就认为成功,需要确认中间件对 /invoke 和 /stream 同时生效。
自测时优先用 curl 查看状态码,然后检查响应体是否包含模型返回结果。如果对 /invoke 和 /batch 都测了,但忘了 /stream,后面调试流式输出时会多花时间。下面给出一组测试命令,假设本地服务跑在 8000 端口,模型路由为 /model/invoke。
# 1. 不带 token
curl -i http://localhost:8000/model/invoke \
-H "Content-Type: application/json" \
-d '{"input": {"question": "hello"}}'
# 期望 401
# 2. 带格式错误的 token
export BAD_TOKEN="not.a.jwt"
curl -i http://localhost:8000/model/invoke \
-H "Authorization: Bearer $BAD_TOKEN" \
-H "Content-Type: application/json" \
-d '{"input": {"question": "hello"}}'
# 期望 401
# 3. 带有效 token(60秒过期)
TOKEN=$(python -c "import jwt, os; print(jwt.encode({'sub':'test','exp':__import__('time').time()+60, 'scope':'model:read'}, os.environ['JWT_SECRET'], algorithm='HS256'))")
curl -i http://localhost:8000/model/invoke \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"input": {"question": "hello"}}'
# 期望 200
# 4. 过期 token(exp 已过)
EXPIRED=$(python -c "import jwt, os, time; print(jwt.encode({'sub':'test','exp':time.time()-10, 'scope':'model:read'}, os.environ['JWT_SECRET'], algorithm='HS256'))")
curl -i http://localhost:8000/model/invoke \
-H "Authorization: Bearer $EXPIRED" \
-H "Content-Type: application/json" \
-d '{"input": {"question": "hello"}}'
# 期望 401
# 5. 错误密钥签名
WRONG=$(python -c "import jwt, time; print(jwt.encode({'sub':'test','exp':time.time()+60, 'scope':'model:read'}, 'wrong-secret', algorithm='HS256'))")
curl -i http://localhost:8000/model/invoke \
-H "Authorization: Bearer $WRONG" \
-H "Content-Type: application/json" \
-d '{"input": {"question": "hello"}}'
# 期望 401这些命令中,生成 token 的 python 代码依赖环境变量 JWT_SECRET,所以执行前先 export。如果测试时发现 /docs 已经关闭,但根路径 / 仍能访问,那很正常,因为根路径没有注册模型路由;如果确实想让根路径也受保护,中间件会拦截所有请求,但需要确认没有妨碍健康检查。
边界与下一步判断
中间件方案适合模型服务本身就是独立进程、部署在可控网络里的场景。如果服务规模变大,需要细粒度控制每个用户调用模型的频率、记录每次请求的输入输出,那 JWT 中间件只解决“谁可以访问”,不解决“谁用了多少量”,需要再叠加限流和审计日志。另外,如果你已经在用 API 网关(如 Kong、APISIX),完全可以不做中间件,而是由网关统一校验 JWT,后端 LangServe 保持裸奔,这样运维更集中。但如果团队没有专职网关管理,中间件反而是最少改动、最容易回滚的方案——回滚时只需把中间件函数删掉,重启进程即可。
最后提醒一点:本地模型服务往往跑在 GPU 机器上,如果同时有多个项目直连这个服务,认证信息不要直接用 root 权限写入 /etc/environment。建议每次启动服务前用 export JWT_SECRET=... 或通过 docker secret 传入,并在启动日志里打一个“JWT_SECRET 已设置”的标志,但不输出密钥本身。这样排查问题时能快速确认环境变量是否生效,又不泄露敏感信息。
这套配置不复杂,关键是把校验逻辑收拢在一个中间件里,同时关闭不必要的文档暴露。后续如果加了不同的模型路由,中间件还会自动覆盖新路由,不需要逐个改 add_routes。只要密钥管理得当、TLS 配置正确,LangServe 就能在公网环境下安全地提供服务。