协作与服务端故障排查

Organization Server 提示 Route not found

App 与 Duobox Server 版本不兼容，或者 App 仍然连接旧的服务端进程。升级两端、重启服务，并确认 duobox server status 显示了预期的公开地址。

提示 Federation is unavailable

Duobox Server 无法通过 Federation 识别 App 的 Token。检查 Server 到所配置 Federation 的网络连接、Bureau Token 和 City ID。这是鉴权依赖错误，不是 Git 错误。Duobox 会直接反馈失败，不使用重复重试掩盖问题。

Organization 没有显示

确认当前 Federation 账户拥有 active Membership，并且 organizations/my 返回该 Organization。已归档的 Organization 不能访问 Space。

无法创建 Space

只有拥有 Duobox manager 权限的用户能创建 Space。Organization Owner 和 Admin 自动获得 manager；Editor 和 Viewer 可以打开已有 Space。请在 Organization 设置中确认当前账户和角色。

Server 为什么占用终端

日常后台运行使用 duobox server start。duobox server start --foreground 会有意持续占用终端，适合前台调试，或交给 systemd、Docker、Dokploy 管理进程。停止前台进程请按 Ctrl+C；停止后台进程请使用 duobox server stop。

push 或同步被拒绝

确认 Membership 仍然 active，并且 Duobox 角色是 manager 或 editor。服务端还会拒绝 force push、删除 main、更新非 main 分支，以及任何超过 20 MiB 的单个 blob。

Sync conflict 怎么处理

冲突面板会列出真实内容文件。可以选择“保留我的版本”或“使用远端版本”；也可以手动编辑冲突标记，保存后点击“继续同步”。“取消同步”会退出本次 rebase，并保留同步前的本地修改。

.downcity/ 和 .duobox/ 属于本机运行状态，不需要人工合并。Duobox 会自动解除它们的 Git 跟踪，同时保留本地文件。