Docker Compose 部署参考

Cybros 采用双镜像分层架构进行容器化部署：Core Matrix 作为控制平面运行于 PostgreSQL 之上，Fenix 作为代理程序运行时运行于 SQLite 之上。两套镜像均基于多阶段构建，通过 Thruster 反向代理对外暴露 80 端口。本文档详述生产 Docker Compose 编排的结构、环境配置、服务依赖关系与调优参数，覆盖 Core Matrix 独立部署和 Core Matrix + Fenix 联合部署两种场景。

Sources: Dockerfile, compose.yaml.sample, Dockerfile, docker-compose.fenix.yml

架构总览

整个部署拓扑由以下核心服务构成。Core Matrix 的 compose 编排包含四个服务（数据库、迁移器、Web 应用、后台作业），Fenix 的 compose 编排包含两个服务（代理运行时、开发代理）。两者可独立运行，也可通过环境变量互联。

上图中实线表示直接服务依赖，虚线表示跨编排的运行时连接。Core Matrix 的 migrator 必须在 db 健康且迁移成功后才允许 app 和 jobs 启动——这是通过 service_completed_successfully 条件实现的严格启动门控。

Sources: compose.yaml.sample, docker-compose.fenix.yml

镜像构建分析

Core Matrix 镜像

Core Matrix 镜像采用经典的三阶段构建模式，基于 ruby:4.0.2-slim：

构建过程中 SECRET_KEY_BASE_DUMMY=1 用于绕过资产预编译对密钥的依赖，最终镜像不包含构建工具链和 node_modules，确保镜像体积最小化。容器以 rails 用户（uid/gid 1000）运行，入口点在启动 Rails server 前自动执行 db:prepare 进行数据库迁移。

Sources: Dockerfile, bin/docker-entrypoint

Fenix 镜像

Fenix 镜像的构建更为复杂，采用四阶段构建且基于 ubuntu:24.04 而非 Ruby 官方镜像，因为 Fenix 运行时需要 Playwright、Caddy、Node.js、Python 等额外的系统依赖：

Fenix 入口点的设计与 Core Matrix 有一个关键区别：它以 root 身份启动，执行 /rails/storage 和 /rails/tmp 目录的创建与权限设置后，通过 setpriv 降权至应用用户再执行实际命令。这确保了挂载卷在首次运行时具有正确的所有权。

Sources: Dockerfile, bin/docker-entrypoint, bootstrap-runtime-deps.sh

Core Matrix 编排详解

服务依赖与启动顺序

compose.yaml.sample 的 YAML 锚点 &default-app 定义了所有应用服务的共享配置，通过 <<: *default-app 合并到各服务中。启动顺序严格遵循以下依赖链：

migrator 服务设置 restart: "no"，确保迁移只执行一次。若迁移失败则 service_completed_successfully 条件不满足，app 和 jobs 不会启动——这是防止应用连接未迁移数据库的关键保护。

Sources: compose.yaml.sample

数据库服务

Core Matrix 使用 pgvector/pgvector:pg18-trixie 镜像，在 PostgreSQL 18 基础上内置 pgvector 扩展，支持向量相似度搜索场景。数据库配置要点如下：

Production 环境下 Core Matrix 使用四数据库架构：primary（业务数据）、cache（Solid Cache）、queue（Solid Queue）、cable（Solid Cable），共享同一 PostgreSQL 实例但使用独立数据库。连接字符串通过 RAILS_DB_URL_BASE 环境变量统一注入，格式为 postgresql://postgres:密码@db，各数据库名称由 config/database.yml 自动拼接。

Sources: compose.yaml.sample, config/database.yml

Web 应用服务

app 服务通过 Thruster（基于 HAProxy 的轻量反向代理）包装 Puma，对外暴露 80 端口（映射至宿主机 8080）。健康检查通过 curl -f http://localhost/up 验证 Rails 就绪状态，启动宽限期为 60 秒。

资源限制设置为 2 核 CPU / 2GB 内存，与数据库服务保持一致。config.d 目录以只读方式挂载至 /rails/config.d，允许在不重建镜像的情况下覆盖 LLM Provider 目录等配置。

Sources: compose.yaml.sample

后台作业服务

jobs 服务运行 Solid Queue 工作器，负责处理 LLM 请求、工具调用、工作流编排和维护任务。资源限制设置为 1 核 CPU / 1GB 内存，低于 Web 服务——因为作业处理主要是 I/O 密集型（等待 LLM API 响应）。

队列拓扑由 config/runtime_topology.yml 定义，通过 config/queue.yml 动态生成 Solid Queue 配置。默认拓扑包含 5 个 LLM 队列（按 Provider 隔离）、1 个工具调用队列、1 个工作流队列和 1 个维护队列，每个队列的线程数和进程数均可通过环境变量覆盖。

Sources: compose.yaml.sample, config/runtime_topology.yml

Fenix 编排详解

服务组成

Fenix 的 docker-compose.fenix.yml 定义了两个服务：

fenix 服务是主运行时，承载 Puma Web 服务器和 Solid Queue（通过 Puma 插件内嵌运行）。fenix-dev-proxy 服务运行 Caddy 反向代理，用于浏览器预览验证。两者通过 fenix_proxy_routes 卷共享 Caddy 路由配置文件。

Fenix 使用 SQLite 数据库（区别于 Core Matrix 的 PostgreSQL），数据库文件存储在 /rails/storage 目录中，通过 fenix_storage 卷持久化。同样采用双数据库架构：primary（业务数据）和 queue（Solid Queue），连接池大小分别由 FENIX_PRIMARY_DB_POOL 和 FENIX_QUEUE_DB_POOL 控制。

Sources: docker-compose.fenix.yml, config/database.yml

Core Matrix 与 Fenix 的互联

当 Fenix 作为代理运行时与 Core Matrix 配对部署时，需配置以下连接参数：

在验收测试场景中，acceptance/bin/activate_fenix_docker_runtime.sh 脚本演示了完整的 Fenix Docker 运行时激活流程：构建镜像 → 启动容器 → 等待健康检查 → 执行运行时依赖引导 → 启动 runtime-worker 进程。当 Core Matrix 运行在宿主机而 Fenix 运行在 Docker 中时，CORE_MATRIX_BASE_URL 应设置为 http://host.docker.internal:3000。

Sources: env.sample, activate_fenix_docker_runtime.sh

环境变量参考

必需变量

以下环境变量在生产部署中必须配置：

Sources: env.sample (Core Matrix), env.sample (Fenix)

性能调优变量

以下变量具有合理的默认值，仅在需要偏离基线时才需显式设置。默认值针对 4 核 / 8GB 内存的基准宿主机构型设计。

Core Matrix 调优参数：

Fenix 调优参数：

Sources: env.sample (Core Matrix), env.sample (Fenix)

运行时配置覆盖机制

Core Matrix 的 compose 编排将 ./config.d 目录以只读方式挂载至容器内 /rails/config.d，实现运行时配置覆盖而不重建镜像。这一机制的典型应用场景是 LLM Provider 目录定制：

1. 将 config.d/llm_catalog.yml.sample 复制为 config.d/llm_catalog.yml
2. 按需添加或修改 Provider 和模型定义
3. 重启容器即可生效，无需重新构建镜像

覆盖文件支持深度合并策略：Hash 类型键递归合并，Array 类型键整体替换。API 密钥等敏感信息不应放在此目录中，而应通过 .env 文件或 Rails credentials 管理。

Sources: compose.yaml.sample, llm_catalog.yml.sample

快速部署指南

Core Matrix 独立部署

操作步骤如下：

1. 进入 core_matrix/ 目录，复制环境模板：cp env.sample .env
2. 编辑 .env，填写 POSTGRES_PASSWORD、SECRET_KEY_BASE 和三组 Active Record Encryption 密钥
3. 复制编排文件：cp compose.yaml.sample compose.yaml（该文件已在 .dockerignore 和 .gitignore 中被忽略）
4. 如需定制 LLM Provider，编辑 config.d/llm_catalog.yml
5. 构建并启动：docker compose build && docker compose up -d
6. 验证健康状态：curl -f http://localhost:8080/up

Sources: env.sample, compose.yaml.sample

Core Matrix + Fenix 联合部署

当需要部署完整的代理运行时能力时，在 Core Matrix 基础上追加 Fenix 服务。关键步骤：

1. 确保 Core Matrix 已正常运行且可访问
2. 在 Core Matrix 中为目标代理程序创建机器凭证（用于 CORE_MATRIX_MACHINE_CREDENTIAL）
3. 进入 agents/fenix/ 目录，复制 env.sample 为 .env
4. 填写 SECRET_KEY_BASE、Active Record Encryption 密钥、CORE_MATRIX_BASE_URL 和 CORE_MATRIX_MACHINE_CREDENTIAL
5. 启动：docker compose -f docker-compose.fenix.yml up -d
6. 验证 Fenix 健康状态：curl -f http://localhost:3101/up
7. 验证运行时注册：curl -f http://localhost:3101/runtime/manifest

如果两个 compose 编排运行在同一 Docker 主机上，可以创建共享网络使 Fenix 通过服务名访问 Core Matrix，此时 CORE_MATRIX_BASE_URL 应设置为 http://core-matrix-app:80（需确保 Core Matrix 的 app 服务加入了共享网络）。

Sources: docker-compose.fenix.yml, activate_fenix_docker_runtime.sh

开发容器配置

除生产 Docker Compose 外，Core Matrix 在 .devcontainer/ 中提供了 VS Code Dev Containers / GitHub Codespaces 的开发环境配置。该配置使用 ghcr.io/rails/devcontainer/images/ruby 预构建镜像，配合 PostgreSQL 18 和 Selenium Chromium 两个辅助服务，通过 postCreateCommand 自动执行 bin/setup --skip-server 完成环境初始化。此配置仅用于开发场景，不应用于生产部署。

Sources: .devcontainer/devcontainer.json, .devcontainer/compose.yaml

常见问题排查

Sources: compose.yaml.sample, env.sample, bin/docker-entrypoint

下一步阅读：了解 Core Matrix 的内部架构，请参阅 六大限界上下文与领域模型总览。关于 Fenix 代理程序如何与 Core Matrix 协同工作，请参阅 Fenix 产品定位与配对清单契约。队列拓扑的详细设计请参阅 运行时拓扑与 Solid Queue 队列配置。