服务端配置
本文档是服务端的启动与配置指南，重点回答三个问题：
- 怎么启动（本地 / 云端 / 桌面三种形态）
- 是否需要公网（结论：本体不需要，只有 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 建议固定，更换会使旧租户凭据全部作废 |