部署服务端

这页面向服务管理员。你只需准备一次共同的 Server，再分别向设备用户发放邀请、向应用开发者提供访问凭据。普通设备用户直接阅读安装与连接；已有服务的开发者从SDK 接入开始。

默认用一个 Docker 容器运行 Server，宿主机无需安装 Node.js、Codex 或 dsh。管理员部署一次，设备用户通过 App 邀请连接，应用和 Agent 只接 SDK。下面复用已有 Nginx 与有效 TLS 证书，远程连接使用 WSS。

部署准备#

准备 Linux 主机、Docker Compose、curl、GNU sha256sum、域名与有效 TLS 证书。以下从已发布的 Server 归档构建本机镜像，使用已有 Nginx 终止 TLS，server 仅监听回环地址。服务端无需安装 Codex、dsh 或设备 Daemon；原生执行仍在所选 Mac 上。

此路径无需 Git、pnpm 或仓库源码。维护者需要修改源码或提供已构建镜像时，再看构建与分发。macOS 设备包与 Linux server 镜像分别分发，不要跨平台复制 daemon 的 node_modules。

下载已发布 Server 并构建镜像#

在目标 Linux 主机的新目录中执行。固定 SDK 0.1.2 Developer Alpha 发行包含 harness-dock-server-0.1.2.tar.gz、源码与构建元数据及校验和；它与设备 App 分别发行。

mkdir harness-dock-server
cd harness-dock-server
umask 077
mkdir -p .local/downloads
base="https://github.com/hutian-ai/harness-dock/releases/download/sdk-v0.1.2"
for file in harness-dock-server-0.1.2.tar.gz release.json README.txt SHA256SUMS; do
  curl --fail --location "$base/$file" --output ".local/downloads/$file" || exit 1
done
(cd .local/downloads && sha256sum --ignore-missing --check SHA256SUMS) || exit 1
tar -xzf .local/downloads/harness-dock-server-0.1.2.tar.gz
docker build --tag harness-dock-server:sdk-v0.1.2 ./server

这里仅下载 Server 与元数据；GNU --ignore-missing 只校验本目录实际下载的文件，跳过清单中的 SDK 和设备归档。核对 release.json 的源码 revision 和构建来源；摘要检测下载损坏，不能替代发布者身份验证。

解压结果为 server/，其中的 Dockerfile 使用 node:22.22.2-bookworm-slim，复制随包依赖，并以 node dist/cli.js 为入口。构建需要取得该基础镜像；harness-dock-server:sdk-v0.1.2 是下面流程使用的本地镜像名。该步骤不创建服务配置、不启动服务，也不执行模型任务。

生成配置与部署文件#

保持在刚创建的 harness-dock-server/ 目录执行，替换示例域名。.local/control 与 .local/deployment 必须是新目录；镜像名与上一步一致：

export DOCK_IMAGE=harness-dock-server:sdk-v0.1.2
# 始终在当前部署项目目录运行；脚本在容器里执行管理命令。
./server/docker.sh init .local/control \
  --public-endpoint wss://dock.example.com/
./server/docker.sh deploy .local/control/server.json \
  --output .local/deployment --image "$DOCK_IMAGE"

容器内的 init 生成 server.json、device-pairing.json 和 client.json；设备与应用领取文件直接使用公网 WSS 入口。deploy 在新目录生成 Compose、.env、Nginx 片段与操作说明。

核对私有配置与反向代理#

1. 确认本地镜像名称与上一步 deploy --image 一致。
2. 将 server.json 私下放入目标服务器的受保护目录，保持 0600。
3. 上述命令直接在目标 Linux 主机运行时，生成的 .env 路径、邀请状态目录与 UID/GID 已对应当前宿主用户，可直接核对。迁移到另一台主机时，更新 .env 中的 DOCK_CONFIG_FILE 与 DOCK_INVITATION_STATE 为目标机绝对路径，保留邀请状态并设置目录 0700，Compose 的 user UID/GID 须与配置文件和该目录属主一致。复制部署目录后尤其要更新这两条路径，不能沿用构建机路径。
4. 核对生成的 Nginx 片段、域名和证书路径，将其合入现有 http 上下文。

需要自定义证书路径时，在 deploy 使用 --tls-cert 与 --tls-key。若维护者已提供并核验镜像归档，可使用 docker load -i /private/image.tar 导入，替代上一步本机构建；核对固定镜像名称，并让 deploy --image 使用同一名称。源码构建与镜像导出见维护者分发流程。

启动并检查#

先阅读生成目录中的操作说明。以下从 harness-dock-server/ 项目目录进入生成的 Compose 目录执行，最后返回项目目录；现有服务的切换选择维护窗口，避免占用相同端口。

cd .local/deployment
docker compose -p harness-dock config --quiet
docker compose -p harness-dock up -d
docker compose -p harness-dock ps
docker compose -p harness-dock logs --tail 50
cd ../..

配置 Nginx 后先检查 nginx -t，再按服务器现有流程安装或重载配置。确认公网入口：

curl --fail https://dock.example.com/healthz
./server/docker.sh doctor .local/control/server.json

doctor 分别检查传输、协议与实际加载的配置摘要。服务健康不等于设备已上线，也不等于模型执行通过。

分发设备邀请#

推荐给设备用户提供邀请链接，点击后由客户端确认并接入。管理员在上述项目目录运行 ./server/docker.sh invite .local/control/server.json，将输出的短期邀请私下交给对应设备用户。管理员生成命令与反向代理、持久状态要求见 生成设备邀请链接。以下 JSON 文件保留给服务维护、应用 SDK 和旧版设备兼容。

每台设备、每个应用使用独立凭据。新增、转移、轮换与撤权见配对与访问管理。

运行注意事项#

• 设备和应用都主动连接 server；家庭路由器通常无需为设备开放入站端口。
• 远程使用经过验证的 WSS，明文 WS 仅用于回环地址。
• Docker Compose 使用 restart 策略管理进程，不叠加第二套应用进程守护。
• 修改配对文件后需要重启目标 server 并核对已加载配置；不会自动热加载。
• server 不持久化执行正文；执行会话与状态由设备 Daemon 持有。
• 邀请消费状态需要持久化到 DOCK_INVITATION_STATE 指向的受保护目录；不要在重启或升级时清空，否则失去已领取邀请的防重放记录。该目录仅存摘要与到期时间，不存设备 token。

网络与端口#

server 的默认设备端口为 48518，应用端口为 48519；可通过初始化参数选择独立端口。远程入口由 --public-endpoint 指定，设备与应用使用服务端生成的领取文件连接。部署示例使用回环监听与 Nginx 公网 WSS。

私有 CA 通过设备初始化的 --ca-file 或应用 client.json 的 caFile 配置，证书链和主机名仍须校验。Compose 的 host network 共享宿主网络；健康检查只标记状态，不能代替进程退出后的重启策略或模型验证。

源码与候选包#

修改 Server 时，由维护者从当前源码生成 Linux server bundle，再以 bundle 为上下文构建固定镜像，见构建与分发。server/docker.sh 从部署项目目录运行，只挂载该目录，配置和输出均放在此目录下。宿主机已有 Node.js 时，也可直接运行 node server/dist/cli.js 的同名管理命令。