简介这份资源是一套基于Flask框架、ChatGPT接口与Docker容器化部署的微信公众号聊天机器人完整项目面向具备Python基础、希望快速搭建智能对话公众号的开发者与学习者。项目将后端服务、模型调用与容器编排整合在一起适合用作课程设计、个人练手或二次开发的基础模板。压缩包共15个文件约52KB包含3个py源码文件、3个md部署与说明文档、2个yml容器编排配置以及Pipfile依赖清单、Dockerfile、LICENSE等工程化文件覆盖从代码到部署的完整链路。目前已有142人学习下载。读者可获得可直接运行的机器人后端源码、Flask与Docker两套部署文档、依赖锁定文件与容器化配置便于理解微信公众号消息接入、ChatGPT对话逻辑与一键部署流程并在此基础上替换数据、扩展功能或进行排错调试。1. 从一条公众号消息到 ChatGPT 回复这套 Flask 后端到底能跑通什么公众号后台收到一条用户消息微信服务器会在 5 秒内要求你返回结果超时就直接重试三次。这个硬约束决定了任何公众号接大模型的项目核心难点从来不是调 API而是怎么在 5 秒内把异步的模型回复塞回用户手里。这套基于 Flask ChatGPT Docker 的微信公众号聊天机器人源码解决的正是这件事它用 Flask 起一个 webhook 服务接收微信推送把用户消息转给 ChatGPT再把回复按微信要求的 XML 格式吐回去同时用 Docker 把整个运行环境封成一个镜像省掉在服务器上逐个装依赖的功夫。适合谁看手上已经有一个认证过的公众号服务号或订阅号都行订阅号需要服务器配置权限、一台能跑 Docker 的机器、一个能调通的 OpenAI API Key。如果你只是想本地跑个 demo 看看效果这套东西也能用但公众号那部分得靠内网穿透或者干脆跳过只测 Flask 接口。下面按资源里有什么 → 怎么把它跑起来 → 参数怎么调 → 哪里会翻车的顺序拆一遍源码包里的app.py、chatgpt.py、docker-compose.yml是三个最该先看的文件。2. 拆开压缩包先看什么Flask 入口、ChatGPT 封装与 Docker 三件套拿到wechat-chatgpt-master这个目录别急着pip install。先花十分钟把文件结构过一遍能省掉后面一半的调试时间。这套项目的分层其实很清晰app.py是 Flask 的 webhook 入口chatgpt.py封装了和 OpenAI 的交互log.py管日志Dockerfile和docker-compose.yml负责环境Pipfile/Pipfile.lock锁依赖版本。部署文档有两份一份讲 Python 系统部署一份讲 Flask 系统部署内容有重叠看 Flask 那份就够。2.1 app.py 里的微信签名校验与消息路由微信服务器配置 URL 时会先发一个 GET 请求带signature、timestamp、nonce、echostr四个参数来验证你的服务器是不是活的。校验逻辑是把token、timestamp、nonce三个值按字典序排序后拼接做一次 SHA1再和signature比对。这一步错了公众号后台点提交永远提示token验证失败。# app.py 中微信接入验证的核心逻辑示意以实际源码为准 import hashlib WECHAT_TOKEN your_token_here # 必须和公众号后台填的 Token 完全一致 def check_signature(signature, timestamp, nonce): # 1. 三个值按字典序排序 sort_list sorted([WECHAT_TOKEN, timestamp, nonce]) # 2. 拼接成一个字符串 sort_str .join(sort_list) # 3. SHA1 加密 hash_str hashlib.sha1(sort_str.encode(utf-8)).hexdigest() # 4. 与微信传来的 signature 比对 return hash_str signature逻辑说明WECHAT_TOKEN是你在公众号后台服务器配置里自己填的一串字符必须和代码里完全一致大小写敏感。sorted()默认按字符编码排序微信官方文档要求的就是字典序别改成按时间排序。SHA1 输出是十六进制小写hexdigest()正好对上。参数说明signature是微信算好的签名你算出来的hash_str和它相等才算通过。常见错误是把token写成了access_token那是两码事。消息路由部分微信 POST 过来的是 XML不是 JSON。Flask 里得用request.data拿原始字节再解析用request.json会直接报错。解析出MsgType后判断是text还是event文本消息取Content字段事件消息比如关注取Event字段。回复也得是 XML格式错了微信不认用户那边就是该公众号暂时无法提供服务。2.2 chatgpt.py 的请求封装与超时控制chatgpt.py干的事是把用户文本发给 OpenAI 的接口拿回回复文本。这里有两个参数直接决定用户体验model和timeout。模型选gpt-3.5-turbo这类对话模型别用text-davinci那种补全模型后者对中文对话场景不友好。超时时间建议设 4 秒以内因为微信那边 5 秒就断留 1 秒给网络和 XML 组装。# chatgpt.py 请求封装示意 import openai openai.api_key sk-xxxxxxxx # 换成你自己的 Key openai.api_base https://api.openai.com/v1 # 有中转就改这里 def get_gpt_reply(user_text, timeout4): try: resp openai.ChatCompletion.create( modelgpt-3.5-turbo, messages[{role: user, content: user_text}], timeouttimeout, max_tokens500 ) return resp.choices[0].message.content.strip() except Exception as e: # 超时或报错时给用户一个兜底回复别让公众号卡死 return 稍等我这边有点忙请再发一次逻辑说明messages用列表结构role可以是system、user、assistant想加人设就加一条system。max_tokens控制回复长度设太大不仅慢还费额度。timeout是 requests 层面的超时不是模型推理时间设 4 秒意味着 4 秒内没拿到完整响应就抛异常。参数说明api_base如果你用的是官方地址就保持默认用第三方中转就改成对应地址但注意中转的稳定性和合规性自己把握。异常处理里返回兜底文案比让用户干等 5 秒然后收到该公众号暂时无法提供服务体验好得多。2.3 Dockerfile 与 docker-compose.yml 的环境固化Dockerfile一般基于python:3.7-slim或python:3.9-slim把Pipfile拷进去用pipenv install --system --deploy装依赖再COPY . .最后CMD [python, app.py]。docker-compose.yml则把端口映射、环境变量、重启策略写在一起一条docker-compose up -d就能起服务。# docker-compose.yml 结构示意 version: 3 services: wechat-bot: build: . ports: - 80:5000 # 宿主机 80 映射容器 5000微信要求 80 或 443 environment: - WECHAT_TOKENyour_token_here - OPENAI_API_KEYsk-xxxxxxxx restart: always # 崩了自动拉起生产环境必加逻辑说明微信服务器配置只接受 80 或 443 端口所以宿主机映射必须用这两个之一容器内部 Flask 默认跑 5000 就映射成80:5000。环境变量把 Token 和 Key 从代码里抽出来改配置不用重新 build 镜像。restart: always是血泪经验Flask 单进程遇到未捕获异常会退出没这行半夜挂了都不知道。参数说明build: .表示用当前目录的 Dockerfile 构建如果你要拉现成镜像就换成image: xxx。3. 从零跑通Python 本地调试与 Docker 一键部署两条路这套资源给了两种跑法本地 Python 直跑适合调试Docker 适合上线。建议先在本地把逻辑跑通确认签名校验和 GPT 调用都没问题再上 Docker。直接上 Docker 的话日志在容器里排查起来多一层。3.1 本地 Python 环境准备与依赖安装Python 版本按文档要求 3.7 或以上实测 3.9 和 3.10 也能跑但 3.11 之后某些老依赖可能编译报错。用 Pipenv 的话进目录先pipenv install它会读Pipfile装依赖并生成虚拟环境。不想用 Pipenv 就直接pip install flask openai requests但版本可能和Pipfile.lock锁的不一致遇到玄学问题优先怀疑版本。# 方式一用 Pipenv推荐和项目锁文件一致 cd wechat-chatgpt-master pip install pipenv pipenv install pipenv shell # 进入虚拟环境 # 方式二直接 pip快但版本可能漂移 pip install flask openai requests # 启动服务 python app.py # 看到 Running on http://0.0.0.0:5000 就算起来了逻辑说明pipenv shell进虚拟环境后所有命令都在隔离环境里跑不会污染系统 Python。python app.py启动的是 Flask 自带的开发服务器够调试用但生产环境必须换 gunicorn 或 uwsgiFlask 自带服务器扛不住并发。参数说明如果app.py里写死了app.run(debugTrue)上线前记得关掉 debug否则报错页面会暴露源码路径。本地跑起来后公众号那边还没法直接连因为微信要求公网可访问的 80/443。调试阶段常见做法是用内网穿透工具把本地 5000 映射出去拿到一个临时域名填到公众号后台。但注意穿透工具的域名每次重启会变公众号配置也得跟着改比较折腾。更稳的做法是直接在一台有公网 IP 的云服务器上跑。3.2 Docker 镜像构建与容器编排服务器上装好 Docker 和 docker-compose 后把整个目录传上去改好docker-compose.yml里的环境变量两条命令搞定。# 构建并后台启动 docker-compose up -d --build # 查看日志确认没有报错 docker-compose logs -f # 查看容器状态STATUS 要是 Up docker ps # 改完代码重新部署 docker-compose down docker-compose up -d --build逻辑说明--build强制重新构建镜像改了代码不加这个参数容器里还是旧的。logs -f实时跟日志CtrlC 退出但不影响容器运行。docker ps看STATUS列如果是Restarting说明启动就崩了得看日志找原因。参数说明-d是后台运行不加的话终端一关服务就停。down会删容器但保留镜像up -d --build重新构建启动这是改代码后的标准动作。部署完在公众号后台填服务器地址格式是http://你的域名/wechat路径看app.py里路由怎么写的Token 填和代码里一致的点提交。如果提示成功再给公众号发条消息几秒内应该能收到 GPT 的回复。收不到就按下一章的排查顺序走。3.3 公众号后台服务器配置与消息联调公众号后台开发 → 基本配置 → 服务器配置里URL 填公网地址Token 填自定义字符串EncodingAESKey 随机生成消息加解密方式选明文模式最省事。选安全模式的话代码里还得处理 AES 解密这套源码不一定带了别给自己找麻烦。提交时微信会发 GET 验证请求通过后配置才生效。生效后发消息微信 POST 到你的 URL你的服务返回 XML。联调阶段最容易卡在三个地方签名校验失败、XML 格式不对、5 秒超时。签名失败看 Token 是否一致XML 格式不对看返回的Content字段有没有转义特殊字符超时看 GPT 调用是不是太慢。建议在app.py里把收到的原始 XML 和返回的 XML 都打日志出问题一眼就能定位。4. 参数调优与避坑Token、超时、模型选择里的那些坑这套东西跑起来不难难的是稳定跑下去。下面几条是实际部署时最常撞上的每条按现象 → 原因 → 解决写照着排查能省不少时间。4.1 避坑一公众号提示该公众号暂时无法提供服务现象后台配置提交成功但一发消息就提示无法提供服务日志里可能连请求都没收到。原因最常见的是返回的 XML 格式不对。微信要求回复的 XML 根节点是xml里面ToUserName和FromUserName的位置和请求里是反的——请求里ToUserName是你的公众号回复里ToUserName要填用户的 OpenID。搞反了微信直接丢弃。解决对照微信官方文档的回复 XML 模板逐字段核对特别注意ToUserName和FromUserName互换CreateTime是秒级时间戳不是毫秒。另外Content里如果有、、这些字符要做 XML 转义否则解析失败。4.2 避坑二GPT 回复慢导致微信重试三次现象用户发一条消息公众号回了三条一样的或者回复内容对不上。原因微信 5 秒没收到响应就重试重试三次。你的服务如果每次都调 GPT 且耗时超过 5 秒微信就认为你没收到重复推送。而你的服务每次收到都调一次 GPT就回了多次。解决两个方向。一是把 GPT 调用超时压到 4 秒以内超时就返回兜底文案保证 5 秒内必回。二是做消息去重用MsgId做键处理过的直接返回空串或缓存结果微信收到空串不会重试。生产环境建议两个都做。4.3 避坑三Docker 容器起来了但外部访问不通现象docker ps显示 Up但浏览器访问域名超时公众号也连不上。原因端口映射写错或者服务器安全组没放行。docker-compose.yml里80:5000前面是宿主机端口后面是容器端口写反了外部访问 5000 但容器里 Flask 监听的是 5000宿主机 80 没映射上。另外云服务器默认安全组只开 2280 和 443 要手动放行。解决docker port 容器名看实际映射关系确认宿主机端口对。安全组在云控制台加规则放行 80 和 443 的入方向。本地curl http://localhost:80能通但外网不通基本就是安全组问题。4.4 避坑四API Key 泄露或额度被刷爆现象账单突然暴涨或者 Key 被禁用。原因Key 硬编码在chatgpt.py里代码传到公开仓库或者镜像被拉走Key 就泄露了。另外没有做频率限制被人恶意刷接口。解决Key 一律走环境变量docker-compose.yml里用environment注入代码里os.environ.get(OPENAI_API_KEY)读。加一层简单的频率限制比如同一个 OpenID 每分钟最多 5 次用内存字典或 Redis 都行。公开仓库前务必检查有没有把 Key 提交上去提交过的话换 Key改历史记录没用。4.5 避坑五Python 版本和依赖版本不匹配现象pipenv install报编译错误或者跑起来ImportError。原因Pipfile.lock锁的是特定版本Python 3.11 之后某些包比如老版本cryptography没有预编译 wheel要现场编译缺系统库就报错。或者系统里同时有多个 Pythonpip装到了 A 环境python跑的是 B 环境。解决优先用文档要求的 Python 3.7~3.10。确认which python和which pip指向同一个环境。Docker 部署能规避大部分这类问题因为镜像里 Python 版本是固定的所以生产环境强烈建议走 Docker。5. 进阶把单轮问答改成带上下文的多轮对话默认这套源码是单轮的用户每发一句都是独立请求GPT 不记得上一句说了什么。想改成多轮核心是维护一个会话历史。最简单的做法是用字典按 OpenID 存最近几轮对话每次请求把历史一起发给 GPT。# 多轮对话维护示意 from collections import defaultdict # 每个用户最多保留 5 轮防止 token 超限 history defaultdict(list) MAX_ROUNDS 5 def get_reply_with_context(openid, user_text): history[openid].append({role: user, content: user_text}) # 只保留最近 MAX_ROUNDS 轮 if len(history[openid]) MAX_ROUNDS * 2: history[openid] history[openid][-MAX_ROUNDS * 2:] resp openai.ChatCompletion.create( modelgpt-3.5-turbo, messageshistory[openid], timeout4 ) reply resp.choices[0].message.content.strip() history[openid].append({role: assistant, content: reply}) return reply逻辑说明history用defaultdict(list)每个 OpenID 一个列表存user和assistant交替的消息。MAX_ROUNDS * 2是因为一轮对话包含一问一答两条消息。超出就切片保留最近的防止消息列表无限增长把 token 撑爆。参数说明MAX_ROUNDS设 5 意味着记得最近 5 轮设太大不仅慢还费钱设太小用户觉得失忆。这个方案的内存版重启就丢历史要持久化就换 Redis键用 OpenID值存 JSON 序列化的消息列表加个过期时间比如 30 分钟。验证多轮是否生效发我叫小明再发我叫什么能答出小明就对了。如果答不出检查history是不是每次请求都新建了或者 OpenID 取错了字段。另外注意多轮会让每次请求的 token 数增加响应时间变长4 秒超时可能不够得根据实际网络情况调必要时把兜底文案改成正在思考请稍等再发一次。从那以后我每次部署这类 webhook 服务都强制先本地打日志跑通签名和 XML 往返再上 Docker最后才配公众号后台——顺序反了排查起来就是黑匣子。希望帮到你。本文还有配套的精品资源点击获取
