连接服务器
Add Server Wizard 是连接 RoqueOS 前端（在 https://roqueos.com.br/app）到您的 RoqueOS Server 的官方路径。它在 Settings → Server → 添加服务器 中。
替换了旧流程，该流程要求用户在浏览器中打开 <server>:27021/admin。现在一切都发生在应用内部。
何时使用
- ✅ 新安装的服务器（
install.sh运行，尚未有 API Keys）— wizard 创建第一个 admin key - ✅ 已在使用的服务器（您已保存 apiKey + apiSecret）— wizard 验证并添加到列表
- ✅ 切换服务器 — 添加第二个服务器，通过菜单栏中的切换器在它们之间切换
引导流程（空白服务器）
7 个步骤。总时间: ~1 分钟。
Step 1 — URL
粘贴服务器 URL。接受:
http://localhost:27021（Docker 在您的机器上运行 — 通过 loopback 工作）https://server.example.com（在 Cloudflare Tunnel 或 TLS 证书后面）
Wizard 规范化协议（server.example.com → 自动 https://server.example.com），并在继续之前检测已注册的服务器。
⚠️ HTTP vs HTTPS — 浏览器限制
前端 roqueos.com.br/app 在 HTTPS 上运行。根据现代浏览器的设计（Mixed Content 策略），HTTPS 页面 无法调用 HTTP API — 浏览器在请求离开机器之前就静默阻止它。
这意味着尝试连接 http://192.168.1.50:27021（LAN）或 http://server.com:27021（公共）将失败，显示"couldn't connect"，看起来像服务器错误，但实际上是浏览器阻止。
Wizard 为您检测这一点 并在请求执行之前显示解释问题的黄色横幅。三种解决方案，按优先顺序:
1. 通过 Cloudflare Tunnel 的 HTTPS（推荐）
免费，即插即用。install.sh 已经具有内置支持:
curl -fsSL https://roqueos.com.br/install.sh | bash -s -- --update
# 之后: Settings → Server → Cloudflare Tunnel → 连接结果: 您的服务器将位于 https://<id>.cloud.roqueos.com.br 或您自己的域名。自动 TLS，无需调整防火墙，无需公共 IP。
完整 install.sh + Cloudflare Tunnel 指南 →
2. 使用桌面或移动应用
原生包装器（Microsoft Store、Play Store、App Store）没有混合内容限制 — 它们运行本机代码，而不是严格 HTTPS 的网页。
适用于: 您不想/不能配置 tunnel 的 homelab 环境。
3. localhost 上的服务器（loopback）
http://localhost:27021、http://127.0.0.1:27021 和 http://[::1]:27021 由现代浏览器通过 Secure Contexts spec 被视为安全上下文 — 因此即使前端 HTTPS 也能工作。
适用于: 本地开发，在上传到真实服务器之前测试。
Step 2 — Detect
Wizard 并行命中 2 个匿名端点:
GET /health/version-info— 版本 + minClientVersionGET /admin/setup— 如果返回{ needsSetup: true }，则服务器为空
这里也检查版本兼容性。如果服务器为 v1.0.10 但客户端（前端）需要 v1.0.13+，显示友好的"先更新服务器"警告 + install.sh --update 的链接。
Step 3 — Bootstrap（空白服务器）
"创建 admin key" 按钮 → POST /admin/setup（在服务器上按 IP 限速以避免 setup race）。
返回 { apiKey, apiSecret }，wizard 在下一步中显示。
竞争处理: 如果 2 个浏览器同时尝试 setup，第二个会收到 error: 'Setup already completed'，wizard 转移到步骤 5（手动 credentials）。
Step 4 — keyCreated
显示返回的 apiKey + apiSecret，在 带复制按钮的只读字段 中。
⚠️ 关键 UX 保护:
- 模态具有
closeOnBackdrop=false（点击外部不关闭） - X 按钮打开确认子模态（"您是否保存了 credentials？"）
- 必需的复选框 "我已保存我的 credentials" 启用 Next 按钮
- 如果您未保存就关闭，key 保留在服务器上但您丢失 — 只能通过
/adminHTML 旧版恢复
Step 5 — credentials（服务器已配置）
如果在步骤 2 检测指出 setup 已完成，则直接跳转到此处:
- 字段
apiKey - 字段
apiSecret - 链接"打开服务器 admin 面板 ↗"（在新选项卡中打开
<server>/adminHTML 旧版）
旧版页面继续作为恢复和自动化的后门。
Step 6 — 名称
唯一字段: 服务器的友好名称（出现在菜单栏的 Server Switcher 中）。
建议默认: URL.hostname（例如: demo.level-hard.com 或 localhost）。
Step 7 — 完成
Wizard 调用:
addBackendService({ name, url })— 保存到backendSettings.services列表setApiCredentials(apiKey, apiSecret, serviceId)— 将 creds 存储在 Firestore 中setActiveBackendService(serviceId)— 使其活跃
模态关闭。服务器已连接。您处于 Server Mode 中。
Server Switcher（菜单栏）
当您注册了 2+ 服务器时，菜单栏（左上角）会出现一个下拉菜单，显示活跃服务器。点击切换。
当前状态（2026 年 5 月）: 组件
ROSServerSwitcher在之前的会话之后尚未重建 — 该功能已计划但尚未交付。目前，在服务器之间切换是通过 Settings → Server → 点击所需的服务器。
公共演示服务器
要在不安装任何东西的情况下测试 Server Mode，RoqueOS 已经附带了 预配置的公共演示服务器:
- 在
https://roqueos.com.br/app登录 - 转到 Settings → Server
- DEMO 服务器已经出现在列表中 — 点击激活
无需粘贴 URL、apiKey 或 apiSecret — credentials 嵌入到客户端并直接工作。
什么是演示: RoqueOS Server 的真实实例，由创始人更新，每日清理（孤立容器、> 24h 的 agents/sessions、悬空卷）。限制:
- 非管理员看不到 Server Admin Panel（安全门）
- Cloud Gaming 可以清除僵尸会话
- 容器在 prune 之前保留 ~24h
- 在所有访客之间共享
适用于: 探索 Containers、Terminal、嵌入式 VS Code、Files。不适用于: 长期持久性、敏感或重要数据 — RoqueOS 中登录的任何人都可能在并行使用相同的演示。
对于实际使用，请使用 one-liner 安装您自己的服务器。
故障排除
| 症状 | 解决方案 |
|---|---|
| "服务器不可访问" | 确认 curl <url>/health 返回 200。可能是端口 27021 未释放或 Docker 已停止 |
| "服务器已注册" | Wizard 检测到重复。转到 Settings → Server 并选择现有的 |
| "服务器已过时" | 在服务器上运行 --update: curl -fsSL https://roqueos.com.br/install.sh | bash -s -- --update |
| "Setup already completed" 但您从未配置过 | 重置: docker exec roqueos-server sqlite3 /app/data/roqueos.db "DELETE FROM api_keys;"（注意 — 删除所有现有 keys） |
| 服务器已添加但 Settings 返回空 | 可能缺少 Firestore 登录。检查 DevTools console 是否出现 Firestore: PERMISSION_DENIED |
参考
- install.sh one-liner — 先启动服务器
- Server Admin Panel — 连接后管理
- Volumes & 备份 — 理解持久性
- 内部 Composable: src/composables/useAddServerWizard.js（状态 + 流程）