企业官网建设流程全解析

最近团队在做一整套 Agent 服务，目标很直接：让 Agent 不光能聊天，还能真正调用工具、做任务编排、处理长流程。前期在本地验证得很顺利，但一上云就发现一堆问题——模型接入乱、技能复用差、部署流程散，改完这个炸那个。折腾了一圈之后，最后落到了“腾讯云基础设施 + 统一模型网关 + 技能包设计”的组合上，也就是整套 AI Skills 的最佳实践路线。这篇把我们从架构选型到上线压测的完整过程，以及中间踩过的坑，全部梳理出来，给正准备做 Agent 上云的同学一个可复用的参考。

先说结论：Agent 这个事儿，框架选型只占 20%，剩下 80% 的功夫都在工程化——模型出入口统一、Skill 拆分粒度、云端部署规范、状态持久化，哪一块偷懒，上线之后都会找补回来。

1. 先定架构：Agent、Skill、模型网关的边界到底怎么切

1.1 Agent 不是“一个模型”，而是一套系统

很多人刚接触 Agent 开发，第一反应是“找个聪明的模型，把提示词写长一点”，但真正做生产级 Agent 的时候，这个思路会立刻撞墙。原因很简单：大模型本身的职责是理解和生成，而 Agent 的核心价值在“行动”——它要能读外部输入、调内部工具、记上下文、判断下一步做什么，这些都不是模型单独能完成的。

我当时画的系统边界是这样的：

• 模型层：负责自然语言理解、推理、生成，可以接不同的模型来平衡成本和质量。
• Agent 层：负责任务解析、规划、工具调度、记忆管理，是整个系统的大脑。
• Skill 层：封装具体的能力，比如查订单、发消息、算数学、检索知识库，对外暴露统一的参数接口。
• 基础设施层：跑在云上，包括服务器、容器、数据库、网络策略、域名证书。

这套分层的好处是每一层都能独立演进。模型层今天用 A 家的，明天发现 B 家更强，换起来不需要动其他层；Skill 层新增能力只需要按规范写一个技能包，Agent 层代码不用改；基础设施层做弹性扩容也不影响业务逻辑。

1.2 Skill 和 Agent 的分工：千万别把两者混为一谈

热搜词列表里有个很典型的问题：“skill 和 agent 的区别”。我们做第一版时也犯过这个错——把所有功能一股脑塞进 Agent 的逻辑里，结果每个 Agent 都是“巨无霸”，改一个功能要全量回归。

后面我把它拆清楚了：

• Agent是“调度者”，负责理解用户意图、拆解步骤、决定调哪个 Skill、汇总结果。
• Skill是“执行者”，负责具体的某个能力，输入输出都是结构化的，不关心用户的话术。

用生活中的例子来类比：Agent 是餐厅的前厅经理，客人说要“一桌适合素食者的晚餐，预算 300 以内”，经理要拆解出位置、素食、预算三个条件，然后分别叫后厨（素食菜单 Skill）、订位系统（座位查询 Skill）、收银台（预算计算 Skill）去处理。经理不需要自己会炒菜，但他知道什么情况该叫哪个后厨。

这个边界的直接收益是：新加能力不用改 Agent 核心逻辑，只写一个新 Skill 注册进去就行。这也是“AI Skills 最佳实践”里最重要的一条原则。

1.3 为什么承载层选了腾讯云而不是继续本地跑

本地开发环境跑通后，我考虑过是否要自建机房或直接用裸金属，但算了一笔账就放弃了：

• 模型侧网关需要稳定公网入口，家里的网络和 IP 稳定性不够。
• Agent 要部署成可对外服务的形态，必须有像样的域名、证书和端口管理。
• 团队协作开发时，测试环境、生产环境需要隔离，本地搞这一套运维成本太高。

腾讯云在这套架构里的定位是“承载底座”，具体用到几类东西：云服务器跑 Agent 主服务和模型网关，容器镜像服务做 Skill 的打包分发，二级域名和 HTTPS 证书统一入口，Redis 做记忆和会话存储。下面按这几个模块逐个讲最佳实践。

2. 云上环境准备：服务器、域名、端口、镜像，四个容易被细节卡住的地方

2.1 服务器规格与镜像选型建议

我们的 Agent 服务主要消耗在两部分：模型网关的并发转发、Agent 主服务的逻辑编排。这两者都是 CPU 密集和内存敏感的，GPU 倒不是必需品（推理不在本地）。所以我选了4核8G的配置起步，系统镜像直接用Ubuntu 22.04 LTS。

这里有个经验：别一上来就买最大配，也别买最小配。太小了跑几个 Docker 容器就内存告急，太大了前期成本浪费。4核8G 足够支撑几百个并发请求的网关转发和几十个 Skill 同时调度，真正不够时再横向加机器，比一开始就上 16核32G 划算得多。我们当时跑 LiteLLM Proxy 和 Agent 主服务、Redis 容器，总共内存占用在 5G 左右，负载很健康。

2.2 开放端口与安全组的正确姿势

热搜词里有“腾讯云如何开放所有端口”，这个我必须拎出来劝一句：千万不要为省事直接放通全部端口。云服务器的安全组本质上是你的第一道防火墙，全放通等于把自己裸奔在公网上，早晚会被扫描和爆破盯上。

正确做法是：

1. 只开放需要公网访问的端口。比如 HTTP/HTTPS 的 80/443，以及模型网关可能用到的自定义端口（比如 4000）。
2. 管理端口（SSH）只对办公网 IP 开放，或者至少把默认端口改掉，再配合密钥登录，禁止密码登录。
3. 内网组件（Redis、数据库）不绑定公网，也不要在安全组里放通。它们只能被同一私有网络内的应用访问。

我在腾讯云控制台配安全组的实际规则是这样：

每一条规则都要能说清用途，配完截图留存。这样即使后面被人扫到端口，也不至于直接被打穿。

2.3 二级域名申请与 HTTPS 证书配置

域名这块，热搜词里有“腾讯云怎么申请二级域名”。实操流程其实不复杂，但容易在“解析”和“证书”两步踩坑。

我们的主域名有一个在腾讯云备案过的根域，二级域名做的事情如下：

1. 添加解析记录：在 DNS 解析控制台，给agent.example.com添加一条 A 记录，指向云服务器的公网 IP。
2. 等待生效：TTL 默认 600 秒，一般几分钟内就能解析成功。用ping或者nslookup验证是否已经指向目标 IP。
3. 申请免费证书：腾讯云有免费的 HTTPS 证书，申请时验证域名归属。推荐用DNS 验证，它会给你一条 TXT 记录，添加到解析里等它校验通过即可。
4. 下载证书部署到 Nginx：证书会给你pem和key两个文件，放到服务器上，在 Nginx 配置里指定ssl_certificate和ssl_certificate_key即可。

这一步的关键提醒：证书申请下来后一定要记得在到期前续期，免费证书一般有效期一年。建议在手机上设个日历提醒，或者写一个定时任务自动检测证书有效期，避免过期导致整个 Agent 服务在用户端报“不安全连接”。

2.4 容器镜像服务：Docker 推送的正确流程

Skill 以容器方式部署是我最推荐的方式，因为隔离性好、依赖打包干净、扩容也方便。热搜词里“docker推送到腾讯云容器镜像服务”是这个流程的关键词。

我当时的操作流程：

# 1. 登录腾讯云容器镜像服务 docker login ccr.ccs.tencentyun.com --username 你的腾讯云账号ID # 2. 给本地镜像打标签，指向你的命名空间和仓库 docker tag agent-skill-order:latest ccr.ccs.tencentyun.com/your_namespace/agent-skill-order:latest # 3. 推送 docker push ccr.ccs.tencentyun.com/your_namespace/agent-skill-order:latest # 4. 服务器上拉取 docker pull ccr.ccs.tencentyun.com/your_namespace/agent-skill-order:latest # 5. 运行 docker run -d --name agent-skill-order --network my-agent-network \ -e REDIS_URL=redis://internal-redis:6379 \ ccr.ccs.tencentyun.com/your_namespace/agent-skill-order:latest

镜像仓库这里有一个点值得警惕：登录凭证不要直接写在 Dockerfile 或命令历史里。腾讯云容器镜像服务的临时登录密码有效期很短，但如果你用手动docker login，凭证会缓存在服务器上。建议用专门的部署账号，并把密码放到环境变量或密钥管理服务中，发布流程通过 CI/CD 执行，而不是每次手动登录。

3. 模型接入统一入口：LiteLLM Proxy 部署与最佳实践

3.1 为什么中间要挡一层模型网关

团队开发 Agent 的时候，最痛苦的事不是写逻辑，而是“模型接入到处都是”。有的 Skill 直接调 OpenAI 接口，有的调国内模型商的接口，有的走阿里云百炼，代码里到处都是不同的 SDK、不同的鉴权方式、不同的超时处理。等你要给 Agent 换一个主力模型，等于全项目大改。

LiteLLM Proxy 解决的就是这个问题：它把各种模型提供方的接口统一成一个 OpenAI 兼容的入口，你只需要在它的配置里声明每个模型对应的 provider、api_key、model 名称，之后所有代码都只面向这个代理调用。

这个思路跟“数据库连接池”很像——应用不直接连各种数据库，而是统一走连接池，换数据库只需改连接池配置，应用代码几乎不动。模型网关就是模型层的连接池。

3.2 一份可直接抄作业的 proxy 配置

我们用的 LiteLLM Proxy 配置核心大概长这样（省略真实的 key）：

model_list: - model_name: gpt-4o-mini litellm_params: model: gpt-4o-mini api_key: sk-your-key api_base: https://your-openai-compatible-endpoint - model_name: deepseek-chat litellm_params: model: deepseek/deepseek-chat api_key: sk-your-deepseek-key - model_name: qwen-plus litellm_params: model: openai/qwen-plus api_key: sk-your-qwen-key api_base: https://dashscope.aliyuncs.com/compatible-mode/v1 litellm_settings: drop_params: true set_verbose: false general_settings: master_key: sk-my-master-key database_url: postgresql://...

几个要重点说明的配置项：

• model_name是暴露给上层应用的别名，litellm_params是真正路由需要的信息。这样上层 Agent 在代码里只写gpt-4o-mini或deepseek-chat，后面要换供应商，改配置重启代理即可，应用层零改动。
• master_key相当于网关的管理员密码，上层应用调用时在 header 里带上Authorization: Bearer sk-my-master-key。
• database_url用来存调用日志和预算数据，建议配一个，不然你很难知道每个 Skill 烧了多少 token、哪个模型经常超时。

启动命令很直接：

docker run -d --name litellm-proxy \ -p 4000:4000 \ -v $(pwd)/config.yaml:/app/config.yaml \ ghcr.io/berriai/litellm:main-latest \ --config /app/config.yaml

启动日志里看到Uvicorn running on http://0.0.0.0:4000，说明网关已经就绪。用 curl 验证一下：

curl http://your-server-ip:4000/v1/models \ -H "Authorization: Bearer sk-my-master-key"

能返回模型列表，就说明代理正常工作。

3.3 模型网关的优化与容错配置

LiteLLM Proxy 能做的远不止“转发”。我在实践里比较依赖这几个能力：

• 成本控制：可以在配置里设置每个模型的最大预算、每分钟请求数上限，防止某个 Skill 出现 bug 时无限调用模型烧钱。
• 负载均衡：同一个模型配置多个 key，LiteLLM 会自动轮询和故障转移，某个 key 配额用完了自动切下一个。
• 重试与超时：针对波动比较大的模型供应商，设置合理的重试次数（比如 2 次），重试有指数退避，避免流量高峰时雪崩。
• 统一观测：所有请求日志都从网关走，可以按 Skill 维度统计 token 消耗、延迟、错误率。这个数据对后续优化 Skill 的提示词和参数非常关键。

网关部署在腾讯云服务器上之后，其他 Skill 容器访问它的地址就是http://litellm-proxy:4000这种容器间网络地址，前提是你把它们放在同一个 Docker 网络里。这一点在编排的时候要提前规划好，别各跑各的 bridge 网络，后面联调互相访问不到。

4. 从“能跑”到“好用”：AI Skills 的设计与编排经验

4.1 Skill 的最小闭环：一个技能包该包含什么

AI Skills 这个词在不同语境下含义略有差异，但在我这套架构里，一个 Skill 就是一个独立部署、暴露统一接口的能力单元。它内部可以调模型、可以写代码、可以访问数据库，但对外只做一件事：接收结构化输入，返回结构化输出。

我们用一个查询物流的 Skill 举例。它接收的参数是订单号，返回的是物流轨迹。定义参数的时候用 JSON Schema，Agent 层根据这个 Schema 自动生成调用参数：

{ "name": "query_logistics", "description": "查询订单物流轨迹", "parameters": { "type": "object", "properties": { "order_id": { "type": "string", "description": "订单号，例如 SF1234567890" } }, "required": ["order_id"] } }

这里最考验设计功力的是description 字段。大模型不是程序员，它不懂你的参数含义，它靠 description 来理解应该传什么。比如上例中“订单号，例如 SF1234567890”，模型看到示例值就能更准确地从用户对话里提取参数。如果 description 写得太抽象，模型就容易传错参数。

Skill 内部实现则无拘无束，Python、Node.js、甚至一个 shell 脚本都行，只要按照约定监听请求、返回 JSON。我们统一用 FastAPI 写，因为自动生成的接口文档能直接给调试用。

4.2 技能路由：Agent 怎么知道该调哪个 Skill

Agent 要能工作，就得有一个“能力注册表”——告诉它现在有哪些 Skill 可用。这个注册表本质上就是上面那种 JSON 描述，Agent 层的实现是：把用户意图和所有 Skill 的描述一起交给模型，让模型判断调用哪个，并产出参数。

这个机制叫function calling / tool use。很多框架已经封装好了，但它的上限不在于框架，而在于 Skill 描述写得好不好。我们一开始吃过亏：技能描述写得太笼统，比如“查询订单”，模型经常不知道该用哪个订单接口；后来把所有 Skill 的 description 改成“何时应该调用 + 关键参数说明 + 示例”，路由准确率从 70% 提到 95% 左右。

这里有一个通用的写法模板，可以套用：

当用户提到 <业务动作> 且满足 <条件> 时，调用本技能。 参数 <paramA> 对应 <用户说法里的什么信息>。 示例：用户说 “帮我查下订单 SF1234567890 到哪了”，此时 order_id = "SF1234567890"。

描述越具体，模型的判断越稳。这不是玄学，而是大模型对“语义匹配”天然擅长，你把匹配需要的语义信息给它，它就能准确匹配。

4.3 长任务编排：多 Skill 如何串成一条流水线

单技能路由解决的是“一次调用”，但真正的 Agent 场景往往是多步编排。比如用户说“帮我把昨天订单里没发货的整理成表格，并统计各物流公司的延误率”，这个需求至少要三步：

1. 调订单查询 Skill，筛选出昨天未发货订单；
2. 调物流查询 Skill，批量获得每个订单的物流状态；
3. 调数据分析 Skill，汇总统计并生成表格。

我用的是Step 模式：给每个 Skill 定义输入、输出，从上一步的输出里提取下一步需要的参数。编排层写成一个 DAG（有向无环图）描述，Agent 根据用户意图动态选择路径。

这里要特别注意中间结果的传递。上一步输出的是一个 JSON，下一步需要从里面提取字段，如果 Skill 返回格式不统一，编排层就要写大量胶水代码。所以我们的规范是：所有 Skill 返回值必须是{ "status": ..., "data": ..., "message": ... }三层结构，这样编排层只用关心data字段，处理逻辑统一，新增 Skill 基本不需要改编排代码。

4.4 调试与测试的实操姿势

Skill 开发中大家容易低估测试的复杂度。我之前吃过亏：本地单测全通过，一接 Agent 就怎么调都不对。后面总结了一套层次化测试方法：

1. 单元测试：给 Skill 构造各种边界输入，验证输出格式正确。
2. 模型调度测试：用一组典型的用户话术，验证 Agent 是否准确路由到目标 Skill，这一步最容易发现 description 写得不清楚的问题。
3. 全链路测试：用户话术 -> Agent 规划 -> 多 Skill 编排 -> 结果返回，完整跑通，记录耗时和中间每一步的输入输出。

日志是整个调试的救命稻草。我们每个 Skill 的容器标准输出里都会打一行结构化日志，包含请求 ID、Skill 名称、入参、出参、耗时，配合腾讯云日志服务收集，debug 的时候按请求 ID 一拉就出来完整链路。

5. 记忆与状态持久化：Redis 配置踩坑与正确方案

5.1 记忆方案选型：为什么最终落到 Redis

Agent 要表现出“记忆力”，核心是要有一个存储会话状态的地方。这个状态包括：用户的长期偏好、当前多轮对话的上下文、某个长任务的执行进度。

方案对比下来，Redis 是最合适的中间方案：

• 内存读写快，延迟到毫秒级，不会拖慢 Agent 的响应。
• 支持 TTL 过期，会话数据可以自动清理，不用手动删。
• 数据结构丰富，Hash 存会话、List 存历史记录、String 直接做缓存，都能用上。
• 部署简单，一个 Docker 容器搞定，腾讯云服务器内网直连，没有额外成本。

5.2 一个让我头疼一下午的坑：修改 Redis 密码后重启失败

热搜词里有一条很接地气：“主要是我在腾讯云服务器上安装 redis，但是我修改 redis 密码之后再重启 redis 就一直不……”——这正好是我踩过的同一个坑。

事情是这样的：Redis 默认配置里requirepass是空的，客户端连接不需要密码。我修改配置加上密码后，重启 Redis，表面上看服务起来了，但客户端连的时候一直报NOAUTH Authentication required。更诡异的是，有一回配置改了之后 Redis 直接起不来了，服务状态反复重启失败。

根因有两个，都很典型：

第一，Redis 配置文件的权限和路径问题。如果你用systemctl管理 Redis，配置文件通常要求属主是 redis 用户，且权限不能被其他用户写。如果我在改配置时不小心用了错误的文件权限，或者改了错误的配置文件路径，Redis 启动时会拒绝加载。

第二，启用了保护模式。Redis 默认protected-mode yes，在没有设置密码且绑定了公网地址时，它只允许本机回环地址访问。我设置了bind 0.0.0.0但密码没配对，日志里会频繁出现拒绝连接的记录，看起来就像“重启后一直不行”。

排查链路我从日志入手：

journalctl -u redis-server --no-pager -n 100

日志里如果看到Configuration file /etc/redis/redis.conf的存在但无法解析，或# Warning: requirepass is empty，基本就是密码和绑定的问题。

正确做法是：

# 1. 编辑配置文件 vim /etc/redis/redis.conf # 修改如下内容 bind 127.0.0.1 ::1 protected-mode yes requirepass 你的强密码

这里最关键的修改是：把 bind 设为 127.0.0.1，而不是 0.0.0.0。原因很简单——Redis 不需要对公网暴露，Agent 服务和 Skill 容器都在同一台服务器或同一内网，通过容器的内网 IP 访问即可。绑定回环地址 + 开启保护模式 + 设置密码，三层防护一起做，才是稳妥的组合。

然后重启并验证：

redis-cli -a 你的强密码 ping # 返回 PONG 即正常

如果你是在 Docker 里跑 Redis，那么要注意容器端口映射别直接-p 6379:6379暴露到公网，正确做法是只让其他容器通过--network my-agent-network访问，端口不映射到宿主机，除非你确认安全组做了限制。

5.3 会话设计与 TTL 策略

Redis 配置好了之后，还涉及会话结构怎么设计。我用的方案是：

多轮对话上下文设置 30 分钟过期，是因为超过这个时间用户大概率已经没在继续同一话题，留着占内存没必要。用户长期偏好设 30 天，覆盖“每次来都能记住我”的体验。

这里有个技巧：更新上下文时用 Hash 的 HGETALL + HSET，而不是读出来再整个覆盖。并发场景下如果两个请求同时写一个 key，后写的会覆盖先写的，导致上下文丢失。用 Hash 按字段更新能显著降低冲突概率。

6. 上线前必看：典型错误与安全加固清单

6.1 “execution terminated due to error”：长任务的隐藏杀手

上线后最常碰到的报错之一就是agent execution terminated due to error。这句话翻译过来是：Agent 在执行某个步骤时抛了异常，整个会话中断了。

常见触发场景：

• Skill 接口超时：Agent 等待 Skill 返回结果，等超了，直接终止。特别是调用外部 API 的 Skill，如果外部服务不稳定，很容易触发。
• 参数解析失败：模型返回的 tool_calls 参数是非法 JSON，或者校验不通过，Agent 无法继续。
• 中间结果过大：某一步返回了超大 JSON（比如列表全量数据），模型上下文塞不下，报错终止。
• 循环调用：Agent 在一个步骤上反复调用同一个 Skill，达到最大迭代次数后异常退出。

逐个拆解对策：

1. 给每个 Skill 调用设置超时和重试。超时设定在 10 秒以内，重试 2 次，还不行就降级返回“暂时无法处理”，不要硬等。
2. 在 Agent 解析模型输出时做容错，若 JSON 解析失败，把原文截取一段重新让模型修正，最多重试 1 次，再失败就明确告知用户。
3. 给中间结果做截断和摘要。超过一定长度的 JSON，先摘要再传给模型，保留关键字段，牺牲一点细节换稳定性。
4. 限制最大迭代步数，比如 20 步，超出就优雅结束并给出部分结果，而不是让用户等一个永无止境的循环。

日志层面，要把每一步的耗时、token 数、调用是否成功都记录下来。这样出了terminated due to error，你能快速定位是哪一步出的问题，而不是面对一个黑盒。

6.2 安全加固：Agent 上云不能裸奔

Agent 会对外暴露两个风险面：HTTP 接口和内部基础设施。安全加固我从这两条线分别做：

对外接口层面：

• 鉴权：网关必须校验请求头里的 Bearer token，无 token 请求直接拒绝。
• 频率限制：按用户或 IP 限流，防止被刷调用成本。LiteLLM Proxy 自带 rate limit 配置，可以按模型维度设置。
• 输入过滤：对用户输入做敏感词检测和长度限制，防止恶意长文本塞爆上下文、防提示词注入。

内部基础设施层面：

• 数据库和 Redis 不绑定公网，只在内网被服务访问，安全组不放通数据库端口。
• 所有管理端口用密钥登录，不用密码登录。密码容易被爆破，密钥对的安全性高得多。
• 容器最小权限：Skill 容器不要用 root 跑，创建一个低权限用户执行；挂载目录只读为主，避免容器内被篡改。
• 密钥管理：API key、Redis 密码不要硬编码在代码或环境变量里，用密钥管理服务统一存和轮换。

6.3 上线后的监控与压测建议

最后上线前建议做一轮压测。方法很简单：用 wrk 或 JMeter 对网关接口发起并发请求，重点观察：

• 100 并发时，代理层响应延迟的 P95；
• 内存和 CPU 占用是否线性增长；
• 长时间跑是否出现内存泄漏。

我压测的时候发现一个有意思的情况：很多模型的并发瓶颈不在服务器，而在模型供应商的限流。不像传统 Web 服务压测主要看服务端性能，Agent 服务的瓶颈链条更长，从网关到模型提供商再到 Skill 容器，任何一环卡住都影响整体。所以压测时要把mock 模型和真实模型分组测，先排除网关和 Skill 的自身瓶颈，再测真实模型的极限在哪个并发量。

监控指标建议至少覆盖这四项：请求量、错误率、P95 延迟、模型 token 消耗。腾讯云自带的监控面板就能配，不用额外搭 Prometheus，但如果你想做更细致的按 Skill 维度统计，那还是得在日志上多做文章。

写到这里，这套基于腾讯云的“AI Skills 最佳实践”基本算完整了。从架构分层、模型网关、技能包设计，到 Redis 记忆、安全加固，每一块都是踩过坑之后沉淀下来的。最后再分享一个我个人的体会：Agent 项目最容易失控的地方不在技术，而在“边界”。什么该交给模型推理，什么该交给 Skill 精确执行，什么该在网关层收口，这三条线划清楚，整个系统就稳了。后续如果有时间，我还打算把多 Skill 编排的可视化调试、以及基于调用日志的 Skill 自动优化这两个方向再做深一点，到时候再来更新。