Packages 包City CLI
运维与排查
fed、city、Admin City、数据库直查之间的边界，以及什么时候更适合用 CLI。
CLI 和 Admin City 都能帮你排查 Downcity，但它们适合的工作不一样：fed/downfed 面向 Federation 管理，city/downcity 面向本机 Agent 与本机连接，Admin City 面向可信程序调用。
先给一个最简单的判断标准
如果你想的是：
- “我现在就想看看事实是什么”
优先 CLI。
如果你想的是：
- “这个动作以后要长期存在于系统里”
优先脚本化或 Admin City。
CLI、Admin City、数据库直查各自适合什么
更适合 CLI 的情况
- 本地开发机上快速看数据
- 排查某个 service 到底有没有写表
- 想看模型记录、schema、rows
- 不想为了一个一次性问题先写脚本
更适合 Admin City 的情况
- 要把动作放进业务后端
- 要自动化签 token
- 要做正式管理流程
- 要把管理动作暴露给内部工具或后台
更适合直接数据库排查的情况
- 你已经确认问题落在更底层数据库行为
- 需要做更细粒度 SQL / 运维层检查
- CLI 已经帮你缩小问题范围，但还要看更底层事实
最常见的 CLI 排查动作
city
fed
city federation status
city agent list第一条适合打开交互入口，后两条适合确认 City 连接和本机 Agent 运行状态。
用户系统 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 都会是高频运维入口。
Admin City 不是“更高级的 CLI”
两者不是上下位关系，而是两种不同形态：
Admin City：可信程序调用- CLI：人工终端排查
直接查数据库不应成为第一反应
很多时候 CLI 已经足够把问题缩小到很小范围。
继续阅读
- 想知道
fed/city的基础入口，读 CLI 快速开始 - 想重点看模型和表，读 Models 与 Tables
- 想理解背后的数据层，读 Store 与 Table