企业官网建设流程全解析

1. 订单-库存-搜索链路为什么要统一模型通道

订单服务创建订单后要扣库存、写搜索索引，这条链路一旦串行调用，任何一环抖动都会把响应时间拖到秒级。我试过把库存扣减和索引更新拆成 RabbitMQ 异步消息，订单主流程只负责落库和发消息，响应时间从 800ms 降到 120ms 左右。但异步化之后又冒出新问题：库存服务、搜索服务、订单服务各自维护一套模型调用配置，Key 散落在不同机器的环境变量里，改一次配置要登录三台机器，还容易漏。

这个场景的核心矛盾不是"能不能跑通"，而是"配置能不能收敛到一处"。分布式链路里每个服务都可能调用大模型做意图识别、商品标题生成、搜索词改写，如果每个服务都自己写一套 HTTP 客户端和鉴权逻辑，维护成本会随服务数量线性增长。把模型调用统一到一个兼容 OpenAI 协议的通道上，所有服务共用同一个 Base URL 和 Key，配置迁移就变成改一个地址的事。

适合谁看：已经在用 SpringCloud 做服务拆分，手上有 RabbitMQ 和 Redis，想给微服务加模型能力但不想每个服务重复造轮子的后端同学。你需要对application.yml和 Docker Compose 有基本概念，能看懂@FeignClient和@RabbitListener注解。

链路长这样：Gateway 接请求 → 订单服务落库 → 发消息到 RabbitMQ → 库存服务消费扣减 → 搜索服务消费更新索引 → 任一服务需要模型能力时，通过统一通道调用。Redis 负责缓存商品详情和库存余量，减少数据库压力。下面按这个链路把配置一步步改到位。

2. TaoToken 在微服务链路里的定位与前置准备

TaoToken 在这里扮演的是"统一模型出口"的角色。它提供 OpenAI 兼容的 HTTP 接口，意味着你不需要为每个服务引入不同的 SDK，用 Spring 的RestTemplate或WebClient就能调。对微服务架构来说，兼容协议比功能多更重要——协议统一了，配置才能统一。

前置准备分三块。第一块是账号和 Key：访问官网 https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= 注册后，进控制台 https://taotoken.net/console?utm_source=taotoken_aicg_blog_end&utm_content=console 创建 API Key。Key 只在创建时完整显示一次，复制后先存到密码管理器，后面要写进 Docker Compose 的环境变量。

第二块是确认接口地址。API 根地址是 https://taotoken.net/api ，注意这个地址不带任何查询参数。模型对话的完整路径是https://taotoken.net/api/v1/chat/completions，和 OpenAI 官方路径结构一致。你可以在模型对话页面 https://taotoken.net/models?utm_source=taotoken_aicg_blog_end&utm_content=models 先手动发一条消息，确认 Key 能用、返回格式正常，再往代码里写。

第三块是本地环境。你需要一个能跑 Docker 的机器，Docker Compose 版本 1.29 以上。SpringCloud 项目建议用 JDK 8 或 11，Spring Boot 2.6.x 配 Spring Cloud 2021.0.x 比较稳。RabbitMQ 和 Redis 都用 Docker 起，省去装环境的麻烦。

注意：Key 不要硬编码在application.yml里提交到 Git。用环境变量注入，Docker Compose 里通过environment字段传，本地开发用 IDE 的运行配置传。这是配置迁移能不能落地的关键，Key 泄露了整条链路都得换。

模型 ID 的选择上，如果你只是做意图识别和短文本改写，选轻量模型就够；如果要做商品描述生成，选能力强的。具体有哪些模型、各自什么特点，在模型对话页面能看到完整列表和说明。把选好的 Model ID 记下来，后面配置里要用。

3. 可复制的 application.yml 与 Docker Compose 配置

先改订单服务的application.yml。核心是把模型调用的 Base URL、Key、Model ID 抽成独立配置块，其他服务引用同一套环境变量。

server: port: 8080 spring: application: name: order-service datasource: url: jdbc:mysql://mysql:3306/cloud_order?useSSL=false&serverTimezone=UTC username: root password: ${MYSQL_PASSWORD:123} redis: host: redis port: 6379 rabbitmq: host: rabbitmq port: 5672 username: guest password: guest listener: simple: prefetch: 1 # 统一模型通道配置，所有微服务共用同一套环境变量 llm: base-url: ${LLM_BASE_URL:https://taotoken.net/api} api-key: ${LLM_API_KEY} model-id: ${LLM_MODEL_ID:gpt-4o-mini} chat-path: /v1/chat/completions timeout: 30000

库存服务和搜索服务用同样的llm配置块，值从环境变量读，不需要各自维护。这样改模型地址时，只改 Docker Compose 里的LLM_BASE_URL一个地方。

接着写一个配置类把llm块绑定成 Bean：

@Component @ConfigurationProperties(prefix = "llm") @Data public class LlmProperties { private String baseUrl; private String apiKey; private String modelId; private String chatPath; private int timeout; }

再写一个通用的调用客户端，用RestTemplate发请求。这个类放在公共模块里，订单、库存、搜索都依赖它：

@Component public class LlmClient { @Autowired private LlmProperties props; private final RestTemplate restTemplate = new RestTemplate(); public String chat(String userMessage) { String url = props.getBaseUrl() + props.getChatPath(); HttpHeaders headers = new HttpHeaders(); headers.setContentType(MediaType.APPLICATION_JSON); headers.setBearerAuth(props.getApiKey()); Map<String, Object> body = new HashMap<>(); body.put("model", props.getModelId()); body.put("messages", Collections.singletonList( Map.of("role", "user", "content", userMessage) )); HttpEntity<Map<String, Object>> entity = new HttpEntity<>(body, headers); ResponseEntity<Map> resp = restTemplate.postForEntity(url, entity, Map.class); List<Map<String, Object>> choices = (List<Map<String, Object>>) resp.getBody().get("choices"); Map<String, Object> message = (Map<String, Object>) choices.get(0).get("message"); return (String) message.get("content"); } }

Docker Compose 文件把环境变量集中管理，这是配置迁移的落点：

version: "3.8" services: mysql: image: mysql:5.7.25 environment: MYSQL_ROOT_PASSWORD: 123 volumes: - "./mysql/data:/var/lib/mysql" ports: - "3306:3306" redis: image: redis:6.2 ports: - "6379:6379" rabbitmq: image: rabbitmq:3-management environment: RABBITMQ_DEFAULT_USER: guest RABBITMQ_DEFAULT_PASS: guest ports: - "5672:5672" - "15672:15672" order-service: build: ./order-service environment: LLM_BASE_URL: "https://taotoken.net/api" LLM_API_KEY: "${LLM_API_KEY}" LLM_MODEL_ID: "gpt-4o-mini" MYSQL_PASSWORD: "123" depends_on: - mysql - redis - rabbitmq ports: - "8080:8080" stock-service: build: ./stock-service environment: LLM_BASE_URL: "https://taotoken.net/api" LLM_API_KEY: "${LLM_API_KEY}" LLM_MODEL_ID: "gpt-4o-mini" depends_on: - rabbitmq search-service: build: ./search-service environment: LLM_BASE_URL: "https://taotoken.net/api" LLM_API_KEY: "${LLM_API_KEY}" LLM_MODEL_ID: "gpt-4o-mini" depends_on: - rabbitmq - redis

LLM_API_KEY用${LLM_API_KEY}从宿主机环境变量读，启动前export LLM_API_KEY=你的Key。这样 Compose 文件本身可以进 Git，Key 不进。

RabbitMQ 的异步解耦部分，订单服务发消息：

@Service public class OrderService { @Autowired private RabbitTemplate rabbitTemplate; public void createOrder(Order order) { orderMapper.insert(order); // 发消息到库存队列，库存服务异步扣减 rabbitTemplate.convertAndSend("stock.queue", order.getProductId()); // 发消息到搜索队列，搜索服务异步更新索引 rabbitTemplate.convertAndSend("search.queue", order.getProductId()); } }

库存服务消费并调用模型做库存预警文案生成：

@Component public class StockListener { @Autowired private LlmClient llmClient; @RabbitListener(queues = "stock.queue") public void onStockMessage(Long productId) { int stock = stockService.getStock(productId); if (stock < 10) { String warning = llmClient.chat( "商品" + productId + "库存仅剩" + stock + "件，生成一句简短预警" ); log.warn("库存预警：{}", warning); } } }

Redis 缓存商品详情，减少模型调用频次：

public Product getProduct(Long id) { String key = "product:" + id; String cached = redisTemplate.opsForValue().get(key); if (cached != null) { return JSON.parseObject(cached, Product.class); } Product product = productMapper.selectById(id); redisTemplate.opsForValue().set(key, JSON.toJSONString(product), 10, TimeUnit.MINUTES); return product; }

4. 验证请求与成功结果确认

配置写完，先别急着起全部服务。按依赖顺序验证，出问题好定位。

第一步，单独验证模型通道通不通。用 curl 直接打接口，排除 Spring 配置的干扰：

curl -X POST https://taotoken.net/api/v1/chat/completions \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $LLM_API_KEY" \ -d '{ "model": "gpt-4o-mini", "messages": [{"role": "user", "content": "回复ok两个字"}] }'

返回里choices[0].message.content有内容，说明 Key 和地址都对。如果返回 401，看 Key 是不是复制时带了空格；如果返回 404，检查路径是不是漏了/v1。

第二步，起基础设施。docker-compose up -d mysql redis rabbitmq，等 RabbitMQ 管理页面能打开（http://localhost:15672，guest/guest），再起业务服务。

第三步，起订单服务，看启动日志里LlmProperties有没有绑定成功。可以在启动类里加一行打印：

@Bean public CommandLineRunner checkConfig(LlmProperties props) { return args -> { log.info("LLM base-url: {}", props.getBaseUrl()); log.info("LLM model-id: {}", props.getModelId()); log.info("LLM api-key length: {}", props.getApiKey() == null ? 0 : props.getApiKey().length()); }; }

Key 长度打印出来是 0，说明环境变量没传进去，检查 Docker Compose 的environment字段和宿主机export。

第四步，打订单接口触发全链路：

curl -X POST http://localhost:8080/order/create \ -H "Content-Type: application/json" \ -d '{"productId": 1001, "userId": 1, "count": 2}'

预期结果：订单接口 200 返回，响应时间在 200ms 内；RabbitMQ 管理页面stock.queue和search.queue有消息进出；库存服务日志出现模型生成的预警文案；搜索服务日志出现索引更新记录。如果订单接口返回了但队列没消息，检查RabbitTemplate的convertAndSend队列名和@RabbitListener的queues值是否一致。

第五步，验证 Redis 缓存生效。连续调两次商品查询接口，第二次日志里不应该出现数据库查询语句。用redis-cli看product:1001这个 key 有没有值。

全链路跑通后，把LLM_BASE_URL从https://taotoken.net/api改成别的地址，重启服务，链路照样通——这就证明配置迁移成功了，模型通道和业务逻辑解耦了。

5. 本篇常见错误排查

401 Unauthorized：最常见。三种可能：Key 没传进容器、Key 复制时带了换行、请求头格式不对。先在容器里echo $LLM_API_KEY确认环境变量存在，再用 curl 在容器内打一次接口。请求头必须是Authorization: Bearer sk-xxx，Bearer和 Key 之间一个空格。

Connection refused 或 local proxy failed：检查LLM_BASE_URL是不是写成了https://taotoken.net/api/带尾斜杠，拼接后变成//v1/chat/completions。正确写法是不带尾斜杠，代码里baseUrl + chatPath拼出完整路径。另外确认容器能访问外网，docker exec -it order-service curl -I https://taotoken.net/api看能不能通。

reading choices 空指针：resp.getBody().get("choices")返回 null，说明响应体结构不是预期的 OpenAI 格式。先打印完整响应体看实际返回了什么。常见原因是 Model ID 写错了，服务端返回了错误信息而不是正常结构。去模型对话页面确认 Model ID 的准确拼写。

OAuth 相关报错：如果你用的是 Claude Code 或 Codex 这类工具接入，报 OAuth 错误通常是认证方式没配对。这类工具需要的是 API Key 认证，不是 OAuth 流程。检查配置里是不是误开了 OAuth 选项。Claude Code 接入时 Base URL 填https://taotoken.net/api，Key 填创建的 API Key，Model ID 填对应模型。

RabbitMQ 消息重复消费：库存服务重启后重复扣减。这是消息确认机制的问题，@RabbitListener默认自动 ack，处理失败也会 ack。改成手动 ack：

spring: rabbitmq: listener: simple: acknowledge-mode: manual

然后在监听方法里处理成功后channel.basicAck(deliveryTag, false)，失败时basicNack重回队列或进死信队列。

Redis 连接超时：Docker Compose 里服务名是redis，application.yml里 host 要写redis不是localhost。容器内localhost指向容器自己，不是宿主机。同理 MySQL 和 RabbitMQ 的 host 都写服务名。

Docker Compose 启动顺序问题：depends_on只保证启动顺序，不保证服务就绪。订单服务可能在 MySQL 还没初始化完就启动，导致连接失败。加健康检查：

mysql: healthcheck: test: ["CMD", "mysqladmin", "ping", "-h", "localhost"] interval: 5s retries: 10

业务服务的depends_on改成带条件的写法，等 MySQL 健康再启动。

6. 把配置收敛到一处，链路才算真正跑通

整条链路跑通后回头看，真正花时间的不是写代码，是让三个服务的配置指向同一个模型通道。Base URL、Key、Model ID 这三件套，只要有一个服务写错，链路就在那一环断掉。用环境变量加 Docker Compose 集中管理，改一处全链路生效，这是分布式配置迁移最省事的做法。

如果你后面要加新的微服务，比如评价服务、推荐服务，直接复制llm配置块和LlmClient类，环境变量从 Compose 里继承，不用重新配 Key。模型要换的时候，改LLM_MODEL_ID一个值，所有服务跟着换。

长期做编码和 Agent 类任务的话，可以了解下 Coding Plan https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding-plan&utm_campaign=rewrite ，适合需要持续调用模型的场景。接入文档在 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite ，里面有各语言和工具的接入示例。API Key 管理在 https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api-keys&utm_campaign=rewrite ，可以创建多个 Key 分配给不同服务，方便按服务追踪用量。

最后留一个实用技巧：在LlmClient里加一层简单的重试，网络抖动时自动重发一次，避免因为偶发超时导致消息处理失败进死信队列。重试次数别超过 2 次，否则可能放大问题。