启动节点

「节点」指一台运行 zqagent 的机器：它在本机拥有工作目录、模型配置与会话数据， 既可以只在本机用，也可以接入用户中心被远程管理与查看。

本页讲解如何启动、常驻并接入节点。

三种运行形态

形态	启动方式	适合
交互式 CLI	zqagent	在本机边聊边干活，最常用
常驻服务节点	zqagent serve	跑在服务器/长期开机的机器上，供远程管理
桌面应用	安装桌面应用	想要图形界面；与常驻服务共用同一个开机自启节点

桌面应用与常驻服务节点是同一个节点服务（同一套数据目录与端口），只是操作界面不同： 装了桌面应用再跑 install.sh 不会产生第二个节点。交互式 CLI 则使用当前目录的独立数据， 三者可按需组合。

交互式 CLI

zqagent

进入交互式界面后输入自然语言任务即可，模型用 /connect 配置 （见快速开始）。完整命令见 CLI 使用。

交互式 CLI 是一台「本机可用」的节点，但不监听端口，不能被远程管理。 需要远程管理请看下面的 zqagent serve。

启动常驻节点

zqagent serve 以无界面方式启动服务，监听 HTTP 端口，并在后台运行。

zqagent serve

启动后日志会打印监听地址、数据目录、节点 ID 与演示租户信息 （首次启动自动创建演示租户 demo，其 apiKey 随机生成并打印在启动日志中，可直接用于本机调试）。

参数

参数	说明	默认值
--port <n>	监听端口；被占用时自动改用下一个可用端口（实际端口见数据目录 server-port，日志也会说明）	8787（或环境变量 PORT）
--host <addr>	监听地址；设为 0.0.0.0 允许外部访问	127.0.0.1（或 HOST）
--data-dir <dir>	数据目录（项目、会话、账本、凭据）	./.zqagent_data（或 DATA_DIR）
--hub <url>	用户中心地址，配合 --enroll-code 启动即接入	—
--enroll-code <code>	一次性接入码	—
--label <name>	节点显示名	主机名

默认只监听 127.0.0.1，即仅本机可访问，最安全。确需局域网/公网访问时 再设 --host 0.0.0.0，并注意防火墙与访问控制。

后台常驻

前台运行会随终端关闭而退出，长期运行时请装成系统服务（开机自启 + 崩溃自动拉起）。

Windows：没有 systemd / launchd。用「任务计划程序」创建“登录时运行”的任务， 程序填 zqagent.exe 的绝对路径，参数填 serve --port 8787 --data-dir "%APPDATA%\zqagent"； 也可以把 zqagent.exe serve ... 的快捷方式放进启动文件夹（Win+R → shell:startup）。 停止/重启用任务计划程序或任务管理器操作。

推荐：一条命令（自动下载最新单文件、装服务、并启用自动更新，见单文件安装）：

curl -fsSL https://agent.cd-zq.com/install.sh | sudo sh

装好后：

sudo sh -s -- status        # 运行状态
sudo sh -s -- logs          # 跟踪日志
sudo sh -s -- restart       # 重启
sudo sh -s -- rollback      # 回滚到上次自动更新前
sudo sh -s -- uninstall     # 停止并移除

（sudo sh -s -- <子命令> 与 curl ... | sudo sh -s -- <子命令> 等价； 已下载脚本时也可直接 sudo sh install.sh status。）

从仓库源码安装（开发机 / 已用 npm 安装时），macOS 走 launchd、Linux 走 systemd：

# 在仓库 deploy/service 目录下执行
bash install.sh install     # 安装并启动（开机自启）
bash install.sh status      # 运行状态
bash install.sh logs        # 跟踪日志
bash install.sh restart     # 重启
bash install.sh uninstall   # 停止并移除

默认数据目录：macOS ~/Library/Application Support/zqagent、Linux ~/.zqagent_data； 日志：macOS ~/Library/Logs/zqagent/node.log、Linux ~/.zqagent_data/node.log。 （Linux 早期版本用 /var/lib/zqagent；已装的实例由脚本沿用原 unit 里的路径，不会迁移。） 可用 PORT / HOST / DATA_DIR / LOG / SERVICE_NAME 覆盖，例如：

sudo PORT=9000 DATA_DIR=/data/zqagent bash install.sh install

服务用「绝对路径的 node + CLI 入口」启动，不依赖 nvm/volta 的 PATH； Linux 上的额外环境变量（LLM key、HUB_URL、SECRET_KEY 等）可写 /etc/zqagent.env。 停止走 SIGTERM，serve 会落盘账本后退出（宽限期默认 3s，用 ZQAGENT_SHUTDOWN_GRACE_MS 调整）。

脚本会校验当前 CLI 是否支持 serve：旧版本（如 0.1.33）没有该子命令， 请先 npm i -g @zqagent/core@latest，否则进程会静默进入交互式会话。

手写 systemd unit（不使用脚本时）

# /etc/systemd/system/zqagent.service
[Unit]
Description=zqagent node
After=network-online.target

[Service]
# 把 <用户名> 换成实际运行节点的用户；数据放在该用户家目录，权限天然归它所有
User=<用户名>
ExecStart=/usr/local/bin/zqagent serve --port 8787 --data-dir %h/.zqagent_data
Restart=always
RestartSec=3
KillSignal=SIGTERM
TimeoutStopSec=15

[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload
sudo systemctl enable --now zqagent
journalctl -u zqagent -f      # 查看日志

pm2（备选）

注意不能把整条命令塞进一个字符串（会被当成 bash -c 脚本，参数丢失并退回交互式会话）：

pm2 start "$(command -v zqagent)" --name zqagent -- serve --port 8787 --data-dir "$HOME/.zqagent_data"
pm2 save && pm2 startup   # 开机自启

nohup（临时调试）

nohup zqagent serve --port 8787 --data-dir "$HOME/.zqagent_data" \
  > "$HOME/.zqagent_data/node.log" 2>&1 &

自动更新

以单文件（SEA）安装并交给系统服务托管后，节点会自己保持版本。全新机器建议直接用 单文件安装的一条命令，它会同时装好二进制与服务：

1. 启动 5 分钟后检查一次，之后每 6 小时一次（±15% 抖动）
2. 有新版则静默下载并校验 SHA-256，再跑一次 --version 自检
3. 等到连续空闲 60 秒（没有执行中、也没有等待审批/回答的会话）才替换自身并退出
4. systemd / launchd 把新版本拉起，版本在控制台自动更新

失败不会影响节点运行：下载/校验失败只记日志，同一版本连续失败 3 次后跳过。

前置条件

自动更新只在三个条件同时满足时生效（缺一不可）：

• 单文件形态（由 SEA 产物启动，而不是 node dist/cli/index.js）
• 由 systemd / launchd 托管（install.sh 安装）
• 配置了验签公钥 ZQAGENT_UPDATE_PUBKEY

用 npm 安装的节点不会被自动替换，请用 npm i -g @zqagent/core@latest 升级。

macOS：托管判定与 Linux 一致。服务进程内直接生效；在终端手动执行 zqagent update --status/--check/--now 时也会通过 launchd 作业（pid / program） 与 plist 里的 EnvironmentVariables 自动识别托管状态、公钥与通道， 不需要先 source 任何环境变量。卸载用 sudo sh -s -- uninstall。

Windows：没有 systemd / launchd，单文件节点不会被自动更新（zqagent update --status 会显示“服务托管 未托管（前台/nohup）”）。升级请停止 serve 进程，用新下载的 exe 覆盖旧文件后重新启动； zqagent update --now 在未托管环境下会直接拒绝执行。

安装脚本默认就会获取公钥，一条命令完成安装 + 开启自动更新：

curl -fsSL https://agent.cd-zq.com/install.sh | sudo sh

想用带外保存的公钥覆盖自动获取，加 --pubkey "..." 即可（显式公钥优先，不会再被联网获取覆盖）。

开关与配置

环境变量	默认值	说明
ZQAGENT_AUTO_UPDATE	1	设 0 完全关闭自动更新
ZQAGENT_UPDATE_PUBKEY	安装时自动写入	验签公钥（PEM 或 base64 SPKI DER），缺失则不自动安装
ZQAGENT_UPDATE_CHANNEL	stable	清单通道（stable / beta）
ZQAGENT_UPDATE_URL	https://agent.cd-zq.com/downloads/zqagent/<channel>.json	清单地址，内网可覆盖
ZQAGENT_UPDATE_INTERVAL_MS	21600000（6h）	检查间隔
ZQAGENT_UPDATE_MIN_UPTIME_MS	600000（10min）	启动后多久内不更新
ZQAGENT_UPDATE_IDLE_MS	60000	连续空闲多久才安装
ZQAGENT_UPDATE_INSECURE	—	设 1 允许 http 清单（仅内网自测）

检查是否有更新

zqagent update --check       # 只查有没有新版（不下载，秒回）
zqagent update --status      # 当前版本、通道、上次检查时间、暂存/失败原因

输出示例：

当前版本  v0.2.1
运行形态  单文件（SEA）
服务托管  systemd
更新通道  stable
清单地址  https://agent.cd-zq.com/downloads/zqagent/stable.json
自动更新  已启用

--check 会打印「已是最新版本（vX）」或「发现新版本 vY（当前 vX）」。

手动干预

zqagent update --now         # 立即下载安装（跳过空闲等待，需重启服务）
zqagent update --rollback    # 回到上次更新前的版本

服务侧回滚（自动重启）：

sudo sh -s -- rollback    # 单文件安装（从下载目录取脚本时用 sudo sh install.sh rollback）
sudo bash install.sh rollback        # 仓库内安装

回滚后会跳过该版本：自动更新不会立刻把它再装回来，直到发布更新的版本； 确需强制安装可用 zqagent update --now。

发布侧

一条命令完成：构建 SEA 单文件 → 生成并签名清单 → 同步到下载目录。全程不经过 npm， 节点侧也不需要 Node（二进制自带运行时）。

# 首次：生成签名密钥对（私钥只放发布机或 CI secret，公钥分发给节点）
node packages/core/scripts/gen_update_keys.mjs --out .update-keys

# 每次发版（参数全有默认值：版本取 packages/core/package.json，私钥取 .update-keys/update-private.pem）
bash scripts/release_node.sh

常用参数：

参数	默认值	说明
--version X	packages/core/package.json 的版本	裸版本号；脚本会校验两者一致
--key FILE	.update-keys/update-private.pem	Ed25519 私钥，用于清单签名
--pubkey-file FILE	与私钥同目录的 update-public.b64	节点验签公钥；发布前校验其与私钥成对，并同步到下载目录
--host USER@HOST	空 = 本机发布	发布机就是站点服务器时不用给
--dest DIR	/var/www/zqagent-downloads/zqagent	nginx /downloads/ 实际指向的目录
--notes TEXT	本次更新内容: 例行更新	写进清单，客户端日志可见
--skip-build	—	复用 packages/core/release/cli 已有产物
--dry-run	—	只打印将执行的命令

三种典型用法：

# 1) 发布机就是站点服务器：直接写本机下载目录
bash scripts/release_node.sh --skip-build

# 2) 从别的机器发布：ssh + rsync 推到站点服务器
bash scripts/release_node.sh --host deploy@your-server --skip-build

# 3) 先看清楚会做什么
bash scripts/release_node.sh --dry-run

跨平台产物只能在对应系统/架构上构建，全平台发版请在 CI 矩阵里各构建一次，再用 --skip-build --host ... 汇总发布。

发布后的目录结构：

/downloads/zqagent/
├── install.sh           # 一键安装脚本
├── install-node.sh      # 旧地址兼容副本（内容同 install.sh）
├── update-public.b64    # 验签公钥（安装时用 --pubkey 传入）
├── stable.json          # 更新清单（节点读取）
├── stable.json.sig      # 清单签名
├── stable.txt           # 纯文本清单（安装脚本用）
└── v0.2.2/
    └── zqagent-<platform>-<arch>

节点只在签名验证通过后才下载二进制，并用清单里的 SHA-256 再做一次校验。 发布后自检：

curl -s https://agent.cd-zq.com/downloads/zqagent/stable.txt
curl -s https://agent.cd-zq.com/downloads/zqagent/stable.json | head -20

完整的发布与回滚流程见仓库内 docs/release-runbook.md。

接入用户中心（可选）

接入后可在用户中心查看节点在线状态、项目和事件。 两种方式，任选其一：

• Hub 账号（推荐）：直接使用在用户中心注册的邮箱/手机号 + 密码；
• 一次性接入码：登录用户中心 → 创建节点管理 → 生成接入码（15 分钟有效）。

已运行的节点：热接入（免重启）

# 账号方式：邮箱或手机号 + 密码
zqagent link --hub https://hub.cd-zq.com --username you@example.com --password '<密码>'
zqagent link --hub https://hub.cd-zq.com --username 13800000000 --password '<密码>'

# 手机号 + 短信验证码
zqagent link --hub https://hub.cd-zq.com --username 13800000000 --sms-code <验证码>

# 或一次性接入码
zqagent link --hub https://hub.cd-zq.com --code <接入码>

Windows 单文件：

zqagent.exe link --hub https://hub.cd-zq.com --username you@example.com --password <密码>
zqagent.exe link --hub https://hub.cd-zq.com --code <接入码>

不带任何凭据参数时 zqagent link 会进入交互向导，依次询问 Hub 地址、登录方式和账号密码 （密码隐藏输入）。密码也可以用环境变量 ZQAGENT_HUB_PASSWORD 提供，避免留在命令历史里。

Windows 上的默认数据目录是 %APPDATA%\zqagent，link 会从桌面端登记的 runtime\service.json 自动发现；只有手动配置计划任务、且数据目录不在默认位置时， 才需要补 --data-dir。

link 会先尝试热接入本机正在运行的 serve。Linux 通过 /proc、macOS 通过 ps、 Windows 通过 PowerShell 的 Win32_Process 反查进程命令行，因此即使 serve 用了自定义 --data-dir / --port 也能发现；PowerShell 不可用时会退回“写 fleet.json，下次启动生效”。

发现到多个实例时，link 优先选择由 systemd / launchd 托管的服务（开机自启、重启后仍在）， 其次是命令行里临时启动的 serve；当前目录的 .zqagent_data 只作最后兜底，避免凭据被 临时实例截走、导致命令报成功而托管服务始终离线。

节点名称

接入时没给 --label 的节点，默认用主机名作为显示名，Hub 里看到的是机器名而不是 nodeId。 之后可以在两个地方改，改的是同一份记录：

• Hub 用户中心 → 节点管理 → 节点「改名」；
• 节点机器上执行（本机有服务时热生效，免重启）：

zqagent rename ten004-dev

接入过 Hub 时该命令会用节点自己的凭据同步 Hub 记录，控制台刷新即生效； 未接入时只写本机配置，下次启动 serve 生效。

服务当前没在运行时，link 也会解析 plist / systemd unit 找到它登记的数据目录，把凭据写到 那里（服务下次启动即自动接入），因此无论桌面端还是 install.sh 安装的节点，都不需要用户 手动传 --data-dir。

一般不必手动写 --data-dir：上面这条命令会自动发现本机节点。只有提示「未发现本机节点服务」 时才需要补上，且要用当前用户可写的目录（各平台安装脚本默认值）：

平台	默认数据目录
macOS	$HOME/Library/Application Support/zqagent
Linux	~/.zqagent_data（归当前用户所有；早期版本为 /var/lib/zqagent）
Windows	%APPDATA%\zqagent

别照抄旧教程里的 --data-dir /var/lib/zqagent：新安装默认就在 ~/.zqagent_data， 手动指定一个系统目录反而会撞上 EACCES: permission denied。省略该参数即可。

启动即接入

在 serve 时带上 Hub 地址与账号（或接入码）：

# 账号方式（适合 systemd / 容器等非交互环境）
zqagent serve --hub https://hub.cd-zq.com --username you@example.com --password '<密码>'

# 接入码方式
zqagent serve --hub https://hub.cd-zq.com --enroll-code <接入码>

也可用环境变量（适合容器 / 脚本）：

HUB_URL=https://hub.cd-zq.com ZQAGENT_HUB_USERNAME=you@example.com \
  ZQAGENT_HUB_PASSWORD='<密码>' zqagent serve

HUB_URL=https://hub.cd-zq.com HUB_ENROLL_CODE=<接入码> zqagent serve

交互式 CLI 内接入

在 zqagent 界面中直接：

/link                                # 进入账号接入向导
/link <接入码> [Hub地址]

Docker

docker run -d -p 8787:8787 -v zqagent-data:/data \
  -e HUB_URL=https://hub.cd-zq.com -e HUB_ENROLL_CODE=<接入码> \
  ghcr.io/<owner>/zqagent-server

凭据与网络

• 接入成功后凭据写入 {DATA_DIR}/fleet.json，后续重启无需再带账号或接入码；
• 节点只需出站连接网关（wss://，通常走 443），无需公网入站、无需开放端口；
• 换绑或解绑：用户中心节点详情页操作，或删除 fleet.json 后重新接入。

数据目录

节点所有长期数据都在 {DATA_DIR}（默认 ./.zqagent_data，随项目走）：

路径	内容
{DATA_DIR}/admin.json	管理员密钥
{DATA_DIR}/fleet.json	接入凭据（0600）
{DATA_DIR}/usage/	用量账本、汇总与价格表
会话与项目	由各项目按工作目录保存

模型 API Key 单独加密保存在用户配置目录（macOS / Linux ~/.config/zqagent/， Windows %APPDATA%\zqagent\），与数据目录分离。

验证节点在线

1. 浏览器打开用户中心，进入对应的节点管理；
2. 节点列表中出现该节点且状态为在线；
3. 点击节点进入节点控制台，可查看项目、会话、用量与事件。

节点离线时：确认 serve 进程存活、机器能出站访问网关地址（FLEET_GATEWAY_URL）。

下一步

• 节点控制台：图形界面管理节点、会话与用量
• 远程控制概览：手机与 QQ 远程派任务
• 服务端配置：环境变量、云端接入与公网方案