做虚拟商品自动发货这个方向最让人头疼的不是写功能本身而是订单管理和发货链路总在出各种幺蛾子。XianYuAutoDeliveryX 是我针对闲置交易场景里虚拟商品发货效率太低的问题从零写的一套自动化方案核心做的事情其实很朴素监听订单、校验支付状态、把卡密或下载链接自动发出去再配合大模型做客服话术的自动生成。今天这篇就把整个项目的配置过程、核心逻辑以及对接大模型的完整思路一次性讲清楚。如果你正好在做电商自动化、订单系统或者客服机器人方向这篇文章可以帮你少踩不少坑。既然是完整指南我会按照“项目拆解 - 环境准备 - 项目配置 - 发货核心逻辑 - 大模型对接 - 问题排查 - 上线建议”的顺序来写每个环节都会给出可直接参考的配置和代码也会把我在实际跑项目时踩过的坑标注出来。1. 项目整体拆解这款自动发货工具做了什么在动手安装配置之前先把项目到底在解决什么问题说清楚。很多人拿到这种项目第一反应是“这不就是个循环检测订单然后发消息的脚本吗”实际远没那么简单。虚拟商品自动发货牵扯到订单状态同步、商品库存管理、重复发货防护、消息模板、异常重试再加上如今越来越普遍的大模型客服链路远比想象的复杂。1.1 虚拟商品发货的典型痛点虚拟商品的常见形态包括软件激活码、网盘下载链接、课程兑换码、会员充值卡密等。这类商品和实物商品最大的区别在于“交付即完成”买家付款后希望立刻拿到内容等不了太久。而人工发货在真实场景里有几个绕不开的问题一是时间覆盖不足。半夜下单、节假日下单如果商家不在线买家付款后处于“钱付了但东西没到”的状态轻则退款重则产生纠纷和差评。二是重复劳动严重。一个标准卡密类商品发货动作就是“查订单 - 取库存 - 复制内容 - 发送给买家”。这个动作本质上是机械操作完全可以交给程序做。三是售后咨询量大。买家经常会问“链接失效了怎么办”“卡密怎么激活”这类问题每天重复出现纯靠人工回答耗费大量时间。这套项目要解决的就是上述三个问题的组合通过监听订单实现全时段自动发货通过库存表管理卡密和链接通过对接大模型实现常见客服问题的自动回答。1.2 项目的核心模块与运行流程从模块划分上看XianYuAutoDeliveryX 可以拆成以下几个部分配置管理模块负责读取数据库配置、服务端口、平台授权信息、大模型 API Key 等运行参数订单监听模块定时或通过回调方式获取新订单识别未发货订单库存管理模块管理虚拟商品的卡密/链接库存发货时自动扣减发货执行模块把库存内容按模板组合成消息通过平台消息接口发送给买家通知模块发货成功后通知商家异常情况下告警大模型客服模块对接大模型接口处理买家常规咨询整个运行流程大概是订单监听模块拿到新订单 - 写入本地订单库 - 校验支付状态 - 从库存表取出商品内容 - 生成发货消息 - 调用平台发送接口 - 标记订单已发货并记录日志 - 如果启用大模型客服则后续买家消息由大模型自动回复。这个链路里最需要注意的是“幂等性”设计。也就是说无论同一个订单被监听模块捕获多少次系统都只能发货一次。我的做法是在订单表里增加一个delivery_status字段发货前用事务更新状态状态更新成功才执行发货这样可以最大程度避免重复发货。2. 环境准备先把依赖装明白这个项目基于 Node.js 开发数据库使用 MySQL代码管理用 Git。所以环境准备阶段需要把 Node.js、MySQL、Git 这三样安装配置好。很多新手在配置阶段就放弃了绝大多数问题不是项目本身的问题而是环境没装对。2.1 Node.js 安装与版本选择项目依赖了比较新的 npm 包建议使用 Node.js 16 及以上版本。我个人推荐装 Node.js 18 LTS 或 20 LTS这两个版本稳定性和生态兼容性都比较好。在 Windows 环境下直接到 Node.js 官网下载安装包安装时一路 Next 即可。安装完成后需要确认环境变量是否生效打开命令行执行node -v npm -v如果提示“node 不是内部或外部命令”说明环境变量没有配置到位。安装包安装的 Node.js 一般会自动写入 PATH如果你是用绿色解压版需要手动把 Node.js 目录添加到系统环境变量里。我实际踩过的一个坑是node 和 npm 版本不匹配。例如 node 版本很高但 npm 是老版本安装依赖时会报各种未知错误。遇到这种情况可以通过 npm 自己升级npm install -g npmlatest另外如果你的开发环境需要同时维护多个 Node 项目建议安装 nvm-windows 来管理 Node 版本切换起来非常方便避免不同项目对 Node 版本要求冲突。2.2 MySQL 安装、初始化与账号配置MySQL 在本项目里扮演的角色是订单和库存的持久化存储。安装有两种主流方案一种是安装 MySQL Community Server另一种是直接用 Docker 跑容器。如果你只是本地开发调试Docker 方案最省心如果你希望数据文件更直观可控建议装社区版。以 MySQL 8.x 为例安装完成后首先要确认服务已启动。Linux 下用 systemctlWindows 下在服务管理器里查看 MySQL 服务状态。接着常规操作是初始化数据库和账号mysql -u root -p进入 MySQL 命令行后创建项目专用的数据库和账号CREATE DATABASE IF NOT EXISTS xianyu_delivery DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci; CREATE USER delivery_userlocalhost IDENTIFIED BY YourStrongPassword; GRANT ALL PRIVILEGES ON xianyu_delivery.* TO delivery_userlocalhost; FLUSH PRIVILEGES;字符集建议强制使用 utf8mb4因为虚拟商品内容里可能出现表情符号或者特殊字符utf8mb4 才能完整存储这一点非常关键。MySQL 8.x 默认的认证插件是 caching_sha2_password如果你在做项目对接时一直报认证错误可能是因为 Node.js 的 mysql 客户端不支持这个认证方式。解决方法是在 MySQL 里把用户认证插件改回 mysql_native_passwordALTER USER delivery_userlocalhost IDENTIFIED WITH mysql_native_password BY YourStrongPassword; FLUSH PRIVILEGES;这个问题我在多个环境里碰到过属于非常典型的配置坑。2.3 Git 安装与代码拉取Git 用于拉取项目源码和后续更新。Windows 下安装 Git for Windows 之后会自带 Git Bash用起来比 CMD 舒服很多。Linux/macOS 下用系统包管理器安装即可。安装完成后先把项目代码拉到本地git clone https://github.com/your-repo/XianYuAutoDeliveryX.git cd XianYuAutoDeliveryX如果你只需要参考核心代码而不不需要频繁更新可以只拉取默认分支如果你要二次开发建议先 fork 到自己仓库再 clone方便后续维护自己的改动。3. 项目配置从零到跑通核心流程环境准备好之后进入项目配置阶段。这一步是整个项目从“能跑”到“好好跑”的分水岭配置得当后续运行基本不用再去翻代码配置疏漏调试的时间可能比写代码还长。3.1 下载代码与安装依赖进入项目目录后先安装 npm 依赖。这一步根据不同网络环境耗时差异比较大可能几分钟到十几分钟npm install如果你发现安装速度极慢或某些包安装失败可以切换 npm 镜像源。我用的是国内镜像配置一次之后速度提升非常明显npm config set registry https://registry.npmmirror.com安装完成后先看一下项目目录结构。一个典型的 Node.js 自动发货项目大概长这样XianYuAutoDeliveryX/ ├── config/ │ └── config.js ├── src/ │ ├── core/ │ │ ├── orderMonitor.js │ │ ├── stockManager.js │ │ └── deliveryExecutor.js │ ├── services/ │ │ ├── platformService.js │ │ └── llmService.js │ └── utils/ │ ├── logger.js │ └── retry.js ├── scripts/ │ └── initDatabase.js ├── .env.example ├── package.json └── app.js这个结构很清晰config放配置逻辑src/core放核心业务逻辑src/services放外部服务对接逻辑scripts放初始化脚本。如果你要二次开发照着这个划分往里面加模块即可。3.2 配置项逐项解读项目根目录下会有一个.env.example文件这是所有运行配置的入口。你需要在项目根目录复制一份并改名为.env然后填入真实配置cp .env.example .env下面是我实际填过的一版核心配置每项作用我做了标注# 服务端口 APP_PORT3000 # 数据库配置 DB_HOST127.0.0.1 DB_PORT3306 DB_USERdelivery_user DB_PASSWORDYourStrongPassword DB_NAMExianyu_delivery # 日志级别 LOG_LEVELinfo # 大模型 API 配置 LLM_API_KEYyour_llm_api_key LLM_BASE_URLhttps://api.example.com/v1 LLM_MODELyour-model-name数据库那一块按上一章创建的账号填写即可。大模型配置先留空后续接入时再填。在.env编辑完成之后项目的config.js会自动读取这些环境变量。注意.env文件不要提交到 Git 仓库里面都是敏感信息建议把.env加入.gitignore。3.3 数据库迁移与初始化配置好.env后需要初始化数据库表结构。项目里提供了初始化脚本npm run init-db这个命令会自动连接 MySQL 并创建项目运行所需的数据表。初始化完成后可以用 MySQL 客户端检查一下表结构是否创建成功USE xianyu_delivery; SHOW TABLES;比较核心的表有几个orders订单表、products商品表、stock_items库存表、delivery_logs发货日志表。这里面每一张表都有对应的关键设计。orders表的核心字段是platform_order_id平台侧订单号、buyer_id买家标识、product_id商品ID、delivery_status发货状态其中platform_order_id需要加唯一索引防止重复写入。delivery_status建议用整数枚举0 表示未发货1 表示已发货2 表示发货失败3 表示已退款。stock_items表对应具体卡密或链接核心字段是content卡密内容、status0 未使用、1 已售出、order_id关联的订单号用于追溯。delivery_logs表用于审计记录每一次发货动作的请求参数和返回结果方便排查问题。我发现很多人忽略了delivery_logs表的价值但其实它是排查问题的第一手资料。上线运行一段时间之后如果出现“买家说没收到货”这类问题先查delivery_logs就能定位到是发送环节失败还是买家侧接收问题。4. 自动发货核心逻辑详解配置跑通之后核心业务逻辑就是自动发货。这一章重点讲订单监控、发货执行、库存管理这三个环节的实现细节。4.1 订单监控是如何实现的订单监控有两种常见方案轮询和回调。轮询方案是程序定时调用平台订单查询接口把最近一段时间的新订单拉到本地处理。优点是实现简单、不依赖平台推送缺点是有延迟而且如果轮询频率过高容易被平台限流。回调方案是平台在订单状态变化时主动通知你的服务器。优点实时性好缺点是需要一个公网可访问的服务端接收回调并且回调地址需要提前配置。我在项目里默认用的是轮询方案频率设置为 15 秒一次兼顾实时性和接口调用频率。核心逻辑代码大致是这个思路async function pollNewOrders() { const sinceTime getLastPollTime(); const orders await platformService.fetchOrders({ since: sinceTime }); for (const order of orders) { await handleNewOrder(order); } setLastPollTime(Date.now()); }其中handleNewOrder里要做三件事写入订单表注意去重、校验支付状态、触发发货。这三步逻辑要拆成独立函数方便单测和日志追踪。轮询的最大风险是重复拉取。平台接口通常不会保证分页数据完全稳定订单有可能被重复拉到。所以写入订单表这一步必须做防重处理也就是依赖前面提到的platform_order_id唯一索引插入时用INSERT IGNORE或者先查后插。4.2 发货处理与卡密库存管理订单确认已支付后进入发货环节。发货的动作非常简单从库存表里取一条未售出的库存更新为已售出关联到订单号然后把内容组装成消息发送给买家。但这中间有一个需要谨慎处理的点库存扣减和发货动作的一致性。如果先扣库存再发货发消息失败后库存就少了订单卡住如果先发货再扣库存万一发了重复库存容易出现一单多发。我的做法是使用事务把库存扣减和订单状态更新放在一起async function deliveryWithTransaction(order) { const transaction await db.beginTransaction(); try { const stockItem await stockManager.acquireStock(transaction, order.productId); if (!stockItem) { await orderManager.markFailed(transaction, order.id, 库存不足); await transaction.commit(); return { success: false, reason: 库存不足 }; } await orderManager.markDelivering(transaction, order.id, stockItem.id); await transaction.commit(); // 事务提交成功后再真正发送消息 const result await platformService.sendMessage(order.buyerId, buildMessage(stockItem.content)); await orderManager.markDelivered(order.id, result.messageId); } catch (error) { await transaction.rollback(); await orderManager.markFailed(order.id, error.message); } }注意我特意把“事务内扣库存更新状态”和“事务外发送消息”分开了。原因是发送消息属于外部调用不应该占用数据库事务。这样即使消息发送超时事务也已经提交库存不会因为外部接口抖动而回滚混乱。库存不足是虚拟商品发货里常见的异常。我的处理策略是标记订单发货失败并给商家发送一条告警通知提示“商品 XXX 库存不足请尽快补货”。同时系统可以定时扫描失败订单在补货后自动重试发货避免商家手动逐单处理。4.3 发货消息模板与多渠道通知发货消息不是简单地把卡密甩给买家而是需要一套模板。比如您好您购买的【商品名称】已发货。 内容如下 {卡密内容} 使用方法详见{使用说明} 如有问题请直接回复谢谢。模板里可以带换行方便阅读也可以把使用教程链接一起发出去。很多售后问题其实是因为买家不知道如何激活发消息时把说明带上能显著降低咨询量。除了发给买家的消息商家侧也需要通知。当出现库存不足、发货失败、异常订单时可以通过邮件、Server酱、钉钉机器人等方式推送给商家。推送通知的意义在于及时发现问题尤其是夜间出现的异常不需要等到第二天早上才发现。我在实践中给所有需要人工介入的分支都加了通知包括库存不足、发货失败重试仍失败、大模型调用异常等宁可多打扰一次也不能让异常在后台悄悄堆积。5. 对接大模型从固定话术到智能客服这一章是很多人感兴趣的部分。自动发货本身并不新鲜但接上大模型之后整个项目的价值密度明显提升。大模型在这个项目里能承担的角色大概有三个自动生成发货话术、自动回答售后咨询、分析买家意图做商品推荐。5.1 为什么要给自动发货接大模型传统自动发货的客服部分靠的是关键词匹配或人工无法灵活处理“你好我这个手机是安卓的用不了那个激活工具怎么办”这类需要理解上下文的提问。接入大模型之后可以让 AI 根据订单历史和商品信息生成有针对性、语气自然的回复减少人工介入。另一个实际价值是话术生成。不同买家的提问风格差异很大用统一模板回复体验生硬。大模型可以根据买家的提问内容生成语气合适的回复比如买家问“这个卡密是真的吗”模型可以识别出“信任担忧”并生成安抚性回复。需要注意的是大模型客服不是万能钥匙。涉及退款、纠纷、平台违规判断等敏感场景我建议仍然强制转人工不要让模型自作主张。5.2 大模型对接的配置与封装对接大模型的配置在前面.env里已经预留了三个字段LLM_API_KEY、LLM_BASE_URL、LLM_MODEL。接入时填上真实值即可。在代码层面我不会直接把 OpenAI SDK 或各家 SDK 散落在业务代码里而是封装一个llmService统一处理请求和响应。封装的好处是可以随时切换不同的模型服务商不用改业务代码。核心思路如下class LLMService { constructor(config) { this.apiKey config.apiKey; this.baseUrl config.baseUrl; this.model config.model; } async chat(messages, options {}) { const response await fetch(${this.baseUrl}/chat/completions, { method: POST, headers: { Content-Type: application/json, Authorization: Bearer ${this.apiKey} }, body: JSON.stringify({ model: this.model, messages, temperature: options.temperature ?? 0.7 }) }); if (!response.ok) { throw new Error(LLM API error: ${response.status}); } const data await response.json(); return data.choices[0].message.content; } }使用 fetch 原生请求即可不额外引入 SDK这样无论对接哪家模型服务商只要兼容 OpenAI 风格接口的都可以直接使用。5.3 示例代码大模型生成发货话术与常见问答下面给出两个实际的对接场景示例。第一个场景是自动生成发货话术。虽然大多数商品用一个固定模板就够但部分高价值虚拟商品买家付款后如果只收到一句“已发货请查收”体验偏冷。可以调用大模型生成一段更自然的发货消息async function generateDeliveryMessage(order, product, buyerNickname) { const messages [ { role: system, content: 你是一个虚拟商品店铺的客服助手负责给买家发送发货消息。要求语气友好、简洁不做任何承诺。 }, { role: user, content: 买家昵称${buyerNickname}\n商品名称${product.name}\n发货内容${product.deliveryContent}\n请生成一段发货消息。 } ]; const reply await llmService.chat(messages, { temperature: 0.5 }); return reply; }第二个场景是自动回答售后咨询。买家在收到货之后发来消息先通过平台回调接收消息内容然后调用大模型生成回复async function handleBuyerMessage(buyerMessage) { const isSensitive detectSensitiveTopic(buyerMessage); if (isSensitive) { return { needHuman: true, reply: 这个问题我帮您转人工处理请稍等。 }; } const messages [ { role: system, content: 你是一个闲置交易平台的虚拟商品客服助手。你只能回答与订单、发货、卡密使用相关的问题。遇到不确定的内容请引导买家联系人工客服不要编造信息。 }, { role: user, content: buyerMessage } ]; const reply await llmService.chat(messages, { temperature: 0.3 }); return { needHuman: false, reply }; }这里需要特别强调一个关键设计必须给大模型设置系统提示词明确约束其回答边界。如果没有系统提示词约束大模型可能编造政策、承诺退款条件这在实际运营中是非常危险的。我在项目里把系统提示词放在配置文件中方便随时调整。此外大模型接口的超时控制和重试必须处理。任何外部 API 都有超时风险我的策略是超时时间 10 秒失败重试 2 次仍然失败则转人工处理。绝不能因为大模型接口抖动导致买家消息没人回复。6. 常见问题与排查技巧实录整个项目从配置到运行我整理了实际踩过的十几个问题按类别分享一下排查思路。6.1 环境类问题速查问题可能原因解决方法node -v无输出Node.js 未安装或未写入 PATH重新安装 Node.js检查环境变量npm install速度极慢默认源访问慢切换镜像源启动时报Error: Cannot find module依赖安装不完整删除 node_modules 后重新安装数据库连接报ER_NOT_SUPPORTED_AUTH_MODEMySQL 认证插件不兼容修改用户认证方式为 mysql_native_password服务启动后访问无响应端口被占用检查端口占用更换 APP_PORT端口占用是我碰到的高频坑。启动服务时如果提示EADDRINUSE说明端口已被占用用下面的命令查看占用进程netstat -ano | findstr 3000找到 PID 后在任务管理器结束进程或者直接在.env里换一个端口。6.2 配置类问题配置类问题里最隐蔽的是.env文件格式错误。比如配置项后面加了多余空格、引号未配对、字符编码不是 UTF-8都会导致解析异常。建议编辑.env时使用 VS Code 等编辑器并确认右下角编码是 UTF-8。还有一类问题是大模型配置写错。LLM_BASE_URL必须填写到版本路径之前比如https://api.example.com/v1后面不要再拼接/chat/completions因为代码里已经拼好了。填成完整地址会报 404。平台授权相关配置要特别注意字段含义。有些平台提供的是密钥对需要同时配置 access key 和 secret key只填一个会导致鉴权失败。鉴权失败时先确认平台侧的授权是否有效、是否过期。6.3 运行时问题运行时问题集中在订单不触发、发货重复、库存扣错三个方向。订单不触发时第一件事是看日志。我的项目日志在logs/目录下会按天拆分搜索pollNewOrders相关的日志。如果发现轮询根本没有执行优先检查数据库连接是否正常或者 cron 定时器是否被系统 suspend。发货重复的原因 90% 以上是幂等没做好。排查思路是查orders表里同一platform_order_id是否有多个记录或者delivery_logs里同一个订单出现了多次发送记录。解决方式是给platform_order_id建唯一索引并且在发货前用 UPDATE 判断受影响行数。库存扣错的情况出现在并发场景下。多个订单同时购买同一商品时如果库存查询和更新不是原子操作可能把同一条库存发给两个买家。解决方式是在扣减库存的 SQL 里加条件UPDATE stock_items SET status 1 WHERE id ? AND status 0如果受影响行数为 0说明库存已被其他订单抢走需要重新分配。我个人还养成了一个习惯在本地开发时开一个 debug 模式把每次订单监听、发货、库存扣减的详细参数都打印出来。调试效率能提升非常多远比对着代码猜要快。7. 合规使用与上线建议最后讲一些关于正常上线和长期稳定运行的建议这也是我实际跑这个项目快半年之后总结出来的一些体会。自动发货本身是个提效工具但在使用第三方平台的能力时必须注意边界。7.1 合规使用提醒虚拟商品自动发货工具在技术上并没有什么问题但使用之前建议先确认以下几点一是使用平台官方允许的方式获取订单信息。目前主流交易平台都有开放的开发者能力和接口文档如果你要接入订单查询、消息发送这类功能优先使用官方提供的接口不要用非官方手段去模拟操作这样既稳定也没有被风控的担忧。二是不要过度营销。自动发货系统解决的问题是“及时履约”不是“骚扰买家”。发货后简单说明即可不要给已购买家群发推广消息这一点既是平台规则要求也直接影响店铺体验分和复购率。三是售后兜底要保留人工通道。任何自动化系统都会遇到无法处理的情况大模型也不是万能的。在系统里保留“转人工”的出口让买家在需要时能找到真人处理比让 AI 硬撑着更能避免纠纷。四是数据安全。买家的订单数据、联系方式都要妥善保管日志脱敏、数据库定期备份这些自动化工具反而容易被人忽视。建议在服务器上配置定时备份任务至少每天备份一次数据库。7.2 上线前检查清单我在每次部署这套系统到新环境时都会过一遍以下检查项这里直接分享给你确认.env里的数据库账号密码是强密码且不与其他系统共用确认.env未被提交到公共 Git 仓库确认数据库已启用 utf8mb4 字符集避免特殊字符写入失败确认平台授权信息有效用脚本手动调用一次订单查询接口确认返回数据正常用小额订单或测试商品跑一遍完整发货流程确认买家可以正常收到消息检查通知渠道邮件/钉钉/Server酱能否正常收到告警确认 Node.js 服务已经配置了进程守护比如使用 pm2避免进程意外退出后没有人拉起检查日志文件是否有定时清理策略避免长期运行后磁盘被日志占满实际跑下来之后我把 pm2 的配置也固化到了项目里通过pm2 start app.js --name xianyu-delivery --max-memory-restart 400M这类命令统一管理配合开机自启基本实现了无人值守。写在最后跑自动化发货这个方向也有大半年了我个人最大的体会是这类工具的价值不在于代码有多复杂而在于把“订单来了有人管、货发了有人知、出事了有人报”这套流程真正跑顺。后面我还在计划给这个项目加上数据看板功能把每天的订单量、发货成功率、库存消耗曲线都可视化出来。库存少于阈值时自动提醒补货甚至根据近几天的发货速度预测未来的库存需求。如果你也在做类似方向欢迎在评论区一起交流踩过的坑和优化思路尤其是大模型客服和自动发货结合的经验我很想听听大家的做法。