把 data-agent 装到阿里云 ECS 上、连上同地域的 RDS，是本篇要走的完整一条路。插件本身不负责开网络，真正卡人的地方几乎都集中在「版本对不对」和「云上放不放行」这两类问题上。下面按环境 → 装插件 → RDS → ECS → 连接配置 → 跑通查询的顺序走一遍，最后附五个高频坑。
环境：先把 DSH 版本对齐
插件 @yejiming/dsh-data-agent 的 registry 最新版是 0.2.2（发布于 2026-09-29），它的 peerDependencies 全部要求 >=0.2.0-rc.1，其中 @deepseek-ai/cordis 钉在精确的 4.0.4。README 的口径是「DeepSeek Harness >= 0.2.0-rc.1」，而当前已完成运行验证的版本是 0.2.0-rc.2。
ECS 上第一件事是确认引擎版本够格了再装插件。还有一点要留意：包的 engines.node 未声明，Node 版本下限没有官方口径，需要你自己保证它与所装的 DSH 版本匹配——建议直接用能把 DSH 跑起来的那个 Node。
装插件：Web 与终端两个 profile
按你要用的入口选一个，装到对应 profile：
装完不需要重启机器，但要让会话重新拉起插件。插件走的是新版 dsh-agent-preset-registry 注册数据模式，预设仍从 $DSH_HOME/.agent-presets/<presetId>/ 读取，宿主注册表负责工具作用域、空会话切换与卸载。
RDS 侧：只读账号 + 内网白名单
在 RDS 控制台为 data-agent 单独建一个只读账号，只授权到要分析的那个库，不要图省事用主账号。接着处理白名单：把 ECS 的内网网段加进 RDS 白名单。这一步最容易漏——很多人只放行了本机公网 IP，ECS 走内网出口时自然连不上（见坑五）。
连接优先用 RDS 的内网地址，同地域内网延迟低，也不占公网带宽。
ECS 侧：安全组与出网
ECS 的安全组要放行到 RDS 端口的出方向流量。如果是通过 SSH 隧道绕行，还要在本机与 ECS 之间先把隧道端口打通。实例规格不必夸张——查询瓶颈通常在数据库端，但报告生成与图表渲染是本地 CPU 活，别挑最小规格。
连接配置与测试连接
Web 界面里：启动 dsh --profile web → 新建会话并选「数据模式」→ 点「连接配置」，或进会话后点输入框右上角的数据库图标 → 在弹出工作台中填连接信息。填完先点测试连接，通了再提问。终端入口则是先 /preset data-agent 切模式，再 /database connect 连接。
跑通第一条查询
连接成功后，先用大白话问一条能快速验证链路的，比如「对比最近 30 天各渠道转化率」。AI 会自己探查库表结构、编写并执行 SQL。跑通后再考虑打开「数据治理」做中文业务释义。
坑一 · DSH 版本不够，插件装上也起不来
现象。 装完在界面里看不到「数据模式」，或启动直接报错。原因。 插件 0.2.2 的 peerDependencies 全部要求 >=0.2.0-rc.1，@deepseek-ai/cordis 更是钉在 4.0.4；README 明确「旧版 DSH 请继续使用相应旧版插件」。解决。 先确认 dsh 版本达到 0.2.0-rc.1 以上（已完成运行验证的是 0.2.0-rc.2），再装 @yejiming/dsh-data-agent。
坑二 · 启动报 $.prefix missing required value
现象。 升级插件后首次启动，会话初始化失败，提示 $.prefix missing required value。原因。 新版 DSH 要求预设的 persona.config.prefix 必填；被自定义过的预设不会被自动覆盖，于是缺字段。解决。 备份 $DSH_HOME/.agent-presets/data-agent/agent.cordis.yml（默认位于 ~/.dsh），在 persona 的 config 中让 prefix 与原 text 使用相同提示词，然后重启。
坑三 · 连接能通，SQL 却被拦下来
现象。 测试连接成功，但一执行写操作就报错或被拒绝。原因。 只读保护要靠两件事同时成立：数据库账号本身只读 + 连接时开启「只读模式」；只做一件，护栏都只剩一半。解决。 在 RDS 侧建只读账号授权到目标库，再在连接配置里勾选只读模式；两处都配好后再做一次写操作验证会被拦。
坑四 · 报告找不到，其实落在了工作目录
现象。 Agent 说已生成报告，但在 ~ 下翻不到。原因。 报告存到当前工作目录的 analysis-reports/，而 Agent 的 cwd 由会话决定，不是固定 home 目录。解决。 先在会话里确认工作目录（或直接问 Agent 报告绝对路径），必要时固定会话工作目录，让同类报告集中落一处。
坑五 · ECS 内网连不上 RDS
现象。 插件在 ECS 上测试连接超时，但本机连同一台库正常。原因。 RDS 的白名单/安全组只放行了本机公网 IP；ECS 走内网或另一出口时不在白名单内。解决。 把 ECS 的内网网段加入 RDS 白名单，优先用内网地址连接；用 ECS 上的 telnet/nc 先验证到库端口的连通性，再回插件里点「测试连接」。
总结
走完这六步，data-agent 在阿里云上的落地其实就是「版本对齐 + 网络放行 + 只读双保险」这三件事；想对照同类插件的中文清单与安装形态见 DeepSeek Harness Hub 插件清单。
适合与不适合
适合：已有阿里云 ECS + RDS、想用对话做业务分析的分析师；需要给非技术同事自动产出离线 HTML 报告的团队；库表字段是英文缩写、想先做一轮中文业务释义的数据同学；习惯终端操作、想用 dsh-tui 快速连库的工程师。不适合：DSH 还停在 0.1.x 且不打算升级的用户；没有任何可连数据库、只想看演示效果的人；指望「装完即安全」、不愿手动配只读账号与只读模式的场景。
标签：dsh-data-agent、DeepSeek Harness、阿里云 ECS、RDS、只读保护
本文由 DeepSeek Harness Hub 自动整理，数据来源于插件详情页。
