1. 先说清楚Clawdbot 解决的是什么问题1.1 自托管聊天机器人的典型使用场景真正让我下决心折腾自托管聊天机器人网关的是一个很朴素的需求我不愿意把对话记录交给第三方托管服务同时希望机器人能同时接入网页端、IM 渠道和内部 API 调用方而不是每个渠道各写一套对接逻辑。当时看到 Clawdbot 这个项目代号的时候第一反应是又一个聊天机器人壳子但把部署、反向代理、WebAuth 认证这三件事完整串下来之后我才意识到它解决的其实是消息接入、模型路由、会话管理、访问控制这几类脏活的统一问题。这篇文章记录的就是我拿到一台裸服务器之后从零完成 Clawdbot 部署、配置 Nginx 反向代理、接入 WebAuth 鉴权的全过程。适合手里有云服务器、不想把聊天记录交给第三方、想给多个渠道统一接入大模型能力的开发者参考。整条链路跑通之后后面再做类似的自托管服务基本就是复制粘贴加微调的事了。在动手之前我想清楚了一件事自托管网关和现成托管服务的差别不在于有没有聊天功能而在于控制力。对比维度现成托管服务自托管网关Clawdbot 这类会话数据存在服务商那里导出麻烦存在自己的数据库里随时可查可删模型路由只能选平台固定模型可自由配置多个模型地址按渠道或关键词切换提示词调整受平台限制管理后台直接改改完即时生效费用模型按调用量阶梯计费只付服务器和模型接口的费用扩展能力平台开放接口有限完全可控可以加自己的中间逻辑如果你只是偶尔体验下 AI 对话托管服务完全够用但如果机器人会成为业务的一部分要接多个渠道、要留审计日志、要控制成本自托管是绕不开的方向。1.2 我的模块划分思路与整体架构Clawdbot 这里并不是指某个现成的商业产品而是我给自家这套消息网关起的代号。它的核心结构拆开看并不复杂就是四条线接入层接收网页端、IM 渠道回调和内部 API 调用统一转成标准消息格式。网关层维护多轮会话上下文按配置路由到不同大模型接口拿到回复再返给接入层。存储层保存会话快照、消息记录、用户配置我用 PostgreSQL 存结构化数据。管理面一个 Web 后台用于查看运行日志、调整模型参数、管理渠道令牌。实际部署的时候我让 Nginx 统一接收公网流量WebAuth 认证服务挂在 Nginx 的 auth_request 上做前置校验业务容器完全收在内网网段。这样设计的好处是应用本身不需要处理 SSL 证书和复杂的登录逻辑只要关注消息处理就行。2. 部署从裸机到容器跑起来2.1 目录规划与容器编排我的服务器环境比较常规Ubuntu 系统2 核 4G 内存系统盘之外挂了一块数据盘。Clawdbot 这类网关服务的资源消耗不算高主要开销在数据库和模型接口调用上4G 内存跑起来绰绰有余。我把所有文件放在/opt/chatbot目录下结构是这样的/opt/chatbot ├── docker-compose.yml ├── .env ├── app/ │ └── config/ │ └── channels.yaml ├── certs/ │ └── (证书文件挂载目录) └── data/ └── postgres/选择 Docker Compose 而不是直接在宿主机上跑主要看中三件事依赖隔离、可重复部署、数据卷便于备份。后面无论升级还是迁移只需要把 compose 文件和.env带走配合数据卷备份基本不会出大问题。docker-compose.yml的核心配置大致长这样version: 3.8 services: db: image: postgres:16-alpine restart: unless-stopped environment: POSTGRES_USER: ${DB_USER} POSTGRES_PASSWORD: ${DB_PASSWORD} POSTGRES_DB: ${DB_NAME} volumes: - ./data/postgres:/var/lib/postgresql/data healthcheck: test: [CMD-SHELL, pg_isready -U ${DB_USER}] interval: 5s timeout: 3s retries: 10 app: image: clawdbot-gateway:latest restart: unless-stopped depends_on: db: condition: service_healthy env_file: .env ports: - 127.0.0.1:3000:3000 volumes: - ./app/config:/app/config - ./certs:/app/certs:ro auth: image: clawdbot-auth:latest restart: unless-stopped env_file: .env ports: - 127.0.0.1:3100:3100注意两个细节第一应用和认证服务的端口都绑定在127.0.0.1上没有直接暴露到公网。后续所有外部流量都必须经过 Nginx这是安全的第一道保险。第二depends_on加了condition: service_healthy确保数据库真正就绪后应用才启动而不是简单地先启动数据库容器。2.2 初次启动的失败记录第一次docker compose up -d之后应用容器没起来。日志里报的是app | Error connecting to database: connect ECONNREFUSED 127.0.0.1:5432 app | [gateway] retry in 5s...原因很清楚虽然容器启动顺序上db在app前面但 PostgreSQL 从容器启动到真正能接受连接中间有几秒的初始化时间。如果应用启动得比数据库初始化还快自然连不上。加上 healthcheck 之后这个问题就消失了。接下来遇到的问题比较隐蔽。配置里填的模型接口地址是http://localhost:11434但网关容器内的localhost指的是容器自己不是宿主机。这一下卡了我半小时最后改成http://host.docker.internal:11434才正常。如果你是应用容器和模型服务同机部署一定要留意容器网络和宿主机网络的区别。2.3 配置项逐条说明排完连接问题我把.env里的配置项逐个看了一遍建议你把下面的字段都提前想好而不是等启动报错再回头补DB_USER/DB_PASSWORD/DB_NAME数据库账号信息不要用默认密码长度至少 16 位。CHANNEL_TOKENIM 渠道回调时校验用的令牌相当于渠道侧的签名密钥。WEBHOOK_SECRET用于验证发往网关的 Webhook 请求合法性的密钥。MODEL_BASE_URL模型接口的基础地址比如调用的 OpenAI 兼容接口的根路径。MODEL_API_KEY模型服务的鉴权密钥。DEFAULT_MODEL默认使用的模型标识路由规则没匹配到时就走这个。这些配置项直接关系到后续反向代理和 WebAuth 的联调尤其是CHANNEL_TOKEN和MODEL_API_KEY在验证 API 鉴权时都会用到。3. 反向代理层把内部服务安全暴露出去3.1 为什么不能直接裸端口Clawdbot 的应用服务跑在 3000 端口认证服务跑在 3100 端口。如果图省事直接在安全组里放行这两个端口浏览器访问http://服务器IP:3000也能用但代价是后端服务完全暴露在公网谁扫到端口都能发请求。没有 TLS 加密消息内容和登录凭证都是明文传输。后续想加认证、限流、日志审计都得改应用代码。反向代理的真正价值在于只开放 80 和 443由 Nginx 负责 TLS 终结、转发规则、超时控制、WebSocket 升级应用容器不需要关心这些基础设施问题。这就好比小区门口的门卫室——访客先经过门卫确认才被带到具体住户而不是每个人都能直接敲开每一户的门。3.2 证书签发与完整 Nginx 配置我这边用certbot申请 Lets Encrypt 免费证书先保证域名解析到了服务器 IP再执行sudo apt install certbot python3-certbot-nginx sudo certbot --nginx -d chat.example.com证书签发后Nginx 配置放在/etc/nginx/conf.d/chatbot.conf完整内容如下server { listen 80; server_name chat.example.com; return 301 https://$host$request_uri; } server { listen 443 ssl http2; server_name chat.example.com; ssl_certificate /etc/letsencrypt/live/chat.example.com/fullchain.pem; ssl_certificate_key /etc/letsencrypt/live/chat.example.com/privkey.pem; client_max_body_size 20m; location / { proxy_pass http://127.0.0.1:3000; 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_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection upgrade; proxy_read_timeout 300s; proxy_send_timeout 300s; } location /auth/ { proxy_pass http://127.0.0.1:3100; proxy_set_header Host $host; } }3.3 三个最容易忽略的细节这段配置我实际踩过三个坑每个都值得单独说。第一个是请求体大小限制。默认client_max_body_size是 1M。机器人在某些场景下需要接收图片、文档或长文本一旦请求体超过 1MNginx 直接返回 413 Request Entity Too Large。我在测试发长消息时收到的就是 413一开始还以为是应用的问题。按实际需要调成 20M 之后就好了。如果你要支持大文件上传建议配合专门的存储服务别把文件流全压到网关这里。第二个是超时时间。默认proxy_read_timeout是 60 秒。当模型接口响应慢或者对话采用流式输出时响应可能超过 60 秒。Nginx 在等待超过时限后主动断开连接应用侧表现为收到一半就断了或者请求超时。我把它调到了 300 秒同时对流式输出的场景做了适配不再等整个响应完整生成再返回。第三个是 WebSocket 转发头。如果机器人后端支持实时推送没有Upgrade和Connection upgrade头浏览器端的 WebSocket 连接会在握手阶段失败。Chrome 控制台会报WebSocket connection failed服务端日志则显示upgrade request without upgrade header。这个错误排查起来很绕因为表面上看 Nginx 配置没问题、端口也能通问题就出在这两个转发头上。提示在反向代理里加了 WebSocket 相关配置后改动 Nginx 配置记得先nginx -t校验语法再systemctl reload nginx。直接重启对线上连接影响大reload 才是平滑的方式。4. WebAuth 鉴权后台和 API 不是谁都能碰的4.1 WebAuth 到底在保护哪些入口部署完成、反代也通了之后Clawdbot 确实能用了但我发现还有一件事不做不行访问控制。Clawdbot 的管理后台暴露着渠道令牌、模型配置、聊天记录几个关键入口。如果后台不带登录认证任何知道地址的人都能打开看到全部对话内容和密钥信息REST API 也是一样没有鉴权的话只要拿到 URL 就能调用网关发消息、读历史记录。这个风险在自托管场景里特别容易被忽略因为自己用的系统下意识会觉得没人知道地址就没事。但实际上公网扫描器 24 小时在跑暴露管理后台和 API 等于把钥匙挂在门口。所以我在 WebAuth 这一步选了认证前置的思路不在应用代码里散落各种登录判断而是在 Nginx 层统一做。每个请求到达 Nginx 后先发往认证服务校验身份令牌校验通过才放行到 Clawdbot 应用。应用拿到的请求里附带了可信的身份信息直接用即可。4.2 OAuth2 授权码模式 JWT 的实现路径WebAuth 的落地我分成了两个场景管理后台的浏览器登录走 OAuth2 授权码模式登录完成后拿到 JWT。Robot API 的调用直接使用Authorization: Bearer JWT头。认证服务本身是独立的小服务工作逻辑的伪代码如下# 最小认证服务逻辑示意生产环境建议直接用成熟的 OIDC 库 from fastapi import FastAPI, HTTPException, Header import jwt import requests app FastAPI() # 登录入口验证用户名密码签发 JWT app.post(/auth/login) def login(username: str, password: str): if not verify_user(username, password): raise HTTPException(status_code401, detailinvalid credentials) token jwt.encode( {sub: username, exp: now 3600}, keySECRET_KEY, algorithmHS256 ) return {access_token: token, token_type: bearer} # Nginx auth_request 会回调这个接口做校验 app.get(/auth/verify) def verify(authorization: str Header(None)): if not authorization or not authorization.startswith(Bearer ): raise HTTPException(status_code401, detailmissing token) token authorization.split( , 1)[1] try: payload jwt.decode(token, keySECRET_KEY, algorithms[HS256]) except jwt.PyJWTError: raise HTTPException(status_code401, detailinvalid or expired token) return {ok: True, user: payload[sub]}认证服务签发的是 JWT校验时只检查签名、有效期和用户状态。之所以选择无状态的 JWT 而不是服务端 session是因为在 Nginx 和高可用部署场景下无状态令牌不需要集中存储会话数据扩容时不用考虑 session 同步问题。当然代价是令牌签发后不能立即失效所以我把有效期设成 1 小时管理后台可以配短一些API 用的令牌根据使用频率再调整。4.3 用 auth_request 把认证挂到 Nginx 上认证服务就绪后我在 Nginx 里加了一段配置server { # 其他配置... # 内部认证校验入口只允许 Nginx 调用不直接暴露 location /internal/auth { internal; proxy_pass http://127.0.0.1:3100/auth/verify; proxy_pass_request_body off; proxy_set_header Content-Type ; proxy_set_header Authorization $http_authorization; } # 管理后台受保护 location /admin/ { auth_request /internal/auth; auth_request_set $auth_user $upstream_http_x_auth_user; proxy_pass http://127.0.0.1:3000; } # API 受保护 location /api/ { auth_request /internal/auth; proxy_pass http://127.0.0.1:3000; } # 登录页和静态资源不受保护 location /auth/login { proxy_pass http://127.0.0.1:3100; } }这里最关键的是auth_request /internal/auth;。Nginx 收到访问/admin/或/api/的请求后会先把请求透传给认证服务的/auth/verify接口。如果认证服务返回 2xxNginx 认为当前请求合法继续往上游转发。如果返回 401/403Nginx 直接拒绝原始请求不会触达 Clawdbot 应用。location /internal/auth里的internal;指令同样重要它确保认证校验入口只能被 Nginx 内部调用外部没法直接访问。这一步相当于把认证前置做了个隔离层应用代码里不再需要处理是否登录、是否过期这类逻辑。5. 端到端联调验证整条链路真的通了5.1 验证消息链路与后台登录部署、反代、认证都配置好之后我按以下顺序做了一轮完整验证而不是只看服务进程是否存活。先用 curl 模拟一个 API 调用方向 Clawdbot 发一条消息curl -X POST https://chat.example.com/api/chat \ -H Authorization: Bearer $TOKEN \ -H Content-Type: application/json \ -d {message: 你好介绍一下你自己}预期返回 200且 body 里包含模型生成的回复。如果返回 401说明 auth_request 生效问题多半在令牌校验环节要么是SECRET_KEY不一致要么是令牌过期时间设置太短。然后验证管理后台的登录流程。先在浏览器访问https://chat.example.com/admin/未登录时应该被重定向到登录页输入账号密码后签发的 JWT 随请求带到后台此时刷新后台页面应该能正常看到会话列表和配置项。5.2 受保护 API 的 401/200 行为验证消息链路能通还不够我还专门测了不存在令牌、错误令牌、过期令牌三种情况curl -i https://chat.example.com/api/chat # 预期 401, 没有 Authorization 头 curl -i https://chat.example.com/api/chat \ -H Authorization: Bearer abc.def.ghi # 预期 401, 签名非法 curl -i https://chat.example.com/api/chat \ -H Authorization: Bearer $EXPIRED_TOKEN # 预期 401, 令牌过期三种情况的响应都应该是 401同时认证服务日志会记录校验失败的具体原因。我用一张表把验证结果整理了一下测试用例请求方式预期结果实测结果正常消息发送POST /api/chat 有效 JWT200 模型回复正常返回缺认证头POST /api/chat401正常拦截非法令牌POST /api/chat 乱写 JWT401正常拦截WebSocket 连接wss://chat.example.com/ws握手成功正常连接后台未登录访问GET /admin/302 到登录页正常跳转5.3 WebSocket 推送链路测试Clawdbot 的实时推送走的是 WebSocket会话建立时也需要带上令牌。我用wscat工具做测试wscat -c wss://chat.example.com/ws?token$TOKEN连接成功后在网页端发一条消息WebSocket 里应该能同步收到推送事件。如果握手失败最常见的原因就是我在前面说的 Upgrade 头没配置好直接检查 Nginx 配置里的proxy_set_header Connection upgrade和proxy_http_version 1.1这两行。注意通过浏览器直接测试 WebSocket 时安全性检查更严格。如果前端页面和后端不在同一个源还需要处理跨域问题。我这边是把网页前端放在同一个域名下避免了 CORS 相关的麻烦。6. 生产环境建议与一些心里话6.1 上线前必须完成的安全加固整套链路跑通之后离真正上线还有几步收尾工作。我列了一个安全加固清单每一项都花不了多少时间但漏掉任意一项都可能出问题防火墙只放行 80 和 443 端口其他端口一概关闭包括 3000、3100 这些内网端口。PostgreSQL 的数据卷要有独立备份策略我在系统盘之外挂了数据盘并且每天定时把数据库导出到对象存储。.env文件权限设为 600避免同机的其他用户读到密钥。密钥不进 git 仓库团队协作时用密钥管理工具分发。定期更新 Nginx、PostgreSQL 和网关容器镜像。我这边的习惯是每两周跑一次镜像更新先看更新说明再动手。容器内不用 root 用户跑主进程。镜像构建时创建独立用户应用以非特权身份运行。6.2 日志监控与升级策略日志是排查问题的第一依据。容器场景下我用docker compose logs -f --tail 200 app快速看实时日志同时把所有容器日志接到统一的采集服务保留 30 天方便回查某个时间点发生了什么。升级策略上我吃过一次亏直接拉最新镜像重启结果新版本的配置格式变了容器起不来。现在的流程是先备份数据卷再读 changelog 和配置变更说明然后拉新镜像、启动新容器做冒烟测试确认无误后再切换流量。整个过程大概十几分钟但对线上服务影响很小。6.3 折腾这套系统后的几点体会最后说点感受。自托管网关这类系统真正麻烦的地方不在于初始部署而在于持续运维。部署是一次性的复杂度运维是长期的小麻烦。如果不想被日常维护拖住最好从一开始就把自动化做进去——健康检查、日志采集、备份脚本这些前期投入一点点时间后面能省大量精力。另一个体会是像反向代理、WebAuth 这种看似非业务功能的工序越早做越好。如果先裸奔跑起来再补认证中间调试的成本会成倍增加。我在实际测试中发现认证前置配合 Nginx auth_request把访问控制收敛在一个入口后续再接入新渠道、新 API基本不需要改动业务代码。这大概就是这套方案最值钱的地方。