邀请与访问权限 | 界舟 · Harness Dock 文档

设备邀请用于把电脑接入服务；应用凭据用于让产品访问获授权设备。它们是两种不同的身份，不要互换。管理员负责生成与分发；设备用户在 App 中核对接入即可。

本页面向服务管理员。以下命令在下载并解压 Server 归档的项目目录运行，其中已有 server/ 和初始化生成的 .local/control/；Docker 部署沿用同一项目目录的 ./server/docker.sh，宿主不需要 Node.js。每次打开新终端，先将 DOCK_IMAGE 设为原先核验的固定镜像。配置由管理员私有保存。设备用户只需使用管理员发出的邀请，不运行这些命令。

生成设备邀请链接#

管理员先为这台设备登记身份、授权给应用并让运行中的 server 加载配置，随后在服务器上生成邀请：

./server/docker.sh invite .local/control/server.json --node-id <设备UUID>
# 旧配置没有 publicEndpoint 时，显式指定公开 WSS 地址：
./server/docker.sh invite .local/control/server.json \
  --node-id <设备UUID> --endpoint wss://dock.example.com/

命令输出可直接发给对应设备用户的 HTTPS 链接。仅一个设备时可省略 --node-id；--expires-in 可设为 60–3600 秒，默认 900 秒。生成邀请不改变配对配置，也不会重启服务；新增设备和令牌轮换仍按原维护流程重启并核对加载版本。

链接中的片段保存短期签名领取凭证，不包含长期设备 token。网页通过 harness-dock:// 唤起客户端，用户确认后客户端通过经过证书校验的 HTTPS 领取并保存本机配置。原生 Codex 安装与登录继续由设备用户管理。

领取状态保存在私有 invitation-state 目录，仅含已消费邀请的摘要与到期时间。容器需持久挂载该目录并设置 HARNESS_DOCK_INVITATION_STATE；重启不清空，存储不可写时拒绝领取。反向代理将 /connect 和 /invitations/redeem 转发到应用端口，更新后的 deploy 产物已包含配置。若领取响应丢失，客户端不会自动重试；先查本机状态，再由管理员生成新邀请。

访问模型#

每台设备只绑定一个控制方；每个应用身份只允许一个活动连接。新增应用最初没有设备权限，需要服务端部署者显式授权或转移设备。

管理命令读写私有配置文件，需由配置属主在可写管理目录执行。命令不直接修改正在运行的 server。

查看与新增#

./server/docker.sh pair .local/control/server.json list
./server/docker.sh pair .local/control/server.json device-add \
  --client <已有应用UUID> --label home-mac --output .local/new-device.json
./server/docker.sh pair .local/control/server.json client-add \
  --output .local/new-client.json

将生成的领取文件私下交给对应接收方，已有输出文件会拒绝覆盖。

转移设备控制方#

./server/docker.sh pair .local/control/server.json grant \
  --node-id <设备UUID> --client <目标应用UUID> --from <原应用UUID>

必须明确原控制方，转移后仍保持单控制方模型。

轮换或移除#

./server/docker.sh pair .local/control/server.json device-rotate \
  --node-id <设备UUID> --output .local/rotated-device.json
./server/docker.sh pair .local/control/server.json device-remove \
  --node-id <设备UUID>

device-export/client-export 导出已有接收方文件；device-rotate/client-rotate 生成新凭据。client-remove 只允许删除不再持有设备的应用。

使变更生效#

取消 server 配对不会删除设备上的原生会话、历史或用户文件。连接恢复也不会重新派发任务。

只读挂载 server.json 的运行容器不适合作为配对管理入口；在配置属主可写的主机管理目录，或独立管理容器中操作。

Docker：保存配置到确认生效#

给原应用增加设备时，先 list 取得应用 UUID，再 device-add；记录返回的新 nodeId，让配置生效后再生成该设备的新邀请。不要复用其他 Mac 的身份。配置写入不会改变运行中的 Server；先在原应用核对活动、待审批和待核对执行，再安排维护窗口。以下从原部署项目目录执行：

export DOCK_IMAGE=harness-dock-server:sdk-v0.1.2
# 自定义过镜像时保留原先核验的固定值。
(cd .local/deployment && docker compose -p harness-dock restart)
./server/docker.sh doctor .local/control/server.json
./server/docker.sh invite .local/control/server.json --node-id <新设备UUID>

doctor 必须读到刚保存的配置摘要。轮换或撤权还需验证旧凭据被拒绝；健康接口 ok 不代表撤权完成。设备和应用会重连，不重派 prompt、工具或审批。保留配置、邀请消费状态和设备执行记录。宿主已有 Node.js 22.19+ 时，可将 ./server/docker.sh 换为 node server/dist/cli.js。