Files

T

LLMGuardX Dev 277f80dc82 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 包测试通过。

2026-08-13 14:39:35 +08:00

4.4 KiB

Raw Blame History

集群与冷备部署方案

本文档说明旗舰版「单机 / 冷备 / 集群」部署形态的落地方式。当前工程的所有有状态组件(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:

# 用法: 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 到各副本):

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 接入现有监控;
备份与恢复演练纳入变更流程。

4.4 KiB Raw Blame History