服務端設定
本文件是服務端的啟動與設定指南，重點回答三個問題：
- 怎麼啟動（本地 / 雲端 / 桌面三種形態）
- 是否需要公網（結論：本體不需要，只有 REST 介面有需要時才要）
- 雲端接入怎麼配（連上 Rust 閘道器，從此可遠端管理）
前置準備
| 項 | 要求 |
|---|---|
| Node.js | ≥ 18.17（推薦 20+） |
| 模型 API Key | OpenAI 相容端點（DeepSeek / OpenAI / Ollama / 自定義） |
| （可選）雲端賬號 | 自建 Rust 閘道器 + Hub，或用託管服務 |
| （可選）QQ 開放平臺機器人 | q.qq.com 註冊 |
bash
# 獲取程式碼並安裝依賴
pnpm install
# 互動式設定（推薦）：LLM 必配，QQ/電子郵件可選、可跳過
bash scripts/configure-server.sh
# 或手動：複製模板後填寫
# cp .env.example .env環境變數總覽
寫入專案根目錄 .env（或啟動前 export）：
| 變數 | 說明 | 預設 |
|---|---|---|
DATA_DIR | 資料/租戶根目錄 | ./.zqagent_data |
PORT | REST 監聽埠 | 8787 |
HOST | 監聽地址（公網部署設 0.0.0.0） | 127.0.0.1 |
WORKSPACE | Agent 工作目錄 | 當前目錄 |
APPROVAL_TIMEOUT_SECONDS | 審核/提問掛起超時 | 900 |
MAX_ITERATIONS | 單輪最大迭代 | 800 |
OPENAI_API_KEY / OPENAI_BASE_URL / OPENAI_MODEL / OPENAI_REASONING_EFFORT | 模型設定（不設 OPENAI_MODEL 時不指定模型，需在控制台裡選） | — |
TENANT_ID / TENANT_API_KEY / MODEL | 首次啟動自動建立的演示租戶 | demo / 首次啟動隨機生成 / 模型預設 |
SECRET_KEY | 加密通知憑據等的主金鑰 | 自動生成 |
FLEET_TOKEN / FLEET_SECRET / FLEET_GATEWAY_URL | 雲端接入（通常由註冊碼接入自動寫入 fleet.json） | — |
QQ_BOT_APP_ID / QQ_BOT_APP_SECRET / QQ_BOT_SANDBOX | QQ 機器人（設定後啟用） | — |
CONTEXT_WINDOW / COMPACTION_THRESHOLD_PCT / COMPACTION_CAP_TOKENS | 長對話壓縮引數 | 自動 |
SECRET_KEY一旦設定建議長期固定：它用於加密租戶簽名金鑰與通知渠道憑據， 更換會導致舊租戶的金鑰與憑據失效。
三種部署形態
本地 / 內網執行（最推薦，無需公網）
bash
# 最小可執行（先確認能啟動、能對話）
pnpm run server
# 日誌：
# zqagent server 監聽 http://127.0.0.1:8787
# 已建立演示租戶: id=demo apiKey=zk_xxxx（隨機生成） model=...
# 完整遠端控制（配好 .env 後）：
# FLEET_GATEWAY_URL=wss://gw.example.com/ws
# QQ_BOT_APP_ID=... QQ_BOT_APP_SECRET=...
# OPENAI_API_KEY=sk-... OPENAI_MODEL=...
pnpm run server啟動後驗證服務可用：
bash
# 演示租戶 apiKey 首次啟動隨機生成並列印在啟動日誌裡，取出來存進 TOKEN
TOKEN=<啟動日誌中的 apiKey> # 形如 zk_1f0c...
curl -s http://localhost:8787/healthz # => {"status":"ok"}
curl -s -H "Authorization: Bearer $TOKEN" http://localhost:8787/api/v1/sessions雲端部署（需要 REST 公網訪問時）
租一臺雲伺服器，HOST=0.0.0.0 暴露埠。
bash
# 推薦用 pm2 常駐
npm install -g pm2
HOST=0.0.0.0 pm2 start "pnpm run server" --name zqagent-server
# 安全建議：只對需要的人開放。若 REST 僅自己用，建議不直接暴露公網，
# 改用內網穿透，或用雲伺服器防火牆限制來源 IP。桌面應用（macOS / Windows）
桌面應用會自動在本地拉起服務端，無需手動啟動。見桌面應用。
需要 REST 公網訪問時的三種方案
| 方案 | 做法 | 適用 |
|---|---|---|
| A. 內網穿透（推薦個人） | Cloudflare Tunnel（免費）或 frp/ngrok，把本地埠對映成公網 HTTPS | 家裡/內網機器，無需租伺服器 |
| B. 雲伺服器 | 直接部署到 VPS，HOST=0.0.0.0 | 有現成伺服器，或需長期穩定 |
| C. 不走 REST | 用閘道器全鏈路（憑據由控制面簽發），REST 只在自己電腦上用 | 完全不想暴露埠 |
雲端接入（Rust 閘道器）
接入後即可從任意裝置遠端管理本節點。節點只需出站連線閘道器（wss://，通常走 443）， 無需公網入站、無需開放埠，也不需要任何 MQTT broker。
方式一：用註冊碼接入（推薦）
在使用者中心（Hub）建立一個一次性註冊碼，然後在節點機器上執行：
bash
zqagent link --hub https://hub.example.com --code <註冊碼>- 本機已有服務在跑 → 熱接入（免重啟）；
- 否則憑據寫入
{DATA_DIR}/fleet.json，下次zqagent serve自動接入。
方式二：手工設定
bash
# .env
FLEET_TOKEN=<高熵隨機> # 名稱空間標識
FLEET_SECRET=<高熵隨機> # 簽名金鑰（須與閘道器側一致）
FLEET_GATEWAY_URL=wss://gw.example.com/ws
SECRET_KEY=<64位hex> # 強烈建議顯式設定啟動後驗證：
bash
curl -s -H "Authorization: Bearer $ADMIN_API_KEY" \
http://localhost:8787/api/v1/fleet/pairing
# => {"data":{"gatewayUrl":"wss://gw.example.com/ws","fleetToken":"...","fleetSecret":"...","nodeId":"..."}}啟動日誌出現「雲端接入: wss://…（節點 nodeId）」即成功。
不接入雲端
不設定任何 FLEET_* 即為純本地節點：所有本地功能照常，只是雲端看不到它。 隨時可執行 zqagent link 接入。
閘道器側的部署（金鑰、TLS、多副本）見倉庫的
docs/rust-gateway-plan.md與deploy/k8s/gateway/。協議細節見docs/wire-protocol.md。
常見問題排查
| 現象 | 排查 |
|---|---|
| 節點連不上閘道器 | 確認地址是 wss://.../ws；證書由 CA 簽發（非自籤）；防火牆放行 443 |
| 日誌「未能接入閘道器」 | 檢查 FLEET_GATEWAY_URL 可達性與 FLEET_SECRET 是否與閘道器一致 |
| 服務端不監聽外部 | HOST 預設 127.0.0.1，公網訪問需設 HOST=0.0.0.0 並放行埠 |
| QQ 閘道器連線失敗 | 檢查 AppID/Secret；intents 許可權是否申請；沙箱用 QQ_BOT_SANDBOX=1 |
| 電子郵件發不出去 | QQ 電子電子郵件用授權碼（非登入密碼）；secure 與埠匹配（465→true，587→false） |
換了 SECRET_KEY 後憑據失效 | SECRET_KEY 建議固定，更換會使舊租戶憑據全部作廢 |