啟動節點

「節點」指一臺執行 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 遠端派任務
• 服務端設定：環境變數、雲端接入與公網方案