ConvergeLoop/docker-compose.yml at master · suoten/ConvergeLoop · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
# ConvergeLoop Docker Compose 配置
#
# 用途：一键启动 ConvergeLoop API 服务，适用于本地开发、测试与生产部署。
#
# 用法：
#   开发模式（无认证）：docker compose up -d
#   生产模式（启用 API Key）：在 .env 中设置 CONVERGELOOP_API_KEY 后 docker compose up -d
#
# 健康检查：使用 /api/v1/ready 端点（已在 server.py 的 skip_paths 白名单中放行，
# 启用 CONVERGELOOP_API_KEY 后仍可无认证访问，避免容器被永久判定 unhealthy）

services:
  convergeloop:
    # 镜像构建：使用项目根目录 Dockerfile（多阶段构建，运行时不含 dev 依赖）
    build:
      context: .
      dockerfile: Dockerfile
    # 生产环境可改为镜像名：image: convergeloop:latest
    image: convergeloop:latest
    container_name: convergeloop
    restart: unless-stopped

    # 启动命令：调用 CLI 的 server 子命令启动 API 服务（含 Web Dashboard）。
    # 与 Dockerfile 默认 CMD ["server"] 保持一致，显式声明确保可读性。
    command: ["server"]

    # 端口映射：宿主端口:容器端口
    # 默认 8080，与 server.py _DEFAULT_API_PORT / main.py / .env.example 保持一致
    ports:
      - "${CONVERGELOOP_API_PORT:-8080}:8080"

    # 环境变量：从 .env 文件加载，未设置时使用默认值
    environment:
      # API 服务监听地址（容器内必须 0.0.0.0 才能被宿主访问）
      CONVERGELOOP_API_HOST: "0.0.0.0"
      # 容器内固定监听 8080（不读取宿主 CONVERGELOOP_API_PORT 环境变量）。
      # 设计意图：容器内端口固定，宿主端口通过上方 ports 段的
      # "${CONVERGELOOP_API_PORT:-8080}:8080" 映射，用户改宿主端口不影响容器内逻辑。
      # 若需同时改容器内端口，需同步修改此处、ports 段右侧、healthcheck 的 URL 端口
      # 和 Dockerfile 的 EXPOSE 端口——4 处必须一致，否则健康检查失败。
      CONVERGELOOP_API_PORT: "8080"
      # API Key 认证（未设置则不启用认证；生产部署必须设置）
      CONVERGELOOP_API_KEY: "${CONVERGELOOP_API_KEY:-}"
      # 未设置 API Key 时是否允许绑定到非 localhost 地址
      # 安全默认 0：防止用户默认部署后公网裸奔（违反硬约束已修复 2026-07）。
      # 容器绑定 0.0.0.0（必须），未设置 API_KEY 时 server.py 受保护模式会 sys.exit(1)。
      # 这是设计意图——强制用户显式选择：
      #   方案A（推荐）：取消注释 CONVERGELOOP_API_KEY 设置强密钥
      #   方案B（仅内网）：设置 CONVERGELOOP_ALLOW_NO_AUTH=1 显式确认风险
      # 任何一种方案都比"默认无认证暴露公网"安全。
      CONVERGELOOP_ALLOW_NO_AUTH: "${CONVERGELOOP_ALLOW_NO_AUTH:-0}"
      # CORS 允许的源（逗号分隔，生产环境需显式设置）
      CONVERGELOOP_CORS_ORIGINS: "${CONVERGELOOP_CORS_ORIGINS:-}"
      # 分析接口速率限制
      CONVERGELOOP_ANALYZE_RATE_LIMIT: "${CONVERGELOOP_ANALYZE_RATE_LIMIT:-10/minute}"
      # worker 进程数（生产建议设为 CPU 核数）
      CONVERGELOOP_WORKERS: "${CONVERGELOOP_WORKERS:-1}"
      # 最大并发运行会话数
      CONVERGELOOP_MAX_SESSIONS: "${CONVERGELOOP_MAX_SESSIONS:-10}"
      # Prometheus 指标端点 IP 白名单（默认仅本地）
      # 必须包含 Docker 网桥网段（172.16.0.0/12）：容器内 Prometheus 抓取从 172.x 发起，
      # 缺失会导致监控采集被 403 拒绝（违反硬约束已修复 2026-07）。
      # 含 172.17.0.0/16（默认 bridge）+ 172.18-31.x（自定义网络）+ IPv6 本地回环
      CONVERGELOOP_METRICS_ALLOW_IPS: "${CONVERGELOOP_METRICS_ALLOW_IPS:-127.0.0.1,::1,172.16.0.0/12}"
      # 是否强制 HTTPS 重定向
      CONVERGELOOP_FORCE_HTTPS: "${CONVERGELOOP_FORCE_HTTPS:-0}"
      # 是否开放 API 文档端点（生产建议关闭）
      CONVERGELOOP_ENABLE_DOCS: "${CONVERGELOOP_ENABLE_DOCS:-0}"
      # 日志级别
      CONVERGELOOP_LOG_LEVEL: "${CONVERGELOOP_LOG_LEVEL:-INFO}"
      # 配置文件路径（容器内固定位置，由 Dockerfile ENV 设置）
      CONVERGELOOP_CONFIG_PATH: "/app/convergeloop/config"

    # 健康检查：使用 /api/v1/ready 端点
    # 注意：该端点必须在 server.py 的 _add_auth_middleware skip_paths 白名单中放行，
    # 启用 CONVERGELOOP_API_KEY 后未在白名单的端点会返回 401，导致容器被永久判定
    # unhealthy 并因 restart: unless-stopped 无限重启循环。
    # 当前 /api/v1/ready 已在 server.py 的 skip_paths 中放行，修改时请同步更新。
    healthcheck:
      test: ["CMD", "python", "-c", "import os, urllib.request; urllib.request.urlopen(f'http://localhost:{os.environ.get(\"CONVERGELOOP_API_PORT\", \"8080\")}/api/v1/ready', timeout=5)"]
      interval: 30s
      timeout: 10s
      retries: 3
      # Python 冷启动（导入 FastAPI + 中间件 + 路由注册）约 20-30s，15s 太短会导致
      # 首次健康检查失败 → Docker 标记 unhealthy → restart: unless-stopped 无限重启循环
      start_period: 40s

    # 数据卷：持久化会话状态、日志、报告
    volumes:
      # 会话存储（包含运行中会话状态、检查点）
      - convergeloop_sessions:/home/convergeloop/.convergeloop/sessions
      # 日志（应用日志、审计日志）
      - convergeloop_logs:/home/convergeloop/.convergeloop/logs
      # 报告输出（生成的成熟度报告、SBOM 等）
      - convergeloop_reports:/home/convergeloop/.convergeloop/reports
      # 可选：挂载本地项目目录供 ConvergeLoop 分析（开发场景）
      # - ./your-project:/workspace:ro

    # 资源限制（生产环境建议根据实际负载调整）
    deploy:
      resources:
        limits:
          cpus: '2.0'
          memory: 2G
        reservations:
          cpus: '0.5'
          memory: 256M

    # 容器安全加固（与 sandbox_manager.py 创建的审计沙箱对齐）
    # 防止攻击者通过 RCE 漏洞攻破服务后在容器内提权、植入持久化后门
    # 注意：未启用 read_only: true，因为 license_manager 需写入
    # /home/convergeloop/.convergeloop/license.json（未由命名卷覆盖）。
    # cap_drop ALL + no-new-privileges 已阻断提权路径。
    cap_drop:
      - ALL
    security_opt:
      - no-new-privileges:true
    tmpfs:
      # 临时文件目录用 tmpfs（noexec 防止执行二进制）
      - /tmp:rw,noexec,nosuid,size=64m

    # 日志驱动：限制日志大小避免磁盘打满
    logging:
      driver: json-file
      options:
        max-size: "50m"
        max-file: "5"

# 命名数据卷：由 Docker 管理，删除容器不会丢失数据
volumes:
  convergeloop_sessions:
    driver: local
  convergeloop_logs:
    driver: local
  convergeloop_reports:
    driver: local