Agent上线崩在权限和日志上：我的一次工程化踩坑复盘

聊《程序员职业规划不只看课程，项目证据才是分水岭》之前，先说一句实在的：别急着背概念，先看它在真实项目里到底解决什么问题。

摘要

我带过的一个内部知识库问答 Agent，最开始只是 Demo 版本，单人用着没问题，后来接入团队，第一天就出问题了。

问题的顺序很有意思：先是个别人访问了不该看的资料，然后是调用链路断了，最后输出里带出了敏感信息。这三个问题，现在看就是权限、日志、可观测，但当时一个个排查的时候，真的有点懵。

现在回头看，这也是很多准备转大模型方向的程序员的共同坎：Demo 能跑通，一上生产就崩。

目录

• 那个崩了的项目
• 为什么 Demo 能跑，上线就崩
• 怎么学，顺序很重要
• 求职时怎么展示
• 适用边界
• 写在最后

那个崩了的项目

系统大致流程是这样的：用户提问 → 意图识别 → 查权限 → 调模型 → 输出回答 → 记录日志。

# 简化的核心逻辑示意
def handle_request(user, question):
    # 1. 权限校验
    if not permission.check(user, question):
        return Error("无权访问该知识库")

    # 2. 意图提取 + RAG 检索
    intent = extract_intent(question)
    context = rag_search(intent)

    # 3. 模型调用
    response = call_llm(context, question)

    # 4. 敏感信息过滤
    filtered_response = sensitive_filter(response)

    # 5. 记录调用链
    trace.log(user_id=user.id, intent=intent, tokens=response.tokens)

    return filtered_response

Demo 阶段我把权限这块简化成了"API Key 校验"，日志只记了"成功/失败"。接入团队后发现三个问题：

1. 不同部门的人都能看到全部知识库，权限完全失效
2. 一次调用断了，查不出是哪一步出的问题
3. 模型输出里包含了其他部门的内部数据

排查权限问题花了半天，排查链路追踪又花了一天，敏感信息问题是运维同学发现的。

后来补了 RBAC 模型、接了 OpenTelemetry、加了输出过滤，API 调用成功率从 87% 提上来之后稳定在 99.2% 以上。

为什么 Demo 能跑，上线就崩

我把失败原因拆成三类，方便大家对照：

业务错误——逻辑写错了。比如权限判断条件写反了，或者 RAG 检索出来的文档匹配了不该匹配的知识库。这类错误通常有明确的异常信息，好定位。

配置错误——参数配错了。比如模型选了个贵但慢的，或者权限策略配得太宽松。这类错误不报错，但行为不对。

环境错误——运行环境和开发环境不一样。比如 Demo 里数据库是内存级的，上线后换成真正的 Postgres，连接池配置不对就崩了。

Agent 项目最容易翻车的是配置和环境错误，因为权限、日志、可观测这三块，Demo 阶段基本没人认真做。

常见误区有两个：

误区一：觉得 API Key 就是权限控制。API Key 只能区分"谁在调用"，区分不了"谁能看什么数据"。生产环境需要的是 RBAC 或者 ABAC，至少要做到数据级隔离。

误区二：觉得日志就是打印一下。真正的日志要能还原整条调用链——用户从哪来、问了什么、用了哪个模型、花了多少 Token、哪里失败了。缺少这些信息，出了问题只能靠猜。

还有一个踩坑点是过度依赖框架。有人用 LangChain 搭了一个 Agent，功能挺全，但框架版本一升级，API 变了，整个系统就挂了。这种问题在团队协作里尤其致命。

怎么学，顺序很重要

很多人学大模型是从 Demo 开始的，这没问题，但后面要尽快补工程化能力。

第一阶段：跑通单个 API

别急着上框架，先用最基础的方式调用一次模型，理解输入输出、Token 计费、延迟这些基本概念。这一步很多人跳过了，直接上手 LangChain，结果连 prompt 怎么写都搞不清楚。

第二阶段：理解权限模型

这是很多 Java 开发者的优势区。Spring Security、Shiro 这些你本来就会，把它迁移到 Agent 场景里就行。要点是理解 RBAC 和 ABAC 的区别，以及怎么做到数据级权限隔离。

第三阶段：做可观测

OpenTelemetry 是现在比较主流的选择，记录 Trace、Span、Metrics 三个维度。日志要用结构化格式，别打印 JSON 字符串了事。这里推荐看官方文档，花半天时间能搞懂基础用法。

第四阶段：Agent 框架

到这一步你已经有了工程化的底子，再学框架会顺手很多。Java 方向可以看看 Spring AI 或者 LangChain4j，Python 方向 LangChain 还是主流。

求职时怎么展示

面试的时候，面试官问的问题顺序大概是这样的：

先问项目，看你能不能说清楚做了什么；再问细节，看你是不是真的做了；最后问权衡，看你有没有工程化思维。

简历上不要只放截图和一句话描述。可以这样写：

> 内部知识库问答 Agent，支持多租户数据隔离，集成 RBAC 权限控制，接入 OpenTelemetry 全链路追踪，API 调用成功率 99.2%

这三个指标——权限、日志、成功率——都是面试官会追问的点。

面试时被问到权限设计，不要只说"我用了 API Key"。要能说出 API Key 不够用的原因，以及你后来怎么改的。被问到链路追踪，要能画出基本的调用链结构图。被问到可观测性，要能说清楚 Trace、Span、Metrics 各自记录什么。

这些内容在简历上写了，面试时就真的有东西可聊。

适用边界

这套方案不是所有场景都需要。

如果你的项目只是个人用的小工具，Demo 跑通就够了，不需要搞那么复杂。如果团队只有三五个人，权限用简单的角色划分就行，不需要上完整的 RBAC。如果数据不涉及敏感信息，输出过滤可以简化。

但如果你的 Agent 要对接多个团队、要访问敏感数据、要有审计需求，那权限和日志就不是可选项，是必选项。

另外，这套方案主要面向生产环境。如果你的目标是在 1-2 个月内快速做一个 Demo 参加比赛，可以先跳过工程化部分，把精力放在核心功能上。但如果你要进公司做正式项目，这些能力越早补越好。

还有一点：不同方向的工程师优势不一样。Java 开发者在权限和日志这块基础好，转大模型有优势。前端开发者可能在交互和可视化上有优势，但在后端工程化上需要补。测试背景的工程师对边界情况敏感，做可观测性设计会比较细致。找到自己的优势，然后补足短板，比跟着热门技术跑更有效。

写在最后

大模型求职这回事，Demo 能跑通只是及格线。真正拉开差距的是工程化能力——权限怎么设计、日志怎么记录、问题怎么追踪。

我见过的几个顺利转过去的同学，都有一个共同点：不满足于 Demo，会主动去想"这东西上线会怎样"。这种习惯比学哪个框架更重要。

现在市场上会调 API 的人不少，能把 Agent 接进团队协作、还能扛住上线的人不多。这个差距，就是你接下来要填的。

总结

本文完成了关键概念、工程实践和落地建议的梳理。

资料展示

下面是我整理的AI大模型学习资料和工具包预览，适合收藏后按主题逐步学习。

需要这份AI大模型资料清单的话，在评论区回复「清单」即可；我会根据大家的问题继续补充对应的实战内容。