Federation & Service
Downcity AI 基础设施中 Federation 和 Service 是什么
Federation & Service
Federation 是 City 连接的共享服务端运行容器。它负责用户身份、City 隔离、Service 路由、模型目录、用量和支付，并通过统一接口连接多个 AI 提供商。
Federation AIService
Federation AIService 是 City 的一个组件，负责：
- 注册模型提供商及其能力
- 无论后端是什么，都暴露统一的模型 API
- 追踪用量并将请求路由到合适的提供商
- 处理故障转移和速率限制
Agent 通过类似 "default" 或 "quality" 的 ID 绑定模型。Federation AIService 在运行时将该 ID 解析为实时模型实例。
Service / Action 基础设施
City 还提供了一个通用的 Service 和 Action 层，用于构建 Agent 可调用的后端能力：
- Service — 长期运行的后端能力（例如知识库、搜索引擎、数据库）
- Action — Agent 可调用的离散操作（例如发送邮件、查询数据库、调用外部 API）
Service 和 Action 向 City 注册，可被任何已连接的 Agent 发现和调用。
与 City 的关系
Federation 是服务端，City 是携带 user_token 的用户客户端。当你使用 City SDK 时，你在交互的是：
- City 身份与认证
- Federation AIService（模型目录和路由）
- Service/Action 基础设施（后端能力）
- 用量、余额和计费（City Services）
Federation 首次启动会自动生成 Ed25519 Key Ring，并通过 /.well-known/jwks.json 发布公开验签密钥。Embassy 可以直接访问 Federation；产品需要自有后端能力时，再使用 Bureau Token 和独立 Bureau 客户端本地验证用户 Token。Federation 启动不会默认创建 Bureau Token。
管理员登录与恢复
首次运行 fed deploy 时，CLI 会交互式要求设置 Federation 管理员 ID、密码和确认密码。密码至少 12 个字符，Federation 数据库仅保存加盐密码摘要。运行 fed web 后，在登录页输入这组凭证；浏览器不会接触远端管理 Session Token，Token 只存在于本机 BFF 进程内。
普通部署不会修改管理员。密码遗失时，只有拥有 Local 主机权限或 Cloudflare Worker/D1 部署权限的人可以执行：
fed deploy --admin-reset非交互环境还必须显式添加 --yes；该参数只确认重置，不跳过管理员凭证输入。恢复由 CLI 使用本地 SQLite 事务或 Wrangler 远程 D1 权限直接写入管理员数据库，不需要在 Worker 中接收恢复环境变量，也不会把明文密码传给数据库。恢复成功会撤销全部旧管理员会话。Federation 不提供匿名密码重置 API。
fed deploy 会在交互终端持续显示当前步骤与耗时，包括构建、类型检查、Cloudflare 账号检查、D1 / Queue / R2 准备、Worker 发布、健康检查和管理员验证；CI 与重定向输出使用稳定的逐行阶段日志。
fed bureau token 会打开交互式管理界面；选择签发或运行 fed bureau token issue <bureau_id>
后，CLI 会要求输入用途并使用 Admin Session 请求 Federation 签发。Federation 生成明文，
数据库只保存用途、hash 与生命周期状态。明文只返回一次，由运维写入 Bureau 服务器的
DOWNCITY_BUREAU_TOKEN；Federation 和 Bureau 不需要部署在同一台服务器。Bureau Token
只证明机器身份，不能签发 User Token。