AI客户端运维手册

fastbee大约 18 分钟

FastBee 外部 AI 客户端运维手册

本文档用于指导客户在 FastBee 服务部署到服务器后，通过外部 AI 客户端连接 Arthas MCP，对 CPU 高、接口慢、线程阻塞、内存异常、日志报错等问题进行辅助排查。

适用对象：第一次使用 AI 运维的实施人员、运维人员、客户现场工程师。

重要边界：

AI 负责诊断、解释现象、整理证据和给出建议。
AI 不应自动重启服务、不应删除文件、不应修改生产配置、不应执行热更新类命令。
高风险命令必须由人工确认后再执行。
公网开放 Arthas MCP 时，必须配置 Token 和安全组 IP 白名单。

官方参考：

1. 整体原理

FastBee 后端集成 Arthas 后，会在服务进程内启动 Arthas HTTP 服务。当前项目配置如下：

arthas:
  app-name: ${fastbee.name}
  ip: 0.0.0.0
  http-port: 8563
  mcp-endpoint: /admin/mcp
  mcp-protocol: STREAMABLE
  password: "请设置为复杂密码"

部署后，外部 AI 客户端通过 MCP 协议访问：

http://服务器IP:8563/admin/mcp

AI 客户端连接成功后，可以调用 Arthas 提供的诊断工具，例如：

dashboard：查看 JVM 和系统运行面板。
jvm：查看 JVM 参数、启动信息、运行时信息。
memory：查看 JVM 内存分区使用情况。
thread：查看线程、CPU 高线程、阻塞线程。
stack：查看方法调用栈。
trace：追踪接口或方法耗时。
watch：观察方法入参、返回值、异常。
logger：查看日志配置。
viewfile：查看允许目录内的日志文件内容。

2. 服务器准备

2.1 在配置文件中增加生产 Token

生产环境必须配置 arthas.password。为了让 Linux、Docker、宝塔等部署方式使用同一套说明，本文统一要求把密码写在服务器实际使用的 application.yml 或生产配置文件中。

在 application.yml 中补充：

arthas:
  app-name: ${fastbee.name}
  ip: 0.0.0.0
  http-port: 8563
  mcp-endpoint: /admin/mcp
  mcp-protocol: STREAMABLE
  password: "请替换为足够复杂的密码"

注意：

password 的值就是 AI 客户端要使用的 Bearer Token。
密码包含 :、#、@、空格等特殊字符时，建议用英文双引号包起来。
不要把真实生产密码提交到公开仓库；建议只在服务器上的生产配置文件中填写真实密码。

建议密码规则：

长度至少 16 位。
包含大小写字母、数字和特殊字符。
不要使用公司名、项目名、手机号、生日等弱密码。

示例：

arthas:
  app-name: ${fastbee.name}
  ip: 0.0.0.0
  http-port: 8563
  mcp-endpoint: /admin/mcp
  mcp-protocol: STREAMABLE
  password: "FbOps_2026@ChangeMe_9xK!"

2.2 配置 viewfile 日志白名单

如果希望 AI 可以读取日志，需要配置允许访问的日志目录。建议只开放日志目录，不要开放 /、/home、/root 等大范围目录。

你的服务器日志目录如图为：

/var/data/java/logs

目录中常见文件包括：

sys-debug.log
sys-error.log
sys-error.2026-06-24.log
sys-info.log
sys-info.2026-06-24.log
sys-warn.log
sys-user.2026-06-24.log

因此日志白名单建议配置为：

export ARTHAS_MCP_VIEWFILE_ALLOWED_DIRS=/var/data/java/logs,/arthas-output

如果使用 Docker Compose，arthas.password 仍然写在容器内加载的 application.yml 中；这里只需要额外设置日志白名单：

environment:
  ARTHAS_MCP_VIEWFILE_ALLOWED_DIRS: /var/data/java/logs,/arthas-output

如果 FastBee 日志实际在其他目录，例如 /data/fastbee/logs，再替换为实际路径：

export ARTHAS_MCP_VIEWFILE_ALLOWED_DIRS=/data/fastbee/logs,/arthas-output

日志文件选择规则：

当天正在写入的日志不带日期，优先看 /var/data/java/logs/sys-error.log、/var/data/java/logs/sys-info.log。
第二天归档后才会自动加日期；排查历史日期时看 /var/data/java/logs/sys-error.YYYY-MM-DD.log，例如 /var/data/java/logs/sys-error.2026-06-24.log。
当前普通运行日志：看 /var/data/java/logs/sys-info.log。
历史普通运行日志：看 /var/data/java/logs/sys-info.YYYY-MM-DD.log。
警告日志：当天看 sys-warn.log，历史日期看 sys-warn.YYYY-MM-DD.log，用于补充 WARN 级别线索。
调试日志：sys-debug.log 内容可能很多，只在 AI 需要更细节证据时读取最近少量行。
用户行为日志：sys-user.YYYY-MM-DD.log 主要用于核对操作时间线，不作为 JVM 异常首选日志。

2.3 开放 8563 端口

公网 Token 场景下，必须同时满足：

服务器防火墙放行 8563。
云服务器安全组放行 8563。
安全组来源 IP 只填写可信办公 IP、VPN 出口 IP 或客户现场公网 IP。
不允许来源写成 0.0.0.0/0 长期裸露公网。

Linux 防火墙示例：

firewall-cmd --add-port=8563/tcp --permanent
firewall-cmd --reload
firewall-cmd --list-ports

如果使用 ufw：

ufw allow from 可信公网IP to any port 8563 proto tcp
ufw status

Docker Compose 端口映射示例：

ports:
  - "8563:8563"

宝塔面板检查：

打开“安全”。
添加放行端口 8563。
如果宝塔支持来源 IP 限制，只允许可信 IP。
再到云厂商控制台安全组放行同样端口。

云服务器安全组检查：

登录阿里云、腾讯云、华为云或其他云控制台。
找到 FastBee 所在 ECS/云主机。
打开安全组入方向规则。
添加 TCP 8563。
来源填写可信公网 IP，例如 203.0.113.10/32。
保存后等待规则生效。

2.4 重启 FastBee 服务

普通 jar 部署示例：

ps -ef | grep fastbee
kill -15 进程ID
nohup java -jar fastbee-admin.jar > fastbee.out 2>&1 &

systemd 部署示例：

systemctl restart fastbee
systemctl status fastbee

Docker Compose 部署示例：

docker compose down
docker compose up -d
docker compose logs -f fastbee

2.5 验证 MCP 地址

替换变量：

服务器IP：FastBee 服务器公网 IP 或域名。
你的arthas.password：application.yml 中 arthas.password 的真实值。

用 curl 测试：

curl -i \
  -H "Authorization: Bearer 你的arthas.password" \
  http://服务器IP:8563/admin/mcp

常见结果：

返回 200、400、405 或包含 MCP 相关信息：说明端口和鉴权大概率正常，具体交互由 MCP 客户端完成。
返回 401 或 403：Token 错误或未携带 Authorization Header。
连接超时：端口未开放、安全组未放行、服务未启动或 IP 写错。
连接被拒绝：服务器能访问，但 8563 没有进程监听。

检查端口监听：

ss -lntp | grep 8563

查看 FastBee 日志：

tail -n 200 /var/data/java/logs/sys-error.log

如果日志路径不同，请替换为实际路径。

3. 通用 MCP 配置

无论使用哪个 AI 客户端，核心配置都一样：

注意：MCP 客户端中用于传递认证信息的配置项是 http_headers，不是 headers。

{
  "mcpServers": {
    "fastbee-arthas": {
      "type": "streamableHttp",
      "url": "http://服务器IP:8563/admin/mcp",
      "http_headers": {
        "Authorization": "Bearer 你的arthas.password"
      }
    }
  }
}

如果客户端使用 TOML 格式，认证配置写法如下：

[mcpServers.fastbee-arthas]
type = "streamableHttp"
url = "http://服务器IP:8563/admin/mcp"
http_headers = { "Authorization" = "Bearer 你的arthas.password" }

请把：

服务器IP 替换为真实服务器 IP 或域名。
你的arthas.password 替换为配置文件中 arthas.password 的真实值。

例如：

{
  "mcpServers": {
    "fastbee-arthas": {
      "type": "streamableHttp",
      "url": "http://203.0.113.10:8563/admin/mcp",
      "http_headers": {
        "Authorization": "Bearer FbOps_2026@ChangeMe_9xK!"
      }
    }
  }
}

连接成功后，先对 AI 说：

请确认你是否能看到 fastbee-arthas MCP 工具。先不要执行高风险命令，只调用 dashboard、jvm、memory、thread 查看当前 JVM 概况，并用中文总结。

4. 通用 MCP 客户端模板

只要客户端支持 Streamable HTTP MCP，都可以按以下信息填写：

配置项	值
Name	`fastbee-arthas`
Type	`streamableHttp`
URL	`http://服务器IP:8563/admin/mcp`
HTTP Headers	`http_headers = { "Authorization" = "Bearer 你的arthas.password" }`

JSON 模板：

{
  "mcpServers": {
    "fastbee-arthas": {
      "type": "streamableHttp",
      "url": "http://服务器IP:8563/admin/mcp",
      "http_headers": {
        "Authorization": "Bearer 你的arthas.password"
      }
    }
  }
}

TOML 模板：

[mcpServers.fastbee-arthas]
type = "streamableHttp"
url = "http://服务器IP:8563/admin/mcp"
http_headers = { "Authorization" = "Bearer 你的arthas.password" }

5. 标准排查工作流

每次出现问题，建议按固定顺序问 AI：

先看整体状态。
再看线程和内存。
再看日志。
最后才使用 trace、watch 这类采样工具。
不确定时停止，让人工判断。

通用提示词：

你是 FastBee 生产运维助手。请通过 fastbee-arthas MCP 帮我排查问题。

规则：
1. 先只使用 dashboard、jvm、memory、thread、logger、sysprop、sc、sm、viewfile 等低风险工具。
2. trace/watch 必须限制类名、方法名和采样次数，最多采样 5 次。
3. 不要调用 heapdump、ognl、redefine、retransform、vmtool。
4. 不要重启服务、不要删除文件、不要修改生产配置。
5. 每一步都说明你调用了什么工具、看到什么证据、下一步为什么这样做。
6. 最终结论按“现象、证据、可能原因、建议动作、是否需要人工处理”输出。

我的问题是：这里填写具体现象。

6. 典型问题排查模板

6.1 CPU 飙高

用户提问：

FastBee 服务器 CPU 很高，请使用 fastbee-arthas MCP 排查。先不要执行高风险命令。请找出最忙线程、线程栈、可能对应的业务代码，并给出处理建议。

AI 优先工具：

dashboard
thread
thread -n 5
jvm

判断方法：

如果某几个线程 CPU 占用很高，重点看线程名和栈顶方法。
如果线程栈长期停在同一个业务方法，可能是死循环、频繁计算或大量数据处理。
如果 GC 线程很高，可能是内存压力导致频繁 GC。

下一步建议：

让 AI 汇总高 CPU 线程栈。
根据类名和方法名定位业务模块。
如需进一步定位接口耗时，再考虑 trace，并限制采样次数。

必须转人工：

AI 建议执行 ognl、vmtool、redefine、retransform。
CPU 已接近 100%，业务不可用，需要人工评估是否扩容或重启。

6.2 接口响应慢

用户提问：

FastBee 某个接口响应很慢，接口路径是：/xxx/xxx。请先查看 JVM、线程和最近异常日志，再判断是否需要 trace。trace 时必须限制采样 5 次以内。

AI 优先工具：

dashboard
thread
logger
viewfile
trace

判断方法：

如果线程大量等待数据库连接，重点检查数据库连接池或慢 SQL。
如果线程阻塞在 Redis、MQTT、HTTP 调用，重点看外部依赖。
如果 trace 显示某个方法耗时最高，优先分析该方法依赖。

下一步建议：

找到慢点后，让 AI 输出“耗时链路表”。
如果是数据库，检查 SQL、索引、连接池。
如果是外部接口，检查网络和第三方服务。

必须转人工：

需要调整生产数据库索引。
需要重启服务或修改配置。
trace 无法确认具体类名和方法名。

6.3 线程阻塞或死锁

用户提问：

FastBee 疑似线程阻塞或死锁，请使用 fastbee-arthas MCP 检查阻塞线程、死锁迹象和关键线程栈。不要执行高风险命令。

AI 优先工具：

thread
thread -b
dashboard
jvm

判断方法：

BLOCKED 线程很多，说明可能存在锁竞争。
大量线程等待同一个锁、同一个连接池或同一个队列，需要重点分析。
如果 thread -b 找到阻塞源，优先看持锁线程栈。

下一步建议：

让 AI 总结阻塞链路。
找出锁对象、持锁线程、等待线程。
判断是否是数据库连接耗尽、线程池耗尽或业务锁使用不当。

必须转人工：

线程长时间全部卡住。
AI 不能判断是否可以重启。
需要修改代码释放锁或调整线程池。

6.4 内存持续上涨

用户提问：

FastBee 内存持续上涨，请使用 fastbee-arthas MCP 排查 JVM 内存、GC 情况和线程状态。不要直接执行 heapdump，除非我明确批准。

AI 优先工具：

memory
jvm
dashboard
thread

判断方法：

Old 区持续上涨且 GC 后不下降，可能存在内存泄漏。
Metaspace 上涨，可能和类加载、动态代理、脚本有关。
线程数量持续上涨，可能是线程泄漏或任务堆积。

下一步建议：

先观察内存分区。
再看线程数量和 GC 状态。
如必须生成堆快照，由人工确认执行 heapdump，并确保磁盘空间足够。

必须转人工：

需要执行 heapdump。
服务器磁盘空间不足。
服务即将 OOM，需要决定扩容或重启。

6.5 最近日志报错

用户提问：

FastBee 最近出现报错，请通过 fastbee-arthas MCP 分析 /var/data/java/logs 下的日志。

请按顺序读取：
1. 先看 /var/data/java/logs/sys-error.log 最近 200 行。
2. 如果问题发生在今天，继续读取不带日期的 sys-info.log 和 sys-warn.log。
3. 如果问题发生在历史日期，再看对应日期的 /var/data/java/logs/sys-error.YYYY-MM-DD.log。
4. 如果需要还原历史请求时间线，再看同一天的 sys-info.YYYY-MM-DD.log。
5. 如果错误前有 WARN 线索，今天看 sys-warn.log，历史日期看 sys-warn.YYYY-MM-DD.log。
6. sys-debug.log 内容可能很大，只在必要时读取最近 100 行。

重点找 ERROR、Exception、Timeout、Connection refused、OutOfMemoryError、RejectedExecutionException，并按时间线总结可能原因。

AI 优先工具：

logger
viewfile
jvm
thread

判断方法：

Connection refused：依赖服务不可达。
Timeout：数据库、Redis、MQTT、HTTP 外部调用超时。
OutOfMemoryError：内存异常，需要马上人工介入。
RejectedExecutionException：线程池满或任务过多。
sys-error.log：优先用于定位异常根因。
sys-error.YYYY-MM-DD.log：用于回看某天历史异常。
sys-info.log 或 sys-info.YYYY-MM-DD.log：用于补充接口、任务、设备上报等普通运行时间线。
sys-warn.log：用于发现错误发生前的预警。
sys-debug.log：只读取少量末尾内容，避免日志过大影响排查效率。

下一步建议：

让 AI 按时间线整理错误。
只分析允许目录内的日志。
优先从 sys-error.log 找根因，再用 sys-info 和 sys-warn 补上下文。
如果是今天的问题，读取不带日期的 sys-error.log；如果是历史日期，例如 2026-06-24，读取 sys-error.2026-06-24.log。

必须转人工：

日志涉及数据库密码、Token 等敏感信息。
AI 要求读取非日志目录。
出现数据损坏、权限异常、启动失败。

6.6 数据库连接池异常

用户提问：

FastBee 疑似数据库连接池异常，现象是接口慢或大量超时。请通过 Arthas MCP 查看线程栈。若问题发生在今天，请读取 /var/data/java/logs/sys-error.log 最近 200 行；若问题发生在历史日期，请读取对应的 sys-error.YYYY-MM-DD.log。请判断是否有连接池耗尽、慢 SQL 或数据库不可达。

AI 优先工具：

thread
dashboard
viewfile
logger

判断方法：

线程栈停在获取数据库连接，可能是连接池耗尽。
日志出现 SQL timeout，可能是慢 SQL 或数据库负载高。
日志出现 Communications link failure，可能是数据库网络或账号问题。

下一步建议：

检查数据库服务状态。
检查连接池配置和数据库最大连接数。
让 AI 从 sys-error 中提取 SQL timeout、connection、pool、druid、hikari、mysql 等关键词。
收集慢 SQL，再由 DBA 或开发处理。

必须转人工：

需要修改连接池配置。
需要杀数据库连接。
需要调整索引或执行 SQL 变更。

6.7 MQTT 或设备上报异常

用户提问：

FastBee 设备上报或 MQTT 异常，请通过 Arthas MCP 查看 JVM、线程，并读取 /var/data/java/logs/sys-error.log 和 sys-info.log 最近日志。重点关注 mqtt、netty、broker、device、topic、serialNumber、productId 相关内容。

AI 优先工具：

dashboard
thread
viewfile
logger
sc
sm

判断方法：

日志出现 MQTT 连接断开，检查网络、端口、认证。
Netty 线程异常，检查线程栈和连接数。
设备上报无响应，检查 broker、topic、产品协议解析。

下一步建议：

让 AI 按设备编号、topic、时间点整理异常。
如果是今天异常，让 AI 读取不带日期的 sys-error.log 和 sys-info.log；如果是历史日期，再读取 sys-error.YYYY-MM-DD.log 和 sys-info.YYYY-MM-DD.log。
对照设备侧日志和平台日志。
如果是协议解析异常，转开发确认协议适配。

必须转人工：

涉及设备批量离线。
涉及协议代码修改。
涉及 MQTT broker 配置调整。

6.8 服务启动失败

用户提问：

FastBee 服务启动失败，请根据 /var/data/java/logs/sys-error.log 和 sys-info.log 帮我分析原因。如果启动失败发生在历史日期，请读取对应日期的 sys-error.YYYY-MM-DD.log 和 sys-info.YYYY-MM-DD.log。请只读取允许日志目录，不要执行高风险命令。

AI 优先工具：

viewfile
logger
jvm

判断方法：

端口占用：日志通常出现 bind failed。
配置错误：日志通常出现 placeholder、property、yaml 解析错误。
数据库不可达：日志通常出现连接失败、认证失败。
Bean 初始化失败：日志通常出现 Spring Bean 创建异常。

下一步建议：

让 AI 提取最早的根因异常。
不要只看最后一行错误。
优先从 sys-error 找异常栈，再用 sys-info 还原启动过程。
按配置、端口、数据库、依赖服务顺序排查。

必须转人工：

需要改生产配置。
需要修改数据库账号或权限。
需要回滚版本。

7. 安全命令清单

7.1 默认可优先使用

工具	用途	风险
`dashboard`	查看整体状态	低
`jvm`	查看 JVM 信息	低
`memory`	查看内存使用	低
`thread`	查看线程和阻塞	低
`stack`	查看调用栈	中低
`logger`	查看日志配置	中低
`sysprop`	查看系统属性	中低
`sc`	搜索类	低
`sm`	搜索方法	低
`viewfile`	查看日志文件	中

7.2 谨慎使用

工具	风险	要求
`trace`	可能增加线上开销	必须指定类名、方法名，采样不超过 5 次
`watch`	可能输出敏感入参	必须指定类名、方法名，采样不超过 5 次
`heapdump`	可能占用大量磁盘和 CPU	必须人工确认，先检查磁盘空间

7.3 不建议让 AI 执行

工具	原因
`ognl`	可执行表达式，风险高
`redefine`	可热更新类，生产风险高
`retransform`	可修改已加载类，生产风险高
`vmtool`	可操作 JVM 内部对象，风险高
`jad`	可能暴露代码细节，非必要不使用

给 AI 的限制提示词：

禁止调用 ognl、redefine、retransform、vmtool。heapdump 必须先征求我的确认。trace/watch 必须限制采样次数，最多 5 次。

8. 常见问题

8.1 连接不上 8563

检查顺序：

FastBee 是否启动。
Arthas 是否随应用启动。
服务器是否监听 8563。
防火墙是否放行。
云安全组是否放行。
客户端所在公网 IP 是否在白名单内。

命令：

ss -lntp | grep 8563
curl -i http://127.0.0.1:8563/admin/mcp

如果本机能访问、外部不能访问，通常是防火墙或安全组问题。

8.2 401 或 403 Token 错误

检查：

application.yml 是否配置了 arthas.password。
FastBee 实际加载的配置文件中 arthas.password 是否生效。
AI 客户端认证字段是否写成 http_headers。
http_headers 中是否包含 "Authorization": "Bearer 密码"。
Bearer 和密码之间是否有一个空格。
密码是否包含多余空格、中文引号或换行。

正确示例：

http_headers = { "Authorization" = "Bearer FbOps_2026@ChangeMe_9xK!" }

错误示例：

headers = { "Authorization" = "Bearer FbOps_2026@ChangeMe_9xK!" }
http_headers = { "Authorization" = "FbOps_2026@ChangeMe_9xK!" }
http_headers = { "Authorization" = "Bearer" }
http_headers = { "Authorization" = "Bearer  错误密码" }

8.3 客户端看不到 MCP 工具

处理：

检查 JSON 格式。
检查 type 是否为 streamableHttp。
检查 URL 是否带 /admin/mcp。
保存后重启客户端。
在提示词中明确要求“使用 fastbee-arthas MCP 工具”。

8.4 AI 调用了危险命令怎么办

如果 AI 准备调用 ognl、redefine、retransform、vmtool：

立即拒绝授权。
告诉 AI：“禁止使用高风险命令，只能用 dashboard、jvm、memory、thread、viewfile 分析。”
如果客户端支持工具权限，关闭这些高风险工具。
必要时断开 MCP 连接。

8.5 服务器 CPU 已经很高，如何保守排查

先只执行：

dashboard
thread -n 5
jvm
memory

不要一开始就执行：

长时间 trace
长时间 watch
heapdump
profiler

提示词：

服务器 CPU 已经很高，请用最低开销方式排查。只执行 dashboard、thread -n 5、jvm、memory。不要执行 trace、watch、heapdump。

8.6 日志路径找不到

处理：

先确认 FastBee 实际日志目录。
确认该目录在 ARTHAS_MCP_VIEWFILE_ALLOWED_DIRS 中。
重启 FastBee 让日志白名单配置生效。
再让 AI 使用 viewfile 读取日志。

常见日志路径：

/var/data/java/logs/sys-error.log
/var/data/java/logs/sys-error.YYYY-MM-DD.log
/var/data/java/logs/sys-info.log
/var/data/java/logs/sys-info.YYYY-MM-DD.log
/var/data/java/logs/sys-warn.log
/var/data/java/logs/sys-debug.log

你的日志目录是 /var/data/java/logs。排查当天问题时，优先让 AI 读取不带日期的 sys-error.log。只有排查历史日期时，才读取对应日期的 sys-error.日期.log，例如：

/var/data/java/logs/sys-error.2026-06-24.log

如果当天 sys-error.log 只有异常栈但缺少业务上下文，再让 AI 读取当天不带日期的 sys-info.log。如果是历史问题，再读取同一天的 sys-info.日期.log 补充前后请求、任务、设备上报等信息。

8.7 公网访问不安全，如何临时收紧

排查结束后建议：

删除安全组 8563 公网放行规则。
或只保留运维人员当前公网 IP。
更换配置文件中的 arthas.password。
重启 FastBee。
确认外部无法再访问 8563。

9. 客户现场速查清单

交付前确认：

arthas.mcp-endpoint 已配置为 /admin/mcp。
arthas.mcp-protocol 已配置为 STREAMABLE。
生产环境已配置 arthas.password。
已在生产配置文件中设置强密码 arthas.password。
8563 端口只对可信 IP 开放。
AI 客户端 URL 为 http://服务器IP:8563/admin/mcp。
AI 客户端认证字段为 http_headers，值为 Authorization: Bearer 真实密码。
已验证 dashboard、jvm、thread 可调用。
已告知客户不要授权高风险命令。

10. 推荐首条诊断提示词

客户第一次连接成功后，可以直接复制：

你是 FastBee 生产运维助手。请通过 fastbee-arthas MCP 帮我做一次安全巡检。

限制：
1. 只允许调用 dashboard、jvm、memory、thread、logger、sysprop。
2. 不允许调用 heapdump、ognl、redefine、retransform、vmtool。
3. 不要修改任何配置，不要重启服务，不要删除文件。
4. 每一步说明调用的工具和看到的证据。

请输出：
1. 当前 JVM 是否健康。
2. CPU、内存、线程是否有异常。
3. 是否存在明显阻塞或高 CPU 线程。
4. 下一步建议。