运维与排查
fed、city、Embassy Admin、数据库直查之间的边界，以及什么时候更适合用 CLI。
CLI 和 Embassy Admin 都能帮你排查 Downcity，但它们适合的工作不一样：fed/downfed 面向 Federation 管理，city/downcity 面向本机 Agent 与本机连接，Embassy Admin 面向可信程序调用。
先给一个最简单的判断标准
如果你想的是：
- “我现在就想看看事实是什么”
优先 CLI。
如果你想的是：
- “这个动作以后要长期存在于系统里”
优先脚本化或 Embassy Admin。
CLI、Embassy Admin、数据库直查各自适合什么
更适合 CLI 的情况
- 本地开发机上快速看数据
- 排查某个 service 到底有没有写表
- 想看模型记录、schema、rows
- 不想为了一个一次性问题先写脚本
更适合 Embassy Admin 的情况
- 要把动作放进业务后端
- 要自动化签 token
- 要做正式管理流程
- 要把管理动作暴露给内部工具或后台
更适合直接数据库排查的情况
- 你已经确认问题落在更底层数据库行为
- 需要做更细粒度 SQL / 运维层检查
- CLI 已经帮你缩小问题范围，但还要看更底层事实
最常见的 CLI 排查动作
city
fed
city federation status
city agent list第一条适合打开交互入口，后两条适合确认 City 连接和本机 Agent 运行状态。
CLI 与 Desktop 的 City 互斥
CLI 和 Desktop 使用同一组 ~/.downcity 数据，但各自拥有独立的 City 进程。City
启动时会登记当前宿主；如果另一端已经运行，启动方会先询问是否关闭已有 City 并接管。
取消接管不会修改已有宿主。City 关闭后，Agent、Plugin 和 Session 数据仍保留在共享数据目录。
用户系统 Dashboard
打开 fed，选择一个已保存的 Federation，然后在 Admin 菜单中进入 用户系统 Dashboard。
CLI 会读取已安装官方服务的 admin 数据，并在终端内本地计算 Dashboard。
Dashboard 覆盖：
accounts：注册用户、新注册、活跃会话usage：活跃用户、service 调用事件payment：付费用户、首付用户、支付订单、按币种聚合的真实收入balance：已入账 credits、当前余额 credits
如果某个服务没有安装，Dashboard 会把对应模块标记为不可用，同时继续展示其它已安装服务的数据。
收入只来自成功支付记录里的真实 amount_minor；credits 会单独作为余额和充值单位展示，不再当成 revenue。
一条常见排查链路
当你遇到“调用不对、usage 没记、payment 没生效”时，通常可以按这个顺序走：
- 先确认 Federation 是否连对数据库
- 再确认 models / tables 是否存在
- 再确认 service 是否真的写入数据
- 最后才去怀疑更深的业务逻辑
这比一开始就盲猜代码路径更快。
例子：usage 看起来没记录
这时更合理的第一步通常不是改代码，而是先确认事实：
- usage service 有没有启用
- usage 表有没有创建
- 当前数据库是不是你以为的那个
- 有没有任何事件被写进去
CLI 正适合这一步。
例子：支付后还是没权限
优先查这几层事实：
- webhook 有没有到 Federation
- webhook 事件有没有落表
- entitlement 有没有变成 active
这时 CLI 比直接去改前端拦截逻辑更有效。
常见误解
CLI 不只是开发时用一次
只要你管理多个产品、多个 service、多个模型，CLI 都会是高频运维入口。
Embassy Admin 不是“更高级的 CLI”
两者不是上下位关系，而是两种不同形态：
Embassy Admin：可信程序调用- CLI：人工终端排查
直接查数据库不应成为第一反应
很多时候 CLI 已经足够把问题缩小到很小范围。
继续阅读
- 想知道
fed/city的基础入口，读 CLI 快速开始 - 想重点看模型和表，读 Models 与 Tables
- 想理解背后的数据层，读 Store 与 Table