0.11.5: 旗舰版第六轮完善(节点Agent程序/裸机安装脚本/集群冷备部署方案)

- cmd/agent-node:独立节点执行器,心跳/认领/执行/上报闭环;prompt 走本地
  LLM 或网关,http 仅 http(s) 禁重定向限 1MiB,mcp/skill/数字员工经网关
  转发,custom 回显;不执行任意 shell 命令,串行执行 + 优雅退出。
- scripts/install-agent-node.sh:裸机安装 + systemd 加固(0600 配置/
  NoNewPrivileges/ProtectSystem)。
- deploy/CLUSTER.md:单机/冷备/集群形态,多副本网关 compose override +
  nginx least_conn 入口,冷备 master key 同步与恢复演练要点。
- 修复 agent claim 未解包 apiresponse 信封;真实 Agent 进程端到端验证
  (注册→心跳上线→custom/http 任务认领执行上报→管理端成功可见);
  25 包测试通过。

deploy/CLUSTER.md

@@ -0,0 +1,115 @@
+# 集群与冷备部署方案
+
+本文档说明旗舰版「单机 / 冷备 / 集群」部署形态的落地方式。当前工程的所有有状态
+组件(PostgreSQL / Redis / MinIO)仍建议单点或托管服务,无状态控制面
+(gateway-api / 各 worker)可按本文档横向扩展。
+
+## 1. 部署形态对照
+
+| 形态 | 说明 | 适用 |
+|---|---|---|
+| 单机 | 全部容器在一台主机(docker-compose.yml 默认) | 开发/小团队 |
+| 冷备 | 数据层定期备份 + 备用主机完整镜像,主故障时切换 | 生产入门 |
+| 集群 | 无状态组件多副本 + 数据层托管/高可用 | 生产规模化 |
+
+## 2. 为什么可以横向扩展控制面
+
+- **outbox worker**:`SKIP LOCKED` 租约 + Redis Stream 消费组,已支持多实例
+  并发消费,事件不会重复投递(worker 天然多副本安全);
+- **gateway-api**:无本地状态,会话/限流/配额在 Redis,权威数据在 PostgreSQL,
+  任意副本可服务同一请求;审计批量 COPY 由 `audit_events` 分区 + advisory lock
+  维护,多副本写入安全;
+- **调度器/通知/维护 worker**:全部基于数据库租约或消费组,多副本安全;
+- **节点 Agent**:与网关是拉模型(心跳/认领),天然分布式。
+
+## 3. 集群部署(compose override 示例)
+
+`deploy/docker-compose.cluster.yml`:
+
+```yaml
+# 用法: docker compose -f docker-compose.yml -f docker-compose.cluster.yml up -d
+services:
+  gateway-api:
+    deploy:
+      replicas: 3
+    # 集群模式下网关端口不应直接暴露(由入口 nginx 负载均衡到各副本),
+    # 移除主机端口绑定:
+    ports: []
+  gateway-api-lb:
+    image: nginx:1.27-alpine
+    ports:
+      - "127.0.0.1:8080:80"
+    volumes:
+      - ./nginx-cluster.conf:/etc/nginx/conf.d/default.conf:ro
+    depends_on:
+      - gateway-api
+```
+
+`deploy/nginx-cluster.conf`(入口负载均衡,round-robin 到各副本):
+
+```nginx
+upstream gateway_replicas {
+    least_conn;
+    server gateway-api:8080 max_fails=3 fail_timeout=10s;
+    server gateway-api:8080 max_fails=3 fail_timeout=10s;
+    server gateway-api:8080 max_fails=3 fail_timeout=10s;
+}
+
+server {
+    listen 80;
+    server_tokens off;
+    client_max_body_size 256m;
+    location / {
+        proxy_pass http://gateway_replicas;
+        proxy_http_version 1.1;
+        proxy_set_header Host $host;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_read_timeout 300s;
+    }
+}
+```
+
+说明:
+
+- Compose 的 `deploy.replicas` 会为 `gateway-api` 创建多个容器,`least_conn`
+  负载均衡到全部副本;副本间无会话亲和需求(会话令牌在 Redis);
+- worker 类服务保持单副本即可(多副本也安全,但无收益);
+- 网关不再发布主机端口,所有流量经 `gateway-api-lb`。
+
+## 4. 冷备
+
+数据层(权威):
+
+- PostgreSQL: `pg_dump -Fc` 每日全量 + WAL 归档;恢复演练用
+  `pg_restore` 到备用主机;建议配合 `pgBackRest`/云厂商 PITR;
+- Redis critical(会话/限流/配额):`APPENDONLY yes` 已在 compose 开启,定期
+  `redis-cli BGSAVE` 并备份 dump.rdb;丢失只会导致会话失效/限流重置,
+  不会损坏权威数据;
+- MinIO: 对象存储桶异地备份(`mc mirror`)或托管 S3 兼容服务。
+
+备用主机:
+
+- 镜像完整代码与 compose 配置;`deploy/.env`(含 CREDENTIAL_MASTER_KEY)必须
+  同步——**master key 丢失会导致全部加密凭据不可解密**;
+- 故障切换:恢复 DB/Redis 备份 → `docker compose up -d` → 验证
+  `healthz` 与登录;
+- 建议每月做一次恢复演练(切换 runbook 见 `docs/cutover-runbook.md`)。
+
+## 5. 多租户与集群的注意事项
+
+- 会话/限流 Redis 需所有副本共享同一 critical Redis(或 Sentinel 高可用);
+- `X-Forwarded-For` 由入口 nginx 统一设置,gateway-api 的限流/审计 IP 以
+  可信代理逻辑解析(见 `internal/identity/ratelimit.go`),不要直连暴露副本;
+- 节点 Agent 指向入口地址(`AGENT_GATEWAY_URL`),经 LB 到达任意副本,拉模型
+  无粘性要求。
+
+## 6. 生产环境建议清单
+
+- [ ] 数据库连接池上限按副本数调整(`DATABASE_MAX_CONNS`),避免连接耗尽;
+- [ ] PostgreSQL `max_connections` 与 shared_buffers 按主机内存配置;
+- [ ] 入口启用 TLS(nginx/certbot 或云 LB),`CREDENTIAL_MASTER_KEY` 用
+      密钥管理服务注入,不进 compose 文件;
+- [ ] 审计月分区自动维护已由 maintenance worker 执行,多副本由 advisory lock
+      互斥;
+- [ ] 监控:healthz/readyz + Prometheus `/metrics` 接入现有监控;
+- [ ] 备份与恢复演练纳入变更流程。